@illuma-ai/agents 1.5.1 → 2.1.1

package/src/agents/AgentContext.test.ts

@@ -455,4 +455,180 @@ describe('AgentContext', () => {
       expect(mockCallback).toHaveBeenCalledTimes(1);
     });
   });
+
+  describe('system_cache_blocks (tiered prompt cache)', () => {
+    /**
+     * `buildSystemRunnable` is private, so we exercise it via the public
+     * `initializeSystemRunnable` method and inspect the SystemMessage that
+     * gets prepended by the resulting runnable.
+     */
+    const extractSystemMessage = async (context: AgentContext) => {
+      context.initializeSystemRunnable();
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const runnable = (context as unknown as { cachedSystemRunnable: any })
+        .cachedSystemRunnable;
+      if (!runnable) return undefined;
+      const result = await runnable.invoke([]);
+      return result[0];
+    };
+
+    it('stores systemCacheBlocks and instructionsCacheTtl on context', () => {
+      const config: t.AgentInputs = {
+        agentId: 'tier-test',
+        provider: Providers.BEDROCK,
+        clientOptions: { model: 'anthropic.claude-3-5-sonnet-20241022-v2:0' },
+        instructions: 'agent specific',
+        system_cache_blocks: [
+          { text: 'platform tier text', ttl: '5m' },
+        ],
+        instructions_cache_ttl: '1h',
+      };
+      const context = AgentContext.fromConfig(config);
+      expect(context.systemCacheBlocks).toEqual([
+        { text: 'platform tier text', ttl: '5m' },
+      ]);
+      expect(context.instructionsCacheTtl).toBe('1h');
+    });
+
+    it('emits multi-block SystemMessage with single cachePoint after Tier 1 for Bedrock Claude', async () => {
+      const config: t.AgentInputs = {
+        agentId: 'bedrock-claude',
+        provider: Providers.BEDROCK,
+        clientOptions: {
+          model: 'anthropic.claude-3-5-sonnet-20241022-v2:0',
+          promptCache: true,
+        } as t.BedrockAnthropicClientOptions,
+        instructions: 'AGENT_TIER_2',
+        system_cache_blocks: [{ text: 'PLATFORM_TIER_1' }],
+      };
+      const context = AgentContext.fromConfig(config);
+      const systemMessage = await extractSystemMessage(context);
+      expect(systemMessage).toBeDefined();
+      const content = systemMessage?.content as Array<Record<string, unknown>>;
+      expect(Array.isArray(content)).toBe(true);
+      // Only the platform tier gets an explicit cachePoint; the trailing
+      // per-agent block is uncached at the system layer (tools breakpoint
+      // covers it via forward-prefix-hash).
+      expect(content).toEqual([
+        { type: 'text', text: 'PLATFORM_TIER_1' },
+        { cachePoint: { type: 'default' } },
+        { type: 'text', text: expect.stringContaining('AGENT_TIER_2') },
+      ]);
+    });
+
+    it('emits cache_control on Tier 1 text block only for Anthropic with promptCache=true', async () => {
+      const config: t.AgentInputs = {
+        agentId: 'anthropic-direct',
+        provider: Providers.ANTHROPIC,
+        clientOptions: {
+          model: 'claude-3-5-sonnet-20241022',
+          promptCache: true,
+        } as t.AnthropicClientOptions,
+        instructions: 'AGENT_TIER_2',
+        system_cache_blocks: [{ text: 'PLATFORM_TIER_1' }],
+      };
+      const context = AgentContext.fromConfig(config);
+      const systemMessage = await extractSystemMessage(context);
+      const content = systemMessage?.content as Array<Record<string, unknown>>;
+      expect(content).toEqual([
+        {
+          type: 'text',
+          text: 'PLATFORM_TIER_1',
+          cache_control: { type: 'ephemeral' },
+        },
+        {
+          type: 'text',
+          text: expect.stringContaining('AGENT_TIER_2'),
+        },
+      ]);
+    });
+
+    it('falls back to single string SystemMessage for Bedrock Nova (no cachePoint support)', async () => {
+      const config: t.AgentInputs = {
+        agentId: 'bedrock-nova',
+        provider: Providers.BEDROCK,
+        clientOptions: {
+          model: 'amazon.nova-pro-v1:0',
+          promptCache: true,
+        } as unknown as t.BedrockAnthropicClientOptions,
+        instructions: 'AGENT_TIER_2',
+        system_cache_blocks: [{ text: 'PLATFORM_TIER_1' }],
+      };
+      const context = AgentContext.fromConfig(config);
+      const systemMessage = await extractSystemMessage(context);
+      // Non-Claude Bedrock: tiered emission disabled, content stays string
+      expect(typeof systemMessage?.content).toBe('string');
+      expect(systemMessage?.content).toContain('AGENT_TIER_2');
+      // platform tier is NOT in the system message because the lib can't
+      // emit a cachePoint for it on Nova; ranger's quick-patch puts the
+      // bytes into `instructions` for Nova-style providers.
+      expect(systemMessage?.content).not.toContain('PLATFORM_TIER_1');
+    });
+
+    it('falls back to single string for Bedrock Claude when promptCache is false', async () => {
+      const config: t.AgentInputs = {
+        agentId: 'bedrock-claude-nopc',
+        provider: Providers.BEDROCK,
+        clientOptions: {
+          model: 'anthropic.claude-3-5-sonnet-20241022-v2:0',
+          promptCache: false,
+        } as t.BedrockAnthropicClientOptions,
+        instructions: 'AGENT_TIER_2',
+        system_cache_blocks: [{ text: 'PLATFORM_TIER_1' }],
+      };
+      const context = AgentContext.fromConfig(config);
+      const systemMessage = await extractSystemMessage(context);
+      expect(typeof systemMessage?.content).toBe('string');
+    });
+
+    it('preserves legacy single-block Anthropic caching when no system_cache_blocks set', async () => {
+      const config: t.AgentInputs = {
+        agentId: 'anthropic-legacy',
+        provider: Providers.ANTHROPIC,
+        clientOptions: {
+          model: 'claude-3-5-sonnet-20241022',
+          promptCache: true,
+        } as t.AnthropicClientOptions,
+        instructions: 'AGENT_INSTR',
+      };
+      const context = AgentContext.fromConfig(config);
+      const systemMessage = await extractSystemMessage(context);
+      const content = systemMessage?.content as Array<Record<string, unknown>>;
+      expect(content).toEqual([
+        {
+          type: 'text',
+          text: expect.stringContaining('AGENT_INSTR'),
+          cache_control: { type: 'ephemeral' },
+        },
+      ]);
+    });
+
+    it('emits multiple Tier 1 text blocks but only ONE cachePoint at the boundary', async () => {
+      const config: t.AgentInputs = {
+        agentId: 'multi-tier',
+        provider: Providers.BEDROCK,
+        clientOptions: {
+          model: 'anthropic.claude-3-5-sonnet-20241022-v2:0',
+          promptCache: true,
+        } as t.BedrockAnthropicClientOptions,
+        instructions: 'PER_AGENT',
+        system_cache_blocks: [
+          { text: 'TIER1_PLATFORM' },
+          { text: 'TIER1_CAPABILITIES' },
+        ],
+      };
+      const context = AgentContext.fromConfig(config);
+      const systemMessage = await extractSystemMessage(context);
+      const content = systemMessage?.content as Array<Record<string, unknown>>;
+      // Multiple Tier 1 entries collapse into the same cached prefix —
+      // only one cachePoint is emitted (at the Tier1→Tier2 boundary) so
+      // we don't blow the 4-breakpoint cap from Anthropic/Bedrock.
+      expect(content).toEqual([
+        { type: 'text', text: 'TIER1_PLATFORM' },
+        { type: 'text', text: 'TIER1_CAPABILITIES' },
+        { cachePoint: { type: 'default' } },
+        { type: 'text', text: expect.stringContaining('PER_AGENT') },
+      ]);
+    });
+  });
 });