@librechat/agents 3.1.78 → 3.1.80-dev.0

package/src/tools/local/LocalExecutionEngine.ts

@@ -5,7 +5,6 @@ import { mkdir, realpath, rm, writeFile } from 'fs/promises';
 import { createWriteStream } from 'fs';
 import { spawn } from 'child_process';
 import type { ChildProcess } from 'child_process';
-import type { SandboxRuntimeConfig } from '@anthropic-ai/sandbox-runtime';
 import { runBashAstChecks, bashAstFindingsToErrors } from './bashAst';
 import { nodeWorkspaceFS } from './workspaceFS';
 import type { WorkspaceFS } from './workspaceFS';
@@ -188,8 +187,17 @@ type RuntimeCommand = {
   source?: string;
 };
 
-type SandboxRuntimeModule = typeof import('@anthropic-ai/sandbox-runtime');
-type SandboxManagerType = SandboxRuntimeModule['SandboxManager'];
+type SandboxManagerType = {
+  checkDependencies(): { errors: string[] };
+  initialize(config: BuiltSandboxRuntimeConfig): Promise<void>;
+  reset(): Promise<void>;
+  wrapWithSandbox(command: string): Promise<string>;
+};
+
+type SandboxRuntimeModule = {
+  getDefaultWritePaths(): string[];
+  SandboxManager: SandboxManagerType;
+};
 
 let sandboxConfigKey: string | undefined;
 let sandboxInitialized = false;
@@ -229,9 +237,7 @@ export function getLocalCwd(config?: t.LocalExecutionConfig): string {
  * Returns plain absolute paths — callers symlink-resolve when they
  * need realpath equality (see `resolveWorkspacePathSafe`).
  */
-export function getWorkspaceRoots(
-  config?: t.LocalExecutionConfig
-): string[] {
+export function getWorkspaceRoots(config?: t.LocalExecutionConfig): string[] {
   const root = getLocalCwd(config);
   const extras = config?.workspace?.additionalRoots ?? [];
   if (extras.length === 0) return [root];
@@ -258,9 +264,7 @@ export function getWorkspaceRoots(
  * 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 {
+export function getSpawn(config?: t.LocalExecutionConfig): t.LocalSpawn {
   return (config?.exec?.spawn ?? config?.spawn ?? spawn) as t.LocalSpawn;
 }
 
@@ -269,9 +273,7 @@ export function getSpawn(
  * to the Node-host implementation. A future remote engine supplies
  * its own implementation here and inherits every file-touching tool.
  */
-export function getWorkspaceFS(
-  config?: t.LocalExecutionConfig
-): WorkspaceFS {
+export function getWorkspaceFS(config?: t.LocalExecutionConfig): WorkspaceFS {
   return config?.exec?.fs ?? nodeWorkspaceFS;
 }
 
@@ -282,17 +284,17 @@ export function getWorkspaceFS(
  * helpers interpret as "skip the write clamp".
  */
 export function getWriteRoots(
-  config?: t.LocalExecutionConfig
+  config: t.LocalExecutionConfig = {}
 ): string[] | null {
   // Granular flag wins over the legacy one when explicitly set
   // (true OR false) — otherwise a host tightening access during
   // migration (`allowOutsideWorkspace: true, workspace.
   // allowWriteOutside: false`) would still get the loose behavior
   // because the legacy flag short-circuited the OR. Codex P1 #36.
-  const granular = config?.workspace?.allowWriteOutside;
+  const granular = config.workspace?.allowWriteOutside;
   if (granular === true) return null;
   if (granular === false) return getWorkspaceRoots(config);
-  if (config?.allowOutsideWorkspace === true) return null;
+  if (config.allowOutsideWorkspace === true) return null;
   return getWorkspaceRoots(config);
 }
 
@@ -302,14 +304,14 @@ export function getWriteRoots(
  * `allowOutsideWorkspace`) by returning `null`.
  */
 export function getReadRoots(
-  config?: t.LocalExecutionConfig
+  config: t.LocalExecutionConfig = {}
 ): string[] | null {
   // Same precedence as getWriteRoots: granular flag is authoritative
   // when set, legacy flag is the fallback. Codex P1 #36.
-  const granular = config?.workspace?.allowReadOutside;
+  const granular = config.workspace?.allowReadOutside;
   if (granular === true) return null;
   if (granular === false) return getWorkspaceRoots(config);
-  if (config?.allowOutsideWorkspace === true) return null;
+  if (config.allowOutsideWorkspace === true) return null;
   return getWorkspaceRoots(config);
 }
 
@@ -323,10 +325,13 @@ const missingSandboxRuntimeMessage = [
   'Local sandbox is enabled, but @anthropic-ai/sandbox-runtime is not installed.',
   'Install it with `npm install @anthropic-ai/sandbox-runtime`, or disable local sandboxing with `local.sandbox.enabled: false`.',
 ].join(' ');
+const sandboxRuntimePackage = '@anthropic-ai/sandbox-runtime';
 
 /** Lazy-loads the ESM-only sandbox runtime only when sandboxing is enabled. */
 function loadSandboxRuntime(): Promise<SandboxRuntimeModule> {
-  sandboxRuntimePromise ??= import('@anthropic-ai/sandbox-runtime');
+  sandboxRuntimePromise ??= import(
+    sandboxRuntimePackage
+  ) as Promise<SandboxRuntimeModule>;
   return sandboxRuntimePromise;
 }
 
@@ -487,7 +492,9 @@ export async function validateBashCommand(
   }
 
   if (config.readOnly === true && mutatingCommandPattern.test(normalized)) {
-    errors.push('Command appears to mutate files or repository state in read-only local mode.');
+    errors.push(
+      'Command appears to mutate files or repository state in read-only local mode.'
+    );
   }
 
   // Use the same shell the actual execution path will use. Hard-coding
@@ -504,12 +511,14 @@ export async function validateBashCommand(
       sandbox: { enabled: false },
     },
     { internal: true }
-  ).catch((error: Error): SpawnResult => ({
-    stdout: '',
-    stderr: error.message,
-    exitCode: 1,
-    timedOut: false,
-  }));
+  ).catch(
+    (error: Error): SpawnResult => ({
+      stdout: '',
+      stderr: error.message,
+      exitCode: 1,
+      timedOut: false,
+    })
+  );
 
   if (syntax.exitCode !== 0) {
     errors.push(
@@ -567,14 +576,7 @@ async function ensureSandbox(
     await runtime.SandboxManager.reset();
   }
 
-  // Cast at the runtime boundary — our public `BuiltSandboxRuntimeConfig`
-  // is intentionally structural to keep the optional peer dep out of
-  // generated `.d.ts` (Codex P1 #22). It's a structural subset of the
-  // peer's `SandboxRuntimeConfig`, so the assignment is sound at the
-  // one site where the peer is actually loaded.
-  await runtime.SandboxManager.initialize(
-    runtimeConfig as unknown as SandboxRuntimeConfig
-  );
+  await runtime.SandboxManager.initialize(runtimeConfig);
   sandboxInitialized = true;
   sandboxConfigKey = nextKey;
   return runtime.SandboxManager;
@@ -715,8 +717,7 @@ export async function spawnLocalProcess(
   // so a process producing unbounded output gets stopped instead of
   // letting the host OOM.
   const inMemoryCapBytes = maxOutputChars * 2;
-  const hardKillBytes =
-    config.maxSpawnedBytes ?? DEFAULT_MAX_SPAWNED_BYTES;
+  const hardKillBytes = config.maxSpawnedBytes ?? DEFAULT_MAX_SPAWNED_BYTES;
   const sandboxManager = await ensureSandbox(config, cwd);
   // Internal probes (validateBashCommand syntax preflight,
   // isRipgrepAvailable, syntax-check probe cache priming) pass
@@ -775,10 +776,7 @@ export async function spawnLocalProcess(
       spillStream.write('\n===== overflow stream begins here =====\n');
     };
 
-    const handleChunk = (
-      buf: Buffer,
-      kind: 'stdout' | 'stderr'
-    ): void => {
+    const handleChunk = (buf: Buffer, kind: 'stdout' | 'stderr'): void => {
       totalSpawnedBytes += buf.length;
       // hardKillBytes <= 0 means "no cap" per the public config contract
       // (see LocalExecutionConfig.maxSpawnedBytes). Skip the kill check
@@ -857,11 +855,11 @@ export async function spawnLocalProcess(
       }, timeoutMs);
     }
 
-    child.stdout?.on('data', (chunk: Buffer) => {
+    child.stdout.on('data', (chunk: Buffer) => {
       handleChunk(chunk, 'stdout');
     });
 
-    child.stderr?.on('data', (chunk: Buffer) => {
+    child.stderr.on('data', (chunk: Buffer) => {
       handleChunk(chunk, 'stderr');
     });
 
@@ -928,8 +926,7 @@ export async function executeLocalBash(
  * Codex P1 [45], extended for dot-glob in Codex P1 [47] (mirrors the
  * `DESTRUCTIVE_TARGET` suffix matrix exactly).
  */
-const PROTECTED_TARGET_ARG_RE =
-  /^(?:\/|~|\$\{?HOME\}?|\.)(?:\/?\.?\*|\/)?$/;
+const PROTECTED_TARGET_ARG_RE = /^(?:\/|~|\$\{?HOME\}?|\.)(?:\/?\.?\*|\/)?$/;
 
 /**
  * Mutating-op recognizer for the args check. Conservative: only the
@@ -971,11 +968,7 @@ export async function executeLocalBashWithArgs(
     }
   }
   const shell = config.shell ?? DEFAULT_SHELL;
-  return spawnLocalProcess(
-    shell,
-    ['-lc', command, '--', ...args],
-    config
-  );
+  return spawnLocalProcess(shell, ['-lc', command, '--', ...args], config);
 }
 
 export async function executeLocalCode(
@@ -1009,7 +1002,11 @@ export async function executeLocalCode(
       config.shell
     );
     if (runtime.source != null) {
-      await writeFile(resolve(tempDir, runtime.fileName), runtime.source, 'utf8');
+      await writeFile(
+        resolve(tempDir, runtime.fileName),
+        runtime.source,
+        'utf8'
+      );
     }
     return await spawnLocalProcess(runtime.command, runtime.args, config);
   } finally {
@@ -1205,7 +1202,7 @@ function killProcessTree(child: ChildProcess): void {
   // window. Use unref() so the timer doesn't keep the Node process
   // alive past the parent's natural exit.
   const escalation = setTimeout(() => sigkill(child), SIGKILL_ESCALATION_MS);
-  escalation.unref?.();
+  escalation.unref();
   child.once('close', () => clearTimeout(escalation));
 }
 
@@ -1225,9 +1222,12 @@ export function resolveWorkspacePath(
   intent: 'read' | 'write' = 'write'
 ): string {
   const cwd = getLocalCwd(config);
-  const absolutePath = isAbsolute(filePath) ? resolve(filePath) : resolve(cwd, filePath);
+  const absolutePath = isAbsolute(filePath)
+    ? resolve(filePath)
+    : resolve(cwd, filePath);
 
-  const roots = intent === 'write' ? getWriteRoots(config) : getReadRoots(config);
+  const roots =
+    intent === 'write' ? getWriteRoots(config) : getReadRoots(config);
   if (roots == null) return absolutePath; // explicit allow-outside
 
   if (absolutePath === cwd || isInsideAnyRoot(absolutePath, roots)) {
@@ -1306,7 +1306,8 @@ export async function resolveWorkspacePathSafe(
   intent: 'read' | 'write' = 'write'
 ): Promise<string> {
   const lexical = resolveWorkspacePath(filePath, config, intent);
-  const roots = intent === 'write' ? getWriteRoots(config) : getReadRoots(config);
+  const roots =
+    intent === 'write' ? getWriteRoots(config) : getReadRoots(config);
   if (roots == null) {
     return lexical;
   }

package/src/tools/local/LocalExecutionTools.ts

@@ -115,7 +115,7 @@ export function createLocalCodeExecutionTool(
         {
           session_id: getLocalSessionId(config),
           files: [],
-        },
+        } satisfies t.CodeExecutionArtifact,
       ];
     },
     {
@@ -151,7 +151,7 @@ export function createLocalBashExecutionTool(options?: {
         {
           session_id: getLocalSessionId(config),
           files: [],
-        },
+        } satisfies t.CodeExecutionArtifact,
       ];
     },
     {

package/src/tools/local/LocalProgrammaticToolCalling.ts

@@ -79,7 +79,9 @@ type LocalProgrammaticParams = {
 
 type ToolFilter = (toolDefs: t.LCTool[], code: string) => t.LCTool[];
 
-function resolveRuntime(params: LocalProgrammaticParams): LocalProgrammaticRuntime {
+function resolveRuntime(
+  params: LocalProgrammaticParams
+): LocalProgrammaticRuntime {
   const rawRuntime = params.lang ?? params.runtime ?? params.language ?? 'bash';
   return rawRuntime === 'py' || rawRuntime === 'python' ? 'python' : 'bash';
 }
@@ -494,13 +496,17 @@ async function runLocalProgrammaticTool(args: {
   localConfig: t.LocalExecutionConfig;
   runtime: LocalProgrammaticRuntime;
 }): Promise<[string, t.ProgrammaticExecutionArtifact]> {
-  const { toolMap, toolDefs, hookContext } = getProgrammaticContext(args.config);
+  const { toolMap, toolDefs, hookContext } = getProgrammaticContext(
+    args.config
+  );
 
   if (toolMap == null || toolMap.size === 0) {
     throw new Error('No toolMap provided for local programmatic execution.');
   }
   if (toolDefs == null || toolDefs.length === 0) {
-    throw new Error('No tool definitions provided for local programmatic execution.');
+    throw new Error(
+      'No tool definitions provided for local programmatic execution.'
+    );
   }
 
   const { effectiveTools, effectiveMap } = createEffectiveToolMap(
@@ -512,17 +518,28 @@ async function runLocalProgrammaticTool(args: {
   const bridge = await createToolBridge(effectiveMap, hookContext);
 
   try {
-    const timeoutMs = args.params.timeout ?? args.localConfig.timeoutMs ?? DEFAULT_TIMEOUT;
+    const timeoutMs =
+      args.params.timeout ?? args.localConfig.timeoutMs ?? DEFAULT_TIMEOUT;
     const result =
       args.runtime === 'bash'
         ? await executeLocalBash(
-          createBashProgram(args.params.code, effectiveTools, bridge.url, bridge.token),
+          createBashProgram(
+            args.params.code,
+            effectiveTools,
+            bridge.url,
+            bridge.token
+          ),
           { ...args.localConfig, timeoutMs }
         )
         : await executeLocalCode(
           {
             lang: 'py',
-            code: createPythonProgram(args.params.code, effectiveTools, bridge.url, bridge.token),
+            code: createPythonProgram(
+              args.params.code,
+              effectiveTools,
+              bridge.url,
+              bridge.token
+            ),
           },
           { ...args.localConfig, timeoutMs }
         );

package/src/types/diff.d.ts

@@ -0,0 +1,15 @@
+declare module 'diff' {
+  export type PatchOptions = {
+    context?: number;
+  };
+
+  export function createTwoFilesPatch(
+    oldFileName: string,
+    newFileName: string,
+    oldStr: string,
+    newStr: string,
+    oldHeader?: string,
+    newHeader?: string,
+    options?: PatchOptions
+  ): string;
+}

package/src/types/tools.ts

@@ -138,42 +138,90 @@ export type ToolEndEvent = {
   type?: 'tool_call';
 };
 
-export type CodeEnvFile = {
+/**
+ * Closed set of resource kinds for sandbox file caching. Defined as a
+ * `as const` tuple so the runtime list and the TypeScript union can't
+ * drift on future additions — adding a new kind to the tuple updates
+ * both at once.
+ *
+ * - `skill`: shared per skill identity. Cross-user-within-tenant
+ *   sharing. Codeapi sessionKey omits the user dimension. `version`
+ *   is required (skill's monotonic counter scopes cache per revision).
+ * - `agent`: shared per agent identity. Same sharing semantic as
+ *   skills.
+ * - `user`: user-private. Codeapi sessionKey is keyed by the
+ *   requesting user from auth context. Used for chat attachments
+ *   and code-output files.
+ */
+export const CODE_ENV_KINDS = ['skill', 'agent', 'user'] as const;
+export type CodeEnvKind = (typeof CODE_ENV_KINDS)[number];
+
+type CodeEnvFileBase = {
+  /**
+   * Resource identity. Semantics depend on `kind`:
+   *  - `skill`: skill `_id` (sessionKey-meaningful, cross-user shared).
+   *  - `agent`: agent id (sessionKey-meaningful, cross-user shared).
+   *  - `user`: informational only — codeapi derives sessionKey from
+   *    the auth-context user. Kept on the type for shape uniformity;
+   *    do not rely on it for routing.
+   */
   id: string;
   name: string;
-  session_id: string;
   /**
-   * Identifier of the entity that owns this file's session (skill id,
-   * agent id, etc). Forwarded to codeapi so it can resolve the
-   * per-file sessionKey instead of falling back to a single
-   * request-level entity. Required when a single execute request
-   * references files uploaded under different entities (e.g. a skill
-   * file plus a user attachment in the same call).
+   * Storage session — the long-lived bucket where this file's bytes
+   * live in object storage. Distinct from the (transient) execution
+   * session id that appears at the top level of an execute response;
+   * the two used to share the field name `session_id` and the
+   * conflation caused real bugs. See codeapi #1455 / agents #148.
    */
-  entity_id?: string;
+  storage_session_id: string;
 };
 
+/**
+ * `CodeEnvFile` is a discriminated union on `kind`. `version` is
+ * statically required for `kind: 'skill'` and statically forbidden
+ * for `agent` / `user` — the constraint holds at compile time on
+ * every consumer, not just on codeapi's runtime validator.
+ *
+ * Codeapi switches on `kind` to derive the sessionKey for cache
+ * scoping (`<tenant>:<kind>:<id>[:v:<version>]`). Cross-user sharing
+ * for `kind: 'skill'` / `'agent'` is a designed property of the
+ * kind switch.
+ */
+export type CodeEnvFile =
+  | (CodeEnvFileBase & { kind: 'skill'; version: number })
+  | (CodeEnvFileBase & { kind: 'agent' })
+  | (CodeEnvFileBase & { kind: 'user' });
+
 export type CodeExecutionToolParams =
   | undefined
   | {
+      /** Execution session — see `CodeSessionContext.session_id`. */
       session_id?: string;
       user_id?: string;
       files?: CodeEnvFile[];
     };
 
 export type FileRef = {
+  /**
+   * Resource identity. Semantics depend on `kind` (when present):
+   *  - `skill` / `agent`: shared resource id (sessionKey-meaningful).
+   *  - `user`: informational only — codeapi derives sessionKey from
+   *    the auth-context user. Do not rely on it for routing.
+   */
   id: string;
   name: string;
   path?: string;
-  /** Session ID this file belongs to (for multi-session file tracking) */
-  session_id?: string;
   /**
-   * Entity that owns this file's session (skill id, agent id, etc).
-   * Carried on tracked session files so it can flow through to
-   * `_injected_files` when a subsequent execute references a mix of
-   * files uploaded under different entities.
+   * Storage session this file lives in. See `CodeEnvFile.storage_session_id`
+   * for the full motivation.
    */
-  entity_id?: string;
+  storage_session_id?: string;
+  /** Resource kind — see `CodeEnvFile.kind`. */
+  kind?: CodeEnvKind;
+  /** Resource version — see `CodeEnvFile.version`. Only meaningful when
+   *  `kind === 'skill'`. */
+  version?: number;
   /**
    * `true` when the codeapi sandbox echoed this entry as an unchanged
    * passthrough of an input the caller already owns (skill files,
@@ -188,6 +236,11 @@ export type FileRef = {
 export type FileRefs = FileRef[];
 
 export type ExecuteResult = {
+  /**
+   * Execution session id — the (transient) sandbox run that produced
+   * this output. Distinct from per-file `storage_session_id` on the
+   * files array.
+   */
   session_id: string;
   stdout: string;
   stderr: string;
@@ -254,6 +307,7 @@ export type ToolCallRequest = {
   turn?: number;
   /** Code execution session context for session continuity in event-driven mode */
   codeSessionContext?: {
+    /** Execution session — see `CodeSessionContext.session_id`. */
     session_id: string;
     files?: CodeEnvFile[];
   };
@@ -775,6 +829,7 @@ export type PTCToolResult = {
  */
 export type ProgrammaticExecutionResponse = {
   status: 'tool_call_required' | 'completed' | 'error' | unknown;
+  /** Execution session — see `CodeSessionContext.session_id`. */
   session_id?: string;
 
   /** Present when status='tool_call_required' */
@@ -794,6 +849,7 @@ export type ProgrammaticExecutionResponse = {
  * Artifact returned by the PTC tool
  */
 export type ProgrammaticExecutionArtifact = {
+  /** Execution session — see `CodeSessionContext.session_id`. */
   session_id?: string;
   files?: FileRefs;
 };
@@ -827,7 +883,12 @@ export type ProgrammaticToolCallingParams = {
  * Stored in Graph.sessions and injected into subsequent tool invocations.
  */
 export type CodeSessionContext = {
-  /** Session ID from the code execution environment */
+  /**
+   * Execution session id — the (transient) sandbox run id. Used by
+   * ToolNode to thread session continuity into the next code-execution
+   * tool call. Distinct from per-file `storage_session_id` carried on
+   * `files`.
+   */
   session_id: string;
   /** Files generated in this session (for context/tracking) */
   files?: FileRefs;
@@ -840,6 +901,7 @@ export type CodeSessionContext = {
  * Used to extract session context after tool completion.
  */
 export type CodeExecutionArtifact = {
+  /** Execution session — see `CodeSessionContext.session_id`. */
   session_id?: string;
   files?: FileRefs;
 };