@illuma-ai/agents 1.0.81

package/src/graphs/Graph.ts

@@ -0,0 +1,2228 @@
+/* eslint-disable no-console */
+// src/graphs/Graph.ts
+import { nanoid } from 'nanoid';
+import { concat } from '@langchain/core/utils/stream';
+import { ToolNode } from '@langchain/langgraph/prebuilt';
+import { ChatVertexAI } from '@langchain/google-vertexai';
+import {
+  START,
+  END,
+  Command,
+  StateGraph,
+  Annotation,
+  messagesStateReducer,
+} from '@langchain/langgraph';
+import {
+  Runnable,
+  RunnableConfig,
+  RunnableLambda,
+} from '@langchain/core/runnables';
+import {
+  ToolMessage,
+  SystemMessage,
+  AIMessageChunk,
+  HumanMessage,
+} from '@langchain/core/messages';
+import type {
+  BaseMessageFields,
+  UsageMetadata,
+  BaseMessage,
+} from '@langchain/core/messages';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type * as t from '@/types';
+import {
+  GraphNodeKeys,
+  ContentTypes,
+  GraphEvents,
+  Providers,
+  StepTypes,
+  MessageTypes,
+  Constants,
+} from '@/common';
+import {
+  formatAnthropicArtifactContent,
+  ensureThinkingBlockInMessages,
+  convertMessagesToContent,
+  addBedrockCacheControl,
+  modifyDeltaProperties,
+  formatArtifactPayload,
+  formatContentStrings,
+  createPruneMessages,
+  addCacheControl,
+  extractToolDiscoveries,
+} from '@/messages';
+import {
+  resetIfNotEmpty,
+  isOpenAILike,
+  isGoogleLike,
+  joinKeys,
+  sleep,
+} from '@/utils';
+import {
+  buildContextAnalytics,
+  type ContextAnalytics,
+} from '@/utils/contextAnalytics';
+import { getChatModelClass, manualToolStreamProviders } from '@/llm/providers';
+import { ToolNode as CustomToolNode, toolsCondition } from '@/tools/ToolNode';
+import { ChatOpenAI, AzureChatOpenAI } from '@/llm/openai';
+import { safeDispatchCustomEvent } from '@/utils/events';
+import { createSchemaOnlyTools } from '@/tools/schema';
+import { prepareSchemaForProvider } from '@/schemas/validate';
+import { AgentContext } from '@/agents/AgentContext';
+import { StructuredOutputRefusalError, StructuredOutputTruncatedError } from '@/types/graph';
+import { createFakeStreamingLLM } from '@/llm/fake';
+import { HandlerRegistry } from '@/events';
+
+const { AGENT, TOOLS } = GraphNodeKeys;
+
+export abstract class Graph<
+  T extends t.BaseGraphState = t.BaseGraphState,
+  _TNodeName extends string = string,
+> {
+  abstract resetValues(): void;
+  abstract initializeTools({
+    currentTools,
+    currentToolMap,
+  }: {
+    currentTools?: t.GraphTools;
+    currentToolMap?: t.ToolMap;
+  }): CustomToolNode<T> | ToolNode<T>;
+  abstract initializeModel({
+    currentModel,
+    tools,
+    clientOptions,
+  }: {
+    currentModel?: t.ChatModel;
+    tools?: t.GraphTools;
+    clientOptions?: t.ClientOptions;
+  }): Runnable;
+  abstract getRunMessages(): BaseMessage[] | undefined;
+  abstract getContentParts(): t.MessageContentComplex[] | undefined;
+  abstract generateStepId(stepKey: string): [string, number];
+  abstract getKeyList(
+    metadata: Record<string, unknown> | undefined
+  ): (string | number | undefined)[];
+  abstract getStepKey(metadata: Record<string, unknown> | undefined): string;
+  abstract checkKeyList(keyList: (string | number | undefined)[]): boolean;
+  abstract getStepIdByKey(stepKey: string, index?: number): string;
+  abstract getRunStep(stepId: string): t.RunStep | undefined;
+  abstract dispatchRunStep(
+    stepKey: string,
+    stepDetails: t.StepDetails,
+    metadata?: Record<string, unknown>
+  ): Promise<string>;
+  abstract dispatchRunStepDelta(
+    id: string,
+    delta: t.ToolCallDelta
+  ): Promise<void>;
+  abstract dispatchMessageDelta(
+    id: string,
+    delta: t.MessageDelta
+  ): Promise<void>;
+  abstract dispatchReasoningDelta(
+    stepId: string,
+    delta: t.ReasoningDelta
+  ): Promise<void>;
+  abstract handleToolCallCompleted(
+    data: t.ToolEndData,
+    metadata?: Record<string, unknown>,
+    omitOutput?: boolean
+  ): Promise<void>;
+
+  abstract createCallModel(
+    agentId?: string,
+    currentModel?: t.ChatModel
+  ): (state: T, config?: RunnableConfig) => Promise<Partial<T>>;
+  messageStepHasToolCalls: Map<string, boolean> = new Map();
+  messageIdsByStepKey: Map<string, string> = new Map();
+  prelimMessageIdsByStepKey: Map<string, string> = new Map();
+  config: RunnableConfig | undefined;
+  contentData: t.RunStep[] = [];
+  stepKeyIds: Map<string, string[]> = new Map<string, string[]>();
+  contentIndexMap: Map<string, number> = new Map();
+  toolCallStepIds: Map<string, string> = new Map();
+  signal?: AbortSignal;
+  /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
+  invokedToolIds?: Set<string>;
+  handlerRegistry: HandlerRegistry | undefined;
+  /**
+   * 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: t.ToolSessionMap = new Map();
+}
+
+export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
+  overrideModel?: t.ChatModel;
+  /** Optional compile options passed into workflow.compile() */
+  compileOptions?: t.CompileOptions | undefined;
+  messages: BaseMessage[] = [];
+  runId: string | undefined;
+  startIndex: number = 0;
+  signal?: AbortSignal;
+  /** Map of agent contexts by agent ID */
+  agentContexts: Map<string, AgentContext> = new Map();
+  /** Default agent ID to use */
+  defaultAgentId: string;
+  /** Normalized finish/stop reason from the last LLM invocation */
+  lastFinishReason: string | undefined;
+
+  constructor({
+    // parent-level graph inputs
+    runId,
+    signal,
+    agents,
+    tokenCounter,
+    indexTokenCountMap,
+  }: t.StandardGraphInput) {
+    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?: boolean): void {
+    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(): string | undefined {
+    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: number): string {
+    // 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: string): t.RunStep | undefined {
+    const index = this.contentIndexMap.get(stepId);
+    if (index !== undefined) {
+      return this.contentData[index];
+    }
+    return undefined;
+  }
+
+  getAgentContext(metadata: Record<string, unknown> | undefined): AgentContext {
+    if (!metadata) {
+      throw new Error('No metadata provided to retrieve agent context');
+    }
+
+    const currentNode = metadata.langgraph_node as string;
+    if (!currentNode) {
+      throw new Error(
+        'No langgraph_node in metadata to retrieve agent context'
+      );
+    }
+
+    let agentId: string | undefined;
+    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: Record<string, unknown> | undefined): string {
+    if (!metadata) return '';
+
+    const keyList = this.getKeyList(metadata);
+    if (this.checkKeyList(keyList)) {
+      throw new Error('Missing metadata');
+    }
+
+    return joinKeys(keyList);
+  }
+
+  getStepIdByKey(stepKey: string, index?: number): string {
+    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: string): [string, number] {
+    const stepIds = this.stepKeyIds.get(stepKey);
+    let newStepId: string | undefined;
+    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: Record<string, unknown> | undefined
+  ): (string | number | undefined)[] {
+    if (!metadata) return [];
+
+    const keyList = [
+      metadata.run_id as string,
+      metadata.thread_id as string,
+      metadata.langgraph_node as string,
+      metadata.langgraph_step as number,
+      metadata.checkpoint_ns as string,
+    ];
+
+    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: (string | number | undefined)[]): boolean {
+    return keyList.some((key) => key === undefined);
+  }
+
+  /* Misc.*/
+
+  getRunMessages(): BaseMessage[] | undefined {
+    return this.messages.slice(this.startIndex);
+  }
+
+  getContentParts(): t.MessageContentComplex[] | undefined {
+    return convertMessagesToContent(this.messages.slice(this.startIndex));
+  }
+
+  /**
+   * Get all run steps, optionally filtered by agent ID
+   */
+  getRunSteps(agentId?: string): t.RunStep[] {
+    if (agentId == null || agentId === '') {
+      return [...this.contentData];
+    }
+    return this.contentData.filter((step) => step.agentId === agentId);
+  }
+
+  /**
+   * Get run steps grouped by agent ID
+   */
+  getRunStepsByAgent(): Map<string, t.RunStep[]> {
+    const stepsByAgent = new Map<string, t.RunStep[]>();
+
+    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(): string[] {
+    const agentIds = new Set<string>();
+    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(): Map<number, string> {
+    const contentPartAgentMap = new Map<number, string>();
+
+    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(): {
+    instructions: number;
+    artifacts: number;
+    tools: number;
+    toolCount: number;
+    toolContext: number;
+    total: number;
+    toolsDetail: Array<{ name: string; tokens: number }>;
+    toolContextDetail: Array<{ name: string; tokens: number }>;
+  } | null {
+    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(): ContextAnalytics | null {
+    return this.lastContextAnalytics ?? null;
+  }
+
+  /** Store the latest context analytics for retrieval after run */
+  private lastContextAnalytics: ContextAnalytics | null = null;
+
+  /* Graph */
+
+  createSystemRunnable({
+    provider,
+    clientOptions,
+    instructions,
+    additional_instructions,
+  }: {
+    provider?: Providers;
+    clientOptions?: t.ClientOptions;
+    instructions?: string;
+    additional_instructions?: string;
+  }): t.SystemRunnable | undefined {
+    let finalInstructions: string | BaseMessageFields | undefined =
+      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 as t.AnthropicClientOptions).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: BaseMessage[]) => {
+        return [systemMessage, ...messages];
+      }).withConfig({ runName: 'prompt' });
+    }
+  }
+
+  initializeTools({
+    currentTools,
+    currentToolMap,
+    agentContext,
+  }: {
+    currentTools?: t.GraphTools;
+    currentToolMap?: t.ToolMap;
+    agentContext?: AgentContext;
+  }): CustomToolNode<t.BaseGraphState> | ToolNode<t.BaseGraphState> {
+    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 CustomToolNode<t.BaseGraphState>({
+        tools: schemaTools as t.GenericTool[],
+        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 CustomToolNode<t.BaseGraphState>({
+      tools: (currentTools as t.GenericTool[] | undefined) ?? [],
+      toolMap: currentToolMap,
+      toolCallStepIds: this.toolCallStepIds,
+      errorHandler: (data, metadata) =>
+        StandardGraph.handleToolCallErrorStatic(this, data, metadata),
+      toolRegistry: agentContext?.toolRegistry,
+      sessions: this.sessions,
+    });
+  }
+
+  initializeModel({
+    provider,
+    tools,
+    clientOptions,
+  }: {
+    provider: Providers;
+    tools?: t.GraphTools;
+    clientOptions?: t.ClientOptions;
+  }): Runnable {
+    const ChatModelClass = getChatModelClass(provider);
+    const model = new ChatModelClass(clientOptions ?? {});
+
+    if (
+      isOpenAILike(provider) &&
+      (model instanceof ChatOpenAI || model instanceof AzureChatOpenAI)
+    ) {
+      model.temperature = (clientOptions as t.OpenAIClientOptions)
+        .temperature as number;
+      model.topP = (clientOptions as t.OpenAIClientOptions).topP as number;
+      model.frequencyPenalty = (clientOptions as t.OpenAIClientOptions)
+        .frequencyPenalty as number;
+      model.presencePenalty = (clientOptions as t.OpenAIClientOptions)
+        .presencePenalty as number;
+      model.n = (clientOptions as t.OpenAIClientOptions).n as number;
+    } else if (
+      provider === Providers.VERTEXAI &&
+      model instanceof ChatVertexAI
+    ) {
+      model.temperature = (clientOptions as t.VertexAIClientOptions)
+        .temperature as number;
+      model.topP = (clientOptions as t.VertexAIClientOptions).topP as number;
+      model.topK = (clientOptions as t.VertexAIClientOptions).topK as number;
+      model.topLogprobs = (clientOptions as t.VertexAIClientOptions)
+        .topLogprobs as number;
+      model.frequencyPenalty = (clientOptions as t.VertexAIClientOptions)
+        .frequencyPenalty as number;
+      model.presencePenalty = (clientOptions as t.VertexAIClientOptions)
+        .presencePenalty as number;
+      model.maxOutputTokens = (clientOptions as t.VertexAIClientOptions)
+        .maxOutputTokens as number;
+    }
+
+    if (!tools || tools.length === 0) {
+      return model as unknown as Runnable;
+    }
+
+    return (model as t.ModelWithTools).bindTools(tools);
+  }
+
+  overrideTestModel(
+    responses: string[],
+    sleep?: number,
+    toolCalls?: ToolCall[]
+  ): void {
+    this.overrideModel = createFakeStreamingLLM({
+      responses,
+      sleep,
+      toolCalls,
+    });
+  }
+
+  getNewModel({
+    provider,
+    clientOptions,
+  }: {
+    provider: Providers;
+    clientOptions?: t.ClientOptions;
+  }): t.ChatModelInstance {
+    const ChatModelClass = getChatModelClass(provider);
+    return new ChatModelClass(clientOptions ?? {});
+  }
+
+  getUsageMetadata(
+    finalMessage?: BaseMessage
+  ): Partial<UsageMetadata> | undefined {
+    if (
+      finalMessage &&
+      'usage_metadata' in finalMessage &&
+      finalMessage.usage_metadata != null
+    ) {
+      return finalMessage.usage_metadata as Partial<UsageMetadata>;
+    }
+  }
+
+  /** Execute model invocation with streaming support */
+  private async attemptInvoke(
+    {
+      currentModel,
+      finalMessages,
+      provider,
+      tools,
+    }: {
+      currentModel?: t.ChatModel;
+      finalMessages: BaseMessage[];
+      provider: Providers;
+      tools?: t.GraphTools;
+    },
+    config?: RunnableConfig
+  ): Promise<Partial<t.BaseGraphState>> {
+    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: AIMessageChunk | undefined;
+      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 as AIMessageChunk] };
+    } else {
+      const finalMessage = await model.invoke(finalMessages, config);
+      if ((finalMessage.tool_calls?.length ?? 0) > 0) {
+        finalMessage.tool_calls = finalMessage.tool_calls?.filter(
+          (tool_call: ToolCall) => !!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)
+   */
+  private async attemptStructuredInvoke(
+    {
+      currentModel,
+      finalMessages,
+      schema,
+      structuredOutputConfig,
+      provider,
+      agentContext,
+    }: {
+      currentModel: t.ChatModelInstance;
+      finalMessages: BaseMessage[];
+      schema: Record<string, unknown>;
+      structuredOutputConfig: t.StructuredOutputConfig;
+      provider?: Providers;
+      agentContext?: AgentContext;
+    },
+    config?: RunnableConfig
+  ): Promise<{
+    structuredResponse: Record<string, unknown>;
+    rawMessage?: AIMessageChunk;
+  }> {
+    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 as any).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: t.ResolvedStructuredOutputMethod;
+    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 as any).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 as any).model || (model as any).modelId || 'unknown',
+    });
+
+    let lastError: Error | undefined;
+    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 as AIMessageChunk;
+          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 as AIMessageChunk & { refusal?: string }).refusal;
+          if (refusal) {
+            throw new StructuredOutputRefusalError(refusal);
+          }
+        }
+
+        // Handle response - we always use includeRaw internally
+        if (result?.raw && result?.parsed !== undefined) {
+          return {
+            structuredResponse: result.parsed as Record<string, unknown>,
+            rawMessage: result.raw as AIMessageChunk,
+          };
+        }
+
+        // Fallback for models that don't support includeRaw
+        return {
+          structuredResponse: result as Record<string, unknown>,
+        };
+      } 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 as 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?: t.ChatModel): void {
+    if (!this.signal) {
+      return;
+    }
+    const model = this.overrideModel ?? currentModel;
+    if (!model) {
+      return;
+    }
+    const client = (model as ChatOpenAI | undefined)?.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).
+   */
+  private async performStructuredOutput({
+    agentContext,
+    finalMessages,
+    config,
+  }: {
+    agentContext: AgentContext;
+    finalMessages: BaseMessage[];
+    config: RunnableConfig;
+  }): Promise<Partial<t.BaseGraphState>> {
+    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 } as t.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 as any).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 as t.BedrockAnthropicClientOptions;
+        if (bedrockOpts.additionalModelRequestFields) {
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+          const additionalFields = Object.assign({}, bedrockOpts.additionalModelRequestFields) as any;
+          delete additionalFields.thinking;
+          delete additionalFields.budgetTokens;
+          bedrockOpts.additionalModelRequestFields = additionalFields;
+        }
+      }
+
+      // Remove thinking configuration for Anthropic direct API
+      if (agentContext.provider === Providers.ANTHROPIC) {
+        const anthropicOpts = structuredClientOptions as t.AnthropicClientOptions;
+        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: AIMessageChunk | undefined;
+    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: t.BaseGraphState,
+      config?: RunnableConfig
+    ): Promise<Partial<t.BaseGraphState>> => {
+      /**
+       * 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 as Runnable);
+      }
+
+      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 as { name: string }).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 as t.AnthropicClientOptions).thinking !=
+              null) ||
+          (agentContext.provider === Providers.BEDROCK &&
+            (agentContext.clientOptions as t.BedrockAnthropicInput)
+              .additionalModelRequestFields?.['thinking'] != null) ||
+          (agentContext.provider === Providers.OPENAI &&
+            (
+              (agentContext.clientOptions as t.OpenAIClientOptions).modelKwargs
+                ?.thinking as t.AnthropicClientOptions['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 as t.AnthropicClientOptions).thinking !=
+            null) ||
+        (agentContext.provider === Providers.BEDROCK &&
+          (agentContext.clientOptions as t.BedrockAnthropicInput)
+            .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 as
+          | t.AnthropicClientOptions
+          | undefined;
+        if (anthropicOptions?.promptCache === true) {
+          finalMessages = addCacheControl<BaseMessage>(finalMessages);
+        }
+      } else if (agentContext.provider === Providers.BEDROCK) {
+        const bedrockOptions = agentContext.clientOptions as
+          | t.BedrockAnthropicClientOptions
+          | undefined;
+        // 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<BaseMessage>(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: Partial<t.BaseGraphState> | undefined;
+      const fallbacks =
+        (agentContext.clientOptions as t.LLMConfig | undefined)?.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 as
+        | t.BedrockAnthropicClientOptions
+        | undefined;
+      const modelId =
+        bedrockOpts?.model ||
+        (agentContext.clientOptions as t.AnthropicClientOptions | undefined)
+          ?.modelName;
+      const thinkingConfig =
+        bedrockOpts?.additionalModelRequestFields?.['thinking'] ||
+        (agentContext.clientOptions as t.AnthropicClientOptions | undefined)
+          ?.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 as { name: string }).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: string[] = [];
+        for (const msg of finalMessages) {
+          const content = typeof msg.content === 'string'
+            ? msg.content
+            : Array.isArray(msg.content)
+              ? msg.content.map((p: unknown) => {
+                  const part = p as Record<string, unknown>;
+                  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: string) => 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 as Error).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 as
+                | t.BedrockAnthropicClientOptions
+                | undefined;
+              const modelId = bedrockOptions?.model?.toLowerCase() ?? '';
+              const supportsCaching =
+                modelId.includes('claude') ||
+                modelId.includes('anthropic') ||
+                modelId.includes('nova');
+              if (bedrockOptions?.promptCache === true && supportsCaching) {
+                retryMessages =
+                  addBedrockCacheControl<BaseMessage>(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 as Error).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 as Error).message
+                );
+              }
+            }
+          }
+        }
+
+        // If we got a result from retry, skip fallbacks
+        if (result) {
+          // result already set from retry
+        } else {
+          let lastError: unknown = 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)
+              ) as t.ChatModelInstance;
+              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 as Record<string, unknown>;
+        // Bedrock streaming nests stopReason inside messageStop: { stopReason: '...' }
+        const messageStop = meta.messageStop as Record<string, unknown> | undefined;
+        this.lastFinishReason =
+          (meta.finish_reason as string) ??              // OpenAI/Azure
+          (meta.stop_reason as string) ??                // Anthropic direct API
+          (meta.stopReason as string) ??                 // Bedrock invoke (non-streaming)
+          (messageStop?.stopReason as string) ??         // Bedrock streaming
+          (meta.finishReason as string) ??               // 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 as AIMessageChunk).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: string): t.CompiledAgentWorfklow {
+    const agentContext = this.agentContexts.get(agentId);
+    if (!agentContext) {
+      throw new Error(`Agent context not found for agentId: ${agentId}`);
+    }
+
+    const agentNode = `${AGENT}${agentId}` as const;
+    const toolNode = `${TOOLS}${agentId}` as const;
+
+    const routeMessage = (
+      state: t.BaseGraphState,
+      config?: RunnableConfig
+    ): string => {
+      this.config = config;
+      return toolsCondition(state, toolNode, this.invokedToolIds);
+    };
+
+    const StateAnnotation = Annotation.Root({
+      messages: Annotation<BaseMessage[]>({
+        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 as unknown as never);
+  }
+
+  createWorkflow(): t.CompiledStateWorkflow {
+    /** Use the default (first) agent for now */
+    const agentNode = this.createAgentNode(this.defaultAgentId);
+    const StateAnnotation = Annotation.Root({
+      messages: Annotation<BaseMessage[]>({
+        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.
+   */
+  protected isMultiAgentGraph(): boolean {
+    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
+   */
+  protected getParallelGroupIdForAgent(_agentId: string): number | undefined {
+    return undefined;
+  }
+
+  /* Dispatchers */
+
+  /**
+   * Dispatches a run step to the client, returns the step ID
+   */
+  async dispatchRunStep(
+    stepKey: string,
+    stepDetails: t.StepDetails,
+    metadata?: Record<string, unknown>
+  ): Promise<string> {
+    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: t.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: t.ToolEndData,
+    metadata?: Record<string, unknown>,
+    omitOutput?: boolean
+  ): Promise<void> {
+    if (!this.config) {
+      throw new Error('No config provided');
+    }
+
+    if (!data.output) {
+      return;
+    }
+
+    const { input, output: _output } = data;
+    if ((_output as Command | undefined)?.lg_name === 'Command') {
+      return;
+    }
+    const output = _output as ToolMessage;
+    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 as t.CodeExecutionArtifact | undefined;
+      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: t.FileRefs = newFiles.map((file) => ({
+          ...file,
+          session_id: artifact.session_id,
+        }));
+
+        const existingSession = this.sessions.get(Constants.EXECUTE_CODE) as
+          | t.CodeSessionContext
+          | undefined;
+        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,
+          } as t.ToolCompleteEvent,
+        },
+        metadata,
+        this
+      );
+  }
+  /**
+   * Static version of handleToolCallError to avoid creating strong references
+   * that prevent garbage collection
+   */
+  static async handleToolCallErrorStatic(
+    graph: StandardGraph,
+    data: t.ToolErrorData,
+    metadata?: Record<string, unknown>
+  ): Promise<void> {
+    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: t.ProcessedToolCall = {
+      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,
+          } as t.ToolCompleteEvent,
+        },
+        metadata,
+        graph
+      );
+  }
+
+  /**
+   * Instance method that delegates to the static method
+   * Kept for backward compatibility
+   */
+  async handleToolCallError(
+    data: t.ToolErrorData,
+    metadata?: Record<string, unknown>
+  ): Promise<void> {
+    await StandardGraph.handleToolCallErrorStatic(this, data, metadata);
+  }
+
+  async dispatchRunStepDelta(
+    id: string,
+    delta: t.ToolCallDelta
+  ): Promise<void> {
+    if (!this.config) {
+      throw new Error('No config provided');
+    } else if (!id) {
+      throw new Error('No step ID found');
+    }
+    const runStepDelta: t.RunStepDeltaEvent = {
+      id,
+      delta,
+    };
+    await safeDispatchCustomEvent(
+      GraphEvents.ON_RUN_STEP_DELTA,
+      runStepDelta,
+      this.config
+    );
+  }
+
+  async dispatchMessageDelta(id: string, delta: t.MessageDelta): Promise<void> {
+    if (!this.config) {
+      throw new Error('No config provided');
+    }
+    const messageDelta: t.MessageDeltaEvent = {
+      id,
+      delta,
+    };
+    await safeDispatchCustomEvent(
+      GraphEvents.ON_MESSAGE_DELTA,
+      messageDelta,
+      this.config
+    );
+  }
+
+  dispatchReasoningDelta = async (
+    stepId: string,
+    delta: t.ReasoningDelta
+  ): Promise<void> => {
+    if (!this.config) {
+      throw new Error('No config provided');
+    }
+    const reasoningDelta: t.ReasoningDeltaEvent = {
+      id: stepId,
+      delta,
+    };
+    await safeDispatchCustomEvent(
+      GraphEvents.ON_REASONING_DELTA,
+      reasoningDelta,
+      this.config
+    );
+  };
+}