@librechat/agents 3.1.77-dev.1 → 3.1.78-dev.0

package/dist/types/tools/ToolNode.d.ts

@@ -2,7 +2,7 @@ import { ToolCall } from '@langchain/core/messages/tool';
 import { END, Command, MessagesAnnotation } from '@langchain/langgraph';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
-import type { ResolvedArgsByCallId } from '@/tools/toolOutputReferences';
+import type { ToolOutputResolveView, ResolvedArgsByCallId } from '@/tools/toolOutputReferences';
 import type * as t from '@/types';
 import { RunnableCallable } from '@/utils';
 import { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
@@ -20,6 +20,36 @@ type RunToolBatchContext = {
     batchScopeId?: string;
     /** Batch-local sink for post-substitution args. */
     resolvedArgsByCallId?: ResolvedArgsByCallId;
+    /**
+     * Frozen pre-batch view of the tool-output registry. When supplied,
+     * `runTool` resolves `{{tool…turn…}}` placeholders against this
+     * snapshot instead of the live registry, so a slow `PreToolUse`
+     * hook on one direct call cannot cause a sibling's just-registered
+     * output to leak into this call's args mid-batch (Codex P1 #18 —
+     * `Promise.all`-induced ordering would otherwise be observable).
+     */
+    preBatchSnapshot?: ToolOutputResolveView;
+    /**
+     * Pre-incremented per-tool usage counter. Set by
+     * `runDirectToolWithLifecycleHooks` so PreToolUse hooks observe
+     * the same `turn` the tool will actually execute under (Codex P2
+     * #27 — without this, parallel direct calls of the same tool in
+     * one Promise.all batch all read `turn=N` for the hook but
+     * actually executed as `turn=N`, `N+1`, `N+2`). When supplied,
+     * `runTool` skips its own counter increment.
+     */
+    usageCount?: number;
+    /**
+     * Per-batch sink for `additionalContext` strings returned by
+     * direct-path PreToolUse / PostToolUse / PostToolUseFailure hooks.
+     * The caller in `run()` materializes the accumulated strings as a
+     * `HumanMessage` appended to outputs so the next model turn sees
+     * them — same shape as the event-driven path's `injected[]`.
+     * Codex P2 #39: pre-fix the direct path called `executeHooks` and
+     * discarded `additionalContexts`, silently breaking the hook API
+     * contract for hosts relying on it for policy / recovery guidance.
+     */
+    additionalContextsSink?: string[];
 };
 export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private toolMap;
@@ -31,6 +61,17 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private toolUsageCount;
     /** Maps toolCallId → turn captured in runTool, used by handleRunToolCompletions */
     private toolCallTurns;
+    /**
+     * `call.id → turn` map dedicated to the direct-path lifecycle so the
+     * turn assigned on first entry is REUSED on LangGraph resume.
+     * Distinct from `toolCallTurns` (which is cleared at the start of
+     * every `run()` to keep per-batch event-dispatch metadata fresh) —
+     * the direct path needs stability across re-entries triggered by
+     * `interrupt()` resumes (Codex P2 #30). Cleared with the rest of
+     * the per-Run state in `clearHeavyState`-equivalent flushes when
+     * the Run ends.
+     */
+    private directPathTurns;
     /** Tool registry for filtering (lazy computation of programmatic maps) */
     private toolRegistry?;
     /** Cached programmatic tools (computed once on first PTC call) */
@@ -43,6 +84,13 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
     private agentId?;
     /** Tool names that bypass event dispatch and execute directly (e.g., graph-managed handoff tools) */
     private directToolNames?;
+    /**
+     * File checkpointer extracted from the local coding tool bundle when
+     * `toolExecution.local.fileCheckpointing === true`. Exposed via
+     * {@link getFileCheckpointer}. Undefined when checkpointing is off
+     * or the local coding suite isn't bound to this node.
+     */
+    private fileCheckpointer?;
     /** Maximum characters allowed in a single tool result before truncation. */
     private maxToolResultChars;
     /** Hook registry for PreToolUse/PostToolUse lifecycle hooks */
@@ -65,6 +113,8 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * ToolNode building its own.
      */
     private toolOutputRegistry?;
+    /** Run-scoped selection for swapping remote code tools to local executors. */
+    private toolExecution?;
     /**
      * Monotonic counter used to mint a unique scope id for anonymous
      * batches (ones invoked without a `run_id` in
@@ -73,7 +123,7 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * other's in-flight state.
      */
     private anonBatchCounter;
-    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, }: t.ToolNodeConstructorParams);
+    constructor({ tools, toolMap, name, tags, errorHandler, toolCallStepIds, handleToolErrors, loadRuntimeTools, toolRegistry, sessions, eventDrivenMode, agentId, directToolNames, maxContextTokens, maxToolResultChars, hookRegistry, humanInTheLoop, toolOutputReferences, toolOutputRegistry, toolExecution, fileCheckpointer, }: t.ToolNodeConstructorParams);
     /**
      * Returns the run-scoped tool output registry, or `undefined` when
      * the feature is disabled.
@@ -83,6 +133,35 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * not mutate the registry directly.
      */
     _unsafeGetToolOutputRegistry(): ToolOutputReferenceRegistry | undefined;
+    /**
+     * Replaces known remote Code API tools with local-process tools when
+     * `RunConfig.toolExecution.engine === 'local'`. In event-driven mode those
+     * names are also marked direct so the SDK executes them locally instead of
+     * dispatching the batch to a host-side remote sandbox handler. When the
+     * local coding suite is enabled, this also injects file/search/edit tools.
+     */
+    private applyToolExecutionOverrides;
+    /**
+     * Returns the per-Run file checkpointer when
+     * `toolExecution.local.fileCheckpointing === true`. Hosts call
+     * `rewind()` on the returned object to restore captured pre-write
+     * file contents — the standard "undo a tool batch" pattern. Returns
+     * undefined when checkpointing is disabled or the local coding suite
+     * isn't bound. Manual review (finding E): without this getter, the
+     * config flag was a silent no-op outside of direct
+     * `createLocalCodingToolBundle()` use.
+     */
+    getFileCheckpointer(): t.LocalFileCheckpointer | undefined;
+    /**
+     * Flush the per-Run direct-path turn cache. Called by the Graph at
+     * end-of-Run via `clearHeavyState`. The map intentionally survives
+     * `run()` re-entry so an interrupt + resume reuses the original
+     * slot (Codex P2 #30), but it would otherwise grow linearly with
+     * tool calls and could collide across Runs if a provider reused
+     * call IDs (Codex P2 #33). Hosts can also call this directly if
+     * they reuse a ToolNode across batches outside of a Graph.
+     */
+    clearDirectPathTurns(): void;
     /**
      * Returns cached programmatic tools, computing once on first access.
      * Single iteration builds both toolMap and toolDefs simultaneously.
@@ -102,6 +181,70 @@ export declare class ToolNode<T = any> extends RunnableCallable<T, T> {
      * substitutions. Omit when no registration should occur.
      */
     protected runTool(call: ToolCall, config: RunnableConfig, batchContext?: RunToolBatchContext): Promise<BaseMessage | Command>;
+    /**
+     * Runs a single in-process tool call with the same lifecycle hooks
+     * the event-dispatch path fires (`PreToolUse`, `PermissionDenied`,
+     * `PostToolUse`, `PostToolUseFailure`). Used for any tool whose
+     * implementation lives in the SDK process — i.e. every entry in
+     * `directToolNames` — so host-supplied policy hooks gate
+     * direct-invoked tools the same way they gate dispatched ones.
+     *
+     * Fast path: when the registry has none of the relevant events
+     * registered for this run, falls through to `runTool` with zero
+     * extra work. The hook list is also checked via
+     * `hasHookFor(event, runId)`, which performs the registry's own
+     * O(1) shortcut.
+     *
+     * Hook semantics intentionally mirror `dispatchToolEvents` for the
+     * single-call case:
+     *   - `PreToolUse` returning `decision: 'deny'` synthesizes an error
+     *     `ToolMessage` and fires `PermissionDenied` (observational).
+     *   - `PreToolUse` returning `decision: 'ask'`:
+     *     • When `humanInTheLoop.enabled === true`: raises a real
+     *       `tool_approval` interrupt for this single tool call (the
+     *       same payload shape the event path produces). On resume:
+     *       `approve` runs the tool, `reject` blocks via
+     *       `blockDirectCall`, `respond` returns the host-supplied
+     *       `responseText` as a synthetic success ToolMessage,
+     *       `edit` re-runs with edited args. LangGraph re-enters
+     *       ToolNode.run from the start on resume; the hook fires
+     *       again and the resume value distinguishes "first ask" from
+     *       "second pass with decision".
+     *     • When HITL is off: collapses to a fail-closed deny (matches
+     *       the rest of the SDK's HITL-disabled default). One-time
+     *       warning logged so hosts notice the gap.
+     *   - `PreToolUse.updatedInput` is applied to the call before
+     *     `runTool` runs; placeholder resolution inside `runTool` is
+     *     idempotent on already-resolved args.
+     *   - `PostToolUse.updatedOutput` replaces the returned
+     *     `ToolMessage` content (preserving id/name/status).
+     *   - `PostToolUseFailure` fires when `runTool` returns a
+     *     `ToolMessage` whose `status === 'error'`. Observational only;
+     *     the error message stays the source of truth.
+     *
+     * `PostToolBatch` aggregation across direct + dispatched outcomes is
+     * a separate concern: `dispatchToolEvents` accumulates batch entries
+     * locally and fires `PostToolBatch` at the end of its scope. Wiring
+     * direct-call entries into that aggregation crosses the two paths'
+     * scopes and is left to a follow-up.
+     */
+    private runDirectToolWithLifecycleHooks;
+    /**
+     * `ask` decisions on direct-path tools collapse to fail-closed deny
+     * only when `humanInTheLoop.enabled !== true` (i.e. there's no host
+     * UI configured to actually prompt the user). Logged once per process
+     * so the gap is visible. When HITL IS enabled, `ask` raises a real
+     * LangGraph `interrupt()` instead — see `runDirectToolWithLifecycleHooks`.
+     */
+    private askDirectWarningEmitted;
+    private resolveAskDecisionForDirectTool;
+    /**
+     * Synthesize a Blocked ToolMessage AND fire `PermissionDenied`
+     * (observational) for a direct-path tool call. Centralised so the
+     * deny path looks identical whether the block came from `'deny'` or
+     * from a fail-closed/`'reject'`/policy-violation path.
+     */
+    private blockDirectCall;
     /**
      * Registers the full, raw output under `refKey` (when provided) and
      * builds the per-message ref metadata stamped onto the resulting

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

@@ -0,0 +1,31 @@
+/**
+ * `compile_check` — a thin LLM-callable wrapper around the project's
+ * standard typecheck/lint command. Lets the agent answer "did my
+ * change break anything?" without us shipping a real LSP client.
+ *
+ * Auto-detection priority (first hit wins):
+ *
+ *   1. `local.compileCheck.command`            — explicit override
+ *   2. `tsconfig.json`                          → `npx --no-install tsc --noEmit`
+ *   3. `package.json` with a typescript dep    → same as 2
+ *   4. `pyproject.toml` or `setup.py` / `setup.cfg`
+ *      with a dev dep on mypy                  → `python3 -m mypy .`
+ *      else                                    → `python3 -m py_compile <every .py>`
+ *      (bounded by find-walk so node_modules
+ *      and `.venv` don't blow up)
+ *   5. `Cargo.toml`                            → `cargo check --message-format=short`
+ *   6. `go.mod`                                → `go vet ./...`
+ *   7. otherwise                               → tells the agent there's
+ *                                                 no detected toolchain.
+ *
+ * Output is the spawn process's stdout/stderr passed through
+ * `truncateLocalOutput` so a 10MB tsc dump can't blow context. The
+ * exit code is reported.
+ */
+import type { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+import { Constants } from '@/common';
+/** Back-compat alias; canonical name lives on `Constants.COMPILE_CHECK`. */
+export declare const CompileCheckToolName = Constants.COMPILE_CHECK;
+export declare function createCompileCheckTool(config?: t.LocalExecutionConfig): DynamicStructuredTool;
+export declare function createCompileCheckToolDefinition(): t.LCTool;

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

@@ -0,0 +1,39 @@
+import type { WorkspaceFS } from './workspaceFS';
+import type * as t from '@/types';
+/**
+ * Per-Run snapshot store for write_file / edit_file. Captures the
+ * pre-write byte content of every path the local engine is about to
+ * mutate so a later `rewind()` can restore the working tree to its
+ * original state. Notes:
+ *
+ *  - Idempotent per path: subsequent captures preserve the first
+ *    snapshot (so rewind always restores the *original* content).
+ *  - Captures missing files as `{ kind: 'absent' }`; rewind deletes
+ *    those paths so created files are removed.
+ *  - In-memory: snapshots live for the lifetime of this instance and
+ *    are not persisted across processes. Tie the lifetime to a Run.
+ *  - Bounded by `maxBytesPerFile` (default 32 MiB) to bound memory.
+ *    A file larger than the cap is recorded but not snapshotted; the
+ *    rewind of that path is best-effort and the caller is told via
+ *    the result count not to trust it.
+ */
+export declare class LocalFileCheckpointerImpl implements t.LocalFileCheckpointer {
+    private readonly maxBytesPerFile;
+    private readonly fs;
+    private snapshots;
+    private oversizePaths;
+    constructor(maxBytesPerFile?: number, fs?: WorkspaceFS);
+    captureBeforeWrite(absolutePath: string): Promise<void>;
+    rewind(): Promise<number>;
+    capturedPaths(): string[];
+}
+/**
+ * Convenience factory so callers don't have to reach for the impl
+ * class directly. Accepts an optional `WorkspaceFS` so a host using a
+ * non-default engine (remote sandbox, in-memory test FS, etc.) can
+ * route the checkpointer through the same I/O.
+ */
+export declare function createLocalFileCheckpointer(options?: {
+    maxBytesPerFile?: number;
+    fs?: WorkspaceFS;
+}): t.LocalFileCheckpointer;

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

@@ -0,0 +1,57 @@
+import type { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+import { Constants } from '@/common';
+/**
+ * Tool name aliases retained for back-compat with consumers that imported
+ * the per-file `Local*ToolName` constants. The canonical names live on
+ * `Constants.*` (see `src/common/enum.ts`); these aliases just point at
+ * them so a typo upstream gets caught at the type level.
+ */
+export declare const LocalWriteFileToolName = Constants.WRITE_FILE;
+export declare const LocalEditFileToolName = Constants.EDIT_FILE;
+export declare const LocalGrepSearchToolName = Constants.GREP_SEARCH;
+export declare const LocalGlobSearchToolName = Constants.GLOB_SEARCH;
+export declare const LocalListDirectoryToolName = Constants.LIST_DIRECTORY;
+export declare const LocalReadFileToolSchema: t.JsonSchemaType;
+export declare const LocalWriteFileToolSchema: t.JsonSchemaType;
+export declare const LocalEditFileToolSchema: t.JsonSchemaType;
+export declare const LocalGrepSearchToolSchema: t.JsonSchemaType;
+export declare const LocalGlobSearchToolSchema: t.JsonSchemaType;
+export declare const LocalListDirectoryToolSchema: t.JsonSchemaType;
+export declare function createLocalReadFileTool(config?: t.LocalExecutionConfig): DynamicStructuredTool;
+export declare function createLocalWriteFileTool(config?: t.LocalExecutionConfig, checkpointer?: t.LocalFileCheckpointer): DynamicStructuredTool;
+export declare function createLocalEditFileTool(config?: t.LocalExecutionConfig, checkpointer?: t.LocalFileCheckpointer): DynamicStructuredTool;
+/**
+ * Test-only reset hook. Clears the ripgrep-availability cache so
+ * tests can swap in mocked spawn backends and reprobe deterministically.
+ *
+ * @internal Not part of the public SDK surface; the leading underscore
+ *   and `@internal` tag together signal that consumers should not call
+ *   this. Tests import it via the module path directly.
+ */
+export declare function _resetRipgrepCacheForTests(): void;
+export declare function createLocalGrepSearchTool(config?: t.LocalExecutionConfig): DynamicStructuredTool;
+export declare function createLocalGlobSearchTool(config?: t.LocalExecutionConfig): DynamicStructuredTool;
+export declare function createLocalListDirectoryTool(config?: t.LocalExecutionConfig): DynamicStructuredTool;
+export type LocalCodingToolBundle = {
+    tools: DynamicStructuredTool[];
+    /**
+     * Present when `config.fileCheckpointing === true` or a `checkpointer`
+     * was passed in. Callers can call `rewind()` to restore captured
+     * pre-write contents.
+     */
+    checkpointer?: t.LocalFileCheckpointer;
+};
+export declare function createLocalCodingTools(config?: t.LocalExecutionConfig, options?: {
+    checkpointer?: t.LocalFileCheckpointer;
+}): DynamicStructuredTool[];
+/**
+ * Variant of `createLocalCodingTools` that returns the bundle alongside
+ * the file checkpointer so callers can later call
+ * `bundle.checkpointer?.rewind()`.
+ */
+export declare function createLocalCodingToolBundle(config?: t.LocalExecutionConfig, options?: {
+    checkpointer?: t.LocalFileCheckpointer;
+}): LocalCodingToolBundle;
+export declare function createLocalCodingToolDefinitions(): t.LCTool[];
+export declare function createLocalCodingToolRegistry(): t.LCToolRegistry;

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

@@ -0,0 +1,149 @@
+import type { WorkspaceFS } from './workspaceFS';
+import type * as t from '@/types';
+type SpawnResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+    /**
+     * True when the process was force-killed because total streamed bytes
+     * exceeded `maxSpawnedBytes`. Distinct from `timedOut`. Without this
+     * flag, callers (`bash_tool`, `execute_code`, etc.) would see a
+     * SIGKILL'd process with `exitCode: null` and treat it as success
+     * (Codex P1 — runaway commands like `yes` or noisy builds silently
+     * looked successful even though their output was truncated).
+     */
+    overflowKilled?: boolean;
+    /**
+     * Signal name (e.g. `'SIGKILL'`, `'SIGSEGV'`) when the process was
+     * terminated by a signal. Distinct from the overflow-kill path:
+     * this captures `kill -9 $$` from inside the script, native crashes,
+     * OS OOM killer, etc. Without this, signal-killed processes
+     * reported `exitCode: null` and looked like clean runs (Codex P2 —
+     * generalization of the overflow-kill fix). When present, the
+     * exitCode field is also synthesized to `128 + signum` per the
+     * POSIX convention so non-null-exit-code consumers see a failure.
+     */
+    signal?: string;
+    /** Path to the full untruncated stdout/stderr when output exceeded `maxOutputChars`. */
+    fullOutputPath?: string;
+};
+export type BashValidationResult = {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+};
+export declare function resolveLocalExecutionConfig(config?: t.ToolExecutionConfig | t.LocalExecutionConfig): t.LocalExecutionConfig;
+export declare function getLocalCwd(config?: t.LocalExecutionConfig): string;
+/**
+ * Resolves the effective workspace boundary: a list of absolute roots
+ * that file operations are allowed to touch. The first entry is always
+ * the canonical root (`getLocalCwd`); subsequent entries come from
+ * `workspace.additionalRoots` when provided.
+ *
+ * Returns plain absolute paths — callers symlink-resolve when they
+ * need realpath equality (see `resolveWorkspacePathSafe`).
+ */
+export declare function getWorkspaceRoots(config?: t.LocalExecutionConfig): string[];
+/**
+ * Pluggable spawn resolver. Honours `local.exec.spawn` first, falls
+ * back to the legacy top-level `local.spawn`, then to Node's
+ * `child_process.spawn`. Centralised so engine swapping is one knob.
+ */
+export declare function getSpawn(config?: t.LocalExecutionConfig): t.LocalSpawn;
+/**
+ * Pluggable filesystem resolver. Honours `local.exec.fs`, falls back
+ * to the Node-host implementation. A future remote engine supplies
+ * its own implementation here and inherits every file-touching tool.
+ */
+export declare function getWorkspaceFS(config?: t.LocalExecutionConfig): WorkspaceFS;
+/**
+ * Resolves the workspace boundary for *write* operations. Honours
+ * `workspace.allowWriteOutside` (and the deprecated
+ * `allowOutsideWorkspace`) by returning `null`, which the path-safety
+ * helpers interpret as "skip the write clamp".
+ */
+export declare function getWriteRoots(config?: t.LocalExecutionConfig): string[] | null;
+/**
+ * Resolves the workspace boundary for *read* operations. Honours
+ * `workspace.allowReadOutside` (and the deprecated
+ * `allowOutsideWorkspace`) by returning `null`.
+ */
+export declare function getReadRoots(config?: t.LocalExecutionConfig): string[] | null;
+export declare function getLocalSessionId(config?: t.LocalExecutionConfig): string;
+/**
+ * Test-only reset hook for the sandbox-off warning latch.
+ *
+ * @internal Not part of the public SDK surface.
+ */
+export declare function _resetLocalEngineWarningsForTests(): void;
+export declare function truncateLocalOutput(value: string, maxChars?: number): string;
+export declare function validateBashCommand(command: string, config?: t.LocalExecutionConfig): Promise<BashValidationResult>;
+/**
+ * Structural shape of the sandbox-runtime config we hand to
+ * `SandboxManager.initialize()`. Intentionally NOT typed as the peer
+ * `SandboxRuntimeConfig` from `@anthropic-ai/sandbox-runtime`: that
+ * package is an OPTIONAL peer dep, and exporting a function whose
+ * return type references it would make our generated `.d.ts` import
+ * a module the consumer may not have installed (Codex P1 #22 — type-
+ * checking would fail with `Cannot find module
+ * '@anthropic-ai/sandbox-runtime'` for any host that doesn't enable
+ * local sandboxing). The shape here is a structural subset; assignable
+ * to the real `SandboxRuntimeConfig` at the one runtime call site.
+ *
+ * @internal
+ */
+export interface BuiltSandboxRuntimeConfig {
+    network: {
+        allowedDomains: string[];
+        deniedDomains: string[];
+        allowUnixSockets?: string[];
+        allowAllUnixSockets?: boolean;
+        allowLocalBinding?: boolean;
+        allowMachLookup?: string[];
+    };
+    filesystem: {
+        denyRead: string[];
+        allowRead?: string[];
+        allowWrite: string[];
+        denyWrite: string[];
+        allowGitConfig?: boolean;
+    };
+}
+export declare function buildSandboxRuntimeConfig(config: t.LocalExecutionConfig, cwd: string, getDefaultWritePaths: () => string[]): BuiltSandboxRuntimeConfig;
+/**
+ * Internal options for {@link spawnLocalProcess} that we don't want
+ * exposed on the public `LocalExecutionConfig` type.
+ *
+ * @internal
+ */
+export interface SpawnLocalProcessOptions {
+    /**
+     * When true, suppress the "sandbox is off" warning AND its latch
+     * for this spawn. Use for SDK-internal probes (`bash -n` syntax
+     * preflight, `rg --version`, etc.) that intentionally run with
+     * the sandbox forced off — the warning is noise for those, and
+     * letting the latch flip would hide the warning when a *real*
+     * unsandboxed execution happens later in the same process.
+     */
+    internal?: boolean;
+}
+export declare function spawnLocalProcess(command: string, args: string[], config?: t.LocalExecutionConfig, options?: SpawnLocalProcessOptions): Promise<SpawnResult>;
+export declare function executeLocalBash(command: string, config?: t.LocalExecutionConfig): Promise<SpawnResult>;
+export declare function executeLocalBashWithArgs(command: string, args: readonly string[], config?: t.LocalExecutionConfig): Promise<SpawnResult>;
+export declare function executeLocalCode(input: {
+    lang: string;
+    code: string;
+    args?: string[];
+}, config?: t.LocalExecutionConfig): Promise<SpawnResult>;
+export declare function shellQuote(value: string): string;
+export declare function resolveWorkspacePath(filePath: string, config?: t.LocalExecutionConfig, intent?: 'read' | 'write'): string;
+/**
+ * Resolves a workspace path AND follows any symlinks before checking
+ * containment, so a symlink inside the workspace pointing outside is
+ * rejected even though the lexical path looks safe. Handles paths that
+ * don't yet exist (e.g. write_file targets) by realpath-resolving the
+ * nearest existing ancestor and re-attaching the unresolved suffix.
+ */
+export declare function resolveWorkspacePathSafe(filePath: string, config?: t.LocalExecutionConfig, intent?: 'read' | 'write'): Promise<string>;
+export {};

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

@@ -0,0 +1,9 @@
+import type { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+export declare const LocalCodeExecutionToolDescription: string;
+export declare const LocalBashExecutionToolDescription: string;
+export declare function createLocalCodeExecutionTool(config?: t.LocalExecutionConfig): DynamicStructuredTool;
+export declare function createLocalBashExecutionTool(options?: {
+    config?: t.LocalExecutionConfig;
+    enableToolOutputReferences?: boolean;
+}): DynamicStructuredTool;

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

@@ -0,0 +1,21 @@
+import type { DynamicStructuredTool } from '@langchain/core/tools';
+import type * as t from '@/types';
+/**
+ * Run the host's `PreToolUse` hook chain for a single bridge call.
+ * Returns the (possibly rewritten) input and a `denyReason` if any
+ * matcher returned `decision: 'deny'` or `'ask'`. `'ask'` collapses
+ * to deny because the bridge can't raise a LangGraph interrupt from
+ * inside an HTTP handler — fail-closed matches the rest of the SDK
+ * when HITL is unavailable.
+ *
+ * @internal Exported for tests so the deny / allow / updatedInput /
+ *   ask branches can be exercised without standing up the full HTTP
+ *   bridge.
+ */
+export declare function applyPreToolUseHooksForBridge(hookContext: t.ProgrammaticHookContext, toolName: string, toolUseId: string, toolInput: Record<string, unknown>): Promise<{
+    input: Record<string, unknown>;
+    denyReason?: string;
+}>;
+export declare function _createBashProgramForTests(code: string, toolDefs: t.LCTool[], bridgeUrl: string, bridgeToken: string): string;
+export declare function createLocalProgrammaticToolCallingTool(localConfig?: t.LocalExecutionConfig): DynamicStructuredTool;
+export declare function createLocalBashProgrammaticToolCallingTool(localConfig?: t.LocalExecutionConfig): DynamicStructuredTool;

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

@@ -0,0 +1,84 @@
+/**
+ * Detects whether a file on disk is an LLM-renderable attachment
+ * (image / PDF) and produces the LangChain `MessageContentComplex[]`
+ * payload a `ToolMessage` needs to actually surface those bytes to
+ * the vision-capable model.
+ *
+ * Same approach as LibreChat's `api/server/utils/files.js`: sniff the
+ * magic bytes (NOT the extension) so a mislabelled `.png` that's
+ * really a binary blob doesn't get embedded as an image. Inlined for
+ * the five formats we actually care about (PNG / JPEG / GIF / WebP /
+ * PDF) instead of pulling the ESM-only `file-type` package — keeps
+ * the test setup CJS-clean.
+ *
+ * Provider compatibility:
+ *   - Anthropic: tool_result content arrays accept `image` / `image_url`
+ *     blocks; LangChain's anthropic adapter at
+ *     `node_modules/@langchain/anthropic/dist/utils/message_inputs.js`
+ *     converts them to native `image` source blocks.
+ *   - OpenAI Chat Completions: image_url blocks in tool messages are
+ *     accepted on vision-capable models.
+ *   - OpenAI Responses API: tool messages are flattened to plain text;
+ *     image_url blocks degrade to a JSON description (still useful as
+ *     a textual hint to the model).
+ *   - Google: image blocks in tool responses are accepted on Gemini
+ *     vision models.
+ *
+ * Configuration:
+ *   - `local.attachReadAttachments` (default `'images-only'`) controls
+ *     which file kinds are returned as inline attachments. Other kinds
+ *     fall through to the existing binary-stub path.
+ *   - `local.maxAttachmentBytes` (default 5 MB) caps the pre-encoding
+ *     size; oversize attachments degrade to a stub describing the
+ *     refusal so the model isn't surprised.
+ */
+import type { WorkspaceFS } from './workspaceFS';
+export type AttachmentMode = 'images-only' | 'images-and-pdf' | 'off';
+export type Attachment = {
+    kind: 'image';
+    mime: string;
+    bytes: number;
+    dataUrl: string;
+} | {
+    kind: 'pdf';
+    mime: 'application/pdf';
+    bytes: number;
+    dataUrl: string;
+} | {
+    kind: 'binary';
+    mime: string;
+    bytes: number;
+} | {
+    kind: 'oversize';
+    mime: string;
+    bytes: number;
+    maxBytes: number;
+} | {
+    kind: 'text-or-unknown';
+    bytes: number;
+};
+export declare function classifyAttachment(args: {
+    path: string;
+    bytes: number;
+    mode: AttachmentMode;
+    maxBytes: number;
+    /**
+     * WorkspaceFS to route I/O through — defaults to host fs/promises
+     * for backward compat. Manual review (finding F): without this
+     * routing, custom/remote FS implementations could either fail to
+     * embed valid attachments or accidentally read a host path with
+     * the same absolute name (since `read_file` itself does go through
+     * the configured WorkspaceFS).
+     */
+    fs?: WorkspaceFS;
+}): Promise<Attachment>;
+/** Build the LangChain content array for an image attachment. */
+export declare function imageAttachmentContent(path: string, attachment: Extract<Attachment, {
+    kind: 'image';
+}>): Array<{
+    type: 'text' | 'image_url';
+    text?: string;
+    image_url?: {
+        url: string;
+    };
+}>;

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

@@ -0,0 +1,11 @@
+import type * as t from '@/types';
+export type BashAstFinding = {
+    code: string;
+    message: string;
+    severity: 'warn' | 'deny';
+};
+export declare function runBashAstChecks(command: string, mode?: t.LocalBashAstMode): BashAstFinding[];
+export declare function bashAstFindingsToErrors(findings: BashAstFinding[]): {
+    errors: string[];
+    warnings: string[];
+};

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

@@ -0,0 +1,28 @@
+/**
+ * Single-occurrence string-replacement strategies for `edit_file`.
+ *
+ * The LLM frequently emits an `oldString` whose whitespace, indentation,
+ * or escape sequences are slightly off from the on-disk content. Rather
+ * than failing the call (which forces a re-read + retry round-trip),
+ * we walk a chain of progressively looser matchers, stopping at the
+ * first one that locates exactly one match. The matched on-disk slice
+ * is then literally replaced with `newString` — we never modify
+ * `newString`, only the search.
+ *
+ * Strategies are ordered from strict to lenient so we don't accidentally
+ * over-match a more specific pattern with a looser one. Inspired by
+ * opencode's nine-strategy chain (sst/opencode), trimmed to the four
+ * highest-yield strategies for a first cut. Add more (block-anchor +
+ * Levenshtein, escape-normalized, etc.) as needed.
+ */
+export interface EditMatch {
+    /** Strategy name that produced the match, for telemetry/diagnostics. */
+    strategy: string;
+    /** Starting offset in the source. */
+    start: number;
+    /** Ending offset (exclusive). */
+    end: number;
+}
+export type EditStrategy = (source: string, oldString: string) => EditMatch | null;
+export declare function locateEdit(source: string, oldString: string): EditMatch | null;
+export declare function applyEdit(source: string, match: EditMatch, newString: string): string;

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

@@ -0,0 +1,12 @@
+export * from './CompileCheckTool';
+export * from './FileCheckpointer';
+export * from './LocalCodingTools';
+export * from './LocalExecutionEngine';
+export * from './LocalExecutionTools';
+export * from './LocalProgrammaticToolCalling';
+export * from './resolveLocalExecutionTools';
+export * from './attachments';
+export * from './bashAst';
+export * from './editStrategies';
+export * from './syntaxCheck';
+export * from './textEncoding';