@illuma-ai/agents 1.5.1 → 2.1.1

package/dist/types/types/agent-cache.d.ts

@@ -1,71 +0,0 @@
-/**
- * Agent system-message prompt-cache types.
- * ==========================================
- *
- * `@illuma-ai/agents` exposes a generic primitive — `system_cache_blocks` —
- * for composing a system message that gets explicit cache markers
- * (cachePoint on Bedrock, cache_control on Anthropic) at consumer-defined
- * boundaries. The library encodes each entry into the right wire format
- * for the active provider; consumers decide what content to put in each
- * block.
- *
- * Why this is generic rather than tier-named
- * ------------------------------------------------
- * Earlier iterations exposed `platform_instructions` and `cache_ttl:
- * { platform, agent }` — vocabulary borrowed from a specific consumer's
- * multi-tenant chat-platform mental model. That leaked one consumer's
- * domain into the library and made it confusing for other consumers
- * (CLI tools, desktop apps, gateways) which have no notion of
- * "platforms" or "agents".
- *
- * The current shape lets every consumer define their own cache-tier
- * organization without the library knowing or caring.
- *
- * Cache key composition
- * ---------------------
- * Both Anthropic and Bedrock hash the message bytes leading up to each
- * cache marker. So entry N's cache key is the concatenation of bytes
- * 0..N. Stable content (universal rules, framework docs) goes earlier;
- * volatile content (per-agent identity, per-tool docs) goes later. The
- * earlier entries get cross-tenant cache hits; the later entries get
- * narrower hits.
- *
- * Provider budget
- * ---------------
- * Bedrock's Converse API supports up to 4 cachePoint blocks per request.
- * The default tools-array cache strategy (see `IllumaBedrockConverse`)
- * uses up to 2 of those. So at most 2 entries should appear in
- * `system_cache_blocks` to leave budget for the trailing
- * `instructions` block. The library throws on more than 2.
- *
- * Anthropic supports up to 4 cache breakpoints per request workspace-wide;
- * the same constraint applies to keep tools + system within budget.
- */
-/** Provider TTL hint applied to a cachePoint / cache_control marker. */
-export type AgentCacheTTL = '5m' | '1h';
-/**
- * One cacheable system content block. Each entry produces a text block
- * followed by a provider-specific cache marker in the assembled system
- * message. Entries are emitted in array order — earlier = more stable
- * = wider cache key.
- */
-export interface SystemCacheBlock {
-    /**
-     * Text payload. Caller is responsible for keeping this byte-stable
-     * across requests that should share a cache entry. ANY change to
-     * these bytes invalidates every cache key that includes this entry.
-     */
-    text: string;
-    /**
-     * Optional TTL hint for the cache marker. Defaults to '5m' when
-     * omitted. '1h' costs more to write (2× base vs 1.25×) but survives
-     * longer idle, which is the right tradeoff for low-traffic blocks.
-     */
-    ttl?: AgentCacheTTL;
-}
-/**
- * Maximum number of `system_cache_blocks` entries the library accepts.
- * Higher than this would exceed Bedrock's 4-cachePoint budget once the
- * tools array and trailing `instructions` block are counted.
- */
-export declare const MAX_SYSTEM_CACHE_BLOCKS = 2;

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

@@ -1,259 +0,0 @@
-/* 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

@@ -1,266 +0,0 @@
-/* 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 a downstream consumer's actual system-block-assembly logic
- *     produces a byte-identical Tier 1. That's the consumer's
- *     responsibility (and its own 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 a multi-tenant platform's shared branding + tool-routing
- * + common-tool documentation block.
- * 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);
-  });
-});