@librechat/agents 3.1.77 → 3.1.78

package/src/tools/local/workspaceFS.ts

@@ -0,0 +1,89 @@
+/**
+ * Engine-agnostic filesystem seam for the local-coding tool suite.
+ *
+ * The current "local" engine maps every operation to Node's
+ * `fs/promises` against the host machine. A future engine — e.g. a
+ * stateful remote sandbox (e2b / Modal / Daytona / ssh-jail) —
+ * supplies its own `WorkspaceFS` implementation and reuses every
+ * tool factory unchanged. Same fuzzy-match `edit_file`, same
+ * checkpointer, same syntax-check, same image attachments — only
+ * the underlying I/O changes.
+ *
+ * Path semantics belong to the implementation. The local engine
+ * interprets paths as host filesystem paths; a remote engine would
+ * interpret them as remote-namespace paths. Tool factories don't
+ * inspect the strings beyond passing them through.
+ *
+ * Keep this surface minimal. Add a method only when an existing
+ * tool genuinely needs it; resist the temptation to mirror all of
+ * `fs/promises`.
+ */
+
+import {
+  mkdir as fsMkdir,
+  open as fsOpen,
+  readdir as fsReaddir,
+  readFile as fsReadFile,
+  realpath as fsRealpath,
+  stat as fsStat,
+  unlink as fsUnlink,
+  writeFile as fsWriteFile,
+} from 'fs/promises';
+import type { MakeDirectoryOptions, Stats, WriteFileOptions } from 'fs';
+import type { FileHandle } from 'fs/promises';
+
+export type ReaddirEntry = {
+  name: string;
+  isFile(): boolean;
+  isDirectory(): boolean;
+  isSymbolicLink(): boolean;
+};
+
+export interface WorkspaceFS {
+  readFile(path: string, encoding: 'utf8'): Promise<string>;
+  readFile(path: string): Promise<Buffer>;
+  writeFile(
+    path: string,
+    content: string | Buffer,
+    options?: WriteFileOptions
+  ): Promise<void>;
+  stat(path: string): Promise<Stats>;
+  readdir(
+    path: string,
+    options: { withFileTypes: true }
+  ): Promise<ReaddirEntry[]>;
+  readdir(path: string): Promise<string[]>;
+  mkdir(path: string, options?: MakeDirectoryOptions): Promise<void>;
+  realpath(path: string): Promise<string>;
+  unlink(path: string): Promise<void>;
+  /** Open a file for low-level read access (used by binary detection). */
+  open(path: string, flags: 'r'): Promise<FileHandle>;
+}
+
+/**
+ * Default `WorkspaceFS` backed by Node's `fs/promises` module.
+ * Returned by `getWorkspaceFS(config)` when the host hasn't supplied
+ * an override on `local.exec.fs`.
+ */
+export const nodeWorkspaceFS: WorkspaceFS = {
+  // The runtime impl ignores the encoding-vs-buffer distinction; the
+  // overload signatures above are what callers see.
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  readFile: ((path: string, encoding?: 'utf8') =>
+    encoding != null
+      ? fsReadFile(path, encoding)
+      : fsReadFile(path)) as WorkspaceFS['readFile'],
+  writeFile: (path, content, options) =>
+    fsWriteFile(path, content, options ?? 'utf8'),
+  stat: (path) => fsStat(path),
+  readdir: ((path: string, options?: { withFileTypes: true }) =>
+    options?.withFileTypes === true
+      ? fsReaddir(path, { withFileTypes: true })
+      : fsReaddir(path)) as WorkspaceFS['readdir'],
+  mkdir: async (path, options) => {
+    await fsMkdir(path, options);
+  },
+  realpath: (path) => fsRealpath(path),
+  unlink: (path) => fsUnlink(path),
+  open: (path, flags) => fsOpen(path, flags),
+};

package/src/tools/subagent/SubagentExecutor.ts

@@ -40,6 +40,35 @@ export type SubagentExecuteParams = {
    * without relying on event ordering heuristics.
    */
   parentToolCallId?: string;
+  /**
+   * Snapshot of the parent invocation's `config.configurable` at the
+   * spawn-tool call site. Inherited verbatim into the child workflow's
+   * `configurable` so host-set fields (`requestBody`, `user`,
+   * `userMCPAuthMap`, etc.) propagate — fixing MCP body-placeholder
+   * substitution and per-user lookups for subagent tool calls.
+   *
+   * Inheritance details (verified empirically against LangGraph):
+   *   - host-set keys propagate as-is into the child's tool dispatches;
+   *   - `thread_id` propagates (with `childRunId` as a fallback when
+   *     parent did not supply one) — matches the "subagent is part of
+   *     the same conversation" mental model and aligns with the
+   *     `sessionId: this.parentRunId` convention this executor already
+   *     uses for `SubagentStart` / `SubagentStop` hooks;
+   *   - `parent_run_id` propagates when the host put it on parent's
+   *     configurable;
+   *   - `run_id` is *overwritten by the LangGraph runtime* at child
+   *     invoke time regardless of what we forward — child's tool
+   *     dispatches see the child graph's runtime runId in
+   *     `configurable.run_id`, not the parent's. Hosts that need
+   *     parent-scoped run identity for downstream consumers should
+   *     plumb it via a host-defined key (e.g. `requestBody.messageId`),
+   *     not `run_id`.
+   *
+   * A future revision will likely make this inheritance configurable
+   * per spawn type — background / async subagents may want isolation
+   * rather than sharing parent's host context.
+   */
+  parentConfigurable?: Record<string, unknown>;
 };
 
 export type SubagentExecuteResult = {
@@ -246,6 +275,36 @@ export class SubagentExecutor {
        * nested trace pollution).
        */
       const callbacks: Callbacks = forwarder ? [forwarder] : [];
+      /**
+       * Inherit the parent's `configurable` verbatim — host-set fields
+       * (`requestBody`, `user`, `userMCPAuthMap`, etc.) AND the run-
+       * identity fields (`run_id`, `parent_run_id`, `thread_id`) all
+       * propagate.
+       *
+       * Run-identity propagation is intentional and matches the
+       * convention this executor itself already uses for `SubagentStart`
+       * / `SubagentStop` hooks (`sessionId: this.parentRunId`): the
+       * subagent runs under the parent's session scope, not its own.
+       * Forwarding `run_id` / `parent_run_id` / `thread_id` makes
+       * `ToolNode`'s hook lookups (`hasHookFor(eventName, runId)`),
+       * `ToolOutputReferenceRegistry` keying, and trace lineage all
+       * resolve to the parent's session for tools dispatched from the
+       * subagent — so `PreToolUse` / `PostToolUse` hooks the host
+       * registered against the parent's run fire for subagent tool
+       * calls too. "Same run" matches the user-perceptual mental model.
+       *
+       * `thread_id` falls back to `childRunId` only when the parent
+       * didn't supply one (legacy behavior preserved for hosts that
+       * never set thread_id).
+       *
+       * NOTE: a future revision will likely make this configurable per
+       * spawn type — e.g. a background / async subagent that runs after
+       * the parent's run completes wants isolation, not inheritance.
+       * For now the inheritance path matches LibreChat's primary use
+       * case (synchronous subagents within a single user turn).
+       */
+      const inheritedConfigurable: Record<string, unknown> =
+        params.parentConfigurable ?? {};
       result = await workflow.invoke(
         { messages: [new HumanMessage(description)] },
         {
@@ -255,6 +314,7 @@ export class SubagentExecutor {
           runName: `subagent:${subagentType}`,
           configurable: {
             thread_id: childRunId,
+            ...inheritedConfigurable,
           },
         }
       );

package/src/types/hitl.ts

@@ -233,39 +233,68 @@ export function isAskUserQuestionInterrupt(
  * matches the pre-HITL behavior so existing hosts upgrading the SDK
  * see no change until they're ready to wire the resume UI.
  *
- * ## Scope: event-driven tools only
+ * ## Scope: every tool the ToolNode runs
  *
- * The interrupt path is wired into `ToolNode.dispatchToolEvents`, which
- * runs when the agent uses event-driven tool dispatch (the path
- * LibreChat and most production hosts take). Tools that execute via
- * the direct path — i.e. tools listed in `directToolNames` (the
- * graph-managed handoff and subagent tools) or tools on agents
- * configured WITHOUT `eventDrivenMode` — bypass the hook system
- * entirely. `PreToolUse` hooks do not fire for those tools and HITL
- * approval does not gate them.
+ * The interrupt path is wired into both `dispatchToolEvents` (the
+ * event-driven path) and `runDirectToolWithLifecycleHooks` (the
+ * direct path used by `directToolNames` entries — graph-managed
+ * handoff/subagent tools and every in-process `graphTool` instance).
+ * `PreToolUse` hooks fire for every tool the ToolNode invokes, and
+ * HITL approval gates every tool whose hook returns `'ask'` —
+ * regardless of whether the tool is dispatched as an event or
+ * invoked in-process. This convergence happened in two follow-up
+ * commits to the original HITL surface (see `Graph.ts` —
+ * `hookRegistry`/`humanInTheLoop` are passed in both
+ * event-driven and legacy branches; and `ToolNode.runDirectToolWithLifecycleHooks`
+ * — direct-path tools build their own single-tool `tool_approval`
+ * payload and raise `interrupt()` the same way the event path does).
  *
  * Practical implications:
- *   - LibreChat-style hosts using event-driven dispatch get the full
- *     HITL surface across every tool the model calls.
- *   - Hosts using `AgentInputs.tools` directly without event-driven
- *     mode get policy enforcement for nothing — the hooks register
- *     but never fire. Either switch to event-driven mode or accept
- *     that direct tools are not approval-gated. This is documented
- *     also on `ToolNodeOptions.hookRegistry`.
- *   - Mixed direct + event batches (e.g. a handoff tool sharing an
- *     LLM turn with a regular tool) currently re-execute the direct
- *     half on resume, since LangGraph rolls back the entire ToolNode
- *     on `interrupt()` throw. Hosts whose direct tools have side
- *     effects (subagents that invoke models, handoffs that trigger
- *     downstream work) should avoid mixing those tools into the same
- *     batch as approval-gated event tools.
+ *   - Every host gets the full HITL surface across every tool the
+ *     model calls — event-dispatched, direct, mixed.
+ *   - `createToolPolicyHook` and `createWorkspacePolicyHook` apply
+ *     uniformly. A hook can be registered without knowing or caring
+ *     which path the tool will take.
+ *   - Direct tools that the host opted into via `directToolNames` no
+ *     longer bypass policy. If you need a tool to skip the hook
+ *     surface entirely, omit it from any registered matcher.
+ *
+ * ## Resume re-execution: every tool in the interrupted batch
+ *
+ * LangGraph rolls back to the start of the interrupted node on
+ * resume. That means **every tool in the same batch as the one that
+ * interrupted re-runs from the top on the resume pass**, not just
+ * the interrupting tool, and not just the direct half (this used to
+ * be framed as a direct-tool-specific concern; it is not — it
+ * applies to event-dispatched siblings too). Practical contract:
+ *
+ *   - The body of the interrupting tool itself runs **once** total
+ *     (the first pass interrupted *before* the body, the resume pass
+ *     ran the body after the host's decision was applied).
+ *   - The body of any sibling tool that already executed in the
+ *     same batch before the interrupting tool runs **twice** — once
+ *     on the first pass, once on the resume pass.
+ *   - `PreToolUse` hooks fire **once per pass per tool**. A hook
+ *     that always returns `'ask'` will loop forever on resume; real
+ *     hooks should be deterministic w.r.t. inputs and use the
+ *     `'ask' → host approves → resume → hook returns 'allow'`
+ *     pattern, where the second-pass `allow` reflects the host
+ *     having recorded the approval (e.g., a session-scoped approved-
+ *     paths set keyed by `runId`).
+ *
+ * Consequence: any tool with side effects MUST be idempotent if
+ * there's any chance another tool in the same batch could trigger
+ * an interrupt. This applies equally to direct tools (handoffs,
+ * subagents) and to event tools.
  *
  * ## Note on idempotency
  *
- * When an interrupt fires, LangGraph re-runs the interrupted node
- * from the start on resume, which fires `PreToolUse` hooks again.
- * Hooks that produce side effects (logging, external calls) will see
- * two invocations per paused turn.
+ * Same root cause as the resume re-execution above: LangGraph
+ * re-runs the interrupted node from the start on resume, which
+ * fires `PreToolUse` hooks again. Hooks that produce side effects
+ * (logging, external calls) will see at least two invocations per
+ * paused turn — exactly two for the interrupting tool, possibly
+ * more across siblings.
  */
 export interface HumanInTheLoopConfig {
   /**

package/src/types/run.ts

@@ -11,7 +11,11 @@ import type * as s from '@/types/stream';
 import type * as e from '@/common/enum';
 import type * as g from '@/types/graph';
 import type * as l from '@/types/llm';
-import type { ToolSessionMap, ToolOutputReferencesConfig } from '@/types/tools';
+import type {
+  ToolSessionMap,
+  ToolExecutionConfig,
+  ToolOutputReferencesConfig,
+} from '@/types/tools';
 import type { HumanInTheLoopConfig } from '@/types/hitl';
 import type { HookRegistry } from '@/hooks';
 
@@ -157,6 +161,13 @@ export type RunConfig = {
    * placeholders. Disabled by default so existing runs are unaffected.
    */
   toolOutputReferences?: ToolOutputReferencesConfig;
+  /**
+   * Selects the execution backend for built-in code tools. Omit this to keep
+   * the remote LibreChat Code API sandbox. Set `{ engine: 'local' }` to run
+   * code execution locally and auto-bind the local coding tool suite unless
+   * `local.includeCodingTools` is set to `false`.
+   */
+  toolExecution?: ToolExecutionConfig;
   /**
    * First-class human-in-the-loop (HITL) flow for this run.
    *

package/src/types/summarize.ts

@@ -10,6 +10,30 @@ export type SummarizationTrigger = {
   value: number;
 };
 
+/**
+ * Controls how many recent messages are preserved verbatim during
+ * compaction.  The most recent user-led turn is always preserved
+ * regardless of these caps, so a single oversized first message is
+ * never destroyed by summarization.
+ */
+export type RetainRecentConfig = {
+  /**
+   * Maximum number of recent user-led turns to keep in the tail.  A turn
+   * begins at a HumanMessage and includes every following AIMessage and
+   * ToolMessage up to (but not including) the next HumanMessage.  Cutting
+   * at turn boundaries guarantees tool_use / tool_result pairs are never
+   * split.  Set to `0` to disable the recency window (legacy behavior:
+   * summarize everything).  Defaults to `2`.
+   */
+  turns?: number;
+  /**
+   * Optional cap on retained-recent tokens beyond the most recent turn.
+   * Older turns are added whole only while cumulative tokens stay below
+   * the cap.  Defaults to undefined (no cap; bounded only by `turns`).
+   */
+  tokens?: number;
+};
+
 export type SummarizationConfig = {
   provider?: Providers;
   model?: string;
@@ -20,6 +44,13 @@ export type SummarizationConfig = {
   maxSummaryTokens?: number;
   /** Fraction of the token budget reserved as headroom (0–1). Defaults to 0.05. */
   reserveRatio?: number;
+  /**
+   * Recent-message preservation policy.  When unset, defaults to
+   * `{ turns: 2 }` so the last two user-led turns are kept verbatim
+   * while older content is summarized.  Setting `{ turns: 0 }` reverts
+   * to the legacy behavior of summarizing every message.
+   */
+  retainRecent?: RetainRecentConfig;
 };
 
 export interface SummarizeResult {