@librechat/agents 3.8.6 → 3.8.8

package/src/tools/ProgrammaticToolCalling.ts

@@ -1,5 +1,6 @@
 // src/tools/ProgrammaticToolCalling.ts
 import { config } from 'dotenv';
+import { randomUUID } from 'node:crypto';
 import fetch, { RequestInit } from 'node-fetch';
 import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import type { ToolCall } from '@langchain/core/messages/tool';
@@ -21,6 +22,7 @@ import {
   resolveCodeApiAuthHeaders,
   selectRuntimeSessionHint,
 } from './CodeExecutor';
+import { appendExecutionArtifactFileSummary } from './CodeSessionFileSummary';
 import {
   assertUnambiguousIdentifiers,
   projectProgrammaticToolMap,
@@ -51,6 +53,9 @@ config();
 const DEFAULT_MAX_ROUND_TRIPS = 20;
 
 const DEFAULT_RUN_TIMEOUT_MS = resolveCodeApiRunTimeoutMs();
+const CODE_API_PROGRAMMATIC_REQUEST_HEADER =
+  'X-LibreChat-Code-Request-ID';
+const CANCELLATION_REQUEST_TIMEOUT_MS = 2_000;
 
 // ============================================================================
 // Description Components (Single Source of Truth)
@@ -513,10 +518,12 @@ export async function makeRequest(
   body: Record<string, unknown>,
   proxy?: string,
   authHeaders?: t.CodeApiAuthHeaders,
-  executionProfile?: t.CodeApiExecutionProfile
+  executionProfile?: t.CodeApiExecutionProfile,
+  signal?: AbortSignal
 ): Promise<t.ProgrammaticExecutionResponse> {
   try {
     const resolvedAuthHeaders = await resolveCodeApiAuthHeaders(authHeaders);
+    const requestId = signal != null ? randomUUID() : undefined;
     const fetchOptions: RequestInit = {
       method: 'POST',
       headers: {
@@ -526,8 +533,12 @@ export async function makeRequest(
           resolvedAuthHeaders,
           executionProfile
         ),
+        ...(requestId != null
+          ? { [CODE_API_PROGRAMMATIC_REQUEST_HEADER]: requestId }
+          : {}),
       },
       body: JSON.stringify(body),
+      signal: signal as RequestInit['signal'],
     };
 
     const proxyAgent = resolveFetchProxyAgent(endpoint, proxy);
@@ -535,7 +546,59 @@ export async function makeRequest(
       fetchOptions.agent = proxyAgent;
     }
 
-    const response = await fetch(endpoint, fetchOptions);
+    let cancellationRequest: Promise<void> | undefined;
+    const requestCancellation = (): void => {
+      if (requestId == null || cancellationRequest != null) {
+        return;
+      }
+      cancellationRequest = (async (): Promise<void> => {
+        const cancellationController = new AbortController();
+        const timeout = setTimeout(
+          () => cancellationController.abort(),
+          CANCELLATION_REQUEST_TIMEOUT_MS
+        );
+        try {
+          const cancelOptions: RequestInit = {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              'User-Agent': 'LibreChat/1.0',
+              ...addCodeApiExecutionProfileHeader(
+                resolvedAuthHeaders,
+                executionProfile
+              ),
+            },
+            body: JSON.stringify({ request_id: requestId }),
+            signal: cancellationController.signal as RequestInit['signal'],
+          };
+          if (proxyAgent != null) {
+            cancelOptions.agent = proxyAgent;
+          }
+          await fetch(`${endpoint}/cancel`, cancelOptions);
+        } catch {
+          // Cancellation is best effort for older Code API versions and
+          // transient network failures. The original abort remains the public
+          // result while the server-side execution deadline is the fallback.
+        } finally {
+          clearTimeout(timeout);
+        }
+      })();
+    };
+    signal?.addEventListener('abort', requestCancellation, { once: true });
+    if (signal?.aborted === true) requestCancellation();
+
+    let response;
+    try {
+      response = await fetch(endpoint, fetchOptions);
+    } catch (error) {
+      if (signal?.aborted === true) {
+        requestCancellation();
+        await cancellationRequest;
+      }
+      throw error;
+    } finally {
+      signal?.removeEventListener('abort', requestCancellation);
+    }
 
     if (!response.ok) {
       throw new CodeApiRequestError(
@@ -860,7 +923,8 @@ export async function executeTools(
  */
 export function formatCompletedResponse(
   response: t.ProgrammaticExecutionResponse,
-  sourceCode = ''
+  sourceCode = '',
+  filePersistence: 'session' | 'execution' = 'session'
 ): [string, t.ProgrammaticExecutionArtifact] {
   let formatted = '';
 
@@ -884,10 +948,15 @@ export function formatCompletedResponse(
   );
 
   return [
-    appendCodeSessionFileSummary(outputWithDeliveryWarning, response.files),
+    filePersistence === 'execution'
+      ? appendExecutionArtifactFileSummary(outputWithDeliveryWarning, response.files)
+      : appendCodeSessionFileSummary(outputWithDeliveryWarning, response.files),
     {
       session_id: response.session_id,
       files: response.files,
+      ...(response.deleted_files != null
+        ? { deleted_files: response.deleted_files }
+        : {}),
       ...(artifactDelivery != null
         ? { artifact_delivery: artifactDelivery }
         : {}),
@@ -1161,7 +1230,8 @@ export function createProgrammaticToolCallingTool(
           },
           proxy,
           initParams.authHeaders,
-          initParams.executionProfile
+          initParams.executionProfile,
+          config.signal
         );
 
         // ====================================================================
@@ -1199,7 +1269,8 @@ export function createProgrammaticToolCallingTool(
             },
             proxy,
             initParams.authHeaders,
-            initParams.executionProfile
+            initParams.executionProfile,
+            config.signal
           );
         }
 

package/src/tools/ToolNode.ts

@@ -221,6 +221,8 @@ type RunToolBatchContext<T = unknown> = {
   batchScopeId?: string;
   /** Batch-local sink for post-substitution args. */
   resolvedArgsByCallId?: ResolvedArgsByCallId;
+  /** File identities actually injected into each direct code call. */
+  codeSessionBaselineByCallId?: Map<string, ReadonlyMap<string, string>>;
   /**
    * Frozen pre-batch view of the tool-output registry. When supplied,
    * `runTool` resolves `{{tool…turn…}}` placeholders against this
@@ -651,29 +653,78 @@ function toInjectedFileRef(
 
 /* Stable file identity = `(storage_session_id, id)`. Same name in
  * different storage sessions are distinct files. */
-function fileIdentityKey(file: {
-  storage_session_id?: string;
-  id: string;
-}): string {
-  return `${file.storage_session_id ?? ''}\0${file.id}`;
+function fileIdentityKey(
+  file: {
+    storage_session_id?: string;
+    id: string;
+  },
+  fallbackSessionId = ''
+): string {
+  return `${file.storage_session_id ?? fallbackSessionId}\0${file.id}`;
+}
+
+function codeSessionIdentityByName(
+  context:
+    | t.ToolCallRequest['codeSessionContext']
+    | t.CodeSessionContext
+    | undefined
+): ReadonlyMap<string, string> {
+  return new Map(
+    (context?.files ?? []).map((file) => [
+      file.name,
+      fileIdentityKey(file, context?.session_id),
+    ])
+  );
+}
+
+function storageSessionIdFromIdentity(
+  identity: string | undefined,
+  fileId: string
+): string | undefined {
+  const suffix = `\0${fileId}`;
+  return identity != null && identity.endsWith(suffix)
+    ? identity.slice(0, identity.length - suffix.length)
+    : undefined;
 }
 
 function updateCodeSession(
   sessions: t.ToolSessionMap,
   sessionKey: string,
   execSessionId: string,
-  files: t.FileRefs | undefined
+  files: t.FileRefs | undefined,
+  deletedFiles: readonly string[] | undefined,
+  baselineIdentityByName: ReadonlyMap<string, string> | undefined
 ): void {
   const newFiles = files ?? [];
   const existingSession = sessions.get(sessionKey) as
     | t.CodeSessionContext
     | undefined;
-  const existingFiles = existingSession?.files ?? [];
+  const existingSessionId = existingSession?.session_id ?? '';
+  const existingFiles = (existingSession?.files ?? []).map((file) =>
+    file.storage_session_id == null
+      ? { ...file, storage_session_id: existingSessionId }
+      : file
+  );
+  const deletedIdentityByName = new Map<string, string>();
+  for (const name of deletedFiles ?? []) {
+    const identity = baselineIdentityByName?.get(name);
+    if (identity != null) {
+      deletedIdentityByName.set(name, identity);
+    }
+  }
 
+  /* Absence from `files` is not a deletion signal: older Code API versions
+   * and truncated responses can omit otherwise-live refs. Remove only paths
+   * explicitly attested by `deleted_files`, and only while the current ref
+   * still has the identity injected into that request. */
   if (newFiles.length === 0) {
     sessions.set(sessionKey, {
       session_id: execSessionId,
-      files: existingFiles,
+      files: existingFiles.filter(
+        (file) =>
+          deletedIdentityByName.get(file.name) !==
+          fileIdentityKey(file, existingSessionId)
+      ),
       lastUpdated: Date.now(),
     });
     return;
@@ -685,26 +736,46 @@ function updateCodeSession(
   const filesWithSession: t.FileRefs = [];
   const newFileNames = new Set<string>();
   const incomingByIdentity = new Map<string, number>();
+  const existingIdentities = new Set(
+    existingFiles.map((file) => fileIdentityKey(file, existingSessionId))
+  );
   for (const file of newFiles) {
+    const baselineIdentity = baselineIdentityByName?.get(file.name);
     const withSession = {
       ...file,
-      storage_session_id: file.storage_session_id ?? execSessionId,
+      storage_session_id:
+        file.storage_session_id ??
+        storageSessionIdFromIdentity(baselineIdentity, file.id) ??
+        execSessionId,
     };
-    incomingByIdentity.set(
-      fileIdentityKey(withSession),
-      filesWithSession.length
-    );
+    const identity = fileIdentityKey(withSession);
+    const wasTrackedByRequest = baselineIdentity === identity;
+    /* An inherited echo is evidence that a request observed an existing ref,
+     * not authority to resurrect one removed by a concurrent sibling. Fresh
+     * and modified outputs remain eligible to replace by path below. */
+    if (
+      file.inherited === true &&
+      wasTrackedByRequest &&
+      (!existingIdentities.has(identity) ||
+        deletedIdentityByName.get(file.name) === identity)
+    ) {
+      continue;
+    }
+    incomingByIdentity.set(identity, filesWithSession.length);
     newFileNames.add(withSession.name);
     filesWithSession.push(withSession);
   }
 
   const filteredExisting: t.FileRefs = [];
   for (const e of existingFiles) {
-    const idx = incomingByIdentity.get(fileIdentityKey(e));
+    const idx = incomingByIdentity.get(fileIdentityKey(e, existingSessionId));
     if (idx !== undefined) {
       filesWithSession[idx] = { ...e, ...filesWithSession[idx] };
     }
-    if (!newFileNames.has(e.name)) {
+    const explicitlyDeleted =
+      deletedIdentityByName.get(e.name) ===
+      fileIdentityKey(e, existingSessionId);
+    if (!newFileNames.has(e.name) && !explicitlyDeleted) {
       filteredExisting.push(e);
     }
   }
@@ -1898,6 +1969,12 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           | t.CodeSessionContext
           | undefined;
         const execSessionId = codeSession?.session_id;
+        if (batchContext.codeSessionBaselineByCallId != null) {
+          batchContext.codeSessionBaselineByCallId.set(
+            call.id ?? '',
+            codeSessionIdentityByName(codeSession)
+          );
+        }
         if (execSessionId != null && execSessionId !== '') {
           invokeParams = {
             ...invokeParams,
@@ -3095,7 +3172,11 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     baselineByRequestId: ReadonlyMap<
       string,
       ReadonlyMap<string, string>
-    >
+    > = new Map(),
+    executionBaselineByRequestId: ReadonlyMap<
+      string,
+      ReadonlyMap<string, string>
+    > = baselineByRequestId
   ): void {
     if (!this.sessions) {
       return;
@@ -3131,7 +3212,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         this.sessions,
         this.codeSessionKey,
         execSessionId,
-        artifact?.files
+        artifact?.files,
+        artifact?.deleted_files,
+        executionBaselineByRequestId.get(request.id)
       );
     }
   }
@@ -3200,6 +3283,10 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     outputs: (BaseMessage | Command)[],
     config: RunnableConfig,
     resolvedArgsByCallId?: ResolvedArgsByCallId,
+    codeSessionBaselineByCallId?: ReadonlyMap<
+      string,
+      ReadonlyMap<string, string>
+    >,
     errorOwnership?: ToolErrorOwnership
   ): Promise<void> {
     const ownership = errorOwnership ?? this.looseErrorOwnership;
@@ -3235,7 +3322,11 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         ownership.undispatched.delete(toolCallId);
       }
 
-      if (this.sessions && this.participatesInCodeSession(call.name)) {
+      if (
+        toolMessage.status !== 'error' &&
+        this.sessions &&
+        this.participatesInCodeSession(call.name)
+      ) {
         const artifact = toolMessage.artifact as
           | t.CodeExecutionArtifact
           | undefined;
@@ -3245,7 +3336,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
             this.sessions,
             this.codeSessionKey,
             execSessionId,
-            artifact?.files
+            artifact?.files,
+            artifact?.deleted_files,
+            codeSessionBaselineByCallId?.get(toolCallId)
           );
         }
       }
@@ -4112,12 +4205,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       >(
         plan.allRequests.map((request) => [
           request.id,
-          new Map(
-            (request.codeSessionContext?.files ?? []).map((file) => [
-              file.name,
-              fileIdentityKey(file),
-            ])
-          ),
+          codeSessionIdentityByName(request.codeSessionContext),
         ])
       );
       const eagerExecutions: Array<{
@@ -4319,11 +4407,25 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         ...flattenedEagerResults,
         ...dispatchedResults,
       ];
+      /* Hosts may lazily refresh codeSessionContext while dispatching. The
+       * pre-dispatch snapshot above remains the authority for detecting those
+       * additions, while deletion reconciliation must use the identities the
+       * execution actually received. */
+      const executionBaselineByRequestId = new Map<
+        string,
+        ReadonlyMap<string, string>
+      >(
+        plan.allRequests.map((request) => [
+          request.id,
+          codeSessionIdentityByName(request.codeSessionContext),
+        ])
+      );
 
       this.storeCodeSessionFromResults(
         results,
         requestMap,
-        codeSessionBaselineByRequestId
+        codeSessionBaselineByRequestId,
+        executionBaselineByRequestId
       );
 
       for (const result of results) {
@@ -4993,6 +5095,15 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
       ) {
         baseContext.resolvedArgsByCallId.set(call.id, result.resolvedArgs);
       }
+      if (
+        result.codeSessionBaseline != null &&
+        baseContext.codeSessionBaselineByCallId != null
+      ) {
+        baseContext.codeSessionBaselineByCallId.set(
+          call.id ?? '',
+          new Map(result.codeSessionBaseline)
+        );
+      }
       return result;
     };
     const runOne = async (
@@ -5029,6 +5140,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         call.id == null
           ? undefined
           : baseContext.resolvedArgsByCallId?.get(call.id);
+      const codeSessionBaseline =
+        baseContext.codeSessionBaselineByCallId?.get(call.id ?? '');
       const result: SettledDirectToolResult = {
         proposal: structuredClone({
           name: call.name,
@@ -5042,6 +5155,9 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         output,
         additionalContexts,
         ...(resolvedArgs == null ? {} : { resolvedArgs }),
+        ...(codeSessionBaseline == null
+          ? {}
+          : { codeSessionBaseline: [...codeSessionBaseline.entries()] }),
       };
       const refMeta = isBaseMessage(output)
         ? (output.additional_kwargs as t.ToolMessageRefMetadata)
@@ -5260,6 +5376,10 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
      * ToolNode cannot read or wipe each other's entries.
      */
     const resolvedArgsByCallId = new Map<string, Record<string, unknown>>();
+    const codeSessionBaselineByCallId = new Map<
+      string,
+      ReadonlyMap<string, string>
+    >();
     /** Per-invocation error-completion ownership — see `ToolErrorOwnership`. */
     const errorOwnership = createToolErrorOwnership();
     /**
@@ -5340,6 +5460,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           batchScopeId,
           preBatchSnapshot: replayInputSnapshot,
           resolvedArgsByCallId,
+          codeSessionBaselineByCallId,
           errorOwnership,
           additionalContextsSink: directAdditionalContexts,
           replayBatchKey: sendReplayBatchKey,
@@ -5368,6 +5489,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
         [sendOutput],
         config,
         resolvedArgsByCallId,
+        codeSessionBaselineByCallId,
         errorOwnership
       );
     } else {
@@ -5625,6 +5747,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
                 turn,
                 batchScopeId,
                 resolvedArgsByCallId,
+                codeSessionBaselineByCallId,
                 errorOwnership,
                 preBatchSnapshot,
                 additionalContextsSink: directAdditionalContexts,
@@ -5662,6 +5785,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
             unhandledDirectOutputs,
             config,
             resolvedArgsByCallId,
+            codeSessionBaselineByCallId,
             errorOwnership
           );
           for (let i = 0; i < directCalls.length; i++) {
@@ -5737,6 +5861,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
             turn,
             batchScopeId,
             resolvedArgsByCallId,
+            codeSessionBaselineByCallId,
             errorOwnership,
             preBatchSnapshot,
             additionalContextsSink: directAdditionalContexts,
@@ -5751,6 +5876,7 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
           toolOutputs,
           config,
           resolvedArgsByCallId,
+          codeSessionBaselineByCallId,
           errorOwnership
         );
         // Append accumulated additionalContexts as a single

package/src/tools/toolBatchReplay.ts

@@ -32,6 +32,8 @@ export interface SettledToolBatchResult {
   output: BaseMessage | Command;
   additionalContexts: string[];
   resolvedArgs?: Record<string, unknown>;
+  /** Code-session identities injected into this completed direct call. */
+  codeSessionBaseline?: Array<[string, string]>;
   completionHandled?: boolean;
   referenceContent?: string;
   turn?: number;
@@ -474,6 +476,14 @@ export async function restoreToolBatchReplayState(
               throw new Error('Invalid settled tool batch results');
             }
             const result = entry[1] as Partial<SettledToolBatchResult> | null;
+            const codeSessionBaseline: unknown = (
+              result as { codeSessionBaseline?: unknown } | null
+            )?.codeSessionBaseline;
+            const baselineNames = Array.isArray(codeSessionBaseline)
+              ? codeSessionBaseline.map((pair) =>
+                Array.isArray(pair) ? pair[0] : undefined
+              )
+              : [];
             if (
               result == null ||
               (!isBaseMessage(result.output) && !isCommand(result.output)) ||
@@ -491,7 +501,19 @@ export async function restoreToolBatchReplayState(
               typeof result.proposal.name !== 'string' ||
               result.proposal.name.length === 0 ||
               !isRecord(result.proposal.args) ||
-              (result.resolvedArgs != null && !isRecord(result.resolvedArgs))
+              (result.resolvedArgs != null && !isRecord(result.resolvedArgs)) ||
+              (codeSessionBaseline != null &&
+                (!Array.isArray(codeSessionBaseline) ||
+                  codeSessionBaseline.some(
+                    (pair) =>
+                      !Array.isArray(pair) ||
+                      pair.length !== 2 ||
+                      typeof pair[0] !== 'string' ||
+                      pair[0].length === 0 ||
+                      typeof pair[1] !== 'string' ||
+                      pair[1].length === 0
+                  ) ||
+                  new Set(baselineNames).size !== baselineNames.length))
             ) {
               throw new Error('Invalid settled tool batch results');
             }

package/src/tools/workspaceIdentity.ts

@@ -0,0 +1,15 @@
+const WORKSPACE_INSTANCE_ID_PATTERN = /^[a-f0-9]{64}$/;
+
+export function resolveAttachedWorkspaceInstanceId(
+  value: string | undefined,
+  hasWorkspace: boolean
+): string | undefined {
+  const workspaceInstanceId = value?.trim();
+  if (workspaceInstanceId == null || workspaceInstanceId === '') {
+    return undefined;
+  }
+  if (!hasWorkspace || !WORKSPACE_INSTANCE_ID_PATTERN.test(workspaceInstanceId)) {
+    throw new Error('Invalid attached workspace instance identifier');
+  }
+  return workspaceInstanceId;
+}

package/src/types/tools.ts

@@ -502,6 +502,8 @@ export type ExecuteResult = {
   stdout: string;
   stderr: string;
   files?: FileRefs;
+  /** Persisted input paths explicitly removed during this execution. */
+  deleted_files?: string[];
   artifact_delivery?: ArtifactDeliveryFailure;
   /**
    * Durable runtime session id echoed by a stateful Code API backend
@@ -1346,6 +1348,8 @@ export type ProgrammaticExecutionResponse = {
   stdout?: string;
   stderr?: string;
   files?: FileRefs;
+  /** Persisted input paths explicitly removed during this execution. */
+  deleted_files?: string[];
   artifact_delivery?: ArtifactDeliveryFailure;
 
   /** Durable runtime session echo from a stateful backend (additive). */
@@ -1363,6 +1367,8 @@ export type ProgrammaticExecutionArtifact = {
   /** Execution session — see `CodeSessionContext.session_id`. */
   session_id?: string;
   files?: FileRefs;
+  /** Persisted input paths explicitly removed during this execution. */
+  deleted_files?: string[];
   artifact_delivery?: ArtifactDeliveryFailure;
   /** Durable runtime session echo from a stateful backend (additive). */
   runtime_session_id?: string;
@@ -1370,10 +1376,23 @@ export type ProgrammaticExecutionArtifact = {
 };
 
 /** Parameters for creating a bash execution tool (same API as CodeExecutor, bash-only) */
-export type BashExecutionToolParams = CodeExecutionToolParams;
+export type BashExecutionToolParams =
+  | undefined
+  | (Exclude<CodeExecutionToolParams, undefined> & {
+      /** Trusted attached-workspace identifier selected by the host. */
+      workspaceId?: string;
+      /** Trusted conversation-owned workspace instance selected by the host. */
+      workspaceInstanceId?: string;
+    });
 
 /** Parameters for creating a bash programmatic tool calling tool (same API as PTC, bash-only) */
-export type BashProgrammaticToolCallingParams = ProgrammaticToolCallingParams;
+export type BashProgrammaticToolCallingParams =
+  ProgrammaticToolCallingParams & {
+    /** Trusted attached-workspace identifier selected by the host. */
+    workspaceId?: string;
+    /** Trusted conversation-owned workspace instance selected by the host. */
+    workspaceInstanceId?: string;
+  };
 
 /**
  * Initialization parameters for the PTC tool
@@ -1430,6 +1449,8 @@ export type CodeExecutionArtifact = {
   /** Execution session — see `CodeSessionContext.session_id`. */
   session_id?: string;
   files?: FileRefs;
+  /** Persisted input paths explicitly removed during this execution. */
+  deleted_files?: string[];
   artifact_delivery?: ArtifactDeliveryFailure;
   /** Durable runtime session echo from a stateful backend (additive). */
   runtime_session_id?: string;