@illuma-ai/agents 1.0.81

package/dist/esm/agents/AgentContext.mjs

@@ -0,0 +1,732 @@
+import { SystemMessage } from '@langchain/core/messages';
+import { RunnableLambda } from '@langchain/core/runnables';
+import { createSchemaOnlyTools } from '../tools/schema.mjs';
+import { ContentTypes, Providers } from '../common/enum.mjs';
+import { toJsonSchema } from '../utils/schema.mjs';
+
+/* eslint-disable no-console */
+// src/agents/AgentContext.ts
+/**
+ * Encapsulates agent-specific state that can vary between agents in a multi-agent system
+ */
+class AgentContext {
+    /**
+     * Create an AgentContext from configuration with token accounting initialization
+     */
+    static fromConfig(agentConfig, tokenCounter, indexTokenCountMap) {
+        const { agentId, name, provider, clientOptions, tools, toolMap, toolEnd, toolRegistry, toolDefinitions, instructions, additional_instructions, streamBuffer, maxContextTokens, reasoningKey, useLegacyContent, dynamicContext, structuredOutput: structuredOutputCamel, structured_output: structuredOutputSnake, discoveredTools, summarizeCallback, } = agentConfig;
+        // Normalize structured output: support both camelCase and snake_case inputs
+        // Priority: structuredOutput (camelCase) > structured_output (snake_case with enabled check)
+        let structuredOutput;
+        if (structuredOutputCamel) {
+            structuredOutput = structuredOutputCamel;
+        }
+        else if (structuredOutputSnake?.enabled && structuredOutputSnake.schema) {
+            // Convert snake_case input to StructuredOutputConfig
+            structuredOutput = {
+                schema: structuredOutputSnake.schema,
+                name: structuredOutputSnake.name,
+                description: structuredOutputSnake.description,
+                mode: structuredOutputSnake.mode,
+                strict: structuredOutputSnake.strict,
+            };
+        }
+        const agentContext = new AgentContext({
+            agentId,
+            name: name ?? agentId,
+            provider,
+            clientOptions,
+            maxContextTokens,
+            streamBuffer,
+            tools,
+            toolMap,
+            toolRegistry,
+            toolDefinitions,
+            instructions,
+            additionalInstructions: additional_instructions,
+            reasoningKey,
+            toolEnd,
+            instructionTokens: 0,
+            tokenCounter,
+            useLegacyContent,
+            dynamicContext,
+            structuredOutput,
+            discoveredTools,
+        });
+        if (summarizeCallback) {
+            agentContext.summarizeCallback = summarizeCallback;
+        }
+        if (tokenCounter) {
+            // Initialize system runnable BEFORE async tool token calculation
+            // This ensures system message tokens are in instructionTokens before
+            // updateTokenMapWithInstructions is called
+            agentContext.initializeSystemRunnable();
+            const tokenMap = indexTokenCountMap || {};
+            agentContext.indexTokenCountMap = tokenMap;
+            agentContext.tokenCalculationPromise = agentContext
+                .calculateInstructionTokens(tokenCounter)
+                .then(() => {
+                // Update token map with instruction tokens (includes system + tool tokens)
+                agentContext.updateTokenMapWithInstructions(tokenMap);
+            })
+                .catch((err) => {
+                console.error('Error calculating instruction tokens:', err);
+            });
+        }
+        else if (indexTokenCountMap) {
+            agentContext.indexTokenCountMap = indexTokenCountMap;
+        }
+        return agentContext;
+    }
+    /** Agent identifier */
+    agentId;
+    /** Human-readable name for this agent (used in handoff context). Falls back to agentId if not provided. */
+    name;
+    /** Provider for this specific agent */
+    provider;
+    /** Client options for this agent */
+    clientOptions;
+    /** Token count map indexed by message position */
+    indexTokenCountMap = {};
+    /** Maximum context tokens for this agent */
+    maxContextTokens;
+    /** Current usage metadata for this agent */
+    currentUsage;
+    /** Prune messages function configured for this agent */
+    pruneMessages;
+    /** Token counter function for this agent */
+    tokenCounter;
+    /** Instructions/system message token count */
+    instructionTokens = 0;
+    /** The amount of time that should pass before another consecutive API call */
+    streamBuffer;
+    /** Last stream call timestamp for rate limiting */
+    lastStreamCall;
+    /** Tools available to this agent */
+    tools;
+    /** Tool map for this agent */
+    toolMap;
+    /**
+     * Tool definitions registry (includes deferred and programmatic tool metadata).
+     * Used for tool search and programmatic tool calling.
+     */
+    toolRegistry;
+    /**
+     * Serializable tool definitions for event-driven execution.
+     * When provided, ToolNode operates in event-driven mode.
+     */
+    toolDefinitions;
+    /** Set of tool names discovered via tool search (to be loaded) */
+    discoveredToolNames = new Set();
+    /** Instructions for this agent */
+    instructions;
+    /** Additional instructions for this agent */
+    additionalInstructions;
+    /**
+     * Dynamic context that changes per-request (e.g., current time, user info).
+     * This is NOT included in the system message to preserve cache.
+     * Instead, it's injected as a user message at the start of the conversation.
+     */
+    dynamicContext;
+    /** Reasoning key for this agent */
+    reasoningKey = 'reasoning_content';
+    /** Last token for reasoning detection */
+    lastToken;
+    /** Token type switch state */
+    tokenTypeSwitch;
+    /** Current token type being processed */
+    currentTokenType = ContentTypes.TEXT;
+    /** Whether tools should end the workflow */
+    toolEnd = false;
+    /** Cached system runnable (created lazily) */
+    cachedSystemRunnable;
+    /** Whether system runnable needs rebuild (set when discovered tools change) */
+    systemRunnableStale = true;
+    /** Cached system message token count (separate from tool tokens) */
+    systemMessageTokens = 0;
+    /** Promise for token calculation initialization */
+    tokenCalculationPromise;
+    /** Format content blocks as strings (for legacy compatibility) */
+    useLegacyContent = false;
+    /** Detailed per-tool token breakdown for admin tracking */
+    toolsDetail = [];
+    /** Total tool tokens (sum of all toolsDetail) */
+    toolTokensTotal = 0;
+    /** Per-prompt token breakdown for detailed admin reporting */
+    promptBreakdown = {
+        branding: 0,
+        toolRouting: 0,
+        agentInstructions: 0,
+        mcpInstructions: 0,
+        artifacts: 0,
+        memory: 0,
+    };
+    /**
+     * Handoff context when this agent receives control via handoff.
+     * Contains source and parallel execution info for system message context.
+     */
+    handoffContext;
+    /**
+     * Structured output configuration.
+     * When set, the agent will return a validated JSON response
+     * instead of streaming text.
+     */
+    structuredOutput;
+    /**
+     * Optional callback for summarizing messages that were pruned from context.
+     * When provided, discarded messages are summarized instead of silently dropped.
+     */
+    summarizeCallback;
+    constructor({ agentId, name, provider, clientOptions, maxContextTokens, streamBuffer, tokenCounter, tools, toolMap, toolRegistry, toolDefinitions, instructions, additionalInstructions, dynamicContext, reasoningKey, toolEnd, instructionTokens, useLegacyContent, structuredOutput, discoveredTools, }) {
+        this.agentId = agentId;
+        this.name = name;
+        this.provider = provider;
+        this.clientOptions = clientOptions;
+        this.maxContextTokens = maxContextTokens;
+        this.streamBuffer = streamBuffer;
+        this.tokenCounter = tokenCounter;
+        this.tools = tools;
+        this.toolMap = toolMap;
+        this.toolRegistry = toolRegistry;
+        this.toolDefinitions = toolDefinitions;
+        this.instructions = instructions;
+        this.additionalInstructions = additionalInstructions;
+        this.dynamicContext = dynamicContext;
+        this.structuredOutput = structuredOutput;
+        if (reasoningKey) {
+            this.reasoningKey = reasoningKey;
+        }
+        if (toolEnd !== undefined) {
+            this.toolEnd = toolEnd;
+        }
+        if (instructionTokens !== undefined) {
+            this.instructionTokens = instructionTokens;
+        }
+        this.useLegacyContent = useLegacyContent ?? false;
+        if (discoveredTools && discoveredTools.length > 0) {
+            for (const toolName of discoveredTools) {
+                this.discoveredToolNames.add(toolName);
+            }
+        }
+    }
+    /**
+     * Checks if structured output mode is enabled for this agent.
+     * When enabled, the agent will use model.invoke() instead of streaming
+     * and return a validated JSON response.
+     */
+    get isStructuredOutputMode() {
+        return (this.structuredOutput != null && this.structuredOutput.schema != null);
+    }
+    /**
+     * Gets the structured output schema with normalized defaults.
+     * Returns undefined if structured output is not configured.
+     */
+    getStructuredOutputSchema() {
+        if (!this.structuredOutput?.schema) {
+            return undefined;
+        }
+        const schema = { ...this.structuredOutput.schema };
+        // Ensure type is set
+        if (!schema.type && schema.properties) {
+            schema.type = 'object';
+        }
+        // Add title from config name
+        if (this.structuredOutput.name && !schema.title) {
+            schema.title = this.structuredOutput.name;
+        }
+        // Add description from config
+        if (this.structuredOutput.description && !schema.description) {
+            schema.description = this.structuredOutput.description;
+        }
+        // Enable strict mode by default
+        if (this.structuredOutput.strict !== false && schema.type === 'object') {
+            schema.additionalProperties = schema.additionalProperties ?? false;
+        }
+        return schema;
+    }
+    /**
+     * Resolves the structured output mode to a concrete method based on provider capabilities.
+     *
+     * Resolution logic:
+     * - 'native' or 'auto' + supported provider → native constrained decoding
+     * - 'native' + unsupported provider → fallback to 'functionCalling' with warning
+     * - 'provider' → LangChain's jsonMode (existing behavior)
+     * - 'tool' → function calling trick (existing behavior)
+     * - 'auto' + unsupported provider → 'functionCalling'
+     *
+     * @returns The resolved method for withStructuredOutput, or 'native' for direct API usage
+     */
+    resolveStructuredOutputMode() {
+        const mode = this.structuredOutput?.mode ?? 'auto';
+        const warnings = [];
+        // Providers that support native constrained decoding via LangChain
+        const nativeProviders = new Set([
+            Providers.ANTHROPIC,
+            Providers.OPENAI,
+            Providers.AZURE,
+        ]);
+        // Providers where LangChain supports jsonMode
+        const jsonModeProviders = new Set([
+            Providers.ANTHROPIC,
+            Providers.OPENAI,
+            Providers.AZURE,
+        ]);
+        switch (mode) {
+            case 'native': {
+                if (nativeProviders.has(this.provider)) {
+                    if (this.provider === Providers.ANTHROPIC) {
+                        return { method: 'jsonSchema', warnings };
+                    }
+                    // OpenAI/Azure
+                    return { method: 'jsonSchema', warnings };
+                }
+                // Fallback for unsupported providers
+                warnings.push(`Native structured output is not supported for provider '${this.provider}'. Falling back to function calling.`);
+                return { method: 'functionCalling', warnings };
+            }
+            case 'auto': {
+                if (nativeProviders.has(this.provider)) {
+                    if (this.provider === Providers.ANTHROPIC) {
+                        return { method: 'jsonSchema', warnings };
+                    }
+                    // OpenAI/Azure
+                    return { method: 'jsonSchema', warnings };
+                }
+                // Default to function calling for all other providers
+                return { method: undefined, warnings };
+            }
+            case 'provider': {
+                if (this.provider === Providers.BEDROCK) {
+                    // Bedrock doesn't support jsonMode, fall back to functionCalling
+                    return { method: 'functionCalling', warnings };
+                }
+                if (jsonModeProviders.has(this.provider)) {
+                    return { method: 'jsonMode', warnings };
+                }
+                return { method: 'jsonMode', warnings };
+            }
+            case 'tool': {
+                return { method: 'functionCalling', warnings };
+            }
+            default: {
+                return { method: undefined, warnings };
+            }
+        }
+    }
+    /**
+     * Builds instructions text for tools that are ONLY callable via programmatic code execution.
+     * These tools cannot be called directly by the LLM but are available through the
+     * run_tools_with_code tool.
+     *
+     * Includes:
+     * - Code_execution-only tools that are NOT deferred
+     * - Code_execution-only tools that ARE deferred but have been discovered via tool search
+     */
+    buildProgrammaticOnlyToolsInstructions() {
+        if (!this.toolRegistry)
+            return '';
+        const programmaticOnlyTools = [];
+        for (const [name, toolDef] of this.toolRegistry) {
+            const allowedCallers = toolDef.allowed_callers ?? ['direct'];
+            const isCodeExecutionOnly = allowedCallers.includes('code_execution') &&
+                !allowedCallers.includes('direct');
+            if (!isCodeExecutionOnly)
+                continue;
+            // Include if: not deferred OR deferred but discovered
+            const isDeferred = toolDef.defer_loading === true;
+            const isDiscovered = this.discoveredToolNames.has(name);
+            if (!isDeferred || isDiscovered) {
+                programmaticOnlyTools.push(toolDef);
+            }
+        }
+        if (programmaticOnlyTools.length === 0)
+            return '';
+        const toolDescriptions = programmaticOnlyTools
+            .map((tool) => {
+            let desc = `- **${tool.name}**`;
+            if (tool.description != null && tool.description !== '') {
+                desc += `: ${tool.description}`;
+            }
+            if (tool.parameters) {
+                desc += `\n  Parameters: ${JSON.stringify(tool.parameters, null, 2).replace(/\n/g, '\n  ')}`;
+            }
+            return desc;
+        })
+            .join('\n\n');
+        return ('\n\n## Programmatic-Only Tools\n\n' +
+            'The following tools are available exclusively through the `run_tools_with_code` tool. ' +
+            'You cannot call these tools directly; instead, use `run_tools_with_code` with Python code that invokes them.\n\n' +
+            toolDescriptions);
+    }
+    /**
+     * Gets the system runnable, creating it lazily if needed.
+     * Includes instructions, additional instructions, and programmatic-only tools documentation.
+     * Only rebuilds when marked stale (via markToolsAsDiscovered).
+     */
+    get systemRunnable() {
+        // Return cached if not stale
+        if (!this.systemRunnableStale && this.cachedSystemRunnable !== undefined) {
+            return this.cachedSystemRunnable;
+        }
+        // Stale or first access - rebuild
+        const instructionsString = this.buildInstructionsString();
+        this.cachedSystemRunnable = this.buildSystemRunnable(instructionsString);
+        this.systemRunnableStale = false;
+        return this.cachedSystemRunnable;
+    }
+    /**
+     * Explicitly initializes the system runnable.
+     * Call this before async token calculation to ensure system message tokens are counted first.
+     */
+    initializeSystemRunnable() {
+        if (this.systemRunnableStale || this.cachedSystemRunnable === undefined) {
+            const instructionsString = this.buildInstructionsString();
+            this.cachedSystemRunnable = this.buildSystemRunnable(instructionsString);
+            this.systemRunnableStale = false;
+        }
+    }
+    /**
+     * Builds the raw instructions string (without creating SystemMessage).
+     * Includes agent identity preamble and handoff context when available.
+     */
+    buildInstructionsString() {
+        const parts = [];
+        /** Build agent identity and handoff context preamble */
+        const identityPreamble = this.buildIdentityPreamble();
+        if (identityPreamble) {
+            parts.push(identityPreamble);
+        }
+        /** Add main instructions */
+        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) {
+            parts.push(programmaticToolsDoc);
+        }
+        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.
+     */
+    buildIdentityPreamble() {
+        if (!this.handoffContext)
+            return '';
+        const displayName = this.name ?? this.agentId;
+        const { sourceAgentName, parallelSiblings } = this.handoffContext;
+        const isParallel = parallelSiblings.length > 0;
+        const lines = [];
+        lines.push('## Multi-Agent Workflow');
+        lines.push(`You are "${displayName}", transferred from "${sourceAgentName}".`);
+        if (isParallel) {
+            lines.push(`Running in parallel with: ${parallelSiblings.join(', ')}.`);
+        }
+        lines.push('Execute only tasks relevant to your role. Routing is already handled if requested, unless you can route further.');
+        return lines.join('\n');
+    }
+    /**
+     * Build system runnable from pre-built instructions string.
+     * Only called when content has actually changed.
+     */
+    buildSystemRunnable(instructionsString) {
+        if (!instructionsString) {
+            // 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 === Providers.ANTHROPIC) {
+            const anthropicOptions = this.clientOptions;
+            if (anthropicOptions?.promptCache === true) {
+                finalInstructions = {
+                    content: [
+                        {
+                            type: 'text',
+                            text: instructionsString,
+                            cache_control: { type: 'ephemeral' },
+                        },
+                    ],
+                };
+            }
+        }
+        // Handle Bedrock prompt caching (Converse API)
+        // Adds cachePoint block after text content for system message caching
+        // NOTE: Both Claude and Nova models support cachePoint in system and messages
+        // (Nova does NOT support cachePoint in tools - that check is in bedrock/index.ts)
+        if (this.provider === Providers.BEDROCK) {
+            const bedrockOptions = this.clientOptions;
+            const modelId = bedrockOptions?.model?.toLowerCase() ?? '';
+            const supportsCaching = modelId.includes('claude') ||
+                modelId.includes('anthropic') ||
+                modelId.includes('nova');
+            if (bedrockOptions?.promptCache === true && supportsCaching) {
+                finalInstructions = {
+                    content: [
+                        {
+                            type: 'text',
+                            text: instructionsString,
+                        },
+                        {
+                            cachePoint: { type: 'default' },
+                        },
+                    ],
+                };
+            }
+        }
+        const systemMessage = new SystemMessage(finalInstructions);
+        // Update token counts (subtract old, add new)
+        if (this.tokenCounter) {
+            this.instructionTokens -= this.systemMessageTokens;
+            this.systemMessageTokens = this.tokenCounter(systemMessage);
+            this.instructionTokens += this.systemMessageTokens;
+        }
+        return RunnableLambda.from((messages) => {
+            return [systemMessage, ...messages];
+        }).withConfig({ runName: 'prompt' });
+    }
+    /**
+     * Reset context for a new run
+     */
+    reset() {
+        this.instructionTokens = 0;
+        this.systemMessageTokens = 0;
+        this.toolsDetail = [];
+        this.toolTokensTotal = 0;
+        this.cachedSystemRunnable = undefined;
+        this.systemRunnableStale = true;
+        this.lastToken = undefined;
+        this.indexTokenCountMap = {};
+        this.currentUsage = undefined;
+        this.pruneMessages = undefined;
+        this.lastStreamCall = undefined;
+        this.tokenTypeSwitch = undefined;
+        this.currentTokenType = ContentTypes.TEXT;
+        this.discoveredToolNames.clear();
+        this.handoffContext = undefined;
+    }
+    /**
+     * Update the token count map with instruction tokens
+     */
+    updateTokenMapWithInstructions(baseTokenMap) {
+        if (this.instructionTokens > 0) {
+            // Shift all indices by the instruction token count
+            const shiftedMap = {};
+            for (const [key, value] of Object.entries(baseTokenMap)) {
+                const index = parseInt(key, 10);
+                if (!isNaN(index)) {
+                    shiftedMap[String(index)] =
+                        value + (index === 0 ? this.instructionTokens : 0);
+                }
+            }
+            this.indexTokenCountMap = shiftedMap;
+        }
+        else {
+            this.indexTokenCountMap = { ...baseTokenMap };
+        }
+    }
+    /**
+     * Calculate tool tokens and add to instruction tokens
+     * Note: System message tokens are calculated during systemRunnable creation
+     * Also tracks per-tool token breakdown for admin reporting
+     */
+    async calculateInstructionTokens(tokenCounter) {
+        let toolTokens = 0;
+        this.toolsDetail = []; // Reset per-tool breakdown
+        if (this.tools && this.tools.length > 0) {
+            for (const tool of this.tools) {
+                const genericTool = tool;
+                if (genericTool.schema != null &&
+                    typeof genericTool.schema === 'object') {
+                    const jsonSchema = toJsonSchema(genericTool.schema, genericTool.name ?? '', genericTool.description ?? '');
+                    const toolName = genericTool.name || 'unknown';
+                    const tokens = tokenCounter(new SystemMessage(JSON.stringify(jsonSchema)));
+                    // Track per-tool breakdown
+                    this.toolsDetail.push({ name: toolName, tokens });
+                    toolTokens += tokens;
+                }
+            }
+        }
+        // Store total tool tokens for breakdown reporting
+        this.toolTokensTotal = toolTokens;
+        // Add tool tokens to existing instruction tokens (which may already include system message tokens)
+        this.instructionTokens += toolTokens;
+    }
+    /**
+     * Set the per-prompt token breakdown for detailed admin tracking.
+     * Called by the client after assembling all prompt components.
+     * @param breakdown - Object with token counts per prompt component
+     */
+    setPromptBreakdown(breakdown) {
+        if (breakdown.branding !== undefined)
+            this.promptBreakdown.branding = breakdown.branding;
+        if (breakdown.toolRouting !== undefined)
+            this.promptBreakdown.toolRouting = breakdown.toolRouting;
+        if (breakdown.agentInstructions !== undefined)
+            this.promptBreakdown.agentInstructions = breakdown.agentInstructions;
+        if (breakdown.mcpInstructions !== undefined)
+            this.promptBreakdown.mcpInstructions = breakdown.mcpInstructions;
+        if (breakdown.artifacts !== undefined)
+            this.promptBreakdown.artifacts = breakdown.artifacts;
+        if (breakdown.memory !== undefined)
+            this.promptBreakdown.memory = breakdown.memory;
+    }
+    /**
+     * Get a detailed breakdown of context tokens for admin reporting.
+     * This provides visibility into what's consuming the input token budget.
+     * @returns ContextBreakdown object with per-component token counts
+     */
+    getContextBreakdown() {
+        // Calculate sum of prompt components
+        const promptsTotal = this.promptBreakdown.branding +
+            this.promptBreakdown.toolRouting +
+            this.promptBreakdown.agentInstructions +
+            this.promptBreakdown.mcpInstructions +
+            this.promptBreakdown.artifacts +
+            this.promptBreakdown.memory;
+        return {
+            // System message tokens (instructions + additional_instructions)
+            instructions: this.systemMessageTokens,
+            // Artifacts prompt tokens
+            artifacts: this.promptBreakdown.artifacts,
+            // Total tool definition tokens
+            tools: this.toolTokensTotal,
+            // Number of tools
+            toolCount: this.toolsDetail.length,
+            // Tool context/usage instructions (currently embedded in system message)
+            toolContext: 0,
+            // Total tracked context tokens
+            total: this.instructionTokens,
+            // Per-tool token breakdown
+            toolsDetail: [...this.toolsDetail],
+            // Tool context detail (currently not tracked separately)
+            toolContextDetail: [],
+            // Per-prompt breakdown (only include if any prompts were tracked)
+            prompts: promptsTotal > 0 ? { ...this.promptBreakdown } : undefined,
+        };
+    }
+    /**
+     * Gets the tool registry for deferred tools (for tool search).
+     * @param onlyDeferred If true, only returns tools with defer_loading=true
+     * @returns LCToolRegistry with tool definitions
+     */
+    getDeferredToolRegistry(onlyDeferred = true) {
+        const registry = new Map();
+        if (!this.toolRegistry) {
+            return registry;
+        }
+        for (const [name, toolDef] of this.toolRegistry) {
+            if (!onlyDeferred || toolDef.defer_loading === true) {
+                registry.set(name, toolDef);
+            }
+        }
+        return registry;
+    }
+    /**
+     * Sets the handoff context for this agent.
+     * Call this when the agent receives control via handoff from another agent.
+     * Marks system runnable as stale to include handoff context in system message.
+     * @param sourceAgentName - Name of the agent that transferred control
+     * @param parallelSiblings - Names of other agents executing in parallel with this one
+     */
+    setHandoffContext(sourceAgentName, parallelSiblings) {
+        this.handoffContext = { sourceAgentName, parallelSiblings };
+        this.systemRunnableStale = true;
+    }
+    /**
+     * Clears any handoff context.
+     * Call this when resetting the agent or when handoff context is no longer relevant.
+     */
+    clearHandoffContext() {
+        if (this.handoffContext) {
+            this.handoffContext = undefined;
+            this.systemRunnableStale = true;
+        }
+    }
+    /**
+     * Marks tools as discovered via tool search.
+     * Discovered tools will be included in the next model binding.
+     * Only marks system runnable stale if NEW tools were actually added.
+     * @param toolNames - Array of discovered tool names
+     * @returns true if any new tools were discovered
+     */
+    markToolsAsDiscovered(toolNames) {
+        let hasNewDiscoveries = false;
+        for (const name of toolNames) {
+            if (!this.discoveredToolNames.has(name)) {
+                this.discoveredToolNames.add(name);
+                hasNewDiscoveries = true;
+            }
+        }
+        if (hasNewDiscoveries) {
+            this.systemRunnableStale = true;
+        }
+        return hasNewDiscoveries;
+    }
+    /**
+     * Gets tools that should be bound to the LLM.
+     * In event-driven mode (toolDefinitions present, tools empty), creates schema-only tools.
+     * Otherwise filters tool instances based on:
+     * 1. Non-deferred tools with allowed_callers: ['direct']
+     * 2. Discovered tools (from tool search)
+     * @returns Array of tools to bind to model
+     */
+    getToolsForBinding() {
+        /** Event-driven mode: create schema-only tools from definitions */
+        if (this.toolDefinitions && this.toolDefinitions.length > 0) {
+            return this.getEventDrivenToolsForBinding();
+        }
+        /** Traditional mode: filter actual tool instances */
+        if (!this.tools || !this.toolRegistry) {
+            return this.tools;
+        }
+        return this.filterToolsForBinding(this.tools);
+    }
+    /** Creates schema-only tools from toolDefinitions for event-driven mode */
+    getEventDrivenToolsForBinding() {
+        if (!this.toolDefinitions) {
+            return [];
+        }
+        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;
+        });
+        return createSchemaOnlyTools(defsToInclude);
+    }
+    /** Filters tool instances for binding based on registry config */
+    filterToolsForBinding(tools) {
+        return tools.filter((tool) => {
+            if (!('name' in tool)) {
+                return true;
+            }
+            const toolDef = this.toolRegistry?.get(tool.name);
+            if (!toolDef) {
+                return true;
+            }
+            if (this.discoveredToolNames.has(tool.name)) {
+                const allowedCallers = toolDef.allowed_callers ?? ['direct'];
+                return allowedCallers.includes('direct');
+            }
+            const allowedCallers = toolDef.allowed_callers ?? ['direct'];
+            return (allowedCallers.includes('direct') && toolDef.defer_loading !== true);
+        });
+    }
+}
+
+export { AgentContext };
+//# sourceMappingURL=AgentContext.mjs.map