feat: implement explicit context caching for main agent with stable SI hashing

packages/core/src/utils/apiConversionUtils.test.ts

@@ -90,6 +90,22 @@ describe('apiConversionUtils', () => {
       expect(result['generationConfig']).toBeUndefined();
     });
 
+    it('omits systemInstruction when cachedContent is present', () => {
+      const req: GenerateContentParameters = {
+        model: 'gemini-3-flash',
+        contents: [{ role: 'user', parts: [{ text: 'Hello' }] }],
+        config: {
+          systemInstruction: 'Original instruction',
+          cachedContent: 'cached-content-id',
+        },
+      };
+
+      const result = convertToRestPayload(req);
+
+      expect(result['cachedContent']).toBe('cached-content-id');
+      expect(result['systemInstruction']).toBeUndefined();
+    });
+
     it('retains pure hyperparameters in generationConfig', () => {
       const req: GenerateContentParameters = {
         model: 'gemini-3-flash',

packages/core/src/utils/apiConversionUtils.ts

@@ -46,12 +46,16 @@ export function convertToRestPayload(
   }
 
   // Assign extracted capabilities to the root level.
-  if (restSystemInstruction)
+  // CRITICAL: systemInstruction and cachedContent are mutually exclusive in the API.
+  if (sdkCachedContent) {
+    restPayload['cachedContent'] = sdkCachedContent;
+  } else if (restSystemInstruction) {
     restPayload['systemInstruction'] = restSystemInstruction;
+  }
+
   if (sdkTools) restPayload['tools'] = sdkTools;
   if (sdkToolConfig) restPayload['toolConfig'] = sdkToolConfig;
   if (sdkSafetySettings) restPayload['safetySettings'] = sdkSafetySettings;
-  if (sdkCachedContent) restPayload['cachedContent'] = sdkCachedContent;
 
   return restPayload;
 }

packages/core/src/utils/nextSpeakerChecker.test.ts

@@ -92,6 +92,8 @@ describe('checkNextSpeaker', () => {
         generateContentStream: vi.fn(),
         countTokens: vi.fn(),
         embedContent: vi.fn(),
+        createCachedContent: vi.fn(),
+        updateCachedContent: vi.fn(),
       } as ContentGenerator,
       mockConfig,
     );