@librechat/agents 3.1.67-dev.0 → 3.1.67-dev.4

package/dist/types/types/graph.d.ts

@@ -4,7 +4,7 @@ import type { BaseMessage, AIMessageChunk, SystemMessage } from '@langchain/core
 import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { GoogleAIToolType } from '@langchain/google-common';
-import type { ToolMap, ToolEndEvent, GenericTool, LCTool } from '@/types/tools';
+import type { ToolMap, ToolEndEvent, GenericTool, LCTool, ToolExecuteBatchRequest } from '@/types/tools';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
@@ -45,7 +45,7 @@ export interface AgentLogEvent {
     agentId?: string;
 }
 export interface EventHandler {
-    handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | AgentLogEvent | {
+    handle(event: string, data: StreamEventData | ModelEndData | RunStep | RunStepDeltaEvent | MessageDeltaEvent | ReasoningDeltaEvent | SummarizeStartEvent | SummarizeDeltaEvent | SummarizeCompleteEvent | SubagentUpdateEvent | AgentLogEvent | ToolExecuteBatchRequest | {
         result: ToolEndEvent;
     }, metadata?: Record<string, unknown>, graph?: StandardGraph | MultiAgentGraph): void | Promise<void>;
 }
@@ -269,6 +269,40 @@ export type SubagentConfig = {
 export type ResolvedSubagentConfig = SubagentConfig & {
     agentInputs: AgentInputs;
 };
+/** Lifecycle phase carried on {@link SubagentUpdateEvent}. */
+export type SubagentUpdatePhase = 'start' | 'run_step' | 'run_step_delta' | 'run_step_completed' | 'message_delta' | 'reasoning_delta' | 'stop' | 'error';
+/**
+ * Wrapper event emitted when a subagent's child graph dispatches activity.
+ * Lets hosts show subagent progress in a UI surface separate from the parent
+ * conversation without having to untangle events by agent ID.
+ */
+export interface SubagentUpdateEvent {
+    /** Parent run ID. */
+    runId: string;
+    /** Child run ID (unique per subagent execution). */
+    subagentRunId: string;
+    /**
+     * Parent-side `tool_call_id` for the `subagent` tool invocation that
+     * triggered this run. Stable for the duration of the child; lets hosts
+     * correlate updates deterministically instead of inferring by ordering.
+     * Omitted when the executor was invoked outside of a tool-call context.
+     */
+    parentToolCallId?: string;
+    /** Subagent `type` identifier from the SubagentConfig. */
+    subagentType: string;
+    /** Child agent ID assigned to this subagent execution. */
+    subagentAgentId: string;
+    /** Parent agent ID that spawned this subagent. */
+    parentAgentId?: string;
+    /** Lifecycle phase carried by this update. */
+    phase: SubagentUpdatePhase;
+    /** Underlying event payload (shape depends on phase). */
+    data?: unknown;
+    /** Short human-readable description. Hosts can render this directly. */
+    label?: string;
+    /** ISO timestamp for ordering / display. */
+    timestamp: string;
+}
 export interface AgentInputs {
     agentId: string;
     /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.1.67-dev.0",
+  "version": "3.1.67-dev.4",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -61,6 +61,9 @@
     "tool": "node --trace-warnings -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tools.ts --provider 'bedrock' --name 'Jo' --location 'New York, NY'",
     "search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/search.ts --provider 'bedrock' --name 'Jo' --location 'New York, NY'",
     "tool_search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tool_search.ts",
+    "subagent": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-subagent.ts",
+    "subagent:events": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/subagent-event-driven-debug.ts",
+    "subagent:tools": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/subagent-tools-debug.ts",
     "programmatic_exec": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/programmatic_exec.ts",
     "code_exec_ptc": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/code_exec_ptc.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",
     "programmatic_exec_agent": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/programmatic_exec_agent.ts --provider 'openAI' --name 'Jo' --location 'New York, NY'",

package/src/common/enum.ts

@@ -27,6 +27,8 @@ export enum GraphEvents {
   ON_SUMMARIZE_DELTA = 'on_summarize_delta',
   /** [Custom] Emitted when the summarize node completes with the final summary */
   ON_SUMMARIZE_COMPLETE = 'on_summarize_complete',
+  /** [Custom] Progress update from a running subagent (wraps child-graph events so hosts can display activity separately from parent). */
+  ON_SUBAGENT_UPDATE = 'on_subagent_update',
   /** [Custom] Diagnostic logging event for context management observability */
   ON_AGENT_LOG = 'on_agent_log',
 

package/src/graphs/Graph.ts

@@ -1176,10 +1176,16 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         agentContext
       );
       if (resolvedConfigs.length > 0) {
+        const getParentHandlerRegistry = (): HandlerRegistry | undefined =>
+          this.handlerRegistry;
         const executor = new SubagentExecutor({
           configs: new Map(resolvedConfigs.map((c) => [c.type, c])),
           parentSignal: this.signal,
           hookRegistry: this.hookRegistry,
+          /** Lazy — Run wires the registry onto the graph AFTER
+           *  `createWorkflow()` runs, so a direct capture here would be
+           *  `undefined` at construction time. */
+          parentHandlerRegistry: getParentHandlerRegistry,
           parentRunId: this.runId ?? '',
           parentAgentId: agentContext.agentId,
           tokenCounter: agentContext.tokenCounter,
@@ -1200,10 +1206,25 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           const subagentType =
             typeof input.subagent_type === 'string' ? input.subagent_type : '';
           const threadId = config.configurable?.thread_id as string | undefined;
+          /**
+           * When the tool is dispatched from an LLM's `tool_call`, LangChain
+           * threads the originating `ToolCall` onto the RunnableConfig as
+           * `config.toolCall` (see `ToolRunnableConfig` in
+           * `@langchain/core/tools` — internal but stable since ≥0.3.x).
+           * Surfacing its id lets hosts correlate `SubagentUpdateEvent`s
+           * back to the parent's `tool_call_id` deterministically — no
+           * temporal heuristics needed. If a future LangChain version
+           * changes the threading, the type-guarded read falls back to
+           * `undefined` and the correlation degrades gracefully.
+           */
+          const toolCall = (config as { toolCall?: { id?: string } }).toolCall;
+          const parentToolCallId =
+            typeof toolCall?.id === 'string' ? toolCall.id : undefined;
           const result = await executor.execute({
             description,
             subagentType,
             threadId,
+            parentToolCallId,
           });
           return result.content;
         }, buildSubagentToolParams(resolvedConfigs));

package/src/scripts/subagent-event-driven-debug.ts

@@ -0,0 +1,190 @@
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { ChatModelStreamHandler } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { Providers, GraphEvents, Constants } from '@/common';
+import { Run } from '@/run';
+
+/**
+ * Repro for LibreChat's actual setup: event-driven tools via `toolDefinitions`
+ * + an ON_TOOL_EXECUTE handler that runs the tool. Self-spawn subagent must
+ * be able to drive the SAME tool pipeline.
+ */
+const apiKey = process.env.OPENAI_API_KEY!;
+if (!apiKey) {
+  console.error('Missing OPENAI_API_KEY');
+  process.exit(1);
+}
+
+// Simulate LibreChat: tool definitions only, execution routed via event.
+const calculatorDef: t.LCTool = {
+  name: 'calculator',
+  description: 'Evaluate a math expression. Use for any arithmetic.',
+  parameters: {
+    type: 'object',
+    properties: {
+      expression: {
+        type: 'string',
+        description: "A JS math expression, e.g. '42 * 58'",
+      },
+    },
+    required: ['expression'],
+  },
+};
+
+async function main() {
+  console.log('=== Subagent Event-Driven Tool Diagnostic ===\n');
+
+  const parentAgent: t.AgentInputs = {
+    agentId: 'supervisor',
+    provider: Providers.OPENAI,
+    clientOptions: { modelName: 'gpt-4o-mini', apiKey },
+    instructions: `You have calculator AND can spawn a "self" subagent in an isolated context.
+For any arithmetic question, spawn the "self" subagent with the math task.
+The subagent MUST use the calculator tool — never estimate.`,
+    maxContextTokens: 8000,
+    toolDefinitions: [calculatorDef],
+    subagentConfigs: [
+      {
+        type: 'self',
+        self: true,
+        name: 'supervisor',
+        description:
+          'Spawn a copy of this agent in an isolated context for a focused math subtask.',
+      },
+    ],
+  };
+
+  let toolCallCount = 0;
+  const customHandlers: Record<string, t.EventHandler> = {
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.ON_TOOL_EXECUTE]: {
+      handle: (_event, rawData): void => {
+        const data = rawData as t.ToolExecuteBatchRequest;
+        console.log(
+          `[PARENT ON_TOOL_EXECUTE] agentId=${data.agentId} calls=${data.toolCalls
+            .map((c) => c.name)
+            .join(',')}`
+        );
+        const results: t.ToolExecuteResult[] = data.toolCalls.map((call) => {
+          toolCallCount += 1;
+          const args = call.args as { expression?: string };
+          const expression = args.expression ?? '';
+          let content: string;
+          try {
+            // eslint-disable-next-line no-eval
+            const result = eval(expression);
+            content = `${expression} = ${result}`;
+          } catch (err) {
+            content = `Error: ${String(err)}`;
+          }
+          return {
+            toolCallId: call.id!,
+            status: 'success',
+            content,
+          };
+        });
+        data.resolve(results);
+      },
+    },
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (event, data): void => {
+        const d = data as { type?: string; runId?: string; agentId?: string };
+        console.log(
+          `[PARENT ${event}] type=${d.type} agentId=${d.agentId ?? '-'} runId=${d.runId ?? '-'}`
+        );
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (event, data): void => {
+        const r = (
+          data as { result: { type: string; tool_call?: { name?: string } } }
+        ).result;
+        console.log(
+          `[PARENT ${event}] type=${r.type} tool=${r.tool_call?.name ?? '-'}`
+        );
+      },
+    },
+    [GraphEvents.ON_SUBAGENT_UPDATE]: {
+      handle: (_event, rawData): void => {
+        const d = rawData as t.SubagentUpdateEvent;
+        console.log(
+          `[SUBAGENT ${d.phase}] [${d.subagentType}] tool_call_id=${d.parentToolCallId ?? '-'} ${d.label ?? ''}`
+        );
+      },
+    },
+  };
+
+  const run = await Run.create<t.IState>({
+    runId: `sub-evt-${Date.now()}`,
+    graphConfig: { type: 'standard', agents: [parentAgent] },
+    customHandlers,
+  });
+
+  const question = new HumanMessage(
+    'Compute (42 * 58) + (13 ** 3). Use the self subagent, and have it use the calculator.'
+  );
+
+  console.log('User:', question.content, '\n');
+
+  await run.processStream(
+    { messages: [question] },
+    {
+      configurable: { thread_id: `sub-evt` },
+      version: 'v2' as const,
+    }
+  );
+
+  const msgs = (run.getRunMessages() ?? []) as BaseMessage[];
+  console.log('\n--- Run messages ---\n');
+  for (const msg of msgs) {
+    const type = msg._getType();
+    const name = 'name' in msg ? (msg as { name?: string }).name : undefined;
+    const content =
+      typeof msg.content === 'string'
+        ? msg.content.slice(0, 400)
+        : JSON.stringify(msg.content).slice(0, 400);
+    const toolCalls =
+      'tool_calls' in msg
+        ? (msg as { tool_calls?: Array<{ name: string; args: unknown }> })
+            .tool_calls
+        : undefined;
+    console.log(`[${type}]${name ? ` name=${name}` : ''}`);
+    if (toolCalls?.length) {
+      for (const tc of toolCalls) {
+        console.log(
+          `  tool_call: ${tc.name}(${JSON.stringify(tc.args).slice(0, 150)})`
+        );
+      }
+    }
+    console.log(`  content: ${content}\n`);
+  }
+
+  const subagentMsgs = msgs.filter(
+    (m) =>
+      m._getType() === 'tool' &&
+      (m as { name?: string }).name === Constants.SUBAGENT
+  );
+
+  console.log('--- Verification ---');
+  console.log(`subagent tool calls seen (parent): ${subagentMsgs.length}`);
+  console.log(
+    `ON_TOOL_EXECUTE dispatched (parent saw): ${toolCallCount} (expected >= 1 if subagent used calculator)`
+  );
+  if (subagentMsgs[0]) {
+    console.log(
+      `\nsubagent result:\n${(subagentMsgs[0].content as string).slice(0, 600)}`
+    );
+  }
+}
+
+main().catch((err) => {
+  console.error('Script error:', err);
+  process.exit(1);
+});

package/src/scripts/subagent-tools-debug.ts

@@ -0,0 +1,160 @@
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import { tool } from '@langchain/core/tools';
+import { z } from 'zod';
+import type * as t from '@/types';
+import { ChatModelStreamHandler } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { Providers, GraphEvents, Constants } from '@/common';
+import { Run } from '@/run';
+
+/**
+ * Diagnostic: verify a self-spawned subagent can call parent's real tools.
+ * Expected before-fix: parent delegates to self; child cannot invoke calculator.
+ */
+const apiKey = process.env.OPENAI_API_KEY!;
+if (!apiKey) {
+  console.error('Missing OPENAI_API_KEY');
+  process.exit(1);
+}
+
+const calculator = tool(
+  async ({ expression }) => {
+    const result = eval(expression); // don't do this in prod
+    return `${expression} = ${result}`;
+  },
+  {
+    name: 'calculator',
+    description: 'Evaluate a math expression. Use for any arithmetic.',
+    schema: z.object({
+      expression: z.string().describe("A JS math expression, e.g. '42 * 58'"),
+    }),
+  }
+);
+
+async function main() {
+  console.log('=== Subagent Tool-Access Diagnostic ===\n');
+
+  const parentAgent: t.AgentInputs = {
+    agentId: 'supervisor',
+    provider: Providers.OPENAI,
+    clientOptions: { modelName: 'gpt-4o-mini', apiKey },
+    instructions: `You have calculator AND can spawn a "self" subagent in an isolated context.
+For any arithmetic question that would bloat your context, spawn the "self" subagent with the math task.
+The subagent must use the calculator tool — never estimate.`,
+    maxContextTokens: 8000,
+    tools: [calculator],
+    subagentConfigs: [
+      {
+        type: 'self',
+        self: true,
+        name: 'supervisor',
+        description:
+          'Spawn a copy of this agent in an isolated context for a focused math subtask.',
+      },
+    ],
+  };
+
+  const customHandlers: Record<string, t.EventHandler> = {
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (event, data): void => {
+        console.log(
+          `[PARENT EVENT] ${event}`,
+          JSON.stringify(data).slice(0, 200)
+        );
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (event, data): void => {
+        console.log(
+          `[PARENT EVENT] ${event}`,
+          JSON.stringify(data).slice(0, 200)
+        );
+      },
+    },
+  };
+
+  const run = await Run.create<t.IState>({
+    runId: `subagent-debug-${Date.now()}`,
+    graphConfig: { type: 'standard', agents: [parentAgent] },
+    customHandlers,
+  });
+
+  const question = new HumanMessage(
+    'Compute (42 * 58) + (13 ^ 3). Spawn the self subagent to do this, and have IT use calculator.'
+  );
+
+  console.log('User:', question.content, '\n');
+
+  await run.processStream(
+    { messages: [question] },
+    {
+      configurable: { thread_id: `subagent-debug` },
+      version: 'v2' as const,
+    }
+  );
+
+  const msgs = (run.getRunMessages() ?? []) as BaseMessage[];
+  console.log('\n--- Run messages ---\n');
+  for (const msg of msgs) {
+    const type = msg._getType();
+    const name = 'name' in msg ? (msg as { name?: string }).name : undefined;
+    const content =
+      typeof msg.content === 'string'
+        ? msg.content.slice(0, 400)
+        : JSON.stringify(msg.content).slice(0, 400);
+    const toolCalls =
+      'tool_calls' in msg
+        ? (msg as { tool_calls?: Array<{ name: string; args: unknown }> })
+            .tool_calls
+        : undefined;
+    console.log(`[${type}]${name ? ` name=${name}` : ''}`);
+    if (toolCalls?.length) {
+      for (const tc of toolCalls) {
+        console.log(
+          `  tool_call: ${tc.name}(${JSON.stringify(tc.args).slice(0, 150)})`
+        );
+      }
+    }
+    console.log(`  content: ${content}\n`);
+  }
+
+  const subagentCalls = msgs.filter(
+    (m) =>
+      m._getType() === 'tool' &&
+      'name' in m &&
+      (m as { name?: string }).name === Constants.SUBAGENT
+  );
+  const calculatorCalls = msgs.filter(
+    (m) =>
+      m._getType() === 'tool' &&
+      'name' in m &&
+      (m as { name?: string }).name === 'calculator'
+  );
+
+  console.log('--- Verification ---');
+  console.log(`subagent tool calls seen (parent): ${subagentCalls.length}`);
+  console.log(
+    `calculator tool calls seen (parent): ${calculatorCalls.length} (expected: 0 if subagent did the math)`
+  );
+  if (subagentCalls.length > 0) {
+    const subResult = subagentCalls[0].content as string;
+    console.log(`\nsubagent result snippet:\n${subResult.slice(0, 600)}\n`);
+    if (/\berror\b/i.test(subResult) && /tool/i.test(subResult)) {
+      console.log('⚠️  BUG CONFIRMED: subagent result mentions tool error');
+    } else if (!/\d/.test(subResult)) {
+      console.log('⚠️  POSSIBLY BUGGY: subagent result has no numbers');
+    }
+  }
+}
+
+main().catch((err) => {
+  console.error('Script error:', err);
+  process.exit(1);
+});