@librechat/agents 3.6.13 → 3.6.15

package/src/tools/local/LocalCodingTools.ts

@@ -4,16 +4,19 @@ import { tool } from '@langchain/core/tools';
 import type { DynamicStructuredTool } from '@langchain/core/tools';
 import type * as t from '@/types';
 import {
-  createLocalBashProgrammaticToolCallingTool,
-  createLocalProgrammaticToolCallingTool,
-} from './LocalProgrammaticToolCalling';
-import {
+  commandAvailabilityEnvCacheKey,
   getSpawn,
   getWorkspaceFS,
+  probeLocalCommandAvailability,
   resolveWorkspacePathSafe,
+  setCommandAvailabilityCacheEntry,
   spawnLocalProcess,
   truncateLocalOutput,
 } from './LocalExecutionEngine';
+import {
+  createLocalBashProgrammaticToolCallingTool,
+  createLocalProgrammaticToolCallingTool,
+} from './LocalProgrammaticToolCalling';
 import {
   createLocalBashExecutionTool,
   createLocalCodeExecutionTool,
@@ -736,30 +739,14 @@ export function createLocalEditFileTool(
  * spawn-per-search.
  */
 // Per-backend × per-env cache. Codex P1 #34 — keying by spawn
-// backend alone misses the case where two Runs share a backend but
-// vary `local.env` (especially PATH). Stale cache then claims `rg`
-// is available, the rg path runs, and the spawn fails with ENOENT
-// instead of falling back to the Node walker. The inner Map is
-// keyed by a stable JSON hash of the effective env so each unique
-// env gets its own probe.
+// backend alone misses the case where two Runs share a backend but vary
+// `local.env`. The inner map uses non-plaintext environment hashes and is
+// bounded so stable worlds do not retain unbounded variants or raw secrets.
 let ripgrepAvailabilityByBackend = new WeakMap<
   t.LocalSpawn,
-  Map<string, Promise<boolean>>
+  Map<string, ReturnType<typeof probeLocalCommandAvailability>>
 >();
 
-function envCacheKey(env: NodeJS.ProcessEnv | undefined): string {
-  // PATH is the only env entry that affects command lookup, but
-  // hashing the whole env keeps the key correct for hosts that
-  // vary anything else relevant. Stable JSON via sorted keys so
-  // {A:1,B:2} and {B:2,A:1} produce the same hash.
-  if (env == null) return '';
-  const sorted: Record<string, string | undefined> = {};
-  for (const k of Object.keys(env).sort()) {
-    sorted[k] = env[k];
-  }
-  return JSON.stringify(sorted);
-}
-
 async function isRipgrepAvailable(
   config: t.LocalExecutionConfig
 ): Promise<boolean> {
@@ -769,20 +756,23 @@ async function isRipgrepAvailable(
     envMap = new Map();
     ripgrepAvailabilityByBackend.set(backend, envMap);
   }
-  const envKey = envCacheKey(config.env);
+  const envKey = commandAvailabilityEnvCacheKey(config.env);
   let probePromise = envMap.get(envKey);
   if (probePromise == null) {
-    probePromise = spawnLocalProcess(
-      'rg',
-      ['--version'],
-      { ...config, timeoutMs: 5000, sandbox: { enabled: false } },
-      { internal: true }
-    )
-      .then((probe) => probe.exitCode === 0)
-      .catch(() => false);
-    envMap.set(envKey, probePromise);
+    probePromise = probeLocalCommandAvailability('rg', ['--version'], config);
+    setCommandAvailabilityCacheEntry(envMap, envKey, probePromise);
+  }
+  const result = await probePromise;
+  if (!result.cacheable && envMap.get(envKey) === probePromise) {
+    envMap.delete(envKey);
+  }
+  if (result.cacheUntil != null && result.cacheUntil <= Date.now()) {
+    if (envMap.get(envKey) === probePromise) {
+      envMap.delete(envKey);
+    }
+    return isRipgrepAvailable(config);
   }
-  return probePromise;
+  return result.available;
 }
 
 /**

package/src/tools/local/LocalExecutionEngine.ts

@@ -21,6 +21,36 @@ const DEFAULT_MAX_OUTPUT_CHARS = 200000;
 const DEFAULT_MAX_SPAWNED_BYTES = 50 * 1024 * 1024;
 const DEFAULT_LOCAL_SESSION_ID = 'local';
 const DEFAULT_SHELL = process.platform === 'win32' ? 'bash.exe' : 'bash';
+const MAX_COMMAND_AVAILABILITY_ENVIRONMENTS = 16;
+const NEGATIVE_COMMAND_AVAILABILITY_TTL_MS = 5000;
+
+/** Produces a stable, non-plaintext key for environment-sensitive probes. */
+export function commandAvailabilityEnvCacheKey(
+  env: NodeJS.ProcessEnv | undefined
+): string {
+  if (env == null) {
+    return '';
+  }
+  const sorted = Object.keys(env)
+    .sort()
+    .map((key): [string, string | null] => [key, env[key] ?? null]);
+  return createHash('sha256').update(JSON.stringify(sorted)).digest('hex');
+}
+
+/** Adds a probe entry while bounding retained environment variants. */
+export function setCommandAvailabilityCacheEntry<T>(
+  cache: Map<string, T>,
+  key: string,
+  value: T
+): void {
+  if (!cache.has(key) && cache.size >= MAX_COMMAND_AVAILABILITY_ENVIRONMENTS) {
+    const oldestKey = cache.keys().next().value;
+    if (oldestKey !== undefined) {
+      cache.delete(oldestKey);
+    }
+  }
+  cache.set(key, value);
+}
 
 // `(?:--\s+)?` before each destructive-target alternation: GNU/BSD
 // utilities accept `--` as an end-of-options marker, so `rm -rf -- /`
@@ -259,13 +289,34 @@ export function getWorkspaceRoots(config?: t.LocalExecutionConfig): string[] {
   return out;
 }
 
+/** Node-host execution world used when no backend override is configured. */
+export const nodeExecutionWorld: t.ExecutionWorld = Object.freeze({
+  spawn: spawn as t.LocalSpawn,
+  fs: nodeWorkspaceFS,
+  sandboxed: false,
+});
+
+/** Resolves filesystem and subprocess capabilities as one execution world. */
+export function getExecutionWorld(
+  config?: t.LocalExecutionConfig
+): t.ExecutionWorld {
+  if (config?.exec == null && config?.spawn == null) {
+    return nodeExecutionWorld;
+  }
+  return {
+    spawn: config.exec?.spawn ?? config.spawn ?? nodeExecutionWorld.spawn,
+    fs: config.exec?.fs ?? nodeExecutionWorld.fs,
+    sandboxed: config.exec?.sandboxed ?? false,
+  };
+}
+
 /**
  * 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 function getSpawn(config?: t.LocalExecutionConfig): t.LocalSpawn {
-  return (config?.exec?.spawn ?? config?.spawn ?? spawn) as t.LocalSpawn;
+  return getExecutionWorld(config).spawn;
 }
 
 /**
@@ -274,7 +325,7 @@ export function getSpawn(config?: t.LocalExecutionConfig): t.LocalSpawn {
  * its own implementation here and inherits every file-touching tool.
  */
 export function getWorkspaceFS(config?: t.LocalExecutionConfig): WorkspaceFS {
-  return config?.exec?.fs ?? nodeWorkspaceFS;
+  return getExecutionWorld(config).fs;
 }
 
 /**
@@ -345,7 +396,7 @@ function maybeWarnSandboxOff(config: t.LocalExecutionConfig): void {
   if (
     sandboxOffWarned ||
     shouldUseLocalSandbox(config) ||
-    config.exec?.sandboxed === true
+    getExecutionWorld(config).sandboxed
   ) {
     return;
   }
@@ -904,6 +955,72 @@ export async function spawnLocalProcess(
   });
 }
 
+/** Result of a command-availability probe and whether its verdict is stable. */
+export type CommandAvailabilityProbe = {
+  available: boolean;
+  cacheable: boolean;
+  cacheUntil?: number;
+};
+
+async function isDurableCommandLookupError(
+  error: object,
+  config: t.LocalExecutionConfig
+): Promise<boolean> {
+  if (!('code' in error) || error.code !== 'ENOENT') {
+    return false;
+  }
+  try {
+    const cwd = getLocalCwd(config);
+    return (await getWorkspaceFS(config).stat(cwd)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Probes one executable without turning transient backend failures into
+ * permanent capability facts. Exit 126/127 is a definite unusable/missing
+ * executable. A native ENOENT is stable only when the current working
+ * directory exists; timeouts, transport failures, and ambiguous lookup
+ * failures are retried.
+ */
+export async function probeLocalCommandAvailability(
+  command: string,
+  args: string[],
+  config: t.LocalExecutionConfig
+): Promise<CommandAvailabilityProbe> {
+  try {
+    const result = await spawnLocalProcess(
+      command,
+      args,
+      { ...config, timeoutMs: 5000, sandbox: { enabled: false } },
+      { internal: true }
+    );
+    const available = result.exitCode === 0;
+    const durableNegative =
+      result.exitCode === 126 || result.exitCode === 127;
+    return {
+      available,
+      cacheable: available || durableNegative,
+      ...(durableNegative
+        ? { cacheUntil: Date.now() + NEGATIVE_COMMAND_AVAILABILITY_TTL_MS }
+        : {}),
+    };
+  } catch (error) {
+    const cacheable =
+      typeof error === 'object' &&
+      error != null &&
+      (await isDurableCommandLookupError(error, config));
+    return {
+      available: false,
+      cacheable,
+      ...(cacheable
+        ? { cacheUntil: Date.now() + NEGATIVE_COMMAND_AVAILABILITY_TTL_MS }
+        : {}),
+    };
+  }
+}
+
 export async function executeLocalBash(
   command: string,
   config: t.LocalExecutionConfig = {}

package/src/tools/local/syntaxCheck.ts

@@ -18,12 +18,15 @@
 
 import { extname } from 'path';
 import type * as t from '@/types';
-import { isWorkspaceClientTimeoutError } from './workspaceFS';
 import {
+  commandAvailabilityEnvCacheKey,
   getSpawn,
   getWorkspaceFS,
+  probeLocalCommandAvailability,
+  setCommandAvailabilityCacheEntry,
   spawnLocalProcess,
 } from './LocalExecutionEngine';
+import { isWorkspaceClientTimeoutError } from './workspaceFS';
 
 export type SyntaxCheckOutcome =
   | { ok: true }
@@ -48,26 +51,17 @@ export type SyntaxChecker = (
  * reset hook re-creates the map.
  */
 type ProbeKind = 'hasNode' | 'hasPython' | 'hasBash';
-type ProbeCache = Partial<Record<ProbeKind, Promise<boolean>>>;
+type ProbeCache = Partial<
+  Record<ProbeKind, ReturnType<typeof probeLocalCommandAvailability>>
+>;
 
-// Per-backend × per-env cache. Codex P2 #40 — keying by spawn
-// backend alone misses env-driven availability changes (e.g. PATH
-// loses node between Runs that share the same backend). Same fix
-// shape as the ripgrep cache (Codex P1 #34).
+// Per-backend × hashed-env cache. The inner map is bounded so a long-lived
+// world cannot retain unbounded environment variants.
 let probeCacheByBackend = new WeakMap<
   t.LocalSpawn,
   Map<string, ProbeCache>
 >();
 
-function envCacheKey(env: NodeJS.ProcessEnv | undefined): string {
-  if (env == null) return '';
-  const sorted: Record<string, string | undefined> = {};
-  for (const k of Object.keys(env).sort()) {
-    sorted[k] = env[k];
-  }
-  return JSON.stringify(sorted);
-}
-
 function cacheFor(
   config: t.LocalExecutionConfig
 ): ProbeCache {
@@ -77,11 +71,11 @@ function cacheFor(
     envMap = new Map();
     probeCacheByBackend.set(backend, envMap);
   }
-  const envKey = envCacheKey(config.env);
+  const envKey = commandAvailabilityEnvCacheKey(config.env);
   let entry = envMap.get(envKey);
   if (entry == null) {
     entry = {};
-    envMap.set(envKey, entry);
+    setCommandAvailabilityCacheEntry(envMap, envKey, entry);
   }
   return entry;
 }
@@ -95,17 +89,20 @@ async function probe(
   const entry = cacheFor(config);
   let probePromise = entry[cached];
   if (probePromise == null) {
-    probePromise = spawnLocalProcess(
-      command,
-      args,
-      { ...config, timeoutMs: 5000, sandbox: { enabled: false } },
-      { internal: true }
-    )
-      .then((result) => result != null && result.exitCode === 0)
-      .catch(() => false);
+    probePromise = probeLocalCommandAvailability(command, args, config);
     entry[cached] = probePromise;
   }
-  return probePromise;
+  const result = await probePromise;
+  if (!result.cacheable && entry[cached] === probePromise) {
+    delete entry[cached];
+  }
+  if (result.cacheUntil != null && result.cacheUntil <= Date.now()) {
+    if (entry[cached] === probePromise) {
+      delete entry[cached];
+    }
+    return probe(command, args, cached, config);
+  }
+  return result.available;
 }
 
 /**

package/src/tools/local/workspaceFS.ts

@@ -92,10 +92,9 @@ export interface WorkspaceFS {
  * Returned by `getWorkspaceFS(config)` when the host hasn't supplied
  * an override on `local.exec.fs`.
  */
-export const nodeWorkspaceFS: WorkspaceFS = {
+export const nodeWorkspaceFS = Object.freeze<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)
@@ -113,4 +112,4 @@ export const nodeWorkspaceFS: WorkspaceFS = {
   realpath: (path) => fsRealpath(path),
   unlink: (path) => fsUnlink(path),
   open: (path, flags) => fsOpen(path, flags),
-};
+});

package/src/types/tools.ts

@@ -820,47 +820,35 @@ export type LocalWorkspaceConfig = {
 };
 
 /**
- * Engine-agnostic execution seam. Default uses Node's
- * `child_process.spawn` and `fs/promises`. A future engine (e.g.
- * stateful remote sandbox) supplies its own `spawn` and `fs` and
- * inherits every tool factory unchanged.
+ * One execution world shared by filesystem and subprocess operations.
+ * Backend identity is stable so capability probes remain warm when tool
+ * bundles are rebuilt for later agent bindings.
+ */
+export interface ExecutionWorld {
+  /** Launches a process inside this world's filesystem namespace. */
+  readonly spawn: LocalSpawn;
+  /** Reads and writes the same namespace observed by `spawn`. */
+  readonly fs: Readonly<import('@/tools/local/workspaceFS').WorkspaceFS>;
+  /** Whether the world already enforces a sandbox boundary. */
+  readonly sandboxed: boolean;
+}
+
+/**
+ * Backward-compatible partial execution-world override. Omitted fields use
+ * the Node host world; remote backends should provide the complete trio.
  *
- * **Important — pair `spawn` and `fs` together.** Most file-touching
- * surfaces in the local engine route through `getWorkspaceFS(config)`
- * so a host can transparently swap in a remote/in-memory FS. A small
- * set of helpers — currently the `execute_code` non-bash temp-file
- * write (Codex P2 [48]) — still uses host `fs/promises` directly to
- * stage source on disk before invoking the spawn. If you override
- * `spawn` to point at a remote runtime (SSH, container, etc.) you
- * MUST also override `fs` with the corresponding remote
- * implementation; otherwise temp source files written to the host
- * `/tmp` won't be visible to the remote interpreter and `py`/`js`/
- * `ts`/etc. executions will fail. (Bash-style executions go through
- * `executeLocalBash` which doesn't stage temp files, so they're
- * unaffected.)
+ * Non-bash `execute_code` still stages source through the host temporary
+ * directory. Remote runtimes should use their dedicated execution engine for
+ * that tool until temporary lifecycle operations join this seam.
  *
- * Threat-model note: the regex-based command validators
- * (`dangerousCommandPatterns`, `quotedDestructivePatterns`, etc.) and
- * the workspace policy hook are documented as best-effort tripwires.
- * The hard security boundary is `local.sandbox.enabled: true` (which
- * wraps execution in `@anthropic-ai/sandbox-runtime`); for adversarial-
- * model threat models, do NOT rely on the regex layer alone.
+ * Command validators and workspace policies are best-effort tripwires. For an
+ * adversarial-model threat model, use a backend sandbox boundary rather than
+ * relying on validation alone.
  */
 export type LocalExecConfig = {
-  /** Pluggable spawn (for SSH, container, remote workers, etc.). */
-  spawn?: LocalSpawn;
-  /**
-   * Pluggable filesystem (for remote-workspace engines). Pair with
-   * `spawn` — see the type-level note above on why both should be
-   * overridden together for non-host engines.
-   */
-  fs?: import('@/tools/local/workspaceFS').WorkspaceFS;
-  /**
-   * Set by custom execution backends that already provide their own
-   * sandbox boundary. Suppresses the local host-sandbox warning while
-   * preserving the warning for plain host `child_process` execution.
-   */
-  sandboxed?: boolean;
+  -readonly [Key in keyof ExecutionWorld]?: Key extends 'fs'
+    ? import('@/tools/local/workspaceFS').WorkspaceFS
+    : ExecutionWorld[Key];
 };
 
 export type LocalExecutionConfig = {

package/src/utils/toolContent.ts

@@ -1,4 +1,4 @@
-import { isProxy } from 'node:util/types';
+import { isArrayBuffer, isDate, isProxy } from 'node:util/types';
 import { ToolMessage, type BaseMessage } from '@langchain/core/messages';
 import {
   HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE,
@@ -151,11 +151,17 @@ function jsonStringLength(
 
 type NativeDateRead = { matched: true; time: number } | { matched: false };
 
+/**
+ * `isArrayBuffer` reads the internal slot natively (no user code, cross-realm safe) and
+ * costs nothing for the plain objects that make up almost all content; the getter's
+ * throw path was the expensive part, so it only runs once the brand is already known.
+ */
 function readNativeArrayBufferByteLength(value: unknown): number | undefined {
   if (
     value == null ||
     typeof value !== 'object' ||
-    NATIVE_ARRAY_BUFFER_BYTE_LENGTH_GETTER == null
+    NATIVE_ARRAY_BUFFER_BYTE_LENGTH_GETTER == null ||
+    !isArrayBuffer(value)
   ) {
     return undefined;
   }
@@ -167,7 +173,7 @@ function readNativeArrayBufferByteLength(value: unknown): number | undefined {
 }
 
 function readNativeDate(value: unknown): NativeDateRead {
-  if (value == null || typeof value !== 'object') {
+  if (value == null || typeof value !== 'object' || !isDate(value)) {
     return { matched: false };
   }
   try {