@illuma-ai/agents 1.4.0-alpha.5 → 1.5.0

package/src/agents/__tests__/AgentContext.cacheTtl.live.test.ts

@@ -0,0 +1,259 @@
+/* eslint-disable no-console */
+/**
+ * LIVE Bedrock cache TTL comparison: `5m` (default) vs `1h` (extended).
+ *
+ * Verifies:
+ *   1. Bedrock SDK accepts `cachePoint: { type: 'default', ttl: '1h' }`
+ *      against `us.anthropic.claude-sonnet-4-5-20250929-v1:0`.
+ *   2. Both TTLs create cache entries readable by subsequent calls.
+ *   3. The `cacheWriteInputTokens` charged on cold-write is the same
+ *      structurally — pricing differs by ~60% but the SDK reports the
+ *      same field.
+ *
+ * What this CAN'T verify in a unit-runner timeframe:
+ *   - That a 1h cache actually survives >5 min of idle (would require a
+ *     >5-min sleep). Marked as a manual long-soak test instead.
+ *
+ * Run:
+ *   BEDROCK_AWS_REGION=us-east-1 \
+ *     BEDROCK_AWS_ACCESS_KEY_ID=... BEDROCK_AWS_SECRET_ACCESS_KEY=... \
+ *     npx jest src/agents/__tests__/AgentContext.cacheTtl.live.test.ts
+ */
+
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import type { BaseMessage, AIMessage } from '@langchain/core/messages';
+import { IllumaBedrockConverse } from '@/llm/bedrock';
+
+const region =
+  process.env.BEDROCK_AWS_REGION ??
+  process.env.BEDROCK_AWS_DEFAULT_REGION ??
+  process.env.AWS_REGION ??
+  'us-east-1';
+const accessKeyId =
+  process.env.BEDROCK_AWS_ACCESS_KEY_ID ?? process.env.AWS_ACCESS_KEY_ID;
+const secretAccessKey =
+  process.env.BEDROCK_AWS_SECRET_ACCESS_KEY ??
+  process.env.AWS_SECRET_ACCESS_KEY;
+
+const haveBedrock =
+  accessKeyId !== undefined &&
+  accessKeyId !== '' &&
+  secretAccessKey !== undefined &&
+  secretAccessKey !== '';
+
+const describeFn = haveBedrock ? describe : describe.skip;
+
+/**
+ * Build a unique-per-test stable prefix so we get a true cold-write on
+ * the first call (not piggybacking on a cache populated by a prior test).
+ * 80 rules × ~30 tokens ≈ 2400 tokens — above Bedrock's 1024-token
+ * minimum cache write threshold.
+ */
+const buildUniquePrefix = (suiteId: string): string => {
+  const padding = Array.from({ length: 80 }, (_, i) =>
+    `Rule ${i + 1} (${suiteId}): respond concisely; cite assumptions; treat all users with respect; never fabricate facts; if uncertain, say so explicitly.`
+  ).join('\n');
+  return `You are a helpful assistant for suite ${suiteId}.\n\n${padding}`;
+};
+
+interface UsageReadout {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_input_tokens: number;
+  cache_write_input_tokens: number;
+}
+
+/**
+ * Build the system message manually with a chosen TTL, send it to
+ * Bedrock, and return the cache-related usage from response_metadata.
+ */
+async function callWithTtl({
+  stableInstructions,
+  ttl,
+  query,
+}: {
+  stableInstructions: string;
+  ttl: '5m' | '1h';
+  query: string;
+}): Promise<UsageReadout> {
+  /* Build the system content array with the chosen TTL on the cachePoint.
+   * This bypasses AgentContext.buildSystemRunnable so we can vary TTL
+   * per-call deterministically. The downstream Bedrock converter
+   * (src/llm/bedrock/utils/message_inputs.ts) passes cachePoint blocks
+   * through to the Converse API as-is. */
+  const systemMsg = new SystemMessage({
+    content: [
+      { type: 'text', text: stableInstructions },
+      { cachePoint: { type: 'default', ttl } } as unknown as Record<
+        string,
+        unknown
+      >,
+    ],
+  });
+
+  const messages: BaseMessage[] = [systemMsg, new HumanMessage(query)];
+
+  const llm = new IllumaBedrockConverse({
+    model: 'us.anthropic.claude-sonnet-4-5-20250929-v1:0',
+    region,
+    credentials: {
+      accessKeyId: accessKeyId as string,
+      secretAccessKey: secretAccessKey as string,
+    },
+    promptCache: true,
+    streaming: false,
+  });
+
+  const aiMessage = (await llm.invoke(messages)) as AIMessage;
+
+  type RespMeta = {
+    usage?: {
+      inputTokens?: number;
+      outputTokens?: number;
+      cacheReadInputTokens?: number;
+      cacheWriteInputTokens?: number;
+    };
+  };
+  const u = ((aiMessage.response_metadata ?? {}) as RespMeta).usage ?? {};
+
+  return {
+    input_tokens: u.inputTokens ?? 0,
+    output_tokens: u.outputTokens ?? 0,
+    cache_read_input_tokens: u.cacheReadInputTokens ?? 0,
+    cache_write_input_tokens: u.cacheWriteInputTokens ?? 0,
+  };
+}
+
+describeFn('LIVE: Bedrock cache TTL — 5m vs 1h', () => {
+  jest.setTimeout(120000);
+
+  test('5m TTL: Bedrock accepts and reports cache write/read cycle', async () => {
+    const stable = buildUniquePrefix('5m-test-' + Date.now());
+
+    const cold = await callWithTtl({
+      stableInstructions: stable,
+      ttl: '5m',
+      query: 'reply with the word OK',
+    });
+    const warm = await callWithTtl({
+      stableInstructions: stable,
+      ttl: '5m',
+      query: 'reply with the word YES',
+    });
+
+    console.log('5m cold:', cold);
+    console.log('5m warm:', warm);
+
+    /* Cold call must have written cache (or read it from a prior run with
+     * the same suiteId — unlikely given Date.now() in the suiteId). */
+    const coldDidWork =
+      cold.cache_write_input_tokens > 0 || cold.cache_read_input_tokens > 0;
+    expect(coldDidWork).toBe(true);
+
+    /* Warm call must read from cache. */
+    expect(warm.cache_read_input_tokens).toBeGreaterThan(0);
+  });
+
+  test('1h TTL: Bedrock accepts and reports cache write/read cycle', async () => {
+    const stable = buildUniquePrefix('1h-test-' + Date.now());
+
+    const cold = await callWithTtl({
+      stableInstructions: stable,
+      ttl: '1h',
+      query: 'reply with the word OK',
+    });
+    const warm = await callWithTtl({
+      stableInstructions: stable,
+      ttl: '1h',
+      query: 'reply with the word YES',
+    });
+
+    console.log('1h cold:', cold);
+    console.log('1h warm:', warm);
+
+    const coldDidWork =
+      cold.cache_write_input_tokens > 0 || cold.cache_read_input_tokens > 0;
+    expect(coldDidWork).toBe(true);
+
+    expect(warm.cache_read_input_tokens).toBeGreaterThan(0);
+
+    /* When 1h cache write actually happens (i.e. cold call), the write
+     * token count should match the prefix size — confirming the cachePoint
+     * block reached Bedrock with the correct TTL hint. */
+    if (cold.cache_write_input_tokens > 0) {
+      expect(cold.cache_write_input_tokens).toBeGreaterThan(2000);
+    }
+  });
+
+  test('1h cache survives across multiple read calls within window', async () => {
+    /* Fire 3 reads back-to-back against a 1h-cached prefix — all must
+     * hit the cache. (The point is not "1h vs 5m" here; it's "the 1h
+     * cache is functional and serving reads".) */
+    const stable = buildUniquePrefix('1h-multi-' + Date.now());
+
+    /* Prime */
+    await callWithTtl({
+      stableInstructions: stable,
+      ttl: '1h',
+      query: 'prime',
+    });
+
+    /* Three sequential reads */
+    const reads = await Promise.all([
+      callWithTtl({
+        stableInstructions: stable,
+        ttl: '1h',
+        query: 'one',
+      }),
+      callWithTtl({
+        stableInstructions: stable,
+        ttl: '1h',
+        query: 'two',
+      }),
+      callWithTtl({
+        stableInstructions: stable,
+        ttl: '1h',
+        query: 'three',
+      }),
+    ]);
+
+    reads.forEach((r, i) => {
+      console.log(
+        `1h read ${i + 1}: cache_read=${r.cache_read_input_tokens}, ` +
+          `write=${r.cache_write_input_tokens}, input=${r.input_tokens}`
+      );
+    });
+
+    expect(reads.every((r) => r.cache_read_input_tokens > 0)).toBe(true);
+  });
+
+  /* Skipped by default — uncomment to run a long-soak test that proves
+   * the 1h cache actually outlives the 5m default. Takes 6+ minutes. */
+  test.skip('1h cache survives a 6-minute idle (5m would expire)', async () => {
+    const stable = buildUniquePrefix('1h-soak-' + Date.now());
+
+    const cold = await callWithTtl({
+      stableInstructions: stable,
+      ttl: '1h',
+      query: 'cold',
+    });
+    console.log('1h soak cold:', cold);
+
+    /* Wait > 5 minutes (default Bedrock TTL). */
+    await new Promise((r) => setTimeout(r, 6 * 60 * 1000));
+
+    const afterIdle = await callWithTtl({
+      stableInstructions: stable,
+      ttl: '1h',
+      query: 'after idle',
+    });
+    console.log('1h soak after 6-min idle:', afterIdle);
+
+    /* If 1h TTL works, this must still read from cache. If only 5m
+     * worked, this would re-write. */
+    expect(afterIdle.cache_read_input_tokens).toBeGreaterThan(0);
+  });
+});

package/src/agents/__tests__/AgentContext.crossAgentTier1.live.test.ts

@@ -0,0 +1,264 @@
+/* eslint-disable no-console */
+/**
+ * LIVE Bedrock cross-AGENT Tier 1 cache sharing.
+ *
+ * What this proves: when two completely distinct custom agents share the
+ * same `platform_instructions` (Tier 1) but have totally different
+ * `agent.instructions` (Tier 2), Bedrock serves the Tier 1 prefix from a
+ * single cache entry. This is the load-bearing proof for the multi-tier
+ * cost optimization — every custom agent in a workspace can read the
+ * platform-level cache populated by any other agent (or by ephemeral
+ * traffic).
+ *
+ * What it does NOT prove (out of scope here):
+ *   - That ranger's actual `client.js` system block split is correct.
+ *     That's verified by Phase 3 ranger-side tests.
+ *
+ * Run:
+ *   BEDROCK_AWS_REGION=us-east-1 \
+ *     BEDROCK_AWS_ACCESS_KEY_ID=... BEDROCK_AWS_SECRET_ACCESS_KEY=... \
+ *     npx jest src/agents/__tests__/AgentContext.crossAgentTier1.live.test.ts
+ */
+
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage, AIMessage } from '@langchain/core/messages';
+import { IllumaBedrockConverse } from '@/llm/bedrock';
+import { addBedrockCacheControl } from '@/messages/cache';
+import { AgentContext } from '../AgentContext';
+import { Providers } from '@/common';
+import type * as t from '@/types';
+
+const region =
+  process.env.BEDROCK_AWS_REGION ??
+  process.env.BEDROCK_AWS_DEFAULT_REGION ??
+  process.env.AWS_REGION ??
+  'us-east-1';
+const accessKeyId =
+  process.env.BEDROCK_AWS_ACCESS_KEY_ID ?? process.env.AWS_ACCESS_KEY_ID;
+const secretAccessKey =
+  process.env.BEDROCK_AWS_SECRET_ACCESS_KEY ??
+  process.env.AWS_SECRET_ACCESS_KEY;
+
+const haveBedrock =
+  Boolean(accessKeyId) &&
+  Boolean(secretAccessKey) &&
+  accessKeyId !== '' &&
+  secretAccessKey !== '';
+
+const describeFn = haveBedrock ? describe : describe.skip;
+
+/**
+ * Tier 1 — platform-wide content. Same string for every "agent" in this
+ * test, mimicking ranger's branding + tool routing + common tool docs.
+ * Padded above 1024 tokens so Bedrock will write/read the cache (1024-token
+ * minimum cache write threshold).
+ */
+const PLATFORM_INSTRUCTIONS = (() => {
+  const header =
+    'You are part of a multi-agent platform. Always respond as the agent named in your specific instructions.';
+  const universalRules = Array.from(
+    { length: 60 },
+    (_, i) =>
+      `Universal Rule ${i + 1}: respond concisely; cite assumptions explicitly; treat all users with respect; never fabricate facts; if uncertain, say so explicitly. Use tools only when they add value. Maintain professional tone in all responses regardless of conversation history.`
+  ).join('\n');
+  const toolRouting =
+    'Tool Routing: prefer artifact_tool for documents, execute_code for analysis, web_search for current events. Never reveal underlying model identity.';
+  return `${header}\n\n${universalRules}\n\n${toolRouting}`;
+})();
+
+interface UsageReadout {
+  input_tokens: number;
+  output_tokens: number;
+  cache_read_input_tokens: number;
+  cache_write_input_tokens: number;
+  total_tokens: number;
+}
+
+/**
+ * Build an AgentContext for the given (custom-agent-style) configuration,
+ * extract its system message, and send a request to Bedrock. Returns the
+ * usage breakdown including cache hit/write metrics.
+ */
+async function callAgent({
+  agentId,
+  agentName,
+  platformInstructions,
+  agentInstructions,
+  query,
+}: {
+  agentId: string;
+  agentName: string;
+  platformInstructions: string;
+  agentInstructions: string;
+  query: string;
+}): Promise<UsageReadout> {
+  const ctx = AgentContext.fromConfig({
+    agentId,
+    name: agentName,
+    provider: Providers.BEDROCK,
+    system_cache_blocks: [{ text: platformInstructions }],
+    instructions: agentInstructions,
+    clientOptions: {
+      promptCache: true,
+      model: 'us.anthropic.claude-sonnet-4-5-20250929-v1:0',
+    } as t.BedrockAnthropicClientOptions,
+  });
+
+  const runnable = ctx.systemRunnable;
+  expect(runnable).toBeDefined();
+
+  const systemArr = (await runnable!.invoke([])) as BaseMessage[];
+  const userMessages: BaseMessage[] = [new HumanMessage(query)];
+  const allMessages = [...systemArr, ...userMessages];
+  const finalMessages = addBedrockCacheControl<BaseMessage>(allMessages);
+
+  /* Sanity: system message has at least 2 cachePoints (one per cacheable
+   * tier — platform + agent). */
+  const sysContent = finalMessages[0].content as Array<Record<string, unknown>>;
+  const cachePointCount = sysContent.filter((b) => 'cachePoint' in b).length;
+  expect(cachePointCount).toBeGreaterThanOrEqual(2);
+
+  const llm = new IllumaBedrockConverse({
+    model: 'us.anthropic.claude-sonnet-4-5-20250929-v1:0',
+    region,
+    credentials: {
+      accessKeyId: accessKeyId as string,
+      secretAccessKey: secretAccessKey as string,
+    },
+    promptCache: true,
+    streaming: false,
+  });
+
+  const aiMessage = (await llm.invoke(finalMessages)) as AIMessage;
+
+  type RespMeta = {
+    usage?: {
+      inputTokens?: number;
+      outputTokens?: number;
+      totalTokens?: number;
+      cacheReadInputTokens?: number;
+      cacheWriteInputTokens?: number;
+    };
+  };
+  const u = ((aiMessage.response_metadata ?? {}) as RespMeta).usage ?? {};
+
+  return {
+    input_tokens: u.inputTokens ?? 0,
+    output_tokens: u.outputTokens ?? 0,
+    total_tokens: u.totalTokens ?? 0,
+    cache_read_input_tokens: u.cacheReadInputTokens ?? 0,
+    cache_write_input_tokens: u.cacheWriteInputTokens ?? 0,
+  };
+}
+
+describeFn('LIVE: Bedrock cross-AGENT Tier 1 cache sharing', () => {
+  jest.setTimeout(180000);
+
+  test('two distinct custom agents share the Tier 1 platform cache', async () => {
+    /* Custom Agent A — completely different agent.instructions from B. */
+    const finance = await callAgent({
+      agentId: 'finance-helper',
+      agentName: 'Finance Helper',
+      platformInstructions: PLATFORM_INSTRUCTIONS,
+      agentInstructions:
+        'You are Finance Helper. Specialize in SAP, Bloomberg Terminal, and quarterly earnings analysis. Always cite source data with timestamps.',
+      query: 'one word: hi',
+    });
+
+    console.log('Finance Helper usage:', finance);
+
+    /* Custom Agent B — different name, different instructions, different
+     * domain. Same Tier 1 prefix. */
+    const hr = await callAgent({
+      agentId: 'hr-helper',
+      agentName: 'HR Helper',
+      platformInstructions: PLATFORM_INSTRUCTIONS,
+      agentInstructions:
+        'You are HR Helper. Specialize in Workday, Lever, and employee onboarding workflows. Maintain confidentiality at all times.',
+      query: 'one word: yes',
+    });
+
+    console.log('HR Helper usage:', hr);
+
+    /* CONTRACT 1: Both agents must show cache activity. The first
+     * (or whichever called first) writes the platform cache; the second
+     * reads it. Either pattern is acceptable on a fresh test run. */
+    const totalCacheActivity =
+      finance.cache_read_input_tokens +
+      finance.cache_write_input_tokens +
+      hr.cache_read_input_tokens +
+      hr.cache_write_input_tokens;
+    expect(totalCacheActivity).toBeGreaterThan(0);
+
+    /* CONTRACT 2 (the load-bearing one): HR Helper's cache_read includes
+     * the platform tier from Finance Helper's call. Even though they're
+     * different agents, the platform prefix is byte-identical so the
+     * cache key matches.
+     *
+     * If the ARCHITECTURE works:
+     *   - Finance: cache_write ≈ size(platform) + size(finance.instructions)
+     *   - HR: cache_read ≈ size(platform), cache_write ≈ size(hr.instructions)
+     *
+     * If the architecture is WRONG (e.g. cachePoint missing):
+     *   - HR: cache_read = 0
+     */
+    expect(hr.cache_read_input_tokens).toBeGreaterThan(0);
+  });
+
+  test('Three custom agents share the Tier 1 cache across cold starts', async () => {
+    /* Sequentially invoke 3 custom agents with the same platform tier.
+     * Each agent's Tier 2 (its own instructions) cold-writes once, but
+     * the platform tier writes only on the first agent — all three read
+     * the platform tier from cache. */
+    const agents = [
+      {
+        id: 'eng-helper',
+        name: 'Engineering Helper',
+        ins: 'You are Engineering Helper. Use Jira, GitHub, and Confluence.',
+      },
+      {
+        id: 'sales-helper',
+        name: 'Sales Helper',
+        ins: 'You are Sales Helper. Use Salesforce, Gong, and HubSpot.',
+      },
+      {
+        id: 'legal-helper',
+        name: 'Legal Helper',
+        ins: 'You are Legal Helper. Use DocuSign, Ironclad, and clause libraries.',
+      },
+    ];
+
+    const results: Array<{ agent: typeof agents[0]; usage: UsageReadout }> = [];
+    for (const a of agents) {
+      const usage = await callAgent({
+        agentId: a.id,
+        agentName: a.name,
+        platformInstructions: PLATFORM_INSTRUCTIONS,
+        agentInstructions: a.ins,
+        query: 'one word: ok',
+      });
+      results.push({ agent: a, usage });
+      console.log(
+        `${a.name}: cache_read=${usage.cache_read_input_tokens}, ` +
+          `cache_write=${usage.cache_write_input_tokens}, total=${usage.total_tokens}`
+      );
+    }
+
+    /* All three agents must show evidence of cache activity. */
+    results.forEach(({ usage }) => {
+      const activity =
+        usage.cache_read_input_tokens + usage.cache_write_input_tokens;
+      expect(activity).toBeGreaterThan(0);
+    });
+
+    /* At least 2 of the 3 should show a cache_read (assuming the first
+     * does the write). On a re-run all 3 read. */
+    const usersWithCacheRead = results.filter(
+      (r) => r.usage.cache_read_input_tokens > 0
+    ).length;
+    expect(usersWithCacheRead).toBeGreaterThanOrEqual(2);
+  });
+});