@illuma-ai/agents 1.0.81

package/dist/esm/graphs/Graph.mjs

@@ -0,0 +1,1612 @@
+import { nanoid } from 'nanoid';
+import { concat } from '@langchain/core/utils/stream';
+import { ChatVertexAI } from '@langchain/google-vertexai';
+import { Annotation, messagesStateReducer, StateGraph, START, END } from '@langchain/langgraph';
+import { RunnableLambda } from '@langchain/core/runnables';
+import { SystemMessage, HumanMessage, AIMessageChunk } from '@langchain/core/messages';
+import { GraphNodeKeys, ContentTypes, Providers, GraphEvents, MessageTypes, StepTypes, Constants } from '../common/enum.mjs';
+import { convertMessagesToContent, modifyDeltaProperties, formatAnthropicArtifactContent, formatArtifactPayload } from '../messages/core.mjs';
+import { createPruneMessages } from '../messages/prune.mjs';
+import { ensureThinkingBlockInMessages } from '../messages/format.mjs';
+import { addCacheControl, addBedrockCacheControl } from '../messages/cache.mjs';
+import { formatContentStrings } from '../messages/content.mjs';
+import { extractToolDiscoveries } from '../messages/tools.mjs';
+import { resetIfNotEmpty, joinKeys } from '../utils/graph.mjs';
+import { isOpenAILike, isGoogleLike } from '../utils/llm.mjs';
+import { sleep } from '../utils/run.mjs';
+import 'js-tiktoken';
+import '../utils/toonFormat.mjs';
+import { buildContextAnalytics } from '../utils/contextAnalytics.mjs';
+import 'zod-to-json-schema';
+import { getChatModelClass, manualToolStreamProviders } from '../llm/providers.mjs';
+import { ToolNode, toolsCondition } from '../tools/ToolNode.mjs';
+import { ChatOpenAI, AzureChatOpenAI } from '../llm/openai/index.mjs';
+import { safeDispatchCustomEvent } from '../utils/events.mjs';
+import { createSchemaOnlyTools } from '../tools/schema.mjs';
+import { prepareSchemaForProvider } from '../schemas/validate.mjs';
+import { AgentContext } from '../agents/AgentContext.mjs';
+import { StructuredOutputTruncatedError, StructuredOutputRefusalError } from '../types/graph.mjs';
+import { createFakeStreamingLLM } from '../llm/fake.mjs';
+
+/* eslint-disable no-console */
+// src/graphs/Graph.ts
+const { AGENT, TOOLS } = GraphNodeKeys;
+class Graph {
+    messageStepHasToolCalls = new Map();
+    messageIdsByStepKey = new Map();
+    prelimMessageIdsByStepKey = new Map();
+    config;
+    contentData = [];
+    stepKeyIds = new Map();
+    contentIndexMap = new Map();
+    toolCallStepIds = new Map();
+    signal;
+    /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
+    invokedToolIds;
+    handlerRegistry;
+    /**
+     * Tool session contexts for automatic state persistence across tool invocations.
+     * Keyed by tool name (e.g., Constants.EXECUTE_CODE).
+     * Currently supports code execution session tracking (session_id, files).
+     */
+    sessions = new Map();
+}
+class StandardGraph extends Graph {
+    overrideModel;
+    /** Optional compile options passed into workflow.compile() */
+    compileOptions;
+    messages = [];
+    runId;
+    startIndex = 0;
+    signal;
+    /** Map of agent contexts by agent ID */
+    agentContexts = new Map();
+    /** Default agent ID to use */
+    defaultAgentId;
+    /** Normalized finish/stop reason from the last LLM invocation */
+    lastFinishReason;
+    constructor({ 
+    // parent-level graph inputs
+    runId, signal, agents, tokenCounter, indexTokenCountMap, }) {
+        super();
+        this.runId = runId;
+        this.signal = signal;
+        if (agents.length === 0) {
+            throw new Error('At least one agent configuration is required');
+        }
+        for (const agentConfig of agents) {
+            const agentContext = AgentContext.fromConfig(agentConfig, tokenCounter, indexTokenCountMap);
+            this.agentContexts.set(agentConfig.agentId, agentContext);
+        }
+        this.defaultAgentId = agents[0].agentId;
+    }
+    /* Init */
+    resetValues(keepContent) {
+        this.messages = [];
+        this.lastFinishReason = undefined;
+        this.config = resetIfNotEmpty(this.config, undefined);
+        if (keepContent !== true) {
+            this.contentData = resetIfNotEmpty(this.contentData, []);
+            this.contentIndexMap = resetIfNotEmpty(this.contentIndexMap, new Map());
+        }
+        this.stepKeyIds = resetIfNotEmpty(this.stepKeyIds, new Map());
+        this.toolCallStepIds = resetIfNotEmpty(this.toolCallStepIds, new Map());
+        this.messageIdsByStepKey = resetIfNotEmpty(this.messageIdsByStepKey, new Map());
+        this.messageStepHasToolCalls = resetIfNotEmpty(this.messageStepHasToolCalls, new Map());
+        this.prelimMessageIdsByStepKey = resetIfNotEmpty(this.prelimMessageIdsByStepKey, new Map());
+        this.invokedToolIds = resetIfNotEmpty(this.invokedToolIds, undefined);
+        for (const context of this.agentContexts.values()) {
+            context.reset();
+        }
+    }
+    /**
+     * Returns the normalized finish/stop reason from the last LLM invocation.
+     * Used by callers to detect when the response was truncated due to max_tokens.
+     */
+    getLastFinishReason() {
+        return this.lastFinishReason;
+    }
+    /**
+     * Estimates a human-friendly description of the conversation timeframe based on message count.
+     * Uses rough heuristics to provide context about how much history is available.
+     *
+     * @param messageCount - Number of messages in the remaining context
+     * @returns A friendly description like "the last few minutes", "the past hour", etc.
+     */
+    getContextTimeframeDescription(messageCount) {
+        // Rough heuristics based on typical conversation patterns:
+        // - Very active chat: ~20-30 messages per hour
+        // - Normal chat: ~10-15 messages per hour
+        // - Slow/thoughtful chat: ~5-8 messages per hour
+        // We use a middle estimate of ~12 messages per hour
+        if (messageCount <= 5) {
+            return 'just the last few exchanges';
+        }
+        else if (messageCount <= 15) {
+            return 'the last several minutes';
+        }
+        else if (messageCount <= 30) {
+            return 'roughly the past hour';
+        }
+        else if (messageCount <= 60) {
+            return 'the past couple of hours';
+        }
+        else if (messageCount <= 150) {
+            return 'the past few hours';
+        }
+        else if (messageCount <= 300) {
+            return 'roughly a day\'s worth';
+        }
+        else if (messageCount <= 700) {
+            return 'the past few days';
+        }
+        else {
+            return 'about a week or more';
+        }
+    }
+    /* Run Step Processing */
+    getRunStep(stepId) {
+        const index = this.contentIndexMap.get(stepId);
+        if (index !== undefined) {
+            return this.contentData[index];
+        }
+        return undefined;
+    }
+    getAgentContext(metadata) {
+        if (!metadata) {
+            throw new Error('No metadata provided to retrieve agent context');
+        }
+        const currentNode = metadata.langgraph_node;
+        if (!currentNode) {
+            throw new Error('No langgraph_node in metadata to retrieve agent context');
+        }
+        let agentId;
+        if (currentNode.startsWith(AGENT)) {
+            agentId = currentNode.substring(AGENT.length);
+        }
+        else if (currentNode.startsWith(TOOLS)) {
+            agentId = currentNode.substring(TOOLS.length);
+        }
+        const agentContext = this.agentContexts.get(agentId ?? '');
+        if (!agentContext) {
+            throw new Error(`No agent context found for agent ID ${agentId}`);
+        }
+        return agentContext;
+    }
+    getStepKey(metadata) {
+        if (!metadata)
+            return '';
+        const keyList = this.getKeyList(metadata);
+        if (this.checkKeyList(keyList)) {
+            throw new Error('Missing metadata');
+        }
+        return joinKeys(keyList);
+    }
+    getStepIdByKey(stepKey, index) {
+        const stepIds = this.stepKeyIds.get(stepKey);
+        if (!stepIds) {
+            throw new Error(`No step IDs found for stepKey ${stepKey}`);
+        }
+        if (index === undefined) {
+            return stepIds[stepIds.length - 1];
+        }
+        return stepIds[index];
+    }
+    generateStepId(stepKey) {
+        const stepIds = this.stepKeyIds.get(stepKey);
+        let newStepId;
+        let stepIndex = 0;
+        if (stepIds) {
+            stepIndex = stepIds.length;
+            newStepId = `step_${nanoid()}`;
+            stepIds.push(newStepId);
+            this.stepKeyIds.set(stepKey, stepIds);
+        }
+        else {
+            newStepId = `step_${nanoid()}`;
+            this.stepKeyIds.set(stepKey, [newStepId]);
+        }
+        return [newStepId, stepIndex];
+    }
+    getKeyList(metadata) {
+        if (!metadata)
+            return [];
+        const keyList = [
+            metadata.run_id,
+            metadata.thread_id,
+            metadata.langgraph_node,
+            metadata.langgraph_step,
+            metadata.checkpoint_ns,
+        ];
+        const agentContext = this.getAgentContext(metadata);
+        if (agentContext.currentTokenType === ContentTypes.THINK ||
+            agentContext.currentTokenType === 'think_and_text') {
+            keyList.push('reasoning');
+        }
+        else if (agentContext.tokenTypeSwitch === 'content') {
+            keyList.push('post-reasoning');
+        }
+        if (this.invokedToolIds != null && this.invokedToolIds.size > 0) {
+            keyList.push(this.invokedToolIds.size + '');
+        }
+        return keyList;
+    }
+    checkKeyList(keyList) {
+        return keyList.some((key) => key === undefined);
+    }
+    /* Misc.*/
+    getRunMessages() {
+        return this.messages.slice(this.startIndex);
+    }
+    getContentParts() {
+        return convertMessagesToContent(this.messages.slice(this.startIndex));
+    }
+    /**
+     * Get all run steps, optionally filtered by agent ID
+     */
+    getRunSteps(agentId) {
+        if (agentId == null || agentId === '') {
+            return [...this.contentData];
+        }
+        return this.contentData.filter((step) => step.agentId === agentId);
+    }
+    /**
+     * Get run steps grouped by agent ID
+     */
+    getRunStepsByAgent() {
+        const stepsByAgent = new Map();
+        for (const step of this.contentData) {
+            if (step.agentId == null || step.agentId === '')
+                continue;
+            const steps = stepsByAgent.get(step.agentId) ?? [];
+            steps.push(step);
+            stepsByAgent.set(step.agentId, steps);
+        }
+        return stepsByAgent;
+    }
+    /**
+     * Get agent IDs that participated in this run
+     */
+    getActiveAgentIds() {
+        const agentIds = new Set();
+        for (const step of this.contentData) {
+            if (step.agentId != null && step.agentId !== '') {
+                agentIds.add(step.agentId);
+            }
+        }
+        return Array.from(agentIds);
+    }
+    /**
+     * Maps contentPart indices to agent IDs for post-run analysis
+     * Returns a map where key is the contentPart index and value is the agentId
+     */
+    getContentPartAgentMap() {
+        const contentPartAgentMap = new Map();
+        for (const step of this.contentData) {
+            if (step.agentId != null &&
+                step.agentId !== '' &&
+                Number.isFinite(step.index)) {
+                contentPartAgentMap.set(step.index, step.agentId);
+            }
+        }
+        return contentPartAgentMap;
+    }
+    /**
+     * Get the context breakdown from the primary agent for admin token tracking.
+     * Returns detailed token counts for instructions, tools, etc.
+     */
+    getContextBreakdown() {
+        const primaryContext = this.agentContexts.get(this.defaultAgentId);
+        if (!primaryContext) {
+            return null;
+        }
+        return primaryContext.getContextBreakdown();
+    }
+    /**
+     * Get the latest context analytics from the graph.
+     * Returns metrics like utilization %, TOON stats, message breakdown.
+     */
+    getContextAnalytics() {
+        return this.lastContextAnalytics ?? null;
+    }
+    /** Store the latest context analytics for retrieval after run */
+    lastContextAnalytics = null;
+    /* Graph */
+    createSystemRunnable({ provider, clientOptions, instructions, additional_instructions, }) {
+        let finalInstructions = instructions;
+        if (additional_instructions != null && additional_instructions !== '') {
+            finalInstructions =
+                finalInstructions != null && finalInstructions
+                    ? `${finalInstructions}\n\n${additional_instructions}`
+                    : additional_instructions;
+        }
+        if (finalInstructions != null &&
+            finalInstructions &&
+            provider === Providers.ANTHROPIC &&
+            clientOptions.promptCache === true) {
+            finalInstructions = {
+                content: [
+                    {
+                        type: 'text',
+                        text: instructions,
+                        cache_control: { type: 'ephemeral' },
+                    },
+                ],
+            };
+        }
+        if (finalInstructions != null && finalInstructions !== '') {
+            const systemMessage = new SystemMessage(finalInstructions);
+            return RunnableLambda.from((messages) => {
+                return [systemMessage, ...messages];
+            }).withConfig({ runName: 'prompt' });
+        }
+    }
+    initializeTools({ currentTools, currentToolMap, agentContext, }) {
+        const toolDefinitions = agentContext?.toolDefinitions;
+        const eventDrivenMode = toolDefinitions != null && toolDefinitions.length > 0;
+        if (eventDrivenMode) {
+            const schemaTools = createSchemaOnlyTools(toolDefinitions);
+            const toolDefMap = new Map(toolDefinitions.map((def) => [def.name, def]));
+            return new ToolNode({
+                tools: schemaTools,
+                toolMap: new Map(schemaTools.map((tool) => [tool.name, tool])),
+                toolCallStepIds: this.toolCallStepIds,
+                errorHandler: (data, metadata) => StandardGraph.handleToolCallErrorStatic(this, data, metadata),
+                toolRegistry: agentContext?.toolRegistry,
+                sessions: this.sessions,
+                eventDrivenMode: true,
+                toolDefinitions: toolDefMap,
+                agentId: agentContext?.agentId,
+            });
+        }
+        return new ToolNode({
+            tools: currentTools ?? [],
+            toolMap: currentToolMap,
+            toolCallStepIds: this.toolCallStepIds,
+            errorHandler: (data, metadata) => StandardGraph.handleToolCallErrorStatic(this, data, metadata),
+            toolRegistry: agentContext?.toolRegistry,
+            sessions: this.sessions,
+        });
+    }
+    initializeModel({ provider, tools, clientOptions, }) {
+        const ChatModelClass = getChatModelClass(provider);
+        const model = new ChatModelClass(clientOptions ?? {});
+        if (isOpenAILike(provider) &&
+            (model instanceof ChatOpenAI || model instanceof AzureChatOpenAI)) {
+            model.temperature = clientOptions
+                .temperature;
+            model.topP = clientOptions.topP;
+            model.frequencyPenalty = clientOptions
+                .frequencyPenalty;
+            model.presencePenalty = clientOptions
+                .presencePenalty;
+            model.n = clientOptions.n;
+        }
+        else if (provider === Providers.VERTEXAI &&
+            model instanceof ChatVertexAI) {
+            model.temperature = clientOptions
+                .temperature;
+            model.topP = clientOptions.topP;
+            model.topK = clientOptions.topK;
+            model.topLogprobs = clientOptions
+                .topLogprobs;
+            model.frequencyPenalty = clientOptions
+                .frequencyPenalty;
+            model.presencePenalty = clientOptions
+                .presencePenalty;
+            model.maxOutputTokens = clientOptions
+                .maxOutputTokens;
+        }
+        if (!tools || tools.length === 0) {
+            return model;
+        }
+        return model.bindTools(tools);
+    }
+    overrideTestModel(responses, sleep, toolCalls) {
+        this.overrideModel = createFakeStreamingLLM({
+            responses,
+            sleep,
+            toolCalls,
+        });
+    }
+    getNewModel({ provider, clientOptions, }) {
+        const ChatModelClass = getChatModelClass(provider);
+        return new ChatModelClass(clientOptions ?? {});
+    }
+    getUsageMetadata(finalMessage) {
+        if (finalMessage &&
+            'usage_metadata' in finalMessage &&
+            finalMessage.usage_metadata != null) {
+            return finalMessage.usage_metadata;
+        }
+    }
+    /** Execute model invocation with streaming support */
+    async attemptInvoke({ currentModel, finalMessages, provider, tools, }, config) {
+        const model = this.overrideModel ?? currentModel;
+        if (!model) {
+            throw new Error('No model found');
+        }
+        if ((tools?.length ?? 0) > 0 && manualToolStreamProviders.has(provider)) {
+            if (!model.stream) {
+                throw new Error('Model does not support stream');
+            }
+            const stream = await model.stream(finalMessages, config);
+            let finalChunk;
+            for await (const chunk of stream) {
+                await safeDispatchCustomEvent(GraphEvents.CHAT_MODEL_STREAM, { chunk, emitted: true }, config);
+                finalChunk = finalChunk ? concat(finalChunk, chunk) : chunk;
+            }
+            finalChunk = modifyDeltaProperties(provider, finalChunk);
+            return { messages: [finalChunk] };
+        }
+        else {
+            const finalMessage = await model.invoke(finalMessages, config);
+            if ((finalMessage.tool_calls?.length ?? 0) > 0) {
+                finalMessage.tool_calls = finalMessage.tool_calls?.filter((tool_call) => !!tool_call.name);
+            }
+            return { messages: [finalMessage] };
+        }
+    }
+    /**
+     * Execute model invocation with structured output.
+     * Uses native constrained decoding (jsonSchema method) for supported providers,
+     * or falls back to withStructuredOutput with functionCalling/jsonMode.
+     *
+     * Native mode uses provider APIs directly:
+     * - Anthropic: output_config.format via LangChain's method: 'json_schema'
+     * - OpenAI/Azure: response_format.json_schema via LangChain's method: 'jsonSchema'
+     * - Bedrock: falls back to functionCalling (LangChain doesn't support native yet)
+     */
+    async attemptStructuredInvoke({ currentModel, finalMessages, schema, structuredOutputConfig, provider, agentContext, }, config) {
+        const model = this.overrideModel ?? currentModel;
+        if (!model) {
+            throw new Error('No model found');
+        }
+        // Check if model supports withStructuredOutput
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        if (typeof model.withStructuredOutput !== 'function') {
+            throw new Error(`The selected model does not support structured output. ` +
+                `Please use a model that supports JSON schema output (e.g., OpenAI GPT-4, Anthropic Claude, Google Gemini) ` +
+                `or disable structured output for this agent.`);
+        }
+        const { name = 'StructuredResponse', includeRaw: _includeRaw = false, handleErrors = true, maxRetries = 2, } = structuredOutputConfig;
+        // Resolve the structured output method using AgentContext's provider-aware logic
+        let method;
+        if (agentContext) {
+            const resolved = agentContext.resolveStructuredOutputMode();
+            method = resolved.method;
+            if (resolved.warnings.length > 0) {
+                console.warn('[Graph] Structured output mode warnings:', resolved.warnings);
+            }
+        }
+        else {
+            // Legacy fallback: use the old mode-based resolution
+            const mode = structuredOutputConfig.mode ?? 'auto';
+            if (mode === 'tool') {
+                method = 'functionCalling';
+            }
+            else if (mode === 'provider') {
+                method = provider === Providers.BEDROCK ? 'functionCalling' : 'jsonMode';
+            }
+            else {
+                method = undefined;
+            }
+        }
+        // Prepare schema for provider-specific constraints when using native/jsonSchema mode
+        let preparedSchema = schema;
+        if (method === 'jsonSchema' && provider) {
+            const { schema: prepared, warnings } = prepareSchemaForProvider(schema, provider, structuredOutputConfig.strict !== false);
+            preparedSchema = prepared;
+            if (warnings.length > 0) {
+                console.log('[Graph] Schema preparation warnings:', warnings);
+            }
+        }
+        // Use withStructuredOutput to bind the schema
+        // Always use includeRaw: true internally so we can debug what's returned
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const structuredModel = model.withStructuredOutput(preparedSchema, {
+            name,
+            method: method === 'native' ? undefined : method,
+            includeRaw: true, // Always true internally for debugging
+            strict: structuredOutputConfig.strict !== false,
+        });
+        console.log('[Graph] Structured output config:', {
+            name,
+            method,
+            provider,
+            schemaKeys: Object.keys(preparedSchema),
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            modelName: model.model || model.modelId || 'unknown',
+        });
+        let lastError;
+        let attempts = 0;
+        while (attempts <= maxRetries) {
+            try {
+                // Note: We pass the original config here. The stream aggregator will filter out
+                // the synthetic "response" tool call events from withStructuredOutput()
+                const result = await structuredModel.invoke(finalMessages, config);
+                // Debug: log what we got back
+                console.log('[Graph] Structured output raw result type:', typeof result);
+                // Check for refusal or truncation in the raw message
+                if (result?.raw) {
+                    const rawMsg = result.raw;
+                    console.log('[Graph] Raw message content type:', typeof rawMsg?.content);
+                    console.log('[Graph] Raw message tool_calls:', rawMsg?.tool_calls?.length ?? 0);
+                    if (rawMsg?.content && typeof rawMsg.content === 'string' && rawMsg.content.length > 0) {
+                        console.log('[Graph] Raw message text content (first 200):', rawMsg.content.substring(0, 200));
+                    }
+                    // Check stop reason for refusal or truncation
+                    const responseMetadata = rawMsg.response_metadata ?? {};
+                    const stopReason = responseMetadata.stop_reason ?? // Anthropic
+                        responseMetadata.finish_reason ?? // OpenAI
+                        responseMetadata.stopReason; // Bedrock
+                    if (stopReason === 'max_tokens' || stopReason === 'length') {
+                        throw new StructuredOutputTruncatedError(stopReason);
+                    }
+                    // Check for Anthropic refusal (stop_reason won't be 'refusal' but content may indicate it)
+                    // OpenAI uses message.refusal field
+                    const refusal = rawMsg.refusal;
+                    if (refusal) {
+                        throw new StructuredOutputRefusalError(refusal);
+                    }
+                }
+                // Handle response - we always use includeRaw internally
+                if (result?.raw && result?.parsed !== undefined) {
+                    return {
+                        structuredResponse: result.parsed,
+                        rawMessage: result.raw,
+                    };
+                }
+                // Fallback for models that don't support includeRaw
+                return {
+                    structuredResponse: result,
+                };
+            }
+            catch (error) {
+                // Don't retry on refusal or truncation errors — they need user action
+                if (error instanceof StructuredOutputRefusalError ||
+                    error instanceof StructuredOutputTruncatedError) {
+                    throw error;
+                }
+                lastError = error;
+                attempts++;
+                // If error handling is disabled, throw immediately
+                if (handleErrors === false) {
+                    throw error;
+                }
+                // If we've exhausted retries, throw
+                if (attempts > maxRetries) {
+                    throw new Error(`Structured output failed after ${maxRetries + 1} attempts: ${lastError.message}`);
+                }
+                // Add error message to conversation for retry
+                const errorMessage = typeof handleErrors === 'string'
+                    ? handleErrors
+                    : `The response did not match the expected schema. Error: ${lastError.message}. Please try again with a valid response.`;
+                console.warn(`[Graph] Structured output attempt ${attempts} failed: ${lastError.message}. Retrying...`);
+                // Add the error as a human message for context
+                finalMessages = [
+                    ...finalMessages,
+                    new HumanMessage({
+                        content: `[VALIDATION ERROR]\n${errorMessage}`,
+                    }),
+                ];
+            }
+        }
+        throw lastError ?? new Error('Structured output failed');
+    }
+    cleanupSignalListener(currentModel) {
+        if (!this.signal) {
+            return;
+        }
+        const model = this.overrideModel ?? currentModel;
+        if (!model) {
+            return;
+        }
+        const client = model?.exposedClient;
+        if (!client?.abortHandler) {
+            return;
+        }
+        this.signal.removeEventListener('abort', client.abortHandler);
+        client.abortHandler = undefined;
+    }
+    /**
+     * Perform structured output invocation: creates a fresh model without tools bound,
+     * removes thinking configuration, invokes with the schema, emits the event,
+     * and returns a clean AIMessageChunk without tool_calls.
+     *
+     * Used by both the immediate path (no tools) and the deferred path (after tool use).
+     */
+    async performStructuredOutput({ agentContext, finalMessages, config, }) {
+        const schema = agentContext.getStructuredOutputSchema();
+        if (!schema) {
+            throw new Error('Structured output schema is not configured');
+        }
+        // Get a fresh model WITHOUT tools bound
+        // bindTools() returns RunnableBinding which lacks withStructuredOutput
+        // Also disable thinking mode - Anthropic/Bedrock doesn't allow tool_choice with thinking enabled
+        const structuredClientOptions = { ...agentContext.clientOptions };
+        // Determine if streaming is possible for this structured output mode
+        // Native/jsonSchema modes can stream; tool/functionCalling modes cannot (synthetic tool calls break UX)
+        const resolved = agentContext.resolveStructuredOutputMode();
+        const canStream = resolved.method === 'jsonSchema' || resolved.method === 'jsonMode';
+        if (!canStream) {
+            // Disable streaming for function calling mode (synthetic tool calls break streaming UX)
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            structuredClientOptions.streaming = false;
+        }
+        // For native/jsonSchema mode, Anthropic's constrained decoding works with thinking enabled
+        // (grammar only applies to final output, not thinking blocks). For function calling mode,
+        // thinking must be disabled because forced tool_choice is incompatible with thinking.
+        const needsThinkingDisabled = resolved.method !== 'jsonSchema';
+        if (needsThinkingDisabled) {
+            // Remove thinking configuration for Bedrock
+            if (agentContext.provider === Providers.BEDROCK) {
+                const bedrockOpts = structuredClientOptions;
+                if (bedrockOpts.additionalModelRequestFields) {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const additionalFields = Object.assign({}, bedrockOpts.additionalModelRequestFields);
+                    delete additionalFields.thinking;
+                    delete additionalFields.budgetTokens;
+                    bedrockOpts.additionalModelRequestFields = additionalFields;
+                }
+            }
+            // Remove thinking configuration for Anthropic direct API
+            if (agentContext.provider === Providers.ANTHROPIC) {
+                const anthropicOpts = structuredClientOptions;
+                if (anthropicOpts.thinking) {
+                    delete anthropicOpts.thinking;
+                }
+            }
+        }
+        const structuredModel = this.getNewModel({
+            provider: agentContext.provider,
+            clientOptions: structuredClientOptions,
+        });
+        const { structuredResponse, rawMessage } = await this.attemptStructuredInvoke({
+            currentModel: structuredModel,
+            finalMessages,
+            schema,
+            structuredOutputConfig: agentContext.structuredOutput,
+            provider: agentContext.provider,
+            agentContext,
+        }, config);
+        // Emit structured output event
+        await safeDispatchCustomEvent(GraphEvents.ON_STRUCTURED_OUTPUT, {
+            structuredResponse,
+            schema,
+            raw: rawMessage,
+        }, config);
+        // Create a clean message WITHOUT tool_calls for structured output.
+        // The rawMessage contains a tool_call for the structured output schema (e.g., "response"),
+        // which would cause the graph router to send it to the tool node.
+        // We return a clean AI message that ends the graph.
+        let cleanMessage;
+        if (rawMessage) {
+            cleanMessage = new AIMessageChunk({
+                content: JSON.stringify(structuredResponse, null, 2),
+                id: rawMessage.id,
+                response_metadata: rawMessage.response_metadata,
+                usage_metadata: rawMessage.usage_metadata,
+            });
+        }
+        return {
+            messages: cleanMessage ? [cleanMessage] : [],
+            structuredResponse,
+        };
+    }
+    createCallModel(agentId = 'default') {
+        return async (state, config) => {
+            /**
+             * Get agent context - it must exist by this point
+             */
+            const agentContext = this.agentContexts.get(agentId);
+            if (!agentContext) {
+                throw new Error(`Agent context not found for agentId: ${agentId}`);
+            }
+            if (!config) {
+                throw new Error('No config provided');
+            }
+            let { messages } = state;
+            // CACHE OPTIMIZATION: Inject dynamicContext as a HumanMessage at the start of conversation
+            // This keeps the system message static (cacheable) while providing dynamic context
+            // (timestamps, user info, tool context) as conversation content instead.
+            // Only inject on the first turn when messages don't already have the context marker.
+            if (agentContext.dynamicContext &&
+                messages.length > 0 &&
+                !messages.some((m) => m instanceof HumanMessage &&
+                    typeof m.content === 'string' &&
+                    m.content.startsWith('[SESSION_CONTEXT]'))) {
+                const dynamicContextMessage = new HumanMessage({
+                    content: `[SESSION_CONTEXT]\n${agentContext.dynamicContext}`,
+                });
+                const ackMessage = new AIMessageChunk({
+                    content: 'Understood. I have noted the session context including the current date/time (CST) and will apply it appropriately.',
+                });
+                messages = [dynamicContextMessage, ackMessage, ...messages];
+            }
+            // Extract tool discoveries from current turn only (similar to formatArtifactPayload pattern)
+            const discoveredNames = extractToolDiscoveries(messages);
+            if (discoveredNames.length > 0) {
+                agentContext.markToolsAsDiscovered(discoveredNames);
+            }
+            const toolsForBinding = agentContext.getToolsForBinding();
+            let model = this.overrideModel ??
+                this.initializeModel({
+                    tools: toolsForBinding,
+                    provider: agentContext.provider,
+                    clientOptions: agentContext.clientOptions,
+                });
+            if (agentContext.systemRunnable) {
+                model = agentContext.systemRunnable.pipe(model);
+            }
+            if (agentContext.tokenCalculationPromise) {
+                await agentContext.tokenCalculationPromise;
+            }
+            if (!config.signal) {
+                config.signal = this.signal;
+            }
+            this.config = config;
+            let messagesToUse = messages;
+            // ====================================================================
+            // PRE-PRUNING DELEGATION CHECK
+            // Before pruning strips messages (losing context), check if we should
+            // delegate instead. If context would be pruned AND the agent has the
+            // task tool, inject a delegation hint and SKIP pruning — preserving
+            // the content for the LLM to understand what to delegate.
+            // ====================================================================
+            let delegationInjectedPrePrune = false;
+            const hasTaskToolPrePrune = agentContext.tools?.some((tool) => {
+                const toolName = typeof tool === 'object' && 'name' in tool
+                    ? tool.name
+                    : '';
+                return toolName === 'task';
+            });
+            if (hasTaskToolPrePrune &&
+                agentContext.tokenCounter &&
+                agentContext.maxContextTokens != null) {
+                // Estimate total tokens in messages BEFORE pruning
+                let prePruneTokens = 0;
+                for (const msg of messages) {
+                    prePruneTokens += agentContext.tokenCounter(msg);
+                }
+                // Add instruction tokens (system prompt)
+                prePruneTokens += agentContext.instructionTokens ?? 0;
+                const prePruneUtilization = (prePruneTokens / agentContext.maxContextTokens) * 100;
+                if (prePruneUtilization > 70) {
+                    console.warn(`[Graph] PRE-PRUNE delegation check: ${prePruneUtilization.toFixed(1)}% utilization ` +
+                        `(${prePruneTokens}/${agentContext.maxContextTokens} tokens). ` +
+                        `Injecting delegation hint INSTEAD of pruning.`);
+                    delegationInjectedPrePrune = true;
+                }
+            }
+            if (!agentContext.pruneMessages &&
+                agentContext.tokenCounter &&
+                agentContext.maxContextTokens != null &&
+                agentContext.indexTokenCountMap[0] != null) {
+                const isAnthropicWithThinking = (agentContext.provider === Providers.ANTHROPIC &&
+                    agentContext.clientOptions.thinking !=
+                        null) ||
+                    (agentContext.provider === Providers.BEDROCK &&
+                        agentContext.clientOptions
+                            .additionalModelRequestFields?.['thinking'] != null) ||
+                    (agentContext.provider === Providers.OPENAI &&
+                        agentContext.clientOptions.modelKwargs
+                            ?.thinking?.type === 'enabled');
+                agentContext.pruneMessages = createPruneMessages({
+                    startIndex: this.startIndex,
+                    provider: agentContext.provider,
+                    tokenCounter: agentContext.tokenCounter,
+                    maxTokens: agentContext.maxContextTokens,
+                    thinkingEnabled: isAnthropicWithThinking,
+                    indexTokenCountMap: agentContext.indexTokenCountMap,
+                });
+            }
+            if (agentContext.pruneMessages && !delegationInjectedPrePrune) {
+                const { context, indexTokenCountMap, messagesToRefine } = agentContext.pruneMessages({
+                    messages,
+                    usageMetadata: agentContext.currentUsage,
+                    // startOnMessageType: 'human',
+                });
+                agentContext.indexTokenCountMap = indexTokenCountMap;
+                messagesToUse = context;
+                // Summarize discarded messages if callback provided
+                if (messagesToRefine && messagesToRefine.length > 0 && agentContext.summarizeCallback) {
+                    try {
+                        const summary = await agentContext.summarizeCallback(messagesToRefine);
+                        if (summary) {
+                            const summaryMsg = new SystemMessage(`[Conversation Summary]\n${summary}`);
+                            // Insert after system message (if present), before conversation messages
+                            const systemIdx = messagesToUse[0]?.getType() === 'system' ? 1 : 0;
+                            messagesToUse = [
+                                ...messagesToUse.slice(0, systemIdx),
+                                summaryMsg,
+                                ...messagesToUse.slice(systemIdx),
+                            ];
+                        }
+                    }
+                    catch (err) {
+                        console.error('[Graph] Summarization callback failed:', err);
+                    }
+                }
+            }
+            else if (delegationInjectedPrePrune) {
+                console.info('[Graph] Skipping pruning — delegation will handle context pressure');
+            }
+            let finalMessages = messagesToUse;
+            if (agentContext.useLegacyContent) {
+                finalMessages = formatContentStrings(finalMessages);
+            }
+            const lastMessageX = finalMessages.length >= 2
+                ? finalMessages[finalMessages.length - 2]
+                : null;
+            const lastMessageY = finalMessages.length >= 1
+                ? finalMessages[finalMessages.length - 1]
+                : null;
+            if (agentContext.provider === Providers.BEDROCK &&
+                lastMessageX instanceof AIMessageChunk &&
+                lastMessageY?.getType() === MessageTypes.TOOL &&
+                typeof lastMessageX.content === 'string') {
+                finalMessages[finalMessages.length - 2].content = '';
+            }
+            // Use getType() instead of instanceof to avoid module mismatch issues
+            const isLatestToolMessage = lastMessageY?.getType() === MessageTypes.TOOL;
+            if (isLatestToolMessage &&
+                agentContext.provider === Providers.ANTHROPIC) {
+                formatAnthropicArtifactContent(finalMessages);
+            }
+            else if (isLatestToolMessage &&
+                ((isOpenAILike(agentContext.provider) &&
+                    agentContext.provider !== Providers.DEEPSEEK) ||
+                    isGoogleLike(agentContext.provider))) {
+                formatArtifactPayload(finalMessages);
+            }
+            /**
+             * Handle edge case: when switching from a non-thinking agent to a thinking-enabled agent,
+             * convert AI messages with tool calls to HumanMessages to avoid thinking block requirements.
+             * This is required by Anthropic/Bedrock when thinking is enabled.
+             *
+             * IMPORTANT: This MUST happen BEFORE cache control is applied.
+             * If we add cachePoint to an AI message first, then convert that AI message to a HumanMessage,
+             * the cachePoint is lost. By converting first, we ensure cache control is applied to the
+             * final message structure that will be sent to the API.
+             */
+            const isAnthropicWithThinking = (agentContext.provider === Providers.ANTHROPIC &&
+                agentContext.clientOptions.thinking !=
+                    null) ||
+                (agentContext.provider === Providers.BEDROCK &&
+                    agentContext.clientOptions
+                        .additionalModelRequestFields?.['thinking'] != null);
+            if (isAnthropicWithThinking) {
+                finalMessages = ensureThinkingBlockInMessages(finalMessages, agentContext.provider);
+            }
+            // Apply cache control AFTER thinking block handling to ensure cachePoints aren't lost
+            // when AI messages are converted to HumanMessages
+            if (agentContext.provider === Providers.ANTHROPIC) {
+                const anthropicOptions = agentContext.clientOptions;
+                if (anthropicOptions?.promptCache === true) {
+                    finalMessages = addCacheControl(finalMessages);
+                }
+            }
+            else if (agentContext.provider === Providers.BEDROCK) {
+                const bedrockOptions = agentContext.clientOptions;
+                // Both Claude and Nova models support cachePoint in system and messages
+                // (Llama, Titan, and other models do NOT support cachePoint)
+                const modelId = bedrockOptions?.model?.toLowerCase() ?? '';
+                const supportsCaching = modelId.includes('claude') ||
+                    modelId.includes('anthropic') ||
+                    modelId.includes('nova');
+                if (bedrockOptions?.promptCache === true && supportsCaching) {
+                    finalMessages = addBedrockCacheControl(finalMessages);
+                }
+            }
+            if (agentContext.lastStreamCall != null &&
+                agentContext.streamBuffer != null) {
+                const timeSinceLastCall = Date.now() - agentContext.lastStreamCall;
+                if (timeSinceLastCall < agentContext.streamBuffer) {
+                    const timeToWait = Math.ceil((agentContext.streamBuffer - timeSinceLastCall) / 1000) *
+                        1000;
+                    await sleep(timeToWait);
+                }
+            }
+            agentContext.lastStreamCall = Date.now();
+            let result;
+            const fallbacks = agentContext.clientOptions?.fallbacks ??
+                [];
+            if (finalMessages.length === 0) {
+                throw new Error(JSON.stringify({
+                    type: 'empty_messages',
+                    info: 'Message pruning removed all messages as none fit in the context window. Please increase the context window size or make your message shorter.',
+                }));
+            }
+            // Get model info for analytics
+            const bedrockOpts = agentContext.clientOptions;
+            const modelId = bedrockOpts?.model ||
+                agentContext.clientOptions
+                    ?.modelName;
+            const thinkingConfig = bedrockOpts?.additionalModelRequestFields?.['thinking'] ||
+                agentContext.clientOptions
+                    ?.thinking;
+            // Build and emit context analytics for traces
+            const contextAnalytics = buildContextAnalytics(finalMessages, {
+                tokenCounter: agentContext.tokenCounter,
+                maxContextTokens: agentContext.maxContextTokens,
+                instructionTokens: agentContext.instructionTokens,
+                indexTokenCountMap: agentContext.indexTokenCountMap,
+            });
+            // Store for retrieval via getContextAnalytics() after run completes
+            this.lastContextAnalytics = contextAnalytics;
+            await safeDispatchCustomEvent(GraphEvents.ON_CONTEXT_ANALYTICS, {
+                provider: agentContext.provider,
+                model: modelId,
+                thinkingEnabled: thinkingConfig != null,
+                cacheEnabled: bedrockOpts?.promptCache === true,
+                analytics: contextAnalytics,
+            }, config);
+            // ====================================================================
+            // CONTEXT PRESSURE AWARENESS — Intelligent Sub-Agent Delegation
+            //
+            // Two triggers for delegation hints:
+            // 1. DOCUMENT COUNT: When 3+ documents are detected in the conversation,
+            //    inject a delegation hint on the FIRST iteration (before the LLM
+            //    has called any tools). This ensures the agent delegates upfront
+            //    rather than trying to process all documents itself.
+            // 2. TOKEN UTILIZATION: At EVERY iteration, if context is filling up
+            //    (70%/85%), inject escalating hints to delegate remaining work.
+            //
+            // This runs mid-chain — so even if tool responses push context up
+            // after the first LLM call, subsequent iterations get the hint.
+            // ====================================================================
+            const hasTaskToolInContext = agentContext.tools?.some((tool) => {
+                const toolName = typeof tool === 'object' && 'name' in tool
+                    ? tool.name
+                    : '';
+                return toolName === 'task';
+            });
+            if (hasTaskToolInContext &&
+                contextAnalytics.utilizationPercent != null &&
+                contextAnalytics.maxContextTokens != null) {
+                const utilization = contextAnalytics.utilizationPercent;
+                const totalTokens = contextAnalytics.totalTokens;
+                const maxTokens = contextAnalytics.maxContextTokens;
+                const remainingTokens = maxTokens - totalTokens;
+                // Count attached documents by scanning for document patterns in HumanMessages:
+                // 1. # "filename" headers in "Attached document(s):" blocks (text content)
+                // 2. **filename1, filename2** in "The user has attached:" blocks (embedded files)
+                // 3. Filenames in file_search tool results
+                let documentCount = 0;
+                const documentNames = [];
+                for (const msg of finalMessages) {
+                    const content = typeof msg.content === 'string'
+                        ? msg.content
+                        : Array.isArray(msg.content)
+                            ? msg.content.map((p) => {
+                                const part = p;
+                                return String(part.text || part.content || '');
+                            }).join(' ')
+                            : '';
+                    // Pattern 1: # "filename" headers in attached document blocks
+                    const docMatches = content.match(/# "([^"]+)"/g);
+                    if (docMatches) {
+                        for (const match of docMatches) {
+                            const name = match.replace(/# "/, '').replace(/"$/, '');
+                            if (!documentNames.includes(name)) {
+                                documentNames.push(name);
+                                documentCount++;
+                            }
+                        }
+                    }
+                    // Pattern 2: "The user has attached: **file1, file2**" (embedded files)
+                    const attachedMatch = content.match(/user has attached:\s*\*\*([^*]+)\*\*/i);
+                    if (attachedMatch) {
+                        const names = attachedMatch[1].split(',').map((n) => n.trim()).filter(Boolean);
+                        for (const name of names) {
+                            if (!documentNames.includes(name)) {
+                                documentNames.push(name);
+                                documentCount++;
+                            }
+                        }
+                    }
+                }
+                // BASELINE LOG: Always fires so we can verify this code path runs
+                console.info(`[Graph] Context utilization: ${utilization.toFixed(1)}% ` +
+                    `(${totalTokens}/${maxTokens} tokens, ${remainingTokens} remaining) | ` +
+                    `hasTaskTool: true | messages: ${finalMessages.length} | docs: ${documentCount}`);
+                // TRIGGER 1: Multi-document delegation (3+ documents detected)
+                // Only inject on first iteration (no AI messages yet = agent hasn't responded)
+                const hasAiResponse = finalMessages.some((m) => m._getType?.() === 'ai' || m._getType?.() === 'tool');
+                if (documentCount >= 3 && !hasAiResponse) {
+                    const pressureMsg = new HumanMessage({
+                        content: `[MULTI-DOCUMENT PROCESSING — ${documentCount} documents detected]\n` +
+                            `Documents: ${documentNames.join(', ')}\n\n` +
+                            `You have ${documentCount} documents attached. For thorough analysis, use the "task" tool ` +
+                            `to delegate each document (or group of related documents) to a sub-agent.\n` +
+                            `Each sub-agent has its own fresh context window and can use file_search to retrieve the full document content.\n` +
+                            `After all sub-agents complete, synthesize their results into a comprehensive response.\n\n` +
+                            `This approach ensures each document gets full attention without context limitations.`,
+                    });
+                    finalMessages = [...finalMessages, pressureMsg];
+                    console.info(`[Graph] Multi-document delegation hint injected for ${documentCount} documents: ` +
+                        `${documentNames.join(', ')}`);
+                }
+                // TRIGGER 2: Token utilization thresholds (mid-chain safety net)
+                // Also fires when we skipped pruning due to delegationInjectedPrePrune
+                if (utilization > 85 || (delegationInjectedPrePrune && utilization > 50)) {
+                    // CRITICAL: Context is high — MANDATE delegation
+                    const pressureMsg = new HumanMessage({
+                        content: `[CONTEXT BUDGET CRITICAL — ${utilization.toFixed(0)}% used]\n` +
+                            `You have used ${totalTokens} of ${maxTokens} tokens (${remainingTokens} remaining).\n` +
+                            `Your context is very large. You MUST use the "task" tool to delegate work to sub-agents.\n` +
+                            `Each sub-agent runs in its own fresh context window and can use file_search to access documents.\n` +
+                            `Do NOT attempt to process documents directly — delegate each document to a sub-agent, then synthesize results.`,
+                    });
+                    finalMessages = [...finalMessages, pressureMsg];
+                    console.warn(`[Graph] Context pressure CRITICAL (${utilization.toFixed(0)}%): ` +
+                        `Injected mandatory delegation hint. ${remainingTokens} tokens remaining. ` +
+                        `prePruneSkipped: ${delegationInjectedPrePrune}`);
+                }
+                else if (utilization > 70) {
+                    // WARNING: Context filling up — suggest delegation
+                    const pressureMsg = new HumanMessage({
+                        content: `[CONTEXT BUDGET WARNING — ${utilization.toFixed(0)}% used]\n` +
+                            `You have used ${totalTokens} of ${maxTokens} tokens (${remainingTokens} remaining).\n` +
+                            `Your context is filling up. Consider using the "task" tool to delegate complex operations to sub-agents.\n` +
+                            `Sub-agents run in fresh context windows and won't consume your remaining budget.`,
+                    });
+                    finalMessages = [...finalMessages, pressureMsg];
+                    console.info(`[Graph] Context pressure WARNING (${utilization.toFixed(0)}%): ` +
+                        `Injected delegation suggestion. ${remainingTokens} tokens remaining.`);
+                }
+            }
+            // Structured output mode: when the agent has NO tools, produce structured JSON immediately.
+            // When the agent HAS tools, we defer structured output until after tool use completes
+            // (see the deferred structured output block after attemptInvoke below).
+            const hasTools = (toolsForBinding?.length ?? 0) > 0;
+            if (agentContext.isStructuredOutputMode &&
+                agentContext.structuredOutput &&
+                !hasTools) {
+                try {
+                    const structuredResult = await this.performStructuredOutput({
+                        agentContext,
+                        finalMessages,
+                        config,
+                    });
+                    agentContext.currentUsage = this.getUsageMetadata(structuredResult.messages?.[0]);
+                    this.cleanupSignalListener();
+                    return structuredResult;
+                }
+                catch (structuredError) {
+                    console.error('[Graph] Structured output failed:', structuredError);
+                    throw structuredError;
+                }
+            }
+            try {
+                result = await this.attemptInvoke({
+                    currentModel: model,
+                    finalMessages,
+                    provider: agentContext.provider,
+                    tools: agentContext.tools,
+                }, config);
+            }
+            catch (primaryError) {
+                // Check if this is a "input too long" error from Bedrock/Anthropic
+                const errorMessage = primaryError.message.toLowerCase() ?? '';
+                const isInputTooLongError = errorMessage.includes('too long') ||
+                    errorMessage.includes('input is too long') ||
+                    errorMessage.includes('context length') ||
+                    errorMessage.includes('maximum context') ||
+                    errorMessage.includes('validationexception') ||
+                    errorMessage.includes('prompt is too long');
+                // Log when we detect the error
+                if (isInputTooLongError) {
+                    console.warn('[Graph] Detected input too long error:', errorMessage.substring(0, 200));
+                    console.warn('[Graph] Checking emergency pruning conditions:', {
+                        hasPruneMessages: !!agentContext.pruneMessages,
+                        hasTokenCounter: !!agentContext.tokenCounter,
+                        maxContextTokens: agentContext.maxContextTokens,
+                        indexTokenMapKeys: Object.keys(agentContext.indexTokenCountMap)
+                            .length,
+                    });
+                }
+                // If input too long and we have pruning capability OR tokenCounter, retry with progressively more aggressive pruning
+                // Note: We can create emergency pruneMessages dynamically if we have tokenCounter and maxContextTokens
+                const canPrune = agentContext.tokenCounter && agentContext.maxContextTokens;
+                if (isInputTooLongError && canPrune) {
+                    // Progressive reduction: 50% -> 25% -> 10% of original context
+                    const reductionLevels = [0.5, 0.25, 0.1];
+                    for (const reductionFactor of reductionLevels) {
+                        if (result)
+                            break; // Exit if we got a result
+                        const reducedMaxTokens = Math.floor(agentContext.maxContextTokens * reductionFactor);
+                        console.warn(`[Graph] Input too long. Retrying with ${reductionFactor * 100}% context (${reducedMaxTokens} tokens)...`);
+                        // Build fresh indexTokenCountMap if missing/incomplete
+                        // This is needed when messages were dynamically added without updating the token map
+                        let tokenMapForPruning = agentContext.indexTokenCountMap;
+                        if (Object.keys(tokenMapForPruning).length < messages.length) {
+                            console.warn('[Graph] Building fresh token count map for emergency pruning...');
+                            tokenMapForPruning = {};
+                            for (let i = 0; i < messages.length; i++) {
+                                tokenMapForPruning[i] = agentContext.tokenCounter(messages[i]);
+                            }
+                        }
+                        const emergencyPrune = createPruneMessages({
+                            startIndex: this.startIndex,
+                            provider: agentContext.provider,
+                            tokenCounter: agentContext.tokenCounter,
+                            maxTokens: reducedMaxTokens,
+                            thinkingEnabled: false, // Disable thinking for emergency prune
+                            indexTokenCountMap: tokenMapForPruning,
+                        });
+                        const { context: reducedMessages } = emergencyPrune({
+                            messages,
+                            usageMetadata: agentContext.currentUsage,
+                        });
+                        // Skip if we can't fit any messages
+                        if (reducedMessages.length === 0) {
+                            console.warn(`[Graph] Cannot fit any messages at ${reductionFactor * 100}% reduction, trying next level...`);
+                            continue;
+                        }
+                        // Calculate how many messages were pruned and estimate context timeframe
+                        const prunedCount = finalMessages.length - reducedMessages.length;
+                        const remainingCount = reducedMessages.length;
+                        const estimatedContextDescription = this.getContextTimeframeDescription(remainingCount);
+                        // Inject a personalized context message to inform the agent about pruning
+                        const pruneNoticeMessage = new HumanMessage({
+                            content: `[CONTEXT NOTICE]
+Our conversation has grown quite long, so I've focused on ${estimatedContextDescription} of our chat (${remainingCount} recent messages). ${prunedCount} earlier messages are no longer in my immediate memory.
+
+If I seem to be missing something we discussed earlier, just give me a quick reminder and I'll pick right back up! I'm still fully engaged and ready to help with whatever you need.`,
+                        });
+                        // Insert the notice after the system message (if any) but before conversation
+                        const hasSystemMessage = reducedMessages[0]?.getType() === 'system';
+                        const insertIndex = hasSystemMessage ? 1 : 0;
+                        // Create new array with the pruning notice
+                        const messagesWithNotice = [
+                            ...reducedMessages.slice(0, insertIndex),
+                            pruneNoticeMessage,
+                            ...reducedMessages.slice(insertIndex),
+                        ];
+                        let retryMessages = agentContext.useLegacyContent
+                            ? formatContentStrings(messagesWithNotice)
+                            : messagesWithNotice;
+                        // Apply thinking block handling first (before cache control)
+                        // This ensures AI+Tool sequences are converted to HumanMessages
+                        // before we add cache points that could be lost in the conversion
+                        if (isAnthropicWithThinking) {
+                            retryMessages = ensureThinkingBlockInMessages(retryMessages, agentContext.provider);
+                        }
+                        // Apply Bedrock cache control if needed (after thinking block handling)
+                        if (agentContext.provider === Providers.BEDROCK) {
+                            const bedrockOptions = agentContext.clientOptions;
+                            const modelId = bedrockOptions?.model?.toLowerCase() ?? '';
+                            const supportsCaching = modelId.includes('claude') ||
+                                modelId.includes('anthropic') ||
+                                modelId.includes('nova');
+                            if (bedrockOptions?.promptCache === true && supportsCaching) {
+                                retryMessages =
+                                    addBedrockCacheControl(retryMessages);
+                            }
+                        }
+                        try {
+                            result = await this.attemptInvoke({
+                                currentModel: model,
+                                finalMessages: retryMessages,
+                                provider: agentContext.provider,
+                                tools: agentContext.tools,
+                            }, config);
+                            // Success with reduced context
+                            console.info(`[Graph] ✅ Retry successful at ${reductionFactor * 100}% with ${reducedMessages.length} messages (reduced from ${finalMessages.length})`);
+                        }
+                        catch (retryError) {
+                            const retryErrorMsg = retryError.message.toLowerCase() ?? '';
+                            const stillTooLong = retryErrorMsg.includes('too long') ||
+                                retryErrorMsg.includes('context length') ||
+                                retryErrorMsg.includes('validationexception');
+                            if (stillTooLong && reductionFactor > 0.1) {
+                                console.warn(`[Graph] Still too long at ${reductionFactor * 100}%, trying more aggressive pruning...`);
+                            }
+                            else {
+                                console.error(`[Graph] Retry at ${reductionFactor * 100}% failed:`, retryError.message);
+                            }
+                        }
+                    }
+                }
+                // If we got a result from retry, skip fallbacks
+                if (result) ;
+                else {
+                    let lastError = primaryError;
+                    for (const fb of fallbacks) {
+                        try {
+                            let model = this.getNewModel({
+                                provider: fb.provider,
+                                clientOptions: fb.clientOptions,
+                            });
+                            const bindableTools = agentContext.tools;
+                            model = (!bindableTools || bindableTools.length === 0
+                                ? model
+                                : model.bindTools(bindableTools));
+                            result = await this.attemptInvoke({
+                                currentModel: model,
+                                finalMessages,
+                                provider: fb.provider,
+                                tools: agentContext.tools,
+                            }, config);
+                            lastError = undefined;
+                            break;
+                        }
+                        catch (e) {
+                            lastError = e;
+                            continue;
+                        }
+                    }
+                    if (lastError !== undefined) {
+                        throw lastError;
+                    }
+                }
+            }
+            if (!result) {
+                throw new Error('No result after model invocation');
+            }
+            agentContext.currentUsage = this.getUsageMetadata(result.messages?.[0]);
+            // Extract and normalize the LLM's finish/stop reason for auto-continuation support
+            const finalMsg = result.messages?.[0];
+            if (finalMsg && 'response_metadata' in finalMsg) {
+                const meta = finalMsg.response_metadata;
+                // Bedrock streaming nests stopReason inside messageStop: { stopReason: '...' }
+                const messageStop = meta.messageStop;
+                this.lastFinishReason =
+                    meta.finish_reason ?? // OpenAI/Azure
+                        meta.stop_reason ?? // Anthropic direct API
+                        meta.stopReason ?? // Bedrock invoke (non-streaming)
+                        messageStop?.stopReason ?? // Bedrock streaming
+                        meta.finishReason ?? // VertexAI/Google
+                        undefined;
+            }
+            this.cleanupSignalListener();
+            // DEFERRED STRUCTURED OUTPUT: When the agent has tools AND structured output configured,
+            // we let the agent use tools normally via attemptInvoke(). Once the agent's response
+            // has NO tool_calls (it's done with tools), we produce the final structured JSON response.
+            if (agentContext.isStructuredOutputMode &&
+                agentContext.structuredOutput &&
+                result) {
+                const lastMessage = result.messages?.[0];
+                const resultHasToolCalls = lastMessage &&
+                    'tool_calls' in lastMessage &&
+                    (lastMessage.tool_calls?.length ?? 0) > 0;
+                if (!resultHasToolCalls) {
+                    try {
+                        // Build messages for structured output: include the full conversation
+                        // plus the agent's text response from attemptInvoke, so the structured
+                        // output model has full context (tool results + agent reasoning).
+                        const messagesForStructured = [...finalMessages];
+                        if (lastMessage) {
+                            messagesForStructured.push(lastMessage);
+                        }
+                        const structuredResult = await this.performStructuredOutput({
+                            agentContext,
+                            finalMessages: messagesForStructured,
+                            config,
+                        });
+                        // Accumulate token usage from both API calls
+                        const structuredUsage = this.getUsageMetadata(structuredResult.messages?.[0]);
+                        if (structuredUsage && agentContext.currentUsage) {
+                            agentContext.currentUsage = {
+                                input_tokens: (agentContext.currentUsage.input_tokens ?? 0) +
+                                    (structuredUsage.input_tokens ?? 0),
+                                output_tokens: (agentContext.currentUsage.output_tokens ?? 0) +
+                                    (structuredUsage.output_tokens ?? 0),
+                                total_tokens: (agentContext.currentUsage.total_tokens ?? 0) +
+                                    (structuredUsage.total_tokens ?? 0),
+                            };
+                        }
+                        else if (structuredUsage) {
+                            agentContext.currentUsage = structuredUsage;
+                        }
+                        return structuredResult;
+                    }
+                    catch (structuredError) {
+                        // Graceful fallback: the agent completed its work with tools,
+                        // but we couldn't format the output as structured JSON.
+                        // Return the unstructured text response from attemptInvoke.
+                        console.error('[Graph] Deferred structured output failed after successful tool use:', structuredError);
+                        console.warn('[Graph] Falling back to unstructured response from tool-use phase');
+                        return result;
+                    }
+                }
+            }
+            return result;
+        };
+    }
+    createAgentNode(agentId) {
+        const agentContext = this.agentContexts.get(agentId);
+        if (!agentContext) {
+            throw new Error(`Agent context not found for agentId: ${agentId}`);
+        }
+        const agentNode = `${AGENT}${agentId}`;
+        const toolNode = `${TOOLS}${agentId}`;
+        const routeMessage = (state, config) => {
+            this.config = config;
+            return toolsCondition(state, toolNode, this.invokedToolIds);
+        };
+        const StateAnnotation = Annotation.Root({
+            messages: Annotation({
+                reducer: messagesStateReducer,
+                default: () => [],
+            }),
+        });
+        const workflow = new StateGraph(StateAnnotation)
+            .addNode(agentNode, this.createCallModel(agentId))
+            .addNode(toolNode, this.initializeTools({
+            currentTools: agentContext.tools,
+            currentToolMap: agentContext.toolMap,
+            agentContext,
+        }))
+            .addEdge(START, agentNode)
+            .addConditionalEdges(agentNode, routeMessage)
+            .addEdge(toolNode, agentContext.toolEnd ? END : agentNode);
+        // Cast to unknown to avoid tight coupling to external types; options are opt-in
+        return workflow.compile(this.compileOptions);
+    }
+    createWorkflow() {
+        /** Use the default (first) agent for now */
+        const agentNode = this.createAgentNode(this.defaultAgentId);
+        const StateAnnotation = Annotation.Root({
+            messages: Annotation({
+                reducer: (a, b) => {
+                    if (!a.length) {
+                        this.startIndex = a.length + b.length;
+                    }
+                    const result = messagesStateReducer(a, b);
+                    this.messages = result;
+                    return result;
+                },
+                default: () => [],
+            }),
+        });
+        const workflow = new StateGraph(StateAnnotation)
+            .addNode(this.defaultAgentId, agentNode, { ends: [END] })
+            .addEdge(START, this.defaultAgentId)
+            .compile();
+        return workflow;
+    }
+    /**
+     * Indicates if this is a multi-agent graph.
+     * Override in MultiAgentGraph to return true.
+     * Used to conditionally include agentId in RunStep for frontend rendering.
+     */
+    isMultiAgentGraph() {
+        return false;
+    }
+    /**
+     * Get the parallel group ID for an agent, if any.
+     * Override in MultiAgentGraph to provide actual group IDs.
+     * Group IDs are incrementing numbers (1, 2, 3...) reflecting execution order.
+     * @param _agentId - The agent ID to look up
+     * @returns undefined for StandardGraph (no parallel groups), or group number for MultiAgentGraph
+     */
+    getParallelGroupIdForAgent(_agentId) {
+        return undefined;
+    }
+    /* Dispatchers */
+    /**
+     * Dispatches a run step to the client, returns the step ID
+     */
+    async dispatchRunStep(stepKey, stepDetails, metadata) {
+        if (!this.config) {
+            throw new Error('No config provided');
+        }
+        const [stepId, stepIndex] = this.generateStepId(stepKey);
+        if (stepDetails.type === StepTypes.TOOL_CALLS && stepDetails.tool_calls) {
+            for (const tool_call of stepDetails.tool_calls) {
+                const toolCallId = tool_call.id ?? '';
+                if (!toolCallId || this.toolCallStepIds.has(toolCallId)) {
+                    continue;
+                }
+                this.toolCallStepIds.set(toolCallId, stepId);
+            }
+        }
+        const runStep = {
+            stepIndex,
+            id: stepId,
+            type: stepDetails.type,
+            index: this.contentData.length,
+            stepDetails,
+            usage: null,
+        };
+        const runId = this.runId ?? '';
+        if (runId) {
+            runStep.runId = runId;
+        }
+        /**
+         * Extract agentId and parallelGroupId from metadata
+         * Only set agentId for MultiAgentGraph (so frontend knows when to show agent labels)
+         */
+        if (metadata) {
+            try {
+                const agentContext = this.getAgentContext(metadata);
+                if (this.isMultiAgentGraph() && agentContext.agentId) {
+                    // Only include agentId for MultiAgentGraph - enables frontend to show agent labels
+                    runStep.agentId = agentContext.agentId;
+                    // Set group ID if this agent is part of a parallel group
+                    // Group IDs are incrementing numbers (1, 2, 3...) reflecting execution order
+                    const groupId = this.getParallelGroupIdForAgent(agentContext.agentId);
+                    if (groupId != null) {
+                        runStep.groupId = groupId;
+                    }
+                }
+            }
+            catch (_e) {
+                /** If we can't get agent context, that's okay - agentId remains undefined */
+            }
+        }
+        this.contentData.push(runStep);
+        this.contentIndexMap.set(stepId, runStep.index);
+        await safeDispatchCustomEvent(GraphEvents.ON_RUN_STEP, runStep, this.config);
+        return stepId;
+    }
+    async handleToolCallCompleted(data, metadata, omitOutput) {
+        if (!this.config) {
+            throw new Error('No config provided');
+        }
+        if (!data.output) {
+            return;
+        }
+        const { input, output: _output } = data;
+        if (_output?.lg_name === 'Command') {
+            return;
+        }
+        const output = _output;
+        const { tool_call_id } = output;
+        const stepId = this.toolCallStepIds.get(tool_call_id) ?? '';
+        if (!stepId) {
+            throw new Error(`No stepId found for tool_call_id ${tool_call_id}`);
+        }
+        const runStep = this.getRunStep(stepId);
+        if (!runStep) {
+            throw new Error(`No run step found for stepId ${stepId}`);
+        }
+        /**
+         * Extract and store code execution session context from artifacts.
+         * Each file is stamped with its source session_id to support multi-session file tracking.
+         * When the same filename appears in a later execution, the newer version replaces the old.
+         */
+        const toolName = output.name;
+        if (toolName === Constants.EXECUTE_CODE ||
+            toolName === Constants.PROGRAMMATIC_TOOL_CALLING) {
+            const artifact = output.artifact;
+            const newFiles = artifact?.files ?? [];
+            const hasNewFiles = newFiles.length > 0;
+            if (hasNewFiles &&
+                artifact?.session_id != null &&
+                artifact.session_id !== '') {
+                /**
+                 * Stamp each new file with its source session_id.
+                 * This enables files from different executions (parallel or sequential)
+                 * to be tracked and passed to subsequent calls.
+                 */
+                const filesWithSession = newFiles.map((file) => ({
+                    ...file,
+                    session_id: artifact.session_id,
+                }));
+                const existingSession = this.sessions.get(Constants.EXECUTE_CODE);
+                const existingFiles = existingSession?.files ?? [];
+                /**
+                 * Merge files, preferring latest versions by name.
+                 * If a file with the same name exists, replace it with the new version.
+                 * This handles cases where files are edited/recreated in subsequent executions.
+                 */
+                const newFileNames = new Set(filesWithSession.map((f) => f.name));
+                const filteredExisting = existingFiles.filter((f) => !newFileNames.has(f.name));
+                this.sessions.set(Constants.EXECUTE_CODE, {
+                    /** Keep latest session_id for reference/fallback */
+                    session_id: artifact.session_id,
+                    /** Accumulated files with latest versions preferred */
+                    files: [...filteredExisting, ...filesWithSession],
+                    lastUpdated: Date.now(),
+                });
+            }
+        }
+        const dispatchedOutput = typeof output.content === 'string'
+            ? output.content
+            : JSON.stringify(output.content);
+        const args = typeof input === 'string' ? input : input.input;
+        const tool_call = {
+            args: typeof args === 'string' ? args : JSON.stringify(args),
+            name: output.name ?? '',
+            id: output.tool_call_id,
+            output: omitOutput === true ? '' : dispatchedOutput,
+            progress: 1,
+        };
+        await this.handlerRegistry
+            ?.getHandler(GraphEvents.ON_RUN_STEP_COMPLETED)
+            ?.handle(GraphEvents.ON_RUN_STEP_COMPLETED, {
+            result: {
+                id: stepId,
+                index: runStep.index,
+                type: 'tool_call',
+                tool_call,
+            },
+        }, metadata, this);
+    }
+    /**
+     * Static version of handleToolCallError to avoid creating strong references
+     * that prevent garbage collection
+     */
+    static async handleToolCallErrorStatic(graph, data, metadata) {
+        if (!graph.config) {
+            throw new Error('No config provided');
+        }
+        if (!data.id) {
+            console.warn('No Tool ID provided for Tool Error');
+            return;
+        }
+        const stepId = graph.toolCallStepIds.get(data.id) ?? '';
+        if (!stepId) {
+            throw new Error(`No stepId found for tool_call_id ${data.id}`);
+        }
+        const { name, input: args, error } = data;
+        const runStep = graph.getRunStep(stepId);
+        if (!runStep) {
+            throw new Error(`No run step found for stepId ${stepId}`);
+        }
+        const tool_call = {
+            id: data.id,
+            name: name || '',
+            args: typeof args === 'string' ? args : JSON.stringify(args),
+            output: `Error processing tool${error?.message != null ? `: ${error.message}` : ''}`,
+            progress: 1,
+        };
+        await graph.handlerRegistry
+            ?.getHandler(GraphEvents.ON_RUN_STEP_COMPLETED)
+            ?.handle(GraphEvents.ON_RUN_STEP_COMPLETED, {
+            result: {
+                id: stepId,
+                index: runStep.index,
+                type: 'tool_call',
+                tool_call,
+            },
+        }, metadata, graph);
+    }
+    /**
+     * Instance method that delegates to the static method
+     * Kept for backward compatibility
+     */
+    async handleToolCallError(data, metadata) {
+        await StandardGraph.handleToolCallErrorStatic(this, data, metadata);
+    }
+    async dispatchRunStepDelta(id, delta) {
+        if (!this.config) {
+            throw new Error('No config provided');
+        }
+        else if (!id) {
+            throw new Error('No step ID found');
+        }
+        const runStepDelta = {
+            id,
+            delta,
+        };
+        await safeDispatchCustomEvent(GraphEvents.ON_RUN_STEP_DELTA, runStepDelta, this.config);
+    }
+    async dispatchMessageDelta(id, delta) {
+        if (!this.config) {
+            throw new Error('No config provided');
+        }
+        const messageDelta = {
+            id,
+            delta,
+        };
+        await safeDispatchCustomEvent(GraphEvents.ON_MESSAGE_DELTA, messageDelta, this.config);
+    }
+    dispatchReasoningDelta = async (stepId, delta) => {
+        if (!this.config) {
+            throw new Error('No config provided');
+        }
+        const reasoningDelta = {
+            id: stepId,
+            delta,
+        };
+        await safeDispatchCustomEvent(GraphEvents.ON_REASONING_DELTA, reasoningDelta, this.config);
+    };
+}
+
+export { Graph, StandardGraph };
+//# sourceMappingURL=Graph.mjs.map