@illuma-ai/agents 1.5.0 → 2.1.1

package/dist/types/messages/format.d.ts

@@ -83,9 +83,6 @@ interface LangChainMessage {
  * @returns - The formatted LangChain message.
  */
 export declare const formatFromLangChain: (message: LangChainMessage) => Record<string, any>;
-interface FormatAgentMessagesOptions {
-    provider?: Providers;
-}
 /**
  * Groups content parts by agent and formats them with agent labels
  * This preprocesses multi-agent content to prevent identity confusion
@@ -113,7 +110,7 @@ export declare const labelContentByAgent: (contentParts: MessageContentComplex[]
  *   ToolMessage. Upstream PRs #96 / #97.
  * @returns - Object containing formatted messages and updated indexTokenCountMap if provided.
  */
-export declare const formatAgentMessages: (payload: TPayload, indexTokenCountMap?: Record<number, number | undefined>, tools?: Set<string>, skills?: Map<string, string>, options?: FormatAgentMessagesOptions) => {
+export declare const formatAgentMessages: (payload: TPayload, indexTokenCountMap?: Record<number, number | undefined>, tools?: Set<string>, skills?: Map<string, string>) => {
     messages: Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>;
     indexTokenCountMap?: Record<number, number>;
 };

package/dist/types/tools/CodeExecutor.d.ts

@@ -3,12 +3,6 @@ import type * as t from '@/types';
 import { Constants } from '@/common';
 export declare const imageExtRegex: RegExp;
 export declare const getCodeBaseURL: () => string;
-/**
- * Renders one section of the post-execution file listing. Used by the
- * code/bash tool formatters to keep generated outputs and inherited
- * inputs visually separated. See BashExecutor for full docs.
- */
-export declare function renderFileSection(header: string, files: t.FileRefs, defaultMessage: string): string;
 export declare const CodeExecutionToolSchema: {
     readonly type: "object";
     readonly properties: {

package/dist/types/tools/search/types.d.ts

@@ -2,8 +2,8 @@ import type { Logger as WinstonLogger } from 'winston';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseReranker } from './rerankers';
 import { DATE_RANGE } from './schema';
-export type SearchProvider = 'serper' | 'searxng' | 'tavily';
-export type ScraperProvider = 'firecrawl' | 'serper' | 'tavily';
+export type SearchProvider = 'serper' | 'searxng';
+export type ScraperProvider = 'firecrawl' | 'serper';
 export type RerankerType = 'infinity' | 'jina' | 'cohere' | 'none';
 export interface Highlight {
     score: number;
@@ -56,50 +56,11 @@ export interface Source {
     snippet?: string;
     date?: string;
 }
-export type TavilyTimeRange = 'day' | 'week' | 'month' | 'year';
-export type TavilyTimeRangeInput = TavilyTimeRange | 'h' | 'd' | 'w' | 'm' | 'y';
-export interface TavilySearchOptions {
-    searchDepth?: 'basic' | 'advanced' | 'fast' | 'ultra-fast';
-    maxResults?: number;
-    includeImages?: boolean;
-    includeAnswer?: boolean | 'basic' | 'advanced';
-    includeRawContent?: boolean | 'markdown' | 'text';
-    includeDomains?: string[];
-    excludeDomains?: string[];
-    topic?: 'general' | 'news' | 'finance';
-    timeRange?: TavilyTimeRangeInput;
-    includeImageDescriptions?: boolean;
-    includeFavicon?: boolean;
-    chunksPerSource?: number;
-    safeSearch?: boolean;
-    timeout?: number;
-}
-export interface TavilySearchPayload {
-    query: string;
-    search_depth: NonNullable<TavilySearchOptions['searchDepth']>;
-    topic: NonNullable<TavilySearchOptions['topic']>;
-    max_results: number;
-    safe_search?: boolean;
-    time_range?: TavilyTimeRange;
-    country?: string;
-    include_images?: boolean;
-    include_answer?: NonNullable<TavilySearchOptions['includeAnswer']>;
-    include_raw_content?: NonNullable<TavilySearchOptions['includeRawContent']>;
-    include_domains?: string[];
-    exclude_domains?: string[];
-    include_image_descriptions?: boolean;
-    include_favicon?: boolean;
-    chunks_per_source?: number;
-}
 export interface SearchConfig {
     searchProvider?: SearchProvider;
     serperApiKey?: string;
     searxngInstanceUrl?: string;
     searxngApiKey?: string;
-    tavilyApiKey?: string;
-    tavilySearchUrl?: string;
-    tavilyExtractUrl?: string;
-    tavilySearchOptions?: TavilySearchOptions;
     /** Domains to exclude from search results (e.g., 'reddit.com', 'twitter.com').
      *  Appended as -site: operators to the search query. */
     domainBlocklist?: string[];
@@ -140,16 +101,6 @@ export interface SerperScraperConfig {
     logger?: Logger;
     includeMarkdown?: boolean;
 }
-export interface TavilyScraperConfig {
-    apiKey?: string;
-    apiUrl?: string;
-    timeout?: number;
-    logger?: Logger;
-    extractDepth?: 'basic' | 'advanced';
-    includeImages?: boolean;
-    includeFavicon?: boolean;
-    format?: 'markdown' | 'text';
-}
 export interface ScraperContentResult {
     content: string;
 }
@@ -190,7 +141,6 @@ export interface CohereRerankerResponse {
 export type SafeSearchLevel = 0 | 1 | 2;
 export type Logger = WinstonLogger;
 export interface SearchToolConfig extends SearchConfig, ProcessSourcesConfig, FirecrawlConfig {
-    tavilyScraperOptions?: TavilyScraperConfig;
     logger?: Logger;
     safeSearch?: SafeSearchLevel;
     jinaApiKey?: string;
@@ -213,27 +163,15 @@ export type UsedReferences = {
     originalIndex: number;
     reference: MediaReference;
 }[];
-export type AnyScraperResponse = FirecrawlScrapeResponse | SerperScrapeResponse | TavilyScrapeResponse;
 /** Base Scraper Interface */
 export interface BaseScraper {
-    scrapeUrl(url: string, options?: unknown): Promise<[string, AnyScraperResponse]>;
-    scrapeUrls?(urls: string[], options?: unknown): Promise<Array<[string, AnyScraperResponse]>>;
-    extractContent(response: AnyScraperResponse): [string, undefined | References];
-    extractMetadata(response: AnyScraperResponse): ScrapeMetadata | GenericScrapeMetadata;
+    scrapeUrl(url: string, options?: unknown): Promise<[string, FirecrawlScrapeResponse | SerperScrapeResponse]>;
+    extractContent(response: FirecrawlScrapeResponse | SerperScrapeResponse): [string, undefined | References];
+    extractMetadata(response: FirecrawlScrapeResponse | SerperScrapeResponse): ScrapeMetadata | Record<string, string | number | boolean | null | undefined>;
 }
 /** Firecrawl */
 export type FirecrawlScrapeOptions = Omit<FirecrawlScraperConfig, 'apiKey' | 'apiUrl' | 'version' | 'logger'>;
 export type SerperScrapeOptions = Omit<SerperScraperConfig, 'apiKey' | 'apiUrl' | 'logger'>;
-export type TavilyScrapeOptions = Omit<TavilyScraperConfig, 'apiKey' | 'apiUrl' | 'logger'>;
-export interface TavilyExtractPayload {
-    urls: string[];
-    extract_depth: NonNullable<TavilyScraperConfig['extractDepth']>;
-    include_images: boolean;
-    include_favicon?: boolean;
-    format?: NonNullable<TavilyScraperConfig['format']>;
-    timeout?: number;
-}
-export type GenericScrapeMetadata = Record<string, string | number | boolean | null | undefined>;
 export interface ScrapeMetadata {
     sourceURL?: string;
     url?: string;
@@ -309,38 +247,6 @@ export interface SerperScrapeResponse {
     };
     error?: string;
 }
-export interface TavilyScrapeResponse {
-    success: boolean;
-    data?: {
-        rawContent?: string;
-        images?: string[];
-        favicon?: string;
-    };
-    error?: string;
-}
-export interface TavilySearchResult {
-    title?: string;
-    url?: string;
-    content?: string;
-    score?: number;
-    published_date?: string;
-}
-export type TavilyImageResult = string | {
-    url?: string;
-    description?: string;
-};
-export interface TavilySearchResponse {
-    answer?: string;
-    images?: TavilyImageResult[];
-    results?: TavilySearchResult[];
-}
-export interface TavilyExtractResult {
-    url: string;
-    raw_content?: string;
-    images?: string[];
-    favicon?: string;
-    error?: string;
-}
 export interface FirecrawlScraperConfig {
     apiKey?: string;
     apiUrl?: string;

package/dist/types/tools/search/utils.d.ts

@@ -6,5 +6,5 @@ import type * as t from './types';
  */
 export declare const createDefaultLogger: () => t.Logger;
 export declare const fileExtRegex: RegExp;
-export declare const getDomainName: (link: string, metadata?: t.ScrapeMetadata | t.GenericScrapeMetadata, logger?: t.Logger) => string | undefined;
-export declare function getAttribution(link: string, metadata?: t.ScrapeMetadata | t.GenericScrapeMetadata, logger?: t.Logger): string | undefined;
+export declare const getDomainName: (link: string, metadata?: t.ScrapeMetadata, logger?: t.Logger) => string | undefined;
+export declare function getAttribution(link: string, metadata?: t.ScrapeMetadata, logger?: t.Logger): string | undefined;

package/dist/types/tools/subagent/SubagentExecutor.d.ts

@@ -15,6 +15,35 @@ export type SubagentExecuteParams = {
      * without relying on event ordering heuristics.
      */
     parentToolCallId?: string;
+    /**
+     * Snapshot of the parent invocation's `config.configurable` at the
+     * spawn-tool call site. Inherited verbatim into the child workflow's
+     * `configurable` so host-set fields (`requestBody`, `user`,
+     * `userMCPAuthMap`, etc.) propagate — fixing MCP body-placeholder
+     * substitution and per-user lookups for subagent tool calls.
+     *
+     * Inheritance details (verified empirically against LangGraph):
+     *   - host-set keys propagate as-is into the child's tool dispatches;
+     *   - `thread_id` propagates (with `childRunId` as a fallback when
+     *     parent did not supply one) — matches the "subagent is part of
+     *     the same conversation" mental model and aligns with the
+     *     `sessionId: this.parentRunId` convention this executor already
+     *     uses for `SubagentStart` / `SubagentStop` hooks;
+     *   - `parent_run_id` propagates when the host put it on parent's
+     *     configurable;
+     *   - `run_id` is *overwritten by the LangGraph runtime* at child
+     *     invoke time regardless of what we forward — child's tool
+     *     dispatches see the child graph's runtime runId in
+     *     `configurable.run_id`, not the parent's. Hosts that need
+     *     parent-scoped run identity for downstream consumers should
+     *     plumb it via a host-defined key (e.g. `requestBody.messageId`),
+     *     not `run_id`.
+     *
+     * A future revision will likely make this inheritance configurable
+     * per spawn type — background / async subagents may want isolation
+     * rather than sharing parent's host context.
+     */
+    parentConfigurable?: Record<string, unknown>;
 };
 export type SubagentExecuteResult = {
     content: string;

package/dist/types/types/graph.d.ts

@@ -10,7 +10,6 @@ import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
 import type { RunStep, RunStepDeltaEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
 import type { TokenCounter } from '@/types/run';
-import type { SystemCacheBlock, AgentCacheTTL } from '@/types/agent-cache';
 /** Interface for bound model with stream and invoke methods */
 export interface ChatModel {
     stream?: (messages: BaseMessage[], config?: RunnableConfig) => Promise<AsyncIterable<AIMessageChunk>>;
@@ -568,36 +567,10 @@ export interface AgentInputs {
     toolMap?: ToolMap;
     tools?: GraphTools;
     provider: Providers;
-    /**
-     * Ordered list of cacheable system content blocks emitted BEFORE
-     * `instructions` in the system message. Each block gets its own cache
-     * marker (cachePoint on Bedrock, cache_control on Anthropic) so the
-     * cache key for each block includes only the bytes up to and including
-     * its own marker. Entries are emitted in array order — earlier =
-     * stabler = wider cache key (best for cross-tenant sharing).
-     *
-     * See `src/types/agent-cache.ts` for full semantics. Capped at
-     * `MAX_SYSTEM_CACHE_BLOCKS` (2) entries to stay within Bedrock's
-     * 4-cachePoint budget after the tools array consumes 2.
-     */
-    system_cache_blocks?: SystemCacheBlock[];
-    /**
-     * Stable/cacheable system instructions for this agent. Always emitted
-     * with its own trailing cache marker (when caching is supported by
-     * the provider/model). Use `instructions_cache_ttl` to override the
-     * default '5m' TTL.
-     */
     instructions?: string;
-    /** TTL for the trailing `instructions` cache marker. Defaults to '5m'. */
-    instructions_cache_ttl?: AgentCacheTTL;
     streamBuffer?: number;
     maxContextTokens?: number;
     clientOptions?: ClientOptions;
-    /**
-     * Dynamic system tail appended after the cacheable instructions
-     * without any cache marker. Per-user / per-message context belongs
-     * here so it does not invalidate the cacheable prefix.
-     */
     additional_instructions?: string;
     reasoningKey?: 'reasoning_content' | 'reasoning';
     /**
@@ -688,6 +661,30 @@ export interface AgentInputs {
      * @see SummarizationConfig
      */
     summarizationConfig?: SummarizationConfig;
+    /**
+     * Workspace-shared system-message tiers. Each entry becomes a separate
+     * text block in the SystemMessage with its own cachePoint / cache_control
+     * marker, allowing the platform-tier bytes (e.g. shared branding, tool
+     * routing rules, code-executor instructions) to be hashed independently
+     * from the per-agent `instructions` block. Hosts that don't use tiered
+     * caching can leave this undefined; behavior falls back to the legacy
+     * single SystemMessage.
+     *
+     * Anthropic / Bedrock prompt-cache lookups are forward-prefix-hash, so
+     * blocks are emitted in array order BEFORE `instructions`. Up to 4 blocks
+     * are supported (the LLM cap on cache breakpoints).
+     */
+    system_cache_blocks?: Array<{
+        text: string;
+        ttl?: '5m' | '1h';
+    }>;
+    /**
+     * TTL hint for the per-agent `instructions` block's cache marker.
+     * Defaults to '5m' (matching addCacheControl message-level behavior).
+     * Only consulted when `system_cache_blocks` is set; otherwise the
+     * legacy SystemMessage path is unchanged.
+     */
+    instructions_cache_ttl?: '5m' | '1h';
     /**
      * Lightweight file manifest for the conversation.
      * Contains file IDs, names, and metadata — NOT full content.

package/dist/types/types/index.d.ts

@@ -1,4 +1,3 @@
-export * from './agent-cache';
 export * from './graph';
 export * from './llm';
 export * from './messages';

package/dist/types/types/run.d.ts

@@ -62,9 +62,7 @@ export interface AgentStateChannels {
     messages: BaseMessage[];
     next: string;
     [key: string]: unknown;
-    /** Stable/cacheable system instructions for this agent. */
     instructions?: string;
-    /** Dynamic system tail appended after stable instructions. */
     additional_instructions?: string;
 }
 export interface Member {

package/dist/types/types/tools.d.ts

@@ -123,15 +123,6 @@ export type FileRef = {
     path?: string;
     /** Session ID this file belongs to (for multi-session file tracking) */
     session_id?: string;
-    /**
-     * `true` when the codeapi sandbox echoed this entry as an unchanged
-     * passthrough of an input the caller already owns (skill files,
-     * downloaded inputs whose hash matched the baseline, inherited
-     * `.dirkeep` markers). The tool-result formatter renders these as
-     * "Available files" rather than "Generated files" so the LLM doesn't
-     * conflate infrastructure inputs with newly-produced outputs.
-     */
-    inherited?: true;
 };
 export type FileRefs = FileRef[];
 export type ExecuteResult = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illuma-ai/agents",
-  "version": "1.5.0",
+  "version": "2.1.1",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -9,66 +9,6 @@
       "import": "./dist/esm/main.mjs",
       "require": "./dist/cjs/main.cjs",
       "types": "./dist/types/index.d.ts"
-    },
-    "./langchain": {
-      "import": "./dist/esm/langchain/index.mjs",
-      "require": "./dist/cjs/langchain/index.cjs",
-      "types": "./dist/types/langchain/index.d.ts"
-    },
-    "./langchain/language_models/chat_models": {
-      "import": "./dist/esm/langchain/language_models/chat_models.mjs",
-      "require": "./dist/cjs/langchain/language_models/chat_models.cjs",
-      "types": "./dist/types/langchain/language_models/chat_models.d.ts"
-    },
-    "./langchain/messages": {
-      "import": "./dist/esm/langchain/messages.mjs",
-      "require": "./dist/cjs/langchain/messages.cjs",
-      "types": "./dist/types/langchain/messages.d.ts"
-    },
-    "./langchain/messages/tool": {
-      "import": "./dist/esm/langchain/messages/tool.mjs",
-      "require": "./dist/cjs/langchain/messages/tool.cjs",
-      "types": "./dist/types/langchain/messages/tool.d.ts"
-    },
-    "./langchain/google-common": {
-      "import": "./dist/esm/langchain/google-common.mjs",
-      "require": "./dist/cjs/langchain/google-common.cjs",
-      "types": "./dist/types/langchain/google-common.d.ts"
-    },
-    "./langchain/openai": {
-      "import": "./dist/esm/langchain/openai.mjs",
-      "require": "./dist/cjs/langchain/openai.cjs",
-      "types": "./dist/types/langchain/openai.d.ts"
-    },
-    "./langchain/prompts": {
-      "import": "./dist/esm/langchain/prompts.mjs",
-      "require": "./dist/cjs/langchain/prompts.cjs",
-      "types": "./dist/types/langchain/prompts.d.ts"
-    },
-    "./langchain/runnables": {
-      "import": "./dist/esm/langchain/runnables.mjs",
-      "require": "./dist/cjs/langchain/runnables.cjs",
-      "types": "./dist/types/langchain/runnables.d.ts"
-    },
-    "./langchain/tools": {
-      "import": "./dist/esm/langchain/tools.mjs",
-      "require": "./dist/cjs/langchain/tools.cjs",
-      "types": "./dist/types/langchain/tools.d.ts"
-    },
-    "./langchain/utils/env": {
-      "import": "./dist/esm/langchain/utils/env.mjs",
-      "require": "./dist/cjs/langchain/utils/env.cjs",
-      "types": "./dist/types/langchain/utils/env.d.ts"
-    }
-  },
-  "typesVersions": {
-    "*": {
-      "langchain": [
-        "dist/types/langchain/index.d.ts"
-      ],
-      "langchain/*": [
-        "dist/types/langchain/*"
-      ]
     }
   },
   "type": "module",

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') },
+      ]);
+    });
+  });
 });