@librechat/agents 3.1.68 → 3.1.71-dev.0

package/src/agents/AgentContext.ts

@@ -55,6 +55,8 @@ export class AgentContext {
       contextPruningConfig,
       maxToolResultChars,
       toolSchemaTokens,
+      subagentConfigs,
+      maxSubagentDepth,
     } = agentConfig;
 
     const agentContext = new AgentContext({
@@ -82,6 +84,10 @@ export class AgentContext {
       maxToolResultChars,
     });
 
+    agentContext._sourceInputs = agentConfig;
+    agentContext.subagentConfigs = subagentConfigs;
+    agentContext.maxSubagentDepth = maxSubagentDepth;
+
     if (initialSummary?.text != null && initialSummary.text !== '') {
       agentContext.setInitialSummary(
         initialSummary.text,
@@ -198,6 +204,12 @@ export class AgentContext {
   toolDefinitions?: t.LCTool[];
   /** Set of tool names discovered via tool search (to be loaded) */
   discoveredToolNames: Set<string> = new Set();
+  /** Original AgentInputs used to create this context — used for self-spawn subagent resolution. */
+  _sourceInputs?: t.AgentInputs;
+  /** Subagent configurations for hierarchical delegation. */
+  subagentConfigs?: t.SubagentConfig[];
+  /** Maximum subagent nesting depth. */
+  maxSubagentDepth?: number;
   /** Instructions for this agent */
   instructions?: string;
   /** Additional instructions for this agent */
@@ -685,8 +697,20 @@ export class AgentContext {
     let toolTokens = 0;
     const countedToolNames = new Set<string>();
 
-    if (this.tools && this.tools.length > 0) {
-      for (const tool of this.tools) {
+    /**
+     * Iterate both `tools` (user-provided instance tools) and `graphTools`
+     * (graph-managed tools like handoff + subagent). `graphTools` is often
+     * populated after `fromConfig()` kicks off the initial calculation, so
+     * callers that mutate `graphTools` must re-trigger this method to
+     * refresh `toolSchemaTokens`.
+     */
+    const instanceTools: t.GraphTools = [
+      ...((this.tools as t.GenericTool[] | undefined) ?? []),
+      ...((this.graphTools as t.GenericTool[] | undefined) ?? []),
+    ];
+
+    if (instanceTools.length > 0) {
+      for (const tool of instanceTools) {
         const genericTool = tool as Record<string, unknown>;
         if (
           genericTool.schema != null &&

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',
 
@@ -182,8 +184,21 @@ export enum Constants {
   MCP_DELIMITER = '_mcp_',
   /** Anthropic server tool ID prefix (web_search, code_execution, etc.) */
   ANTHROPIC_SERVER_TOOL_PREFIX = 'srvtoolu_',
+  SKILL_TOOL = 'skill',
+  READ_FILE = 'read_file',
+  BASH_TOOL = 'bash_tool',
+  BASH_PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_bash',
+  SUBAGENT = 'subagent',
 }
 
+/** Tool names that use the code execution environment (shared session, file tracking). */
+export const CODE_EXECUTION_TOOLS: ReadonlySet<string> = new Set([
+  Constants.EXECUTE_CODE,
+  Constants.BASH_TOOL,
+  Constants.PROGRAMMATIC_TOOL_CALLING,
+  Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
+]);
+
 export enum TitleMethod {
   STRUCTURED = 'structured',
   FUNCTIONS = 'functions',
@@ -191,6 +206,5 @@ export enum TitleMethod {
 }
 
 export enum EnvVar {
-  CODE_API_KEY = 'LIBRECHAT_CODE_API_KEY',
   CODE_BASEURL = 'LIBRECHAT_CODE_BASEURL',
 }

package/src/graphs/Graph.ts

@@ -1,5 +1,6 @@
 /* eslint-disable no-console */
 import { nanoid } from 'nanoid';
+import { tool } from '@langchain/core/tools';
 import { ToolNode } from '@langchain/langgraph/prebuilt';
 import { Runnable, RunnableConfig } from '@langchain/core/runnables';
 import { ToolMessage, AIMessageChunk } from '@langchain/core/messages';
@@ -39,7 +40,10 @@ import {
   joinKeys,
   sleep,
 } from '@/utils';
+import { SubagentExecutor, resolveSubagentConfigs } from '@/tools/subagent';
+import { buildSubagentToolParams } from '@/tools/SubagentTool';
 import { ToolNode as CustomToolNode, toolsCondition } from '@/tools/ToolNode';
+import { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import { safeDispatchCustomEvent, emitAgentLog } from '@/utils/events';
 import { attemptInvoke, tryFallbackProviders } from '@/llm/invoke';
 import { shouldTriggerSummarization } from '@/summarization';
@@ -53,6 +57,7 @@ import { isThinkingEnabled } from '@/llm/request';
 import { initializeModel } from '@/llm/init';
 import { HandlerRegistry } from '@/events';
 import { ChatOpenAI } from '@/llm/openai';
+import type { HookRegistry } from '@/hooks';
 
 const { AGENT, TOOLS, SUMMARIZE } = GraphNodeKeys;
 
@@ -123,6 +128,20 @@ export abstract class Graph<
   /** Set of invoked tool call IDs from non-message run steps completed mid-run, if any */
   invokedToolIds?: Set<string>;
   handlerRegistry: HandlerRegistry | undefined;
+  hookRegistry: HookRegistry | undefined;
+  /**
+   * Run-scoped config for the tool output reference registry. Threaded
+   * from `RunConfig.toolOutputReferences` down into every ToolNode this
+   * graph compiles.
+   */
+  toolOutputReferences: t.ToolOutputReferencesConfig | undefined;
+  /**
+   * Shared registry instance used by every ToolNode compiled from this
+   * graph. Lazily constructed on first access so multi-agent graphs
+   * produce one registry per run (not one per agent), letting cross-
+   * agent `{{tool<i>turn<n>}}` substitutions resolve.
+   */
+  private _toolOutputRegistry?: ToolOutputReferenceRegistry;
   /**
    * Tool session contexts for automatic state persistence across tool invocations.
    * Keyed by tool name (e.g., Constants.EXECUTE_CODE).
@@ -147,8 +166,41 @@ export abstract class Graph<
     this.prelimMessageIdsByStepKey = new Map();
     this.invokedToolIds = undefined;
     this.handlerRegistry = undefined;
+    this.hookRegistry = undefined;
+    this.toolOutputReferences = undefined;
+    /**
+     * ToolNodes compiled from this graph captured the registry
+     * instance at construction time, so simply dropping the Graph's
+     * own reference would leave their captured reference — and every
+     * stored `tool<i>turn<n>` entry, plus up to `maxTotalSize` of raw
+     * output — alive across subsequent `processStream()` calls. Wipe
+     * the registry's contents first so subsequent runs start fresh.
+     */
+    this._toolOutputRegistry?.clear();
+    this._toolOutputRegistry = undefined;
     this.sessions.clear();
   }
+
+  /**
+   * Returns the shared `ToolOutputReferenceRegistry` for this run,
+   * constructing it on first access. Returns `undefined` when the
+   * feature is disabled. All ToolNodes compiled from this graph share
+   * this single instance so cross-agent `{{…}}` references resolve.
+   */
+  protected getOrCreateToolOutputRegistry():
+    | ToolOutputReferenceRegistry
+    | undefined {
+    if (this.toolOutputReferences?.enabled !== true) {
+      return undefined;
+    }
+    if (this._toolOutputRegistry == null) {
+      this._toolOutputRegistry = new ToolOutputReferenceRegistry({
+        maxOutputSize: this.toolOutputReferences.maxOutputSize,
+        maxTotalSize: this.toolOutputReferences.maxTotalSize,
+      });
+    }
+    return this._toolOutputRegistry;
+  }
 }
 
 export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
@@ -506,9 +558,11 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         agentId: agentContext?.agentId,
         toolCallStepIds: this.toolCallStepIds,
         toolRegistry: agentContext?.toolRegistry,
+        hookRegistry: this.hookRegistry,
         directToolNames: directToolNames.size > 0 ? directToolNames : undefined,
         maxContextTokens: agentContext?.maxContextTokens,
         maxToolResultChars: agentContext?.maxToolResultChars,
+        toolOutputRegistry: this.getOrCreateToolOutputRegistry(),
         errorHandler: (data, metadata) =>
           StandardGraph.handleToolCallErrorStatic(this, data, metadata),
       });
@@ -540,6 +594,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       sessions: this.sessions,
       maxContextTokens: agentContext?.maxContextTokens,
       maxToolResultChars: agentContext?.maxToolResultChars,
+      toolOutputRegistry: this.getOrCreateToolOutputRegistry(),
     });
   }
 
@@ -1148,6 +1203,111 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       throw new Error(`Agent context not found for agentId: ${agentId}`);
     }
 
+    /**
+     * Depth countdown across graph boundaries: the parent's `maxSubagentDepth`
+     * becomes this executor's `maxDepth`. When the child graph is constructed,
+     * `buildChildInputs()` decrements `maxSubagentDepth` on the child's
+     * `AgentInputs` (only when `allowNested: true`; otherwise subagentConfigs
+     * are stripped entirely). The child graph's own `createAgentNode()` then
+     * reads the decremented value here and creates a narrower executor —
+     * recursion is bounded even though each graph has its own separate
+     * executor instance.
+     */
+    const effectiveSubagentDepth = agentContext.maxSubagentDepth ?? 1;
+    if (
+      agentContext.subagentConfigs != null &&
+      agentContext.subagentConfigs.length > 0 &&
+      effectiveSubagentDepth > 0
+    ) {
+      const resolvedConfigs = resolveSubagentConfigs(
+        agentContext.subagentConfigs,
+        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,
+          maxDepth: effectiveSubagentDepth,
+          createChildGraph: (input): StandardGraph => new StandardGraph(input),
+        });
+
+        const subagentTool = tool(async (rawInput, config) => {
+          const input = rawInput as {
+            description?: string;
+            subagent_type?: string;
+          };
+          const description =
+            typeof input.description === 'string' &&
+            input.description.trim().length > 0
+              ? input.description
+              : 'No task description provided';
+          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));
+
+        if (!agentContext.graphTools) {
+          agentContext.graphTools = [];
+        }
+        (agentContext.graphTools as t.GenericTool[]).push(subagentTool);
+
+        /**
+         * Refresh toolSchemaTokens to include the subagent tool's schema.
+         * `calculateInstructionTokens()` was kicked off in `fromConfig()`
+         * before graphTools was populated, so its result did not count this
+         * tool. Without this retrigger, token-budget/pruning logic
+         * underestimates prompt overhead.
+         */
+        if (agentContext.tokenCounter) {
+          const { tokenCounter, baseIndexTokenCountMap } = agentContext;
+          agentContext.tokenCalculationPromise = agentContext
+            .calculateInstructionTokens(tokenCounter)
+            .then(() => {
+              agentContext.updateTokenMapWithInstructions(
+                baseIndexTokenCountMap
+              );
+            })
+            .catch((err) => {
+              console.error(
+                'Error recalculating instruction tokens after subagent tool injection:',
+                err
+              );
+            });
+        }
+      }
+    }
+
     const agentNode = `${AGENT}${agentId}` as const;
     const toolNode = `${TOOLS}${agentId}` as const;
     const summarizeNode = `${SUMMARIZE}${agentId}` as const;
@@ -1203,6 +1363,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
             },
             runId: this.runId,
             isMultiAgent: this.isMultiAgentGraph(),
+            hookRegistry: this.hookRegistry,
             dispatchRunStep: async (runStep, nodeConfig) => {
               this.contentData.push(runStep);
               this.contentIndexMap.set(runStep.id, runStep.index);

package/src/hooks/HookRegistry.ts

@@ -0,0 +1,208 @@
+// src/hooks/HookRegistry.ts
+import type { HookEvent, HookMatcher } from './types';
+
+/**
+ * Internal matcher storage type.
+ *
+ * Matchers registered via the public `register<E>` API are strictly typed
+ * to a single `E`, but the storage needs one uniform slot type per event.
+ * We store them as `HookMatcher<HookEvent>` and cast once at the variance
+ * boundary — see `ensureList` and `snapshot` below. The invariant (every
+ * matcher in `bucket[event]` was registered with that exact event) is
+ * enforced by the public API; breaking it requires bypassing the types.
+ */
+type MatcherBucket = Partial<Record<HookEvent, HookMatcher<HookEvent>[]>>;
+
+/**
+ * Run-scoped storage for hook matchers with an additional layer for
+ * session-scoped matchers that should be cleaned up between sessions.
+ *
+ * Hosts construct one registry per `Run` (mirroring how `HandlerRegistry` is
+ * scoped) and register global matchers + per-session matchers against it.
+ * Registration is strictly additive — nothing in this class mutates a
+ * matcher's callbacks or flags after insertion.
+ *
+ * ## Why `Map<sessionId, MatcherBucket>` and not `Record`
+ *
+ * LibreChat runs thousands of parallel sessions in one Node process, and
+ * hook registration happens inside hot paths (tool loading, agent spawning).
+ * A `Record<sessionId, ...>` has to be spread on every insertion, which is
+ * O(n) per call and O(n²) total for a batch of parallel registrations. A
+ * Map mutates in place, keeping insertions O(1). This mirrors the reasoning
+ * Claude Code documents at `utils/hooks/sessionHooks.ts:62`.
+ */
+export class HookRegistry {
+  private readonly global: MatcherBucket = {};
+  private readonly sessions: Map<string, MatcherBucket> = new Map();
+
+  /**
+   * Register a matcher for the lifetime of this registry (= one Run).
+   * Returns an unregister function that removes the matcher by reference.
+   */
+  register<E extends HookEvent>(event: E, matcher: HookMatcher<E>): () => void {
+    const list = ensureList(this.global, event);
+    list.push(widen(matcher));
+    return () => {
+      removeFromList(list, matcher);
+    };
+  }
+
+  /**
+   * Register a matcher for a specific session. Cleared automatically when
+   * `clearSession(sessionId)` is called, or can be removed directly via the
+   * returned unregister function.
+   */
+  registerSession<E extends HookEvent>(
+    sessionId: string,
+    event: E,
+    matcher: HookMatcher<E>
+  ): () => void {
+    const bucket = this.ensureSessionBucket(sessionId);
+    const list = ensureList(bucket, event);
+    list.push(widen(matcher));
+    return () => {
+      removeFromList(list, matcher);
+    };
+  }
+
+  /**
+   * Returns all matchers registered for `event`, concatenating global first
+   * and then session-specific (when `sessionId` is supplied). The caller
+   * receives a fresh array, so iterating it is safe even if a matcher is
+   * removed mid-iteration (e.g. via `once: true`).
+   */
+  getMatchers<E extends HookEvent>(
+    event: E,
+    sessionId?: string
+  ): HookMatcher<E>[] {
+    const globalList = readList(this.global, event);
+    if (sessionId === undefined) {
+      return snapshot<E>(globalList);
+    }
+    const bucket = this.sessions.get(sessionId);
+    if (bucket === undefined) {
+      return snapshot<E>(globalList);
+    }
+    const sessionList = readList(bucket, event);
+    if (globalList.length === 0) {
+      return snapshot<E>(sessionList);
+    }
+    if (sessionList.length === 0) {
+      return snapshot<E>(globalList);
+    }
+    return snapshot<E>([...globalList, ...sessionList]);
+  }
+
+  /**
+   * Removes `matcher` by reference from global storage first, falling back
+   * to the session bucket when `sessionId` is supplied. Used by
+   * `executeHooks` to drop `once: true` matchers after they fire.
+   */
+  removeMatcher<E extends HookEvent>(
+    event: E,
+    matcher: HookMatcher<E>,
+    sessionId?: string
+  ): boolean {
+    if (removeFromList(readList(this.global, event), matcher)) {
+      return true;
+    }
+    if (sessionId === undefined) {
+      return false;
+    }
+    const bucket = this.sessions.get(sessionId);
+    if (bucket === undefined) {
+      return false;
+    }
+    return removeFromList(readList(bucket, event), matcher);
+  }
+
+  /**
+   * Drops every session-scoped matcher for `sessionId`. Call this in the
+   * `finally` block around a Run so a `once: true` hook that never fired
+   * cannot leak into the next session on the same registry.
+   */
+  clearSession(sessionId: string): void {
+    this.sessions.delete(sessionId);
+  }
+
+  /** True if at least one matcher exists for `event` (global + session). */
+  hasHookFor(event: HookEvent, sessionId?: string): boolean {
+    if (readList(this.global, event).length > 0) {
+      return true;
+    }
+    if (sessionId === undefined) {
+      return false;
+    }
+    const bucket = this.sessions.get(sessionId);
+    if (bucket === undefined) {
+      return false;
+    }
+    return readList(bucket, event).length > 0;
+  }
+
+  private ensureSessionBucket(sessionId: string): MatcherBucket {
+    const existing = this.sessions.get(sessionId);
+    if (existing !== undefined) {
+      return existing;
+    }
+    const fresh: MatcherBucket = {};
+    this.sessions.set(sessionId, fresh);
+    return fresh;
+  }
+}
+
+function ensureList(
+  bucket: MatcherBucket,
+  event: HookEvent
+): HookMatcher<HookEvent>[] {
+  const existing = bucket[event];
+  if (existing !== undefined) {
+    return existing;
+  }
+  const fresh: HookMatcher<HookEvent>[] = [];
+  bucket[event] = fresh;
+  return fresh;
+}
+
+function readList(
+  bucket: MatcherBucket,
+  event: HookEvent
+): HookMatcher<HookEvent>[] {
+  return bucket[event] ?? [];
+}
+
+function removeFromList<E extends HookEvent>(
+  list: HookMatcher<HookEvent>[],
+  matcher: HookMatcher<E>
+): boolean {
+  const idx = list.indexOf(widen(matcher));
+  if (idx < 0) {
+    return false;
+  }
+  list.splice(idx, 1);
+  return true;
+}
+
+/**
+ * Widen a per-event matcher to the storage's uniform slot type. Unsound at
+ * the type level (function parameters are contravariant) but safe by
+ * construction: `HookRegistry.register<E>` only ever puts matchers into the
+ * bucket slot for their own event, and reads go through `snapshot<E>`
+ * which is only called with the same `E`.
+ */
+function widen<E extends HookEvent>(
+  matcher: HookMatcher<E>
+): HookMatcher<HookEvent> {
+  return matcher as unknown as HookMatcher<HookEvent>;
+}
+
+/**
+ * Narrow a storage list back to a per-event matcher list on the way out.
+ * Sound counterpart to `widen`: the list only contains matchers that were
+ * registered against `E`, because the public API enforces it on insert.
+ */
+function snapshot<E extends HookEvent>(
+  list: readonly HookMatcher<HookEvent>[]
+): HookMatcher<E>[] {
+  return list.slice() as unknown as HookMatcher<E>[];
+}