@langchain/langgraph-sdk 1.5.6 → 1.6.1

package/dist/ui/subagents.d.ts

@@ -0,0 +1,291 @@
+import { DefaultToolCall, Message } from "../types.messages.js";
+import { SubagentStream } from "./types.js";
+
+//#region src/ui/subagents.d.ts
+
+/**
+ * Checks if a namespace indicates a subagent/subgraph message.
+ *
+ * Subagent namespaces contain a "tools:" segment indicating they
+ * originate from a tool call that spawned a subgraph.
+ *
+ * @param namespace - The namespace array from stream events (or checkpoint_ns string)
+ * @returns True if this is a subagent namespace
+ */
+declare function isSubagentNamespace(namespace: string[] | string | undefined): boolean;
+/**
+ * Extracts the tool call ID from a namespace path.
+ *
+ * Namespaces follow the pattern: ["tools:call_abc123", "model_request:xyz", ...]
+ * This function extracts "call_abc123" from the first "tools:" segment.
+ *
+ * @param namespace - The namespace array from stream events
+ * @returns The tool call ID, or undefined if not found
+ */
+declare function extractToolCallIdFromNamespace(namespace: string[] | undefined): string | undefined;
+/**
+ * Calculates the depth of a subagent based on its namespace.
+ * Counts the number of "tools:" segments in the namespace.
+ *
+ * @param namespace - The namespace array
+ * @returns The depth (0 for main agent, 1+ for subagents)
+ */
+declare function calculateDepthFromNamespace(namespace: string[] | undefined): number;
+/**
+ * Extracts the parent tool call ID from a namespace.
+ *
+ * For nested subagents, the namespace looks like:
+ * ["tools:parent_id", "tools:child_id", ...]
+ *
+ * @param namespace - The namespace array
+ * @returns The parent tool call ID, or null if this is a top-level subagent
+ */
+declare function extractParentIdFromNamespace(namespace: string[] | undefined): string | null;
+/**
+ * Options for SubagentManager.
+ */
+interface SubagentManagerOptions {
+  /**
+   * Tool names that indicate subagent invocation.
+   * Defaults to ["task"].
+   */
+  subagentToolNames?: string[];
+  /**
+   * Callback when subagent state changes.
+   */
+  onSubagentChange?: () => void;
+}
+/**
+ * Manages subagent execution state.
+ *
+ * Tracks subagents from the moment they are invoked (AI message with tool calls)
+ * through streaming to completion (tool message result).
+ */
+declare class SubagentManager<ToolCall = DefaultToolCall> {
+  private subagents;
+  /**
+   * Maps namespace IDs (pregel task IDs) to tool call IDs.
+   * LangGraph subgraphs use internal pregel task IDs in their namespace,
+   * which are different from the tool_call_id used to invoke them.
+   */
+  private namespaceToToolCallId;
+  /**
+   * Pending namespace matches that couldn't be resolved immediately.
+   * These are retried when new tool calls are registered.
+   */
+  private pendingMatches;
+  /**
+   * Message managers for each subagent.
+   * Uses the same MessageTupleManager as the main stream for proper
+   * message chunk concatenation.
+   */
+  private messageManagers;
+  private subagentToolNames;
+  private onSubagentChange?;
+  constructor(options?: SubagentManagerOptions);
+  /**
+   * Get or create a MessageTupleManager for a subagent.
+   */
+  private getMessageManager;
+  /**
+   * Get messages for a subagent with proper chunk concatenation.
+   * This mirrors how the main stream handles messages.
+   */
+  private getMessagesForSubagent;
+  /**
+   * Create a complete SubagentStream object with all derived properties.
+   * This ensures consistency with UseStream interface.
+   */
+  private createSubagentStream;
+  /**
+   * Get the tool call ID for a given namespace ID.
+   * Returns the namespace ID itself if no mapping exists.
+   */
+  getToolCallIdFromNamespace(namespaceId: string): string;
+  /**
+   * Try to match a subgraph to a pending subagent by description.
+   * Creates a mapping from namespace ID to tool call ID if a match is found.
+   *
+   * Uses a multi-pass matching strategy:
+   * 1. Exact description match
+   * 2. Description contains/partial match
+   * 3. Any unmapped pending subagent (fallback)
+   *
+   * @param namespaceId - The namespace ID (pregel task ID) from the subgraph
+   * @param description - The description from the subgraph's initial message
+   * @returns The matched tool call ID, or undefined if no match
+   */
+  matchSubgraphToSubagent(namespaceId: string, description: string): string | undefined;
+  /**
+   * Check if a tool call is a subagent invocation.
+   */
+  isSubagentToolCall(toolName: string): boolean;
+  /**
+   * Check if a subagent_type value is valid.
+   * Valid types are proper identifiers like "weather-scout", "experience-curator".
+   */
+  private isValidSubagentType;
+  /**
+   * Check if a subagent should be shown to the user.
+   * Subagents are only shown once they've actually started running.
+   *
+   * This filters out:
+   * - Pending subagents that haven't been matched to a namespace yet
+   * - Streaming artifacts with partial/corrupted data
+   *
+   * The idea is: we register subagents internally when we see tool calls,
+   * but we only show them to the user once LangGraph confirms they're
+   * actually executing (via namespace events).
+   */
+  private isValidSubagent;
+  /**
+   * Build a complete SubagentStream from internal state.
+   * Adds messages and derived properties.
+   */
+  private buildExecution;
+  /**
+   * Get all subagents as a Map.
+   * Filters out incomplete/phantom subagents that lack subagent_type.
+   */
+  getSubagents(): Map<string, SubagentStream<Record<string, unknown>, ToolCall>>;
+  /**
+   * Get all currently running subagents.
+   * Filters out incomplete/phantom subagents.
+   */
+  getActiveSubagents(): SubagentStream<Record<string, unknown>, ToolCall>[];
+  /**
+   * Get a specific subagent by tool call ID.
+   */
+  getSubagent(toolCallId: string): SubagentStream<Record<string, unknown>, ToolCall> | undefined;
+  /**
+   * Get all subagents of a specific type.
+   */
+  getSubagentsByType(type: string): SubagentStream<Record<string, unknown>, ToolCall>[];
+  /**
+   * Get all subagents triggered by a specific AI message.
+   *
+   * @param messageId - The ID of the AI message.
+   * @returns Array of subagent streams triggered by that message.
+   */
+  getSubagentsByMessage(messageId: string): SubagentStream<Record<string, unknown>, ToolCall>[];
+  /**
+   * Parse tool call args, handling both object and string formats.
+   * During streaming, args might come as a string that needs parsing.
+   */
+  private parseArgs;
+  /**
+   * Register new subagent(s) from AI message tool calls.
+   *
+   * Called when an AI message is received with tool calls.
+   * Creates pending subagent entries for each subagent tool call.
+   *
+   * @param toolCalls - The tool calls from an AI message
+   * @param aiMessageId - The ID of the AI message that triggered the tool calls
+   */
+  registerFromToolCalls(toolCalls: Array<{
+    id?: string;
+    name: string;
+    args: Record<string, unknown> | string;
+  }>, aiMessageId?: string | null): void;
+  /**
+   * Retry matching pending namespaces to newly registered tool calls.
+   */
+  private retryPendingMatches;
+  /**
+   * Mark a subagent as running and update its namespace.
+   *
+   * Called when update events are received with a namespace indicating
+   * which subagent is streaming.
+   *
+   * @param toolCallId - The tool call ID of the subagent
+   * @param options - Additional update options
+   */
+  markRunning(toolCallId: string, options?: {
+    namespace?: string[];
+  }): void;
+  /**
+   * Mark a subagent as running using a namespace ID.
+   * Resolves the namespace ID to the actual tool call ID via the mapping.
+   *
+   * @param namespaceId - The namespace ID (pregel task ID) from the subgraph
+   * @param namespace - The full namespace array
+   */
+  markRunningFromNamespace(namespaceId: string, namespace?: string[]): void;
+  /**
+   * Add a serialized message to a subagent from stream events.
+   *
+   * This method handles the raw serialized message data from SSE events.
+   * Uses MessageTupleManager for proper chunk concatenation, matching
+   * how the main stream handles messages.
+   *
+   * @param namespaceId - The namespace ID (pregel task ID) from the stream
+   * @param serialized - The serialized message from the stream
+   * @param metadata - Optional metadata from the stream event
+   */
+  addMessageToSubagent(namespaceId: string, serialized: Message<DefaultToolCall>, metadata?: Record<string, unknown>): void;
+  /**
+   * Update subagent values from a values stream event.
+   *
+   * Called when a values event is received from a subagent's namespace.
+   * This populates the subagent's state values, making them accessible
+   * via the `values` property.
+   *
+   * @param namespaceId - The namespace ID (pregel task ID) from the stream
+   * @param values - The state values from the stream event
+   */
+  updateSubagentValues(namespaceId: string, values: Record<string, unknown>): void;
+  /**
+   * Complete a subagent with a result.
+   *
+   * Called when a tool message is received for the subagent.
+   *
+   * @param toolCallId - The tool call ID of the subagent
+   * @param result - The result content
+   * @param status - The final status (complete or error)
+   */
+  complete(toolCallId: string, result: string, status?: "complete" | "error"): void;
+  /**
+   * Clear all subagent state.
+   */
+  clear(): void;
+  /**
+   * Process a tool message to complete a subagent.
+   *
+   * @param toolCallId - The tool call ID from the tool message
+   * @param content - The result content
+   * @param status - Whether the tool execution was successful
+   */
+  processToolMessage(toolCallId: string, content: string, status?: "success" | "error"): void;
+  /**
+   * Reconstruct subagent state from historical messages.
+   *
+   * This method parses an array of messages (typically from thread history)
+   * to identify subagent executions and their results. It's used to restore
+   * subagent state after:
+   * - Page refresh (when stream has already completed)
+   * - Loading thread history
+   * - Navigating between threads
+   *
+   * The reconstruction process:
+   * 1. Find AI messages with tool calls matching subagent tool names
+   * 2. Find corresponding tool messages with results
+   * 3. Create SubagentStream entries with "complete" status
+   *
+   * Note: Internal subagent messages (their streaming conversation) are not
+   * reconstructed since they are not persisted in the main thread state.
+   *
+   * @param messages - Array of messages from thread history
+   * @param options - Optional configuration
+   * @param options.skipIfPopulated - If true, skip reconstruction if subagents already exist
+   */
+  reconstructFromMessages(messages: Message<DefaultToolCall>[], options?: {
+    skipIfPopulated?: boolean;
+  }): void;
+  /**
+   * Check if any subagents are currently tracked.
+   */
+  hasSubagents(): boolean;
+}
+//#endregion
+export { SubagentManager, calculateDepthFromNamespace, extractParentIdFromNamespace, extractToolCallIdFromNamespace, isSubagentNamespace };
+//# sourceMappingURL=subagents.d.ts.map

package/dist/ui/subagents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagents.d.ts","names":["Message","DefaultToolCall","SubagentStream","isSubagentNamespace","extractToolCallIdFromNamespace","calculateDepthFromNamespace","extractParentIdFromNamespace","SubagentManagerOptions","SubagentManager","Record","ToolCall","Map","Array"],"sources":["../../src/ui/subagents.d.ts"],"sourcesContent":["import type { Message, DefaultToolCall } from \"../types.messages.js\";\nimport type { SubagentStream } from \"./types.js\";\n/**\n * Checks if a namespace indicates a subagent/subgraph message.\n *\n * Subagent namespaces contain a \"tools:\" segment indicating they\n * originate from a tool call that spawned a subgraph.\n *\n * @param namespace - The namespace array from stream events (or checkpoint_ns string)\n * @returns True if this is a subagent namespace\n */\nexport declare function isSubagentNamespace(namespace: string[] | string | undefined): boolean;\n/**\n * Extracts the tool call ID from a namespace path.\n *\n * Namespaces follow the pattern: [\"tools:call_abc123\", \"model_request:xyz\", ...]\n * This function extracts \"call_abc123\" from the first \"tools:\" segment.\n *\n * @param namespace - The namespace array from stream events\n * @returns The tool call ID, or undefined if not found\n */\nexport declare function extractToolCallIdFromNamespace(namespace: string[] | undefined): string | undefined;\n/**\n * Calculates the depth of a subagent based on its namespace.\n * Counts the number of \"tools:\" segments in the namespace.\n *\n * @param namespace - The namespace array\n * @returns The depth (0 for main agent, 1+ for subagents)\n */\nexport declare function calculateDepthFromNamespace(namespace: string[] | undefined): number;\n/**\n * Extracts the parent tool call ID from a namespace.\n *\n * For nested subagents, the namespace looks like:\n * [\"tools:parent_id\", \"tools:child_id\", ...]\n *\n * @param namespace - The namespace array\n * @returns The parent tool call ID, or null if this is a top-level subagent\n */\nexport declare function extractParentIdFromNamespace(namespace: string[] | undefined): string | null;\n/**\n * Options for SubagentManager.\n */\nexport interface SubagentManagerOptions {\n    /**\n     * Tool names that indicate subagent invocation.\n     * Defaults to [\"task\"].\n     */\n    subagentToolNames?: string[];\n    /**\n     * Callback when subagent state changes.\n     */\n    onSubagentChange?: () => void;\n}\n/**\n * Manages subagent execution state.\n *\n * Tracks subagents from the moment they are invoked (AI message with tool calls)\n * through streaming to completion (tool message result).\n */\nexport declare class SubagentManager<ToolCall = DefaultToolCall> {\n    private subagents;\n    /**\n     * Maps namespace IDs (pregel task IDs) to tool call IDs.\n     * LangGraph subgraphs use internal pregel task IDs in their namespace,\n     * which are different from the tool_call_id used to invoke them.\n     */\n    private namespaceToToolCallId;\n    /**\n     * Pending namespace matches that couldn't be resolved immediately.\n     * These are retried when new tool calls are registered.\n     */\n    private pendingMatches;\n    /**\n     * Message managers for each subagent.\n     * Uses the same MessageTupleManager as the main stream for proper\n     * message chunk concatenation.\n     */\n    private messageManagers;\n    private subagentToolNames;\n    private onSubagentChange?;\n    constructor(options?: SubagentManagerOptions);\n    /**\n     * Get or create a MessageTupleManager for a subagent.\n     */\n    private getMessageManager;\n    /**\n     * Get messages for a subagent with proper chunk concatenation.\n     * This mirrors how the main stream handles messages.\n     */\n    private getMessagesForSubagent;\n    /**\n     * Create a complete SubagentStream object with all derived properties.\n     * This ensures consistency with UseStream interface.\n     */\n    private createSubagentStream;\n    /**\n     * Get the tool call ID for a given namespace ID.\n     * Returns the namespace ID itself if no mapping exists.\n     */\n    getToolCallIdFromNamespace(namespaceId: string): string;\n    /**\n     * Try to match a subgraph to a pending subagent by description.\n     * Creates a mapping from namespace ID to tool call ID if a match is found.\n     *\n     * Uses a multi-pass matching strategy:\n     * 1. Exact description match\n     * 2. Description contains/partial match\n     * 3. Any unmapped pending subagent (fallback)\n     *\n     * @param namespaceId - The namespace ID (pregel task ID) from the subgraph\n     * @param description - The description from the subgraph's initial message\n     * @returns The matched tool call ID, or undefined if no match\n     */\n    matchSubgraphToSubagent(namespaceId: string, description: string): string | undefined;\n    /**\n     * Check if a tool call is a subagent invocation.\n     */\n    isSubagentToolCall(toolName: string): boolean;\n    /**\n     * Check if a subagent_type value is valid.\n     * Valid types are proper identifiers like \"weather-scout\", \"experience-curator\".\n     */\n    private isValidSubagentType;\n    /**\n     * Check if a subagent should be shown to the user.\n     * Subagents are only shown once they've actually started running.\n     *\n     * This filters out:\n     * - Pending subagents that haven't been matched to a namespace yet\n     * - Streaming artifacts with partial/corrupted data\n     *\n     * The idea is: we register subagents internally when we see tool calls,\n     * but we only show them to the user once LangGraph confirms they're\n     * actually executing (via namespace events).\n     */\n    private isValidSubagent;\n    /**\n     * Build a complete SubagentStream from internal state.\n     * Adds messages and derived properties.\n     */\n    private buildExecution;\n    /**\n     * Get all subagents as a Map.\n     * Filters out incomplete/phantom subagents that lack subagent_type.\n     */\n    getSubagents(): Map<string, SubagentStream<Record<string, unknown>, ToolCall>>;\n    /**\n     * Get all currently running subagents.\n     * Filters out incomplete/phantom subagents.\n     */\n    getActiveSubagents(): SubagentStream<Record<string, unknown>, ToolCall>[];\n    /**\n     * Get a specific subagent by tool call ID.\n     */\n    getSubagent(toolCallId: string): SubagentStream<Record<string, unknown>, ToolCall> | undefined;\n    /**\n     * Get all subagents of a specific type.\n     */\n    getSubagentsByType(type: string): SubagentStream<Record<string, unknown>, ToolCall>[];\n    /**\n     * Get all subagents triggered by a specific AI message.\n     *\n     * @param messageId - The ID of the AI message.\n     * @returns Array of subagent streams triggered by that message.\n     */\n    getSubagentsByMessage(messageId: string): SubagentStream<Record<string, unknown>, ToolCall>[];\n    /**\n     * Parse tool call args, handling both object and string formats.\n     * During streaming, args might come as a string that needs parsing.\n     */\n    private parseArgs;\n    /**\n     * Register new subagent(s) from AI message tool calls.\n     *\n     * Called when an AI message is received with tool calls.\n     * Creates pending subagent entries for each subagent tool call.\n     *\n     * @param toolCalls - The tool calls from an AI message\n     * @param aiMessageId - The ID of the AI message that triggered the tool calls\n     */\n    registerFromToolCalls(toolCalls: Array<{\n        id?: string;\n        name: string;\n        args: Record<string, unknown> | string;\n    }>, aiMessageId?: string | null): void;\n    /**\n     * Retry matching pending namespaces to newly registered tool calls.\n     */\n    private retryPendingMatches;\n    /**\n     * Mark a subagent as running and update its namespace.\n     *\n     * Called when update events are received with a namespace indicating\n     * which subagent is streaming.\n     *\n     * @param toolCallId - The tool call ID of the subagent\n     * @param options - Additional update options\n     */\n    markRunning(toolCallId: string, options?: {\n        namespace?: string[];\n    }): void;\n    /**\n     * Mark a subagent as running using a namespace ID.\n     * Resolves the namespace ID to the actual tool call ID via the mapping.\n     *\n     * @param namespaceId - The namespace ID (pregel task ID) from the subgraph\n     * @param namespace - The full namespace array\n     */\n    markRunningFromNamespace(namespaceId: string, namespace?: string[]): void;\n    /**\n     * Add a serialized message to a subagent from stream events.\n     *\n     * This method handles the raw serialized message data from SSE events.\n     * Uses MessageTupleManager for proper chunk concatenation, matching\n     * how the main stream handles messages.\n     *\n     * @param namespaceId - The namespace ID (pregel task ID) from the stream\n     * @param serialized - The serialized message from the stream\n     * @param metadata - Optional metadata from the stream event\n     */\n    addMessageToSubagent(namespaceId: string, serialized: Message<DefaultToolCall>, metadata?: Record<string, unknown>): void;\n    /**\n     * Update subagent values from a values stream event.\n     *\n     * Called when a values event is received from a subagent's namespace.\n     * This populates the subagent's state values, making them accessible\n     * via the `values` property.\n     *\n     * @param namespaceId - The namespace ID (pregel task ID) from the stream\n     * @param values - The state values from the stream event\n     */\n    updateSubagentValues(namespaceId: string, values: Record<string, unknown>): void;\n    /**\n     * Complete a subagent with a result.\n     *\n     * Called when a tool message is received for the subagent.\n     *\n     * @param toolCallId - The tool call ID of the subagent\n     * @param result - The result content\n     * @param status - The final status (complete or error)\n     */\n    complete(toolCallId: string, result: string, status?: \"complete\" | \"error\"): void;\n    /**\n     * Clear all subagent state.\n     */\n    clear(): void;\n    /**\n     * Process a tool message to complete a subagent.\n     *\n     * @param toolCallId - The tool call ID from the tool message\n     * @param content - The result content\n     * @param status - Whether the tool execution was successful\n     */\n    processToolMessage(toolCallId: string, content: string, status?: \"success\" | \"error\"): void;\n    /**\n     * Reconstruct subagent state from historical messages.\n     *\n     * This method parses an array of messages (typically from thread history)\n     * to identify subagent executions and their results. It's used to restore\n     * subagent state after:\n     * - Page refresh (when stream has already completed)\n     * - Loading thread history\n     * - Navigating between threads\n     *\n     * The reconstruction process:\n     * 1. Find AI messages with tool calls matching subagent tool names\n     * 2. Find corresponding tool messages with results\n     * 3. Create SubagentStream entries with \"complete\" status\n     *\n     * Note: Internal subagent messages (their streaming conversation) are not\n     * reconstructed since they are not persisted in the main thread state.\n     *\n     * @param messages - Array of messages from thread history\n     * @param options - Optional configuration\n     * @param options.skipIfPopulated - If true, skip reconstruction if subagents already exist\n     */\n    reconstructFromMessages(messages: Message<DefaultToolCall>[], options?: {\n        skipIfPopulated?: boolean;\n    }): void;\n    /**\n     * Check if any subagents are currently tracked.\n     */\n    hasSubagents(): boolean;\n}\n"],"mappings":";;;;;;;AAWA;AAUA;AAQA;AAUA;AAIA;AAiBA;;AAAgDC,iBAjDxBE,mBAAAA,CAiDwBF,SAAAA,EAAAA,MAAAA,EAAAA,GAAAA,MAAAA,GAAAA,SAAAA,CAAAA,EAAAA,OAAAA;;;;;;;;;;AA+F6BS,iBAtIrDN,8BAAAA,CAsIqDM,SAAAA,EAAAA,MAAAA,EAAAA,GAAAA,SAAAA,CAAAA,EAAAA,MAAAA,GAAAA,SAAAA;;;;;;;;AA6B/DD,iBA3JUJ,2BAAAA,CA2JVI,SAAAA,EAAAA,MAAAA,EAAAA,GAAAA,SAAAA,CAAAA,EAAAA,MAAAA;;;;;;;;;;iBAjJUH,4BAAAA;;;;UAIPC,sBAAAA;;;;;;;;;;;;;;;;;cAiBIC,2BAA2BP;;;;;;;;;;;;;;;;;;;;;wBAqBtBM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAiENI,YAAYT,eAAeO,yBAAyBC;;;;;wBAK9CR,eAAeO,yBAAyBC;;;;mCAI7BR,eAAeO,yBAAyBC;;;;oCAIvCR,eAAeO,yBAAyBC;;;;;;;4CAOhCR,eAAeO,yBAAyBC;;;;;;;;;;;;;;;mCAejDE;;;UAGvBH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wDAqC4CT,QAAQC,6BAA6BQ;;;;;;;;;;;oDAWzCA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oCA6ChBT,QAAQC"}