@illuma-ai/agents 1.0.81

package/src/agents/AgentContext.ts

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