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

package/src/agents/AgentContext.ts

@@ -12,6 +12,8 @@ import type * as t from '@/types';
 import type { createPruneMessages } from '@/messages';
 import { createSchemaOnlyTools } from '@/tools/schema';
 import { ContentTypes, Providers } from '@/common';
+import { MAX_SYSTEM_CACHE_BLOCKS } from '@/types/agent-cache';
+import { isBedrockCacheSupported } from '@/llm/bedrock/cacheSupport';
 import { toJsonSchema } from '@/utils/schema';
 
 /**
@@ -37,7 +39,9 @@ export class AgentContext {
       toolEnd,
       toolRegistry,
       toolDefinitions,
+      system_cache_blocks,
       instructions,
+      instructions_cache_ttl,
       additional_instructions,
       streamBuffer,
       maxContextTokens,
@@ -85,7 +89,9 @@ export class AgentContext {
       toolMap,
       toolRegistry,
       toolDefinitions,
+      systemCacheBlocks: system_cache_blocks,
       instructions,
+      instructionsCacheTtl: instructions_cache_ttl,
       additionalInstructions: additional_instructions,
       reasoningKey,
       toolEnd,
@@ -101,6 +107,16 @@ export class AgentContext {
       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
@@ -173,9 +189,18 @@ export class AgentContext {
   toolDefinitions?: t.LCTool[];
   /** Set of tool names discovered via tool search (to be loaded) */
   discoveredToolNames: Set<string> = 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?: t.SystemCacheBlock[];
+  /** Stable/cacheable instructions for this agent (gets trailing marker). */
   instructions?: string;
-  /** Additional instructions for this agent */
+  /** TTL for the trailing instructions cache marker. Defaults to '5m'. */
+  instructionsCacheTtl?: t.AgentCacheTTL;
+  /** Dynamic system tail (per-user / per-message — never cached). */
   additionalInstructions?: string;
   /**
    * Dynamic context that changes per-request (e.g., current time, user info).
@@ -254,6 +279,12 @@ export class AgentContext {
   summarizationConfig?: t.SummarizationConfig;
   /** Lightweight file manifest for file-aware compaction (IDs and names only, no content) */
   fileManifest?: t.FileManifestEntry[];
+  /** Original AgentInputs used to create this context — used for self-spawn subagent resolution. */
+  _sourceInputs?: t.AgentInputs;
+  /** Subagent configurations for hierarchical delegation. */
+  subagentConfigs?: t.SubagentConfig[];
+  /** Maximum subagent nesting depth. */
+  maxSubagentDepth?: number;
 
   constructor({
     agentId,
@@ -268,7 +299,9 @@ export class AgentContext {
     toolMap,
     toolRegistry,
     toolDefinitions,
+    systemCacheBlocks,
     instructions,
+    instructionsCacheTtl,
     additionalInstructions,
     dynamicContext,
     reasoningKey,
@@ -294,7 +327,9 @@ export class AgentContext {
     toolMap?: t.ToolMap;
     toolRegistry?: t.LCToolRegistry;
     toolDefinitions?: t.LCTool[];
+    systemCacheBlocks?: t.SystemCacheBlock[];
     instructions?: string;
+    instructionsCacheTtl?: t.AgentCacheTTL;
     additionalInstructions?: string;
     dynamicContext?: string;
     reasoningKey?: 'reasoning_content' | 'reasoning';
@@ -322,7 +357,20 @@ export class AgentContext {
     this.toolMap = toolMap;
     this.toolRegistry = toolRegistry;
     this.toolDefinitions = toolDefinitions;
+    if (
+      systemCacheBlocks &&
+      systemCacheBlocks.length > MAX_SYSTEM_CACHE_BLOCKS
+    ) {
+      throw new Error(
+        `system_cache_blocks supports at most ${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;
@@ -557,8 +605,11 @@ export class AgentContext {
     }
 
     // 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;
   }
@@ -569,17 +620,27 @@ export class AgentContext {
    */
   initializeSystemRunnable(): void {
     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.)
    */
-  private buildInstructionsString(): string {
+  private buildStableInstructionsString(): string {
     const parts: string[] = [];
 
     /** Build agent identity and handoff context preamble */
@@ -593,7 +654,27 @@ export class AgentContext {
       parts.push(this.instructions);
     }
 
-    /** Add additional instructions */
+    /** Add programmatic tools documentation */
+    const programmaticToolsDoc = this.buildProgrammaticOnlyToolsInstructions();
+    if (programmaticToolsDoc) {
+      parts.push(programmaticToolsDoc);
+    }
+
+    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.
+   */
+  private buildDynamicInstructionsString(): string {
+    const parts: string[] = [];
+
     if (
       this.additionalInstructions != null &&
       this.additionalInstructions !== ''
@@ -601,12 +682,6 @@ export class AgentContext {
       parts.push(this.additionalInstructions);
     }
 
-    /** Add programmatic tools documentation */
-    const programmaticToolsDoc = this.buildProgrammaticOnlyToolsInstructions();
-    if (programmaticToolsDoc) {
-      parts.push(programmaticToolsDoc);
-    }
-
     return parts.join('\n\n');
   }
 
@@ -662,43 +737,168 @@ export class AgentContext {
   }
 
   /**
-   * 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.
+   */
+  private hasAnthropicPromptCache(): boolean {
+    if (this.provider !== Providers.ANTHROPIC) {
+      return false;
+    }
+    const anthropicOptions = this.clientOptions as
+      | t.AnthropicClientOptions
+      | undefined;
+    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).
+   */
+  private hasBedrockPromptCache(): boolean {
+    if (this.provider !== Providers.BEDROCK) {
+      return false;
+    }
+    const bedrockOptions = this.clientOptions as
+      | (t.BedrockAnthropicClientOptions & {
+          model?: string;
+          bedrockCacheModelPatterns?: readonly RegExp[];
+        })
+      | undefined;
+    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 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.
    */
-  private buildSystemRunnable(
-    instructionsString: string
-  ):
+  private buildSystemRunnable({
+    systemCacheBlocks,
+    stableInstructions,
+    dynamicInstructions,
+  }: {
+    systemCacheBlocks: t.SystemCacheBlock[];
+    stableInstructions: string;
+    dynamicInstructions: string;
+  }):
     | Runnable<
         BaseMessage[],
         (BaseMessage | SystemMessage)[],
         RunnableConfig<Record<string, unknown>>
       >
     | undefined {
-    if (!instructionsString) {
+    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: string | BaseMessageFields = instructionsString;
-
-    // Handle Anthropic prompt caching (Direct API)
-    if (this.provider === Providers.ANTHROPIC) {
-      const anthropicOptions = this.clientOptions as
-        | t.AnthropicClientOptions
-        | undefined;
-      if (anthropicOptions?.promptCache === true) {
-        finalInstructions = {
-          content: [
-            {
-              type: 'text',
-              text: instructionsString,
-              cache_control: { type: 'ephemeral' },
-            },
-          ],
-        };
+    const useAnthropicCache = this.hasAnthropicPromptCache();
+    const useBedrockCache = this.hasBedrockPromptCache();
+    const instructionsTtl: t.AgentCacheTTL = this.instructionsCacheTtl ?? '5m';
+
+    let finalInstructions: string | BaseMessageFields;
+    if (useAnthropicCache) {
+      type AnthropicTextBlock = {
+        type: 'text';
+        text: string;
+        cache_control?: { type: 'ephemeral'; ttl?: t.AgentCacheTTL };
+      };
+      const content: AnthropicTextBlock[] = [];
+      // 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 } as BaseMessageFields;
+    } else if (useBedrockCache && (hasAnyCacheBlocks || stableInstructions)) {
+      type BedrockBlock =
+        | { type: 'text'; text: string }
+        | { cachePoint: { type: 'default'; ttl?: t.AgentCacheTTL } };
+      const content: BedrockBlock[] = [];
+      // 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 } as unknown as BaseMessageFields;
+    } else {
+      finalInstructions = [
+        ...systemCacheBlocks.map((b) => b.text),
+        stableInstructions,
+        dynamicInstructions,
+      ]
+        .filter((part) => part !== '')
+        .join('\n\n');
     }
 
     const systemMessage = new SystemMessage(finalInstructions);
@@ -774,6 +974,49 @@ export class AgentContext {
     }
   }
 
+  /** 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. */
+  private getActiveToolDefinitions(): t.LCTool[] {
+    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).
+   */
+  private getEffectiveInstanceTools(): t.GraphTools | undefined {
+    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
@@ -791,9 +1034,17 @@ export class AgentContext {
     // 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 as Record<string, unknown>;
         if (
           genericTool.schema != null &&
@@ -822,25 +1073,27 @@ export 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 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 SystemMessage(JSON.stringify(schema))
+      );
+      this.toolsDetail.push({
+        name: def.name || 'unknown',
+        tokens: defTokens,
+      });
+      toolTokens += defTokens;
     }
 
     // Store total tool tokens for breakdown reporting
@@ -1011,10 +1264,7 @@ export class AgentContext {
     }
 
     /** 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];
@@ -1029,21 +1279,11 @@ export class AgentContext {
       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 = createSchemaOnlyTools(defsToInclude) as t.GraphTools;
+    /* Reuse `getActiveToolDefinitions()` so the binding gate matches the
+     * accounting filter exactly (single source of truth). */
+    const schemaTools = createSchemaOnlyTools(
+      this.getActiveToolDefinitions()
+    ) as t.GraphTools;
 
     const allTools = [...schemaTools];
 
@@ -1051,6 +1291,9 @@ export class AgentContext {
       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);
     }