@illuma-ai/agents 1.5.1 → 2.1.1

package/README.md

@@ -398,68 +398,6 @@ 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,8 +5,6 @@ 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 */
@@ -19,7 +17,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, 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;
+        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, system_cache_blocks, instructions_cache_ttl, } = agentConfig;
         // Normalize structured output: support both camelCase and snake_case inputs
         // Priority: structuredOutput (camelCase) > structured_output (snake_case with enabled check)
         let structuredOutput;
@@ -49,9 +47,7 @@ class AgentContext {
             toolMap,
             toolRegistry,
             toolDefinitions,
-            systemCacheBlocks: system_cache_blocks,
             instructions,
-            instructionsCacheTtl: instructions_cache_ttl,
             additionalInstructions: additional_instructions,
             reasoningKey,
             toolEnd,
@@ -65,9 +61,11 @@ class AgentContext {
             persistedSummary,
             summarizationConfig,
             fileManifest,
+            systemCacheBlocks: system_cache_blocks,
+            instructionsCacheTtl: instructions_cache_ttl,
         });
         /**
-         * Track subagent inputs on the context. `_sourceInputs`
+         * 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.
@@ -145,18 +143,9 @@ class AgentContext {
     toolDefinitions;
     /** Set of tool names discovered via tool search (to be loaded) */
     discoveredToolNames = new Set();
-    /**
-     * 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 for this agent */
     instructions;
-    /** TTL for the trailing instructions cache marker. Defaults to '5m'. */
-    instructionsCacheTtl;
-    /** Dynamic system tail (per-user / per-message — never cached). */
+    /** Additional instructions for this agent */
     additionalInstructions;
     /**
      * Dynamic context that changes per-request (e.g., current time, user info).
@@ -218,13 +207,22 @@ class AgentContext {
     summarizationConfig;
     /** Lightweight file manifest for file-aware compaction (IDs and names only, no content) */
     fileManifest;
+    /**
+     * Workspace-shared system-message tiers. When set, each entry becomes a
+     * separate text block in the SystemMessage with its own cachePoint /
+     * cache_control marker, BEFORE the per-agent `instructions` block.
+     * See {@link t.AgentInputs.system_cache_blocks} for full semantics.
+     */
+    systemCacheBlocks;
+    /** TTL hint for the per-agent instructions cache marker. Defaults to '5m'. */
+    instructionsCacheTtl;
     /** 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, }) {
+    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, systemCacheBlocks, instructionsCacheTtl, }) {
         this.agentId = agentId;
         this.name = name;
         this.description = description;
@@ -237,16 +235,7 @@ 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;
@@ -254,6 +243,12 @@ class AgentContext {
         this.persistedSummary = persistedSummary;
         this.summarizationConfig = summarizationConfig;
         this.fileManifest = fileManifest;
+        if (systemCacheBlocks && systemCacheBlocks.length > 0) {
+            this.systemCacheBlocks = systemCacheBlocks;
+        }
+        if (instructionsCacheTtl) {
+            this.instructionsCacheTtl = instructionsCacheTtl;
+        }
         if (reasoningKey) {
             this.reasoningKey = reasoningKey;
         }
@@ -437,11 +432,8 @@ class AgentContext {
             return this.cachedSystemRunnable;
         }
         // Stale or first access - rebuild
-        this.cachedSystemRunnable = this.buildSystemRunnable({
-            systemCacheBlocks: this.systemCacheBlocks ?? [],
-            stableInstructions: this.buildStableInstructionsString(),
-            dynamicInstructions: this.buildDynamicInstructionsString(),
-        });
+        const instructionsString = this.buildInstructionsString();
+        this.cachedSystemRunnable = this.buildSystemRunnable(instructionsString);
         this.systemRunnableStale = false;
         return this.cachedSystemRunnable;
     }
@@ -451,26 +443,16 @@ class AgentContext {
      */
     initializeSystemRunnable() {
         if (this.systemRunnableStale || this.cachedSystemRunnable === undefined) {
-            this.cachedSystemRunnable = this.buildSystemRunnable({
-                systemCacheBlocks: this.systemCacheBlocks ?? [],
-                stableInstructions: this.buildStableInstructionsString(),
-                dynamicInstructions: this.buildDynamicInstructionsString(),
-            });
+            const instructionsString = this.buildInstructionsString();
+            this.cachedSystemRunnable = this.buildSystemRunnable(instructionsString);
             this.systemRunnableStale = false;
         }
     }
     /**
-     * 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.)
+     * Builds the raw instructions string (without creating SystemMessage).
+     * Includes agent identity preamble and handoff context when available.
      */
-    buildStableInstructionsString() {
+    buildInstructionsString() {
         const parts = [];
         /** Build agent identity and handoff context preamble */
         const identityPreamble = this.buildIdentityPreamble();
@@ -481,6 +463,11 @@ 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) {
@@ -488,23 +475,6 @@ 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.
@@ -542,136 +512,107 @@ class AgentContext {
         return lines.join('\n');
     }
     /**
-     * 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.
+     * Build system runnable from pre-built instructions string.
+     * Only called when content has actually changed.
      */
-    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) {
+    buildSystemRunnable(instructionsString) {
+        if (!instructionsString) {
             // Remove previous tokens if we had a system message before
             this.instructionTokens -= this.systemMessageTokens;
             this.systemMessageTokens = 0;
             return undefined;
         }
-        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 });
+        let finalInstructions = instructionsString;
+        /**
+         * Tiered system-message assembly. When `systemCacheBlocks` is set, build
+         * a multi-block SystemMessage so each tier has its own cache breakpoint:
+         *
+         *   [tier1_block_1][tier1_cachePoint]...[tier1_block_N][tier1_cachePoint]
+         *   [instructions][instructions_cachePoint]
+         *
+         * Forward-prefix-hash means agents in the same workspace whose tier-1
+         * bytes are identical share the platform cache entry; only the per-agent
+         * `instructions` block invalidates per-agent.
+         *
+         * - Bedrock: emit `cachePoint: { type: 'default' }` blocks (handled by
+         *   `convertSystemMessageToConverseMessage`).
+         * - Anthropic: emit `cache_control: { type: 'ephemeral' }` on each text
+         *   block. (TTL hints are dropped for Anthropic — the SDK currently
+         *   only supports `'ephemeral'`. Bedrock cachePoint has no TTL knob.)
+         */
+        const hasTieredCache = Array.isArray(this.systemCacheBlocks) &&
+            this.systemCacheBlocks.length > 0;
+        const isBedrock = this.provider === _enum.Providers.BEDROCK;
+        const isAnthropic = this.provider === _enum.Providers.ANTHROPIC;
+        const anthropicCacheEnabled = isAnthropic &&
+            this.clientOptions
+                ?.promptCache === true;
+        /**
+         * Bedrock cachePoint is Claude-only — Nova/Llama/Titan reject it.
+         * Mirrors the model check in `IllumaBedrockConverse.invocationParams`
+         * (src/llm/bedrock/index.ts:186-189).
+         */
+        const bedrockCacheEnabled = isBedrock &&
+            (() => {
+                const opts = this.clientOptions;
+                const modelId = (opts?.model ?? '').toLowerCase();
+                const isClaudeModel = modelId.includes('claude') || modelId.includes('anthropic');
+                return opts?.promptCache === true && isClaudeModel;
+            })();
+        if (hasTieredCache && (bedrockCacheEnabled || anthropicCacheEnabled)) {
+            /**
+             * Anthropic / Bedrock cap cache breakpoints at 4 per request. The
+             * lib already emits one for tools and up to two for messages, so we
+             * have at most 1 left for the system block. We spend it on Tier 1
+             * (the workspace-shared bytes) — per-agent Tier 2 caching is still
+             * achieved implicitly via the tools breakpoint that follows, since
+             * cache lookups are forward-prefix-hash.
+             *
+             * Tier 1 may itself be emitted as multiple text blocks (one per
+             * `systemCacheBlocks` entry); only the LAST gets the cache marker,
+             * the rest are plain text inside the same cached prefix.
+             */
+            const contentBlocks = [];
+            const tier1Blocks = this.systemCacheBlocks.filter((b) => b?.text);
+            tier1Blocks.forEach((block, idx) => {
+                const isLast = idx === tier1Blocks.length - 1;
+                if (bedrockCacheEnabled) {
+                    contentBlocks.push({ type: 'text', text: block.text });
+                    if (isLast) {
+                        contentBlocks.push({ cachePoint: { type: 'default' } });
+                    }
+                }
+                else if (isLast) {
+                    contentBlocks.push({
+                        type: 'text',
+                        text: block.text,
+                        cache_control: { type: 'ephemeral' },
+                    });
+                }
+                else {
+                    contentBlocks.push({ type: 'text', text: block.text });
+                }
+            });
+            if (instructionsString) {
+                // No cache marker on the trailing per-agent block — tools'
+                // breakpoint covers it.
+                contentBlocks.push({ type: 'text', text: instructionsString });
             }
-            finalInstructions = { content };
+            finalInstructions = {
+                content: contentBlocks,
+            };
         }
-        else {
-            finalInstructions = [
-                ...systemCacheBlocks.map((b) => b.text),
-                stableInstructions,
-                dynamicInstructions,
-            ]
-                .filter((part) => part !== '')
-                .join('\n\n');
+        else if (anthropicCacheEnabled) {
+            // Legacy single-block Anthropic caching (preserved for back-compat).
+            finalInstructions = {
+                content: [
+                    {
+                        type: 'text',
+                        text: instructionsString,
+                        cache_control: { type: 'ephemeral' },
+                    },
+                ],
+            };
         }
         const systemMessage = new messages.SystemMessage(finalInstructions);
         // Update token counts (subtract old, add new)
@@ -740,45 +681,6 @@ 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 #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
@@ -792,16 +694,9 @@ 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 (effectiveInstanceTools && effectiveInstanceTools.length > 0) {
-            for (const tool of effectiveInstanceTools) {
+        if (this.tools && this.tools.length > 0) {
+            for (const tool of this.tools) {
                 const genericTool = tool;
                 if (genericTool.schema != null &&
                     typeof genericTool.schema === 'object') {
@@ -820,25 +715,23 @@ 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).
-        // 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
+        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;
             }
-            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;
@@ -970,7 +863,9 @@ class AgentContext {
             return this.getEventDrivenToolsForBinding();
         }
         /** Traditional mode: filter actual tool instances */
-        const filtered = this.getEffectiveInstanceTools();
+        const filtered = !this.tools || !this.toolRegistry
+            ? this.tools
+            : this.filterToolsForBinding(this.tools);
         if (this.graphTools && this.graphTools.length > 0) {
             return [...(filtered ?? []), ...this.graphTools];
         }
@@ -981,16 +876,22 @@ class AgentContext {
         if (!this.toolDefinitions) {
             return this.graphTools ?? [];
         }
-        /* Reuse `getActiveToolDefinitions()` so the binding gate matches the
-         * accounting filter exactly (single source of truth). */
-        const schemaTools = schema$1.createSchemaOnlyTools(this.getActiveToolDefinitions());
+        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);
         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);
         }