@librechat/agents 3.1.77 → 3.1.78-dev.0

package/dist/types/tools/local/resolveLocalExecutionTools.d.ts

@@ -0,0 +1,38 @@
+import type * as t from '@/types';
+type ResolveLocalToolsResult = {
+    toolMap: t.ToolMap;
+    directToolNames: Set<string>;
+    /**
+     * Set when `local.fileCheckpointing === true` AND the auto-bind
+     * coding suite is in use. ToolNode stashes this on the node and
+     * exposes it via `getFileCheckpointer()` so the host can call
+     * `rewind()` after a failed batch. Manual review (finding E)
+     * flagged that the config flag was previously a no-op in the
+     * Run/ToolNode auto-bind path — only direct
+     * `createLocalCodingToolBundle()` callers could access the
+     * checkpointer.
+     */
+    fileCheckpointer?: t.LocalFileCheckpointer;
+};
+export declare function resolveLocalToolsForBinding(args: {
+    tools?: t.GraphTools;
+    toolExecution?: t.ToolExecutionConfig;
+}): t.GraphTools | undefined;
+export declare function resolveLocalToolRegistry(args: {
+    toolRegistry?: t.LCToolRegistry;
+    toolExecution?: t.ToolExecutionConfig;
+}): t.LCToolRegistry | undefined;
+export declare function resolveLocalExecutionTools(args: {
+    toolMap: t.ToolMap;
+    toolExecution?: t.ToolExecutionConfig;
+    /**
+     * Caller-provided checkpointer that overrides the bundle's
+     * auto-created one. The Graph layer threads a single per-Run
+     * instance so every ToolNode it compiles shares one snapshot
+     * store — without that, a multi-agent graph would each get a
+     * private checkpointer and `Run.rewindFiles()` couldn't reach
+     * any of them.
+     */
+    fileCheckpointer?: t.LocalFileCheckpointer;
+}): ResolveLocalToolsResult;
+export {};

package/dist/types/tools/local/syntaxCheck.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Per-file syntax check used by `edit_file` / `write_file` to surface
+ * obvious errors immediately after the write — strictly cheaper than
+ * full LSP integration and catches the bulk of "you broke the file"
+ * regressions a vision-less agent loop would otherwise miss until
+ * the next call.
+ *
+ * Each checker is a tiny shell-out (or in-process function) keyed on
+ * file extension. Failures are returned as a single short message;
+ * the wiring layer decides whether to append it to the tool result
+ * advisorily (`auto`) or to throw and force the model to react
+ * (`strict`).
+ *
+ * We deliberately do NOT cover TypeScript here because per-file `tsc`
+ * is slow and per-file syntax (without type info) misses most TS
+ * errors anyway. Use the project-level `compile_check` tool for that.
+ */
+import type * as t from '@/types';
+export type SyntaxCheckOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    checker: string;
+    output: string;
+};
+export type SyntaxChecker = (path: string, config: t.LocalExecutionConfig) => Promise<SyntaxCheckOutcome>;
+/**
+ * Test-only reset hook. Clears the per-backend probe cache so tests
+ * can swap in mocked spawn backends and reprobe deterministically.
+ *
+ * @internal Not part of the public SDK surface.
+ */
+export declare function _resetSyntaxCheckProbeCacheForTests(): void;
+/**
+ * Run the post-edit syntax check for `absolutePath`. Returns
+ * `null` when no checker matches the extension (most files), or a
+ * `SyntaxCheckOutcome`.
+ *
+ * Truncates `output` to `maxOutputChars` (default 4096) so a
+ * 10MB-of-errors transpiler dump can't blow the model context.
+ */
+export declare function runPostEditSyntaxCheck(absolutePath: string, config: t.LocalExecutionConfig): Promise<SyntaxCheckOutcome | null>;

package/dist/types/tools/local/textEncoding.d.ts

@@ -0,0 +1,21 @@
+/**
+ * BOM and line-ending preservation helpers for the local engine's
+ * file-mutating tools. We never *introduce* a BOM or change line
+ * endings — only preserve what was already on disk so a Windows-
+ * checked-in source file stays CRLF and a UTF-8-with-BOM JSON file
+ * keeps its BOM after an edit.
+ *
+ * Inspired by opencode's `Bom` helper. Trimmed to the cases that
+ * actually matter for editing source code (UTF-8 BOM only;
+ * UTF-16/UTF-32 are out of scope).
+ */
+export interface EncodedFile {
+    /** File contents with BOM stripped. */
+    text: string;
+    /** Whether the on-disk file started with a UTF-8 BOM. */
+    hasBom: boolean;
+    /** Detected newline style. CRLF wins if any CRLF is present. */
+    newline: '\n' | '\r\n';
+}
+export declare function decodeFile(raw: string): EncodedFile;
+export declare function encodeFile(text: string, encoding: EncodedFile): string;

package/dist/types/tools/local/workspaceFS.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 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 declare const nodeWorkspaceFS: WorkspaceFS;

package/dist/types/types/hitl.d.ts

@@ -203,39 +203,68 @@ export declare function isAskUserQuestionInterrupt(payload: unknown): payload is
  * 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/dist/types/types/run.d.ts

@@ -7,7 +7,7 @@ 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';
 export type ZodObjectAny = z.ZodObject<any, any, any, any>;
@@ -145,6 +145,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/dist/types/types/summarize.d.ts

@@ -4,6 +4,29 @@ export type SummarizationTrigger = {
     type: 'token_ratio' | 'remaining_tokens' | 'messages_to_refine' | (string & {});
     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;
@@ -14,6 +37,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 {
     text: string;