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

package/README.md

@@ -398,6 +398,68 @@ Caching is **automatic** for Anthropic and Bedrock providers:
 }
 ```
 
+### Multi-block system caching (cross-tenant prefix sharing)
+
+For multi-agent platforms where a stable prefix is shared across many
+agents, use `system_cache_blocks` to emit additional cachePoint markers.
+A cacheable block placed BEFORE `instructions` is cached at provider
+level (Anthropic workspace, Bedrock account) and shared across every
+agent that emits the same byte-identical prefix:
+
+```typescript
+{
+  system_cache_blocks: [
+    { text: PLATFORM_WIDE_RULES, ttl: '5m' },  // shared across all agents
+  ],
+  instructions: agentSpecificInstructions,    // per-agent stable
+  additional_instructions: perRequestContext, // never cached
+}
+```
+
+This produces (Bedrock):
+
+```
+[PLATFORM_WIDE_RULES]
+[cachePoint: 5m]                  ← cross-agent share point
+[agentSpecificInstructions]
+[cachePoint: 5m]                  ← per-agent cache
+[perRequestContext]               ← uncached
+```
+
+Capped at `MAX_SYSTEM_CACHE_BLOCKS` (2 entries) to stay within Bedrock's
+4-cachePoint per-request budget. See
+[`docs/prompt-cache-architecture.md`](docs/prompt-cache-architecture.md)
+for the full architecture.
+
+### Tool array cachePoint strategies (Bedrock)
+
+```typescript
+new IllumaBedrockConverse({
+  promptCache: true,
+  toolCacheStrategy: 'split',  // 'single' (default) | 'split' | 'none'
+  toolGroupSelector: (toolName) =>
+    toolName.includes('_mcp_') ? 'mcp' : 'core',
+});
+```
+
+- `'single'`: one cachePoint at the end of the tools array (default)
+- `'split'`: separate cachePoints per group (use when groups have
+  different volatility)
+- `'none'`: no cachePoint on tools
+
+### Extending the Bedrock model allowlist
+
+```typescript
+new IllumaBedrockConverse({
+  model: 'mycorp.future-model-v1:0',
+  promptCache: true,
+  bedrockCacheModelPatterns: [/^mycorp\.future-/i],
+});
+```
+
+Useful when AWS adds a new cache-supporting model family before the
+library's allowlist updates.
+
 ---
 
 ## Structured Output Modes

package/dist/cjs/agents/AgentContext.cjs

@@ -5,6 +5,8 @@ var runnables = require('@langchain/core/runnables');
 var schema$1 = require('../tools/schema.cjs');
 var _enum = require('../common/enum.cjs');
 require('../tools/approval/constants.cjs');
+var agentCache = require('../types/agent-cache.cjs');
+var cacheSupport = require('../llm/bedrock/cacheSupport.cjs');
 var schema = require('../utils/schema.cjs');
 
 /* eslint-disable no-console */
@@ -17,7 +19,7 @@ class AgentContext {
      * Create an AgentContext from configuration with token accounting initialization
      */
     static fromConfig(agentConfig, tokenCounter, indexTokenCountMap) {
-        const { agentId, name, description, provider, clientOptions, tools, toolMap, toolEnd, toolRegistry, toolDefinitions, instructions, additional_instructions, streamBuffer, maxContextTokens, reasoningKey, useLegacyContent, dynamicContext, structuredOutput: structuredOutputCamel, structured_output: structuredOutputSnake, discoveredTools, summarizeCallback, persistedSummary, summarizationConfig, fileManifest, } = agentConfig;
+        const { agentId, name, description, provider, clientOptions, tools, toolMap, toolEnd, toolRegistry, toolDefinitions, system_cache_blocks, instructions, instructions_cache_ttl, additional_instructions, streamBuffer, maxContextTokens, reasoningKey, useLegacyContent, dynamicContext, structuredOutput: structuredOutputCamel, structured_output: structuredOutputSnake, discoveredTools, summarizeCallback, persistedSummary, summarizationConfig, fileManifest, } = agentConfig;
         // Normalize structured output: support both camelCase and snake_case inputs
         // Priority: structuredOutput (camelCase) > structured_output (snake_case with enabled check)
         let structuredOutput;
@@ -47,7 +49,9 @@ class AgentContext {
             toolMap,
             toolRegistry,
             toolDefinitions,
+            systemCacheBlocks: system_cache_blocks,
             instructions,
+            instructionsCacheTtl: instructions_cache_ttl,
             additionalInstructions: additional_instructions,
             reasoningKey,
             toolEnd,
@@ -62,6 +66,15 @@ class AgentContext {
             summarizationConfig,
             fileManifest,
         });
+        /**
+         * Track upstream-aligned subagent inputs on the context. `_sourceInputs`
+         * preserves the original AgentInputs so SubagentExecutor can self-spawn
+         * (`SubagentConfig.self === true`) without separate config; the other
+         * two flow straight from agentConfig.
+         */
+        agentContext._sourceInputs = agentConfig;
+        agentContext.subagentConfigs = agentConfig.subagentConfigs;
+        agentContext.maxSubagentDepth = agentConfig.maxSubagentDepth;
         if (tokenCounter) {
             // Initialize system runnable BEFORE async tool token calculation
             // This ensures system message tokens are in instructionTokens before
@@ -132,9 +145,18 @@ class AgentContext {
     toolDefinitions;
     /** Set of tool names discovered via tool search (to be loaded) */
     discoveredToolNames = new Set();
-    /** Instructions for this agent */
+    /**
+     * Cacheable system content blocks emitted before `instructions`. Each
+     * gets its own cache marker (cachePoint on Bedrock, cache_control on
+     * Anthropic). Earlier entries = wider cache key (best for cross-tenant
+     * sharing). See `src/types/agent-cache.ts`.
+     */
+    systemCacheBlocks;
+    /** Stable/cacheable instructions for this agent (gets trailing marker). */
     instructions;
-    /** Additional instructions for this agent */
+    /** TTL for the trailing instructions cache marker. Defaults to '5m'. */
+    instructionsCacheTtl;
+    /** Dynamic system tail (per-user / per-message — never cached). */
     additionalInstructions;
     /**
      * Dynamic context that changes per-request (e.g., current time, user info).
@@ -196,7 +218,13 @@ class AgentContext {
     summarizationConfig;
     /** Lightweight file manifest for file-aware compaction (IDs and names only, no content) */
     fileManifest;
-    constructor({ agentId, name, description, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, toolDefinitions, instructions, additionalInstructions, dynamicContext, reasoningKey, toolEnd, instructionTokens, useLegacyContent, structuredOutput, discoveredTools, summarizeCallback, persistedSummary, summarizationConfig, fileManifest, }) {
+    /** Original AgentInputs used to create this context — used for self-spawn subagent resolution. */
+    _sourceInputs;
+    /** Subagent configurations for hierarchical delegation. */
+    subagentConfigs;
+    /** Maximum subagent nesting depth. */
+    maxSubagentDepth;
+    constructor({ agentId, name, description, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, toolDefinitions, systemCacheBlocks, instructions, instructionsCacheTtl, additionalInstructions, dynamicContext, reasoningKey, toolEnd, instructionTokens, useLegacyContent, structuredOutput, discoveredTools, summarizeCallback, persistedSummary, summarizationConfig, fileManifest, }) {
         this.agentId = agentId;
         this.name = name;
         this.description = description;
@@ -209,7 +237,16 @@ class AgentContext {
         this.toolMap = toolMap;
         this.toolRegistry = toolRegistry;
         this.toolDefinitions = toolDefinitions;
+        if (systemCacheBlocks &&
+            systemCacheBlocks.length > agentCache.MAX_SYSTEM_CACHE_BLOCKS) {
+            throw new Error(`system_cache_blocks supports at most ${agentCache.MAX_SYSTEM_CACHE_BLOCKS} entries ` +
+                `(received ${systemCacheBlocks.length}); excess entries would exceed ` +
+                `Bedrock's 4-cachePoint per-request budget once the tools array and ` +
+                `trailing 'instructions' marker are counted. See src/types/agent-cache.ts.`);
+        }
+        this.systemCacheBlocks = systemCacheBlocks;
         this.instructions = instructions;
+        this.instructionsCacheTtl = instructionsCacheTtl;
         this.additionalInstructions = additionalInstructions;
         this.dynamicContext = dynamicContext;
         this.structuredOutput = structuredOutput;
@@ -400,8 +437,11 @@ class AgentContext {
             return this.cachedSystemRunnable;
         }
         // Stale or first access - rebuild
-        const instructionsString = this.buildInstructionsString();
-        this.cachedSystemRunnable = this.buildSystemRunnable(instructionsString);
+        this.cachedSystemRunnable = this.buildSystemRunnable({
+            systemCacheBlocks: this.systemCacheBlocks ?? [],
+            stableInstructions: this.buildStableInstructionsString(),
+            dynamicInstructions: this.buildDynamicInstructionsString(),
+        });
         this.systemRunnableStale = false;
         return this.cachedSystemRunnable;
     }
@@ -411,16 +451,26 @@ class AgentContext {
      */
     initializeSystemRunnable() {
         if (this.systemRunnableStale || this.cachedSystemRunnable === undefined) {
-            const instructionsString = this.buildInstructionsString();
-            this.cachedSystemRunnable = this.buildSystemRunnable(instructionsString);
+            this.cachedSystemRunnable = this.buildSystemRunnable({
+                systemCacheBlocks: this.systemCacheBlocks ?? [],
+                stableInstructions: this.buildStableInstructionsString(),
+                dynamicInstructions: this.buildDynamicInstructionsString(),
+            });
             this.systemRunnableStale = false;
         }
     }
     /**
-     * Builds the raw instructions string (without creating SystemMessage).
-     * Includes agent identity preamble and handoff context when available.
+     * Builds the cacheable instructions string (without creating SystemMessage).
+     * Includes agent identity preamble, the agent's static instructions, and
+     * programmatic-only tool documentation. This is the part of the system
+     * message that stays byte-stable across turns and across users for the
+     * same agent — the prompt cache prefix.
+     *
+     * Per-user/per-message dynamic context belongs in
+     * `buildDynamicInstructionsString()` so it does not invalidate the cache
+     * marker. (See `feedback_cache_stability_invariant` for the rule.)
      */
-    buildInstructionsString() {
+    buildStableInstructionsString() {
         const parts = [];
         /** Build agent identity and handoff context preamble */
         const identityPreamble = this.buildIdentityPreamble();
@@ -431,11 +481,6 @@ class AgentContext {
         if (this.instructions != null && this.instructions !== '') {
             parts.push(this.instructions);
         }
-        /** Add additional instructions */
-        if (this.additionalInstructions != null &&
-            this.additionalInstructions !== '') {
-            parts.push(this.additionalInstructions);
-        }
         /** Add programmatic tools documentation */
         const programmaticToolsDoc = this.buildProgrammaticOnlyToolsInstructions();
         if (programmaticToolsDoc) {
@@ -443,6 +488,23 @@ class AgentContext {
         }
         return parts.join('\n\n');
     }
+    /**
+     * Builds the dynamic system-tail string (without creating SystemMessage).
+     * Keep this out of prompt-cache-marked content so volatile per-call
+     * context does not invalidate the stable prefix.
+     *
+     * `additional_instructions` is treated as dynamic (per-user/per-message
+     * memory, runtime context, etc.) and intentionally excluded from the
+     * cacheable prefix.
+     */
+    buildDynamicInstructionsString() {
+        const parts = [];
+        if (this.additionalInstructions != null &&
+            this.additionalInstructions !== '') {
+            parts.push(this.additionalInstructions);
+        }
+        return parts.join('\n\n');
+    }
     /**
      * Builds the agent identity preamble including handoff context if present.
      * This helps the agent understand its role in the multi-agent workflow.
@@ -480,31 +542,136 @@ class AgentContext {
         return lines.join('\n');
     }
     /**
-     * Build system runnable from pre-built instructions string.
-     * Only called when content has actually changed.
+     * True when Anthropic prompt caching is enabled for this agent.
+     * Used by `buildSystemRunnable` to decide whether to emit a cache_control
+     * marker on the stable instructions prefix.
      */
-    buildSystemRunnable(instructionsString) {
-        if (!instructionsString) {
+    hasAnthropicPromptCache() {
+        if (this.provider !== _enum.Providers.ANTHROPIC) {
+            return false;
+        }
+        const anthropicOptions = this.clientOptions;
+        return anthropicOptions?.promptCache === true;
+    }
+    /**
+     * True when Bedrock prompt caching is enabled for this agent AND the
+     * configured model supports `cachePoint` blocks. Only Claude (and Nova)
+     * models on Bedrock honour cachePoint — Llama / Titan reject it.
+     *
+     * Used by `buildSystemRunnable` to inline a `cachePoint` block right
+     * after the stable system text so the system prefix is cached at the
+     * AWS account level (cross-user, cross-conversation).
+     */
+    hasBedrockPromptCache() {
+        if (this.provider !== _enum.Providers.BEDROCK) {
+            return false;
+        }
+        const bedrockOptions = this.clientOptions;
+        if (bedrockOptions?.promptCache !== true) {
+            return false;
+        }
+        /* Allowlist-based check (see src/llm/bedrock/cacheSupport.ts). The
+         * `bedrockCacheModelPatterns` clientOption lets consumers add new
+         * model patterns without forking the library — useful when AWS adds
+         * a new family before the next library release. */
+        return cacheSupport.isBedrockCacheSupported(bedrockOptions.model, bedrockOptions.bedrockCacheModelPatterns);
+    }
+    /**
+     * Build system runnable from cacheable blocks + the trailing
+     * `instructions` block + optional dynamic tail.
+     *
+     *   ┌──────────────────────────────────────────┐
+     *   │ system_cache_blocks[0].text              │ ← consumer-defined block 0
+     *   ├──── cache marker (TTL = blocks[0].ttl) ──┤
+     *   │ system_cache_blocks[1].text              │ ← consumer-defined block 1
+     *   ├──── cache marker (TTL = blocks[1].ttl) ──┤
+     *   │ instructions                             │ ← per-agent stable
+     *   ├──── cache marker (TTL = instructionsCacheTtl) ┤
+     *   │ additional_instructions                  │ ← dynamic (uncached)
+     *   └──────────────────────────────────────────┘
+     *
+     * If `system_cache_blocks` is empty, behavior reduces to the 2-tier
+     * (instructions + dynamic) path used by simpler consumers.
+     *
+     * Provider-specific cache marker:
+     *   - Anthropic: `cache_control: { type: 'ephemeral', ttl?: '1h'|'5m' }` on
+     *     each cacheable text block. Up to 4 cache breakpoints per workspace.
+     *   - Bedrock (Claude/Nova): a `{ cachePoint: { type: 'default', ttl?: '1h'|'5m' } }`
+     *     block inserted after each cacheable section. Up to 4 cachePoints per
+     *     request, of which the tools array can consume up to 2.
+     *
+     * Cache key composition: every byte from message start to a given cache
+     * marker forms that marker's cache key. Earlier blocks = wider cache key
+     * = more cross-tenant share. Place the most stable content first.
+     */
+    buildSystemRunnable({ systemCacheBlocks, stableInstructions, dynamicInstructions, }) {
+        const hasAnyCacheBlocks = systemCacheBlocks.length > 0;
+        if (!hasAnyCacheBlocks && !stableInstructions && !dynamicInstructions) {
             // Remove previous tokens if we had a system message before
             this.instructionTokens -= this.systemMessageTokens;
             this.systemMessageTokens = 0;
             return undefined;
         }
-        let finalInstructions = instructionsString;
-        // Handle Anthropic prompt caching (Direct API)
-        if (this.provider === _enum.Providers.ANTHROPIC) {
-            const anthropicOptions = this.clientOptions;
-            if (anthropicOptions?.promptCache === true) {
-                finalInstructions = {
-                    content: [
-                        {
-                            type: 'text',
-                            text: instructionsString,
-                            cache_control: { type: 'ephemeral' },
-                        },
-                    ],
-                };
+        const useAnthropicCache = this.hasAnthropicPromptCache();
+        const useBedrockCache = this.hasBedrockPromptCache();
+        const instructionsTtl = this.instructionsCacheTtl ?? '5m';
+        let finalInstructions;
+        if (useAnthropicCache) {
+            const content = [];
+            // Emit each system_cache_blocks entry with its own cache_control.
+            for (const block of systemCacheBlocks) {
+                if (!block.text)
+                    continue;
+                content.push({
+                    type: 'text',
+                    text: block.text,
+                    cache_control: { type: 'ephemeral', ttl: block.ttl ?? '5m' },
+                });
+            }
+            // Trailing stable instructions block (also cacheable).
+            if (stableInstructions) {
+                content.push({
+                    type: 'text',
+                    text: stableInstructions,
+                    cache_control: { type: 'ephemeral', ttl: instructionsTtl },
+                });
+            }
+            if (dynamicInstructions) {
+                // Dynamic tail: NO cache_control so it doesn't shift the cache prefix.
+                content.push({ type: 'text', text: dynamicInstructions });
             }
+            finalInstructions = { content };
+        }
+        else if (useBedrockCache && (hasAnyCacheBlocks || stableInstructions)) {
+            const content = [];
+            // Emit each system_cache_blocks entry as text + cachePoint pair.
+            for (const block of systemCacheBlocks) {
+                if (!block.text)
+                    continue;
+                content.push({ type: 'text', text: block.text });
+                content.push({
+                    cachePoint: { type: 'default', ttl: block.ttl ?? '5m' },
+                });
+            }
+            if (stableInstructions) {
+                content.push({ type: 'text', text: stableInstructions });
+                content.push({
+                    cachePoint: { type: 'default', ttl: instructionsTtl },
+                });
+            }
+            if (dynamicInstructions) {
+                content.push({ type: 'text', text: dynamicInstructions });
+            }
+            finalInstructions = { content };
+        }
+        else {
+            finalInstructions = [
+                ...systemCacheBlocks.map((b) => b.text),
+                stableInstructions,
+                dynamicInstructions,
+            ]
+                .filter((part) => part !== '')
+                .join('\n\n');
         }
         const systemMessage = new messages.SystemMessage(finalInstructions);
         // Update token counts (subtract old, add new)
@@ -573,6 +740,45 @@ class AgentContext {
             this.indexTokenCountMap = { ...baseTokenMap };
         }
     }
+    /** Active tool definitions for token accounting (excludes deferred-and-undiscovered entries
+     * and definitions whose `allowed_callers` exclude `'direct'`). Mirrors the gate
+     * `getEventDrivenToolsForBinding` applies so accounting and binding stay aligned. */
+    getActiveToolDefinitions() {
+        if (!this.toolDefinitions) {
+            return [];
+        }
+        return this.toolDefinitions.filter((def) => {
+            const allowedCallers = def.allowed_callers ?? ['direct'];
+            if (!allowedCallers.includes('direct')) {
+                return false;
+            }
+            return (def.defer_loading !== true || this.discoveredToolNames.has(def.name));
+        });
+    }
+    /**
+     * Single source of truth for "which entries of `this.tools` should be
+     * treated as actually bound". Callers:
+     *   - `getToolsForBinding` (non-event-driven branch)
+     *   - `getEventDrivenToolsForBinding` (appends instance tools alongside
+     *     schema-only definitions)
+     *   - `calculateInstructionTokens` (counts schema bytes for accounting)
+     *
+     * In event-driven mode (`toolDefinitions` present) instance tools are
+     * appended unfiltered; outside event-driven mode they pass through
+     * `filterToolsForBinding`. Centralizing the decision here prevents the
+     * accounting/binding paths from drifting apart, which was the root
+     * cause of the original miscount (Fixes upstream #121).
+     */
+    getEffectiveInstanceTools() {
+        if (!this.tools) {
+            return undefined;
+        }
+        const isEventDriven = (this.toolDefinitions?.length ?? 0) > 0;
+        if (isEventDriven || !this.toolRegistry) {
+            return this.tools;
+        }
+        return this.filterToolsForBinding(this.tools);
+    }
     /**
      * Calculate tool tokens and add to instruction tokens
      * Note: System message tokens are calculated during systemRunnable creation
@@ -586,9 +792,16 @@ class AgentContext {
         const countedToolNames = new Set();
         // Reset per-tool breakdown
         this.toolsDetail = [];
+        /* Use `getEffectiveInstanceTools()` so accounting reflects exactly the
+         * subset that `getToolsForBinding` would emit — preventing the
+         * worst-case-ceiling miscount that triggered spurious `empty_messages`
+         * preflight rejections at low `maxContextTokens`. Deferred and
+         * non-`'direct'` `toolDefinitions` are excluded by
+         * `getActiveToolDefinitions()` below. */
+        const effectiveInstanceTools = this.getEffectiveInstanceTools();
         // Count tokens for bound tools (StructuredTool instances with .schema)
-        if (this.tools && this.tools.length > 0) {
-            for (const tool of this.tools) {
+        if (effectiveInstanceTools && effectiveInstanceTools.length > 0) {
+            for (const tool of effectiveInstanceTools) {
                 const genericTool = tool;
                 if (genericTool.schema != null &&
                     typeof genericTool.schema === 'object') {
@@ -607,23 +820,25 @@ class AgentContext {
         // Count tokens for tool definitions (MCP / event-driven tools).
         // These are sent to the provider API as tool schemas alongside bound tools.
         // Both can be populated simultaneously (graph tools + MCP tools).
-        if (this.toolDefinitions && this.toolDefinitions.length > 0) {
-            for (const def of this.toolDefinitions) {
-                if (countedToolNames.has(def.name)) {
-                    continue; // Already counted via this.tools
-                }
-                const schema = {
-                    name: def.name,
-                    description: def.description ?? '',
-                    parameters: def.parameters ?? {},
-                };
-                const defTokens = tokenCounter(new messages.SystemMessage(JSON.stringify(schema)));
-                this.toolsDetail.push({
-                    name: def.name || 'unknown',
-                    tokens: defTokens,
-                });
-                toolTokens += defTokens;
+        // Use `getActiveToolDefinitions()` so programmatic-only definitions
+        // (e.g. `allowed_callers: ['code_execution']`) and deferred-and-
+        // -undiscovered ones don't inflate `toolSchemaTokens` while never
+        // being bound to the model.
+        for (const def of this.getActiveToolDefinitions()) {
+            if (countedToolNames.has(def.name)) {
+                continue; // Already counted via this.tools
             }
+            const schema = {
+                name: def.name,
+                description: def.description ?? '',
+                parameters: def.parameters ?? {},
+            };
+            const defTokens = tokenCounter(new messages.SystemMessage(JSON.stringify(schema)));
+            this.toolsDetail.push({
+                name: def.name || 'unknown',
+                tokens: defTokens,
+            });
+            toolTokens += defTokens;
         }
         // Store total tool tokens for breakdown reporting
         this.toolTokensTotal = toolTokens;
@@ -755,9 +970,7 @@ class AgentContext {
             return this.getEventDrivenToolsForBinding();
         }
         /** Traditional mode: filter actual tool instances */
-        const filtered = !this.tools || !this.toolRegistry
-            ? this.tools
-            : this.filterToolsForBinding(this.tools);
+        const filtered = this.getEffectiveInstanceTools();
         if (this.graphTools && this.graphTools.length > 0) {
             return [...(filtered ?? []), ...this.graphTools];
         }
@@ -768,22 +981,16 @@ class AgentContext {
         if (!this.toolDefinitions) {
             return this.graphTools ?? [];
         }
-        const defsToInclude = this.toolDefinitions.filter((def) => {
-            const allowedCallers = def.allowed_callers ?? ['direct'];
-            if (!allowedCallers.includes('direct')) {
-                return false;
-            }
-            if (def.defer_loading === true &&
-                !this.discoveredToolNames.has(def.name)) {
-                return false;
-            }
-            return true;
-        });
-        const schemaTools = schema$1.createSchemaOnlyTools(defsToInclude);
+        /* Reuse `getActiveToolDefinitions()` so the binding gate matches the
+         * accounting filter exactly (single source of truth). */
+        const schemaTools = schema$1.createSchemaOnlyTools(this.getActiveToolDefinitions());
         const allTools = [...schemaTools];
         if (this.graphTools && this.graphTools.length > 0) {
             allTools.push(...this.graphTools);
         }
+        /* In event-driven mode, instance tools are appended UNFILTERED (matching
+         * `getEffectiveInstanceTools()`'s event-driven branch). Deferred /
+         * non-direct logic is represented in `toolDefinitions`, not here. */
         if (this.tools && this.tools.length > 0) {
             allTools.push(...this.tools);
         }