@librechat/agents 3.8.6 → 3.8.8

package/src/tools/BashExecutor.ts

@@ -11,6 +11,7 @@ import {
   addCodeApiExecutionProfileHeader,
   emptyOutputMessage,
   buildCodeApiHttpErrorMessage,
+  buildCodeApiExecutionErrorMessage,
   CodeApiRequestError,
   buildCodeApiEndpoint,
   getCodeBaseURL,
@@ -23,9 +24,13 @@ import {
   normalizeArtifactDeliveryFailure,
 } from '@/tools/ArtifactDelivery';
 import { logCodeApiDiagnostic } from '@/tools/diagnostics';
+import { appendExecutionArtifactFileSummary } from '@/tools/CodeSessionFileSummary';
+import { resolveAttachedWorkspaceInstanceId } from '@/tools/workspaceIdentity';
 import { resolveFetchProxyAgent } from '@/utils/proxy';
 import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
+import { prepareBashProgrammaticCode } from './BashProgrammaticToolCalling';
+import { makeRequest } from './ProgrammaticToolCalling';
 
 config();
 
@@ -90,6 +95,17 @@ Usage:
 - NEVER use this tool to execute malicious commands.
 `.trim();
 
+const AttachedWorkspaceBashExecutionToolDescription = `
+Runs bash commands in the selected persistent project through an isolated sandbox process.
+
+Usage:
+- Project file changes persist between calls; shell variables, background processes, and execution-private temporary files do not.
+- Injected files and generated artifacts use \${LIBRECHAT_CODE_DATA_DIR:-/mnt/data}; write durable files to the project root.
+- Generated artifacts are automatically delivered; **DO NOT** provide download links.
+- ${BASH_SHELL_GUIDANCE}
+- NEVER use this tool to execute malicious commands.
+`.trim();
+
 /**
  * Supplemental prompt documenting the tool-output reference feature.
  *
@@ -121,11 +137,14 @@ Referencing previous tool outputs:
 export function buildBashExecutionToolDescription(options?: {
   enableToolOutputReferences?: boolean;
   statefulSessions?: boolean;
+  attachedWorkspace?: boolean;
 }): string {
-  const base =
-    options?.statefulSessions === true
-      ? StatefulBashExecutionToolDescription
-      : BashExecutionToolDescription;
+  let base = BashExecutionToolDescription;
+  if (options?.attachedWorkspace === true) {
+    base = AttachedWorkspaceBashExecutionToolDescription;
+  } else if (options?.statefulSessions === true) {
+    base = StatefulBashExecutionToolDescription;
+  }
   if (options?.enableToolOutputReferences === true) {
     return `${base}\n\n${BashToolOutputReferencesGuide}`;
   }
@@ -136,19 +155,33 @@ const STATELESS_BASH_PARAM_NOTE =
   'The environment is stateless; variables and state don\'t persist between executions.';
 const STATEFUL_BASH_PARAM_NOTE =
   'Files written to /mnt/data persist between calls on the same warm machine. Each call runs in a fresh sandbox: shell variables, cwd, /tmp, and background processes do NOT survive the call. Only /mnt/data is durable.';
+const ATTACHED_BASH_PARAM_NOTE =
+  'Commands start in the selected persistent project. Project file changes persist, but shell variables, background processes, and execution-private temporary files do not.';
+const ATTACHED_BASH_ARTIFACT_PATH_GUIDANCE =
+  'Injected files and generated artifacts use `${LIBRECHAT_CODE_DATA_DIR:-/mnt/data}` for this execution only. Write anything needed later into the selected project.';
+const ATTACHED_BASH_TMP_REMINDER =
+  'Note: /tmp files are same-call scratch only and were not persisted; write files needed later into the selected project.';
 
 export function buildBashExecutionToolSchema(opts?: {
   statefulSessions?: boolean;
+  attachedWorkspace?: boolean;
 }): typeof BashExecutionToolSchema {
-  const note =
-    opts?.statefulSessions === true
-      ? STATEFUL_BASH_PARAM_NOTE
-      : STATELESS_BASH_PARAM_NOTE;
-  const commandDescription =
+  let note = STATELESS_BASH_PARAM_NOTE;
+  if (opts?.attachedWorkspace === true) {
+    note = ATTACHED_BASH_PARAM_NOTE;
+  } else if (opts?.statefulSessions === true) {
+    note = STATEFUL_BASH_PARAM_NOTE;
+  }
+  let commandDescription =
     BashExecutionToolSchema.properties.command.description.replace(
       STATELESS_BASH_PARAM_NOTE,
       note
     );
+  if (opts?.attachedWorkspace === true) {
+    commandDescription = commandDescription
+      .replace('- Prior /mnt/data files are available and can be modified in place.\n', '')
+      .replace(CODE_ARTIFACT_PATH_GUIDANCE, ATTACHED_BASH_ARTIFACT_PATH_GUIDANCE);
+  }
   return {
     ...BashExecutionToolSchema,
     properties: {
@@ -163,6 +196,15 @@ export function buildBashExecutionToolSchema(opts?: {
 
 export const BashExecutionToolName = Constants.BASH_TOOL;
 
+function quoteBashArgument(value: string): string {
+  return `'${value.replace(/'/g, '\'"\'"\'')}'`;
+}
+
+function commandWithArguments(command: string, args: string[] | undefined): string {
+  if (args == null || args.length === 0) return command;
+  return `bash -c ${quoteBashArgument(command)} -- ${args.map(quoteBashArgument).join(' ')}`;
+}
+
 /**
  * Default bash tool definition using the base description.
  *
@@ -182,9 +224,21 @@ export const BashExecutionToolDefinition = {
 function createBashExecutionTool(
   params: t.BashExecutionToolParams | null = {}
 ): DynamicStructuredTool {
+  const workspaceId = params?.workspaceId?.trim();
+  const hasWorkspace = workspaceId != null && workspaceId !== '';
+  const workspaceInstanceId = resolveAttachedWorkspaceInstanceId(
+    params?.workspaceInstanceId,
+    hasWorkspace
+  );
+  if (
+    hasWorkspace &&
+    !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(workspaceId)
+  ) {
+    throw new Error('Invalid attached workspace identifier');
+  }
   const execEndpoint = buildCodeApiEndpoint(
     params?.baseUrl ?? getCodeBaseURL(),
-    'exec'
+    hasWorkspace ? 'exec/programmatic' : 'exec'
   );
 
   return tool(
@@ -197,26 +251,37 @@ function createBashExecutionTool(
         executionProfile,
         runtimeSessionHint,
         statefulSessions,
+        workspaceId: _workspaceId,
+        workspaceInstanceId: _workspaceInstanceId,
         ...executionParams
       } = params ?? {};
       void _baseUrl;
+      void _workspaceId;
+      void _workspaceInstanceId;
       /* Drop any model-supplied `runtime_session_hint` from the raw args: the
        * hint must only come from ToolNode's injected `_runtime_session_hint`
        * (below), never from the tool call itself. */
       /* `intent` is a UI display label — never part of the wire body. */
       const {
-        command,
+        command: rawCommand,
         intent: _ignoredIntent,
         runtime_session_hint: _ignoredModelHint,
+        workspace_instance_id: _ignoredModelWorkspaceInstanceId,
+        args,
         ...rest
       } = rawInput as {
         command: string;
         intent?: unknown;
         runtime_session_hint?: unknown;
+        workspace_instance_id?: unknown;
         args?: string[];
       };
       void _ignoredModelHint;
+      void _ignoredModelWorkspaceInstanceId;
       void _ignoredIntent;
+      const command = hasWorkspace
+        ? commandWithArguments(rawCommand, args)
+        : rawCommand;
       const { session_id, _injected_files, _runtime_session_hint } =
         (config.toolCall ?? {}) as {
           session_id?: string;
@@ -226,9 +291,14 @@ function createBashExecutionTool(
 
       const postData: Record<string, unknown> = {
         lang: 'bash',
-        code: command,
+        code: hasWorkspace ? prepareBashProgrammaticCode(command) : command,
+        ...(hasWorkspace ? { tools: [] } : {}),
+        ...(!hasWorkspace && args != null ? { args } : {}),
         ...rest,
         ...executionParams,
+        ...(workspaceInstanceId != null && workspaceInstanceId !== ''
+          ? { workspace_instance_id: workspaceInstanceId }
+          : {}),
       };
 
       const effectiveRuntimeSessionHint = selectRuntimeSessionHint(
@@ -265,44 +335,70 @@ function createBashExecutionTool(
       try {
         const resolvedAuthHeaders =
           await resolveCodeApiAuthHeaders(authHeaders);
-        const fetchOptions: RequestInit = {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-            'User-Agent': 'LibreChat/1.0',
-            ...addCodeApiExecutionProfileHeader(
-              resolvedAuthHeaders,
-              executionProfile
-            ),
-          },
-          body: JSON.stringify(postData),
-        };
+        let result: Partial<t.ExecuteResult> & t.ProgrammaticExecutionResponse;
+        if (hasWorkspace) {
+          result = await makeRequest(
+            execEndpoint,
+            postData,
+            undefined,
+            {
+              ...resolvedAuthHeaders,
+              'X-LibreChat-Code-Workspace-ID': workspaceId,
+            },
+            executionProfile,
+            config.signal
+          );
+        } else {
+          const fetchOptions: RequestInit = {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              'User-Agent': 'LibreChat/1.0',
+              ...addCodeApiExecutionProfileHeader(
+                resolvedAuthHeaders,
+                executionProfile
+              ),
+            },
+            body: JSON.stringify(postData),
+            signal: config.signal,
+          };
 
-        const proxyAgent = resolveFetchProxyAgent(execEndpoint);
-        if (proxyAgent != null) {
-          fetchOptions.agent = proxyAgent;
+          const proxyAgent = resolveFetchProxyAgent(execEndpoint);
+          if (proxyAgent != null) {
+            fetchOptions.agent = proxyAgent;
+          }
+          const response = await fetch(execEndpoint, fetchOptions);
+          if (!response.ok) {
+            throw new CodeApiRequestError(
+              await buildCodeApiHttpErrorMessage('POST', execEndpoint, response, {
+                profile: executionProfile,
+              })
+            );
+          }
+          result = (await response.json()) as Partial<t.ExecuteResult> &
+            t.ProgrammaticExecutionResponse;
         }
-        const response = await fetch(execEndpoint, fetchOptions);
-        if (!response.ok) {
+        if (hasWorkspace && result.status !== 'completed') {
           throw new CodeApiRequestError(
-            await buildCodeApiHttpErrorMessage('POST', execEndpoint, response, {
-              profile: executionProfile,
-            })
+            buildCodeApiExecutionErrorMessage(
+              result as t.ProgrammaticExecutionResponse
+            )
           );
         }
-
-        const result: t.ExecuteResult = await response.json();
         let formattedOutput = '';
-        if (result.stdout) {
+        if (typeof result.stdout === 'string' && result.stdout.length > 0) {
           formattedOutput += `stdout:\n${result.stdout}\n`;
         } else {
           formattedOutput += emptyOutputMessage;
         }
-        if (result.stderr) formattedOutput += `stderr:\n${result.stderr}\n`;
+        if (typeof result.stderr === 'string' && result.stderr.length > 0) {
+          formattedOutput += `stderr:\n${result.stderr}\n`;
+        }
 
         const outputWithReminder = appendTmpScratchReminder(
           formattedOutput,
-          command
+          command,
+          hasWorkspace ? ATTACHED_BASH_TMP_REMINDER : undefined
         );
         const artifactDelivery = normalizeArtifactDeliveryFailure(
           result.artifact_delivery
@@ -312,6 +408,10 @@ function createBashExecutionTool(
           artifactDelivery
         );
         const hasFiles = result.files != null && result.files.length > 0;
+        const deletionEcho =
+          result.deleted_files != null
+            ? { deleted_files: result.deleted_files }
+            : {};
         const runtimeEcho =
           result.runtime_session_id != null
             ? {
@@ -320,7 +420,15 @@ function createBashExecutionTool(
             }
             : {};
         return [
-          appendCodeSessionFileSummary(outputWithDeliveryWarning, result.files),
+          hasWorkspace
+            ? appendExecutionArtifactFileSummary(
+              outputWithDeliveryWarning,
+              result.files
+            )
+            : appendCodeSessionFileSummary(
+              outputWithDeliveryWarning,
+              result.files
+            ),
           (hasFiles
             ? {
               session_id: result.session_id,
@@ -328,6 +436,7 @@ function createBashExecutionTool(
               ...(artifactDelivery != null
                 ? { artifact_delivery: artifactDelivery }
                 : {}),
+              ...deletionEcho,
               ...runtimeEcho,
             }
             : {
@@ -335,6 +444,7 @@ function createBashExecutionTool(
               ...(artifactDelivery != null
                 ? { artifact_delivery: artifactDelivery }
                 : {}),
+              ...deletionEcho,
               ...runtimeEcho,
             }) satisfies t.CodeExecutionArtifact,
         ];
@@ -343,15 +453,21 @@ function createBashExecutionTool(
           normalizeCodeApiRequestError(error).message,
           command
         );
-        throw new CodeApiRequestError(`Execution error:\n\n${messageWithReminder}`);
+        throw new CodeApiRequestError(
+          `Execution error:\n\n${messageWithReminder}`
+        );
       }
     },
     {
       name: BashExecutionToolName,
       description: buildBashExecutionToolDescription({
         statefulSessions: params?.statefulSessions,
+        attachedWorkspace: hasWorkspace,
+      }),
+      schema: buildBashExecutionToolSchema({
+        statefulSessions: params?.statefulSessions,
+        attachedWorkspace: hasWorkspace,
       }),
-      schema: buildBashExecutionToolSchema(params ?? undefined),
       responseFormat: Constants.CONTENT_AND_ARTIFACT,
     }
   );

package/src/tools/BashProgrammaticToolCalling.ts

@@ -11,6 +11,7 @@ import {
   buildCodeApiEndpoint,
   CodeApiRequestError,
   getCodeBaseURL,
+  resolveCodeApiAuthHeaders,
   selectRuntimeSessionHint,
 } from './CodeExecutor';
 import {
@@ -32,6 +33,7 @@ import {
   formatCompletedResponse,
 } from './ProgrammaticToolCalling';
 import { logCodeApiDiagnostic } from '@/tools/diagnostics';
+import { resolveAttachedWorkspaceInstanceId } from '@/tools/workspaceIdentity';
 import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
 
@@ -44,6 +46,11 @@ config();
 const DEFAULT_MAX_ROUND_TRIPS = 20;
 const DEFAULT_RUN_TIMEOUT_MS = resolveCodeApiRunTimeoutMs();
 const BASH_LAST_BACKGROUND_PID_GUARD = ': &\nwait "$!"';
+const CODE_API_WORKSPACE_HEADER = 'X-LibreChat-Code-Workspace-ID';
+const ATTACHED_BASH_DATA_DIRECTORY = '"${LIBRECHAT_CODE_DATA_DIR:-/mnt/data}"';
+const ATTACHED_BASH_ARTIFACT_PATH_GUIDANCE =
+  `Use ${ATTACHED_BASH_DATA_DIRECTORY} for injected files and generated artifacts. ` +
+  'The directory is execution-scoped; the selected workspace is the persistent project root.';
 
 /** Bash reserved words that get `_tool` suffix when used as function names */
 const BASH_RESERVED = new Set([
@@ -81,6 +88,11 @@ Each call is a fresh bash shell. Variables and state do NOT persist between call
 You MUST complete your entire workflow in ONE code block.
 DO NOT split work across multiple calls expecting to reuse variables.`;
 
+const ATTACHED_WORKSPACE_WARNING = `ATTACHED WORKSPACE EXECUTION:
+- Commands start in the selected persistent workspace; project file changes persist between calls.
+- Each sandbox run is a fresh process, so shell variables, background processes, and temporary execution data do not persist.
+- Injected files and generated artifacts use \${LIBRECHAT_CODE_DATA_DIR:-/mnt/data}; do not copy them into the project unless the task requires it.`;
+
 const CORE_RULES = `Rules:
 - One call: state does not persist
 - Tools are pre-defined as bash functions—DO NOT redefine them
@@ -107,6 +119,30 @@ Example (Parallel calls):
   echo "SF: $(jq -r . /mnt/data/sf.json)"
   echo "NY: $(jq -r . /mnt/data/ny.json)"`;
 
+const ATTACHED_CORE_RULES = `Rules:
+- One call: process state does not persist; project files do
+- Tools are pre-defined as bash functions—DO NOT redefine them
+- Each tool function accepts a JSON string argument
+- Resolve tool calls into variables before changing project files; do not redirect a tool call directly into the project
+- Set data_dir=${ATTACHED_BASH_DATA_DIRECTORY}; save generated artifacts there, and write durable project files relative to the working directory
+- Tool stdout is normalized to one compact JSON value when possible; parse saved stdout once, then use fromjson? // . only for JSON-string fields
+- Only echo/printf output returns to the model
+- ${ATTACHED_BASH_ARTIFACT_PATH_GUIDANCE}
+- ${BASH_SHELL_GUIDANCE}
+- timeout caps one sandbox run/replay iteration, not the total multi-round-trip workflow`;
+
+const ATTACHED_EXAMPLES = `Example (Complete workflow in one call):
+  data=$(query_database '{"sql": "SELECT * FROM users"}')
+  echo "$data" | jq '.[] | .name'
+
+Example (Parallel calls):
+  data_dir=${ATTACHED_BASH_DATA_DIRECTORY}
+  { sf=$(web_search '{"query": "SF weather"}'); printf '%s\n' "$sf" > "$data_dir/sf.json"; } &
+  { ny=$(web_search '{"query": "NY weather"}'); printf '%s\n' "$ny" > "$data_dir/ny.json"; } &
+  wait
+  echo "SF: $(jq -r . "$data_dir/sf.json")"
+  echo "NY: $(jq -r . "$data_dir/ny.json")"`;
+
 const CODE_PARAM_DESCRIPTION = `Bash code that calls tools programmatically. Tools are available as bash functions.
 
 ${STATELESS_WARNING}
@@ -175,7 +211,7 @@ export const BashProgrammaticToolCallingDefinition = {
   schema: BashProgrammaticToolCallingSchema,
 } as const;
 
-function prepareBashProgrammaticCode(code: string): string {
+export function prepareBashProgrammaticCode(code: string): string {
   /* The Code API's generated Bash wrapper reads `$!` after user code. A user
    * `set -u` makes that expansion fail when no background process has run.
    * Seed and reap a no-op job before user code so strict mode remains active
@@ -326,7 +362,42 @@ export function createBashProgrammaticToolCallingTool(
   const maxRunTimeoutMs = resolveCodeApiRunTimeoutMs(initParams.runTimeoutMs);
   const proxy = initParams.proxy ?? process.env.PROXY;
   const debug = initParams.debug ?? process.env.BASH_PTC_DEBUG === 'true';
+  const workspaceId = initParams.workspaceId?.trim();
+  const hasWorkspace = workspaceId != null && workspaceId !== '';
+  if (
+    hasWorkspace &&
+    !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(workspaceId)
+  ) {
+    throw new Error('Invalid attached workspace identifier');
+  }
+  const workspaceInstanceId = resolveAttachedWorkspaceInstanceId(
+    initParams.workspaceInstanceId,
+    hasWorkspace
+  );
+  const requestAuthHeaders: t.CodeApiAuthHeaders = hasWorkspace
+    ? async (): Promise<t.CodeApiAuthHeaderMap> => ({
+      ...(await resolveCodeApiAuthHeaders(initParams.authHeaders)),
+      [CODE_API_WORKSPACE_HEADER]: workspaceId,
+    })
+    : (initParams.authHeaders ?? {});
   const EXEC_ENDPOINT = buildCodeApiEndpoint(baseUrl, 'exec/programmatic');
+  const description = hasWorkspace
+    ? BashProgrammaticToolCallingDescription.replace(
+      STATELESS_WARNING,
+      ATTACHED_WORKSPACE_WARNING
+    )
+      .replace(CORE_RULES, ATTACHED_CORE_RULES)
+      .replace(EXAMPLES, ATTACHED_EXAMPLES)
+    : BashProgrammaticToolCallingDescription;
+  const schema = createBashProgrammaticToolCallingSchema(maxRunTimeoutMs);
+  if (hasWorkspace) {
+    schema.properties.code.description = CODE_PARAM_DESCRIPTION.replace(
+      STATELESS_WARNING,
+      ATTACHED_WORKSPACE_WARNING
+    )
+      .replace(CORE_RULES, ATTACHED_CORE_RULES)
+      .replace(EXAMPLES, ATTACHED_EXAMPLES);
+  }
 
   return tool(
     async (rawParams, config) => {
@@ -449,7 +520,7 @@ export function createBashProgrammaticToolCallingTool(
 
         /* Raw `code`, not `preparedCode`: the `$!` guard exists for the
          * programmatic replay wrapper, which plain `/exec` never applies. */
-        if (needsNoTools) {
+        if (needsNoTools && !hasWorkspace) {
           return await runPlainExecution({
             baseUrl,
             lang: 'bash',
@@ -459,7 +530,7 @@ export function createBashProgrammaticToolCallingTool(
             files,
             runtimeSessionHint,
             proxy,
-            authHeaders: initParams.authHeaders,
+            authHeaders: requestAuthHeaders,
             executionProfile: initParams.executionProfile,
           });
         }
@@ -472,14 +543,18 @@ export function createBashProgrammaticToolCallingTool(
             tools: effectiveTools,
             session_id,
             timeout,
+            ...(workspaceInstanceId != null && workspaceInstanceId !== ''
+              ? { workspace_instance_id: workspaceInstanceId }
+              : {}),
             ...(files && files.length > 0 ? { files } : {}),
             ...(runtimeSessionHint != null
               ? { runtime_session_hint: runtimeSessionHint }
               : {}),
           },
           proxy,
-          initParams.authHeaders,
-          initParams.executionProfile
+          requestAuthHeaders,
+          initParams.executionProfile,
+          config.signal
         );
 
         // ====================================================================
@@ -519,8 +594,9 @@ export function createBashProgrammaticToolCallingTool(
               tool_results: toolResults,
             },
             proxy,
-            initParams.authHeaders,
-            initParams.executionProfile
+            requestAuthHeaders,
+            initParams.executionProfile,
+            config.signal
           );
         }
 
@@ -529,7 +605,11 @@ export function createBashProgrammaticToolCallingTool(
         // ====================================================================
 
         if (response.status === 'completed') {
-          return formatCompletedResponse(response, code);
+          return formatCompletedResponse(
+            response,
+            code,
+            hasWorkspace ? 'execution' : 'session'
+          );
         }
 
         if (response.status === 'error') {
@@ -551,8 +631,8 @@ export function createBashProgrammaticToolCallingTool(
     },
     {
       name: Constants.BASH_PROGRAMMATIC_TOOL_CALLING,
-      description: BashProgrammaticToolCallingDescription,
-      schema: createBashProgrammaticToolCallingSchema(maxRunTimeoutMs),
+      description,
+      schema,
       responseFormat: Constants.CONTENT_AND_ARTIFACT,
     }
   );

package/src/tools/CodeExecutor.ts

@@ -58,11 +58,15 @@ export const TMP_SCRATCH_OUTPUT_REMINDER =
 export const FAILED_EXECUTION_FILE_REMINDER =
   'Note: any files written during this failed call were not registered for later calls; fix the error and rerun before relying on them.';
 
-export function appendTmpScratchReminder(output: string, code: string): string {
+export function appendTmpScratchReminder(
+  output: string,
+  code: string,
+  reminder = TMP_SCRATCH_OUTPUT_REMINDER
+): string {
   if (!TMP_PATH_PATTERN.test(code)) {
     return output;
   }
-  return `${output.trimEnd()}\n${TMP_SCRATCH_OUTPUT_REMINDER}\n`;
+  return `${output.trimEnd()}\n${reminder}\n`;
 }
 
 export function appendFailedExecutionFileReminder(
@@ -668,6 +672,10 @@ function createCodeExecutionTool(
           artifactDelivery
         );
         const hasFiles = result.files != null && result.files.length > 0;
+        const deletionEcho =
+          result.deleted_files != null
+            ? { deleted_files: result.deleted_files }
+            : {};
         /* Echo the durable runtime session (stateful backends only) so hosts
          * can surface a "session active / was reset" signal later. Additive:
          * absent on stateless servers. */
@@ -687,6 +695,7 @@ function createCodeExecutionTool(
               ...(artifactDelivery != null
                 ? { artifact_delivery: artifactDelivery }
                 : {}),
+              ...deletionEcho,
               ...runtimeEcho,
             }
             : {
@@ -694,6 +703,7 @@ function createCodeExecutionTool(
               ...(artifactDelivery != null
                 ? { artifact_delivery: artifactDelivery }
                 : {}),
+              ...deletionEcho,
               ...runtimeEcho,
             }) satisfies t.CodeExecutionArtifact,
         ];

package/src/tools/CodeSessionFileSummary.ts

@@ -15,6 +15,8 @@ const IMAGE_FILE_EXTENSIONS = new Set([
 
 const CODE_SESSION_FILE_SUMMARY_PATTERN =
   /^Generated files:\nSession files: \d+ persisted file\(s\) are available in \/mnt\/data, including \d+ image\(s\)\. Use known \/mnt\/data paths directly in later code-tool calls\. The app displays files\/images automatically; do not invent download links or wrap generated images in Markdown\.$/;
+const EXECUTION_ARTIFACT_FILE_SUMMARY_PATTERN =
+  /^Generated files:\nExecution artifacts: \d+ file\(s\), including \d+ image\(s\), were delivered to the app\. They are not retained in the attached project; write durable files to the project root when later commands must reuse them\. The app displays files\/images automatically; do not invent download links or wrap generated images in Markdown\.$/;
 
 function getFileExtension(name: string): string {
   const lastSlash = name.lastIndexOf('/');
@@ -53,7 +55,12 @@ export function stripCodeSessionFileSummary(output: string): string {
   const beforeSummary = output.slice(0, summaryStart);
   if (beforeSummary !== '' && !beforeSummary.endsWith('\n\n')) return output;
   const maybeSummary = output.slice(summaryStart);
-  if (!CODE_SESSION_FILE_SUMMARY_PATTERN.test(maybeSummary)) return output;
+  if (
+    !CODE_SESSION_FILE_SUMMARY_PATTERN.test(maybeSummary) &&
+    !EXECUTION_ARTIFACT_FILE_SUMMARY_PATTERN.test(maybeSummary)
+  ) {
+    return output;
+  }
   return beforeSummary.trimEnd();
 }
 
@@ -78,3 +85,20 @@ export function appendCodeSessionFileSummary(
 
   return `${output.trimEnd()}\n\n${summary}`.trim();
 }
+
+/** Attached-worker artifacts are delivered out of execution-private scratch,
+ * not retained in the selected project or a reusable `/mnt/data` session. */
+export function appendExecutionArtifactFileSummary(
+  output: string,
+  files: t.FileRefs | undefined
+): string {
+  const generatedFiles = files?.filter(isGeneratedFile) ?? [];
+  if (generatedFiles.length === 0) return output.trim();
+  const imageCount = generatedFiles.filter(isImageFile).length;
+  const summary =
+    'Generated files:\n' +
+    `Execution artifacts: ${generatedFiles.length} file(s), including ${imageCount} image(s), were delivered to the app. ` +
+    'They are not retained in the attached project; write durable files to the project root when later commands must reuse them. ' +
+    'The app displays files/images automatically; do not invent download links or wrap generated images in Markdown.';
+  return `${output.trimEnd()}\n\n${summary}`.trim();
+}