@librechat/agents 3.7.21 → 3.8.0

package/dist/types/types/graph.d.ts

@@ -652,6 +652,14 @@ export interface LangfuseConfig {
      */
     additionalHeaders?: Record<string, string>;
     metadata?: Record<string, string | number | boolean | null | undefined>;
+    /**
+     * User identity stamped on every trace this run emits — the agent stream,
+     * titles, activity and reasoning labels, and phases. Hosts set it when the
+     * observability identity differs from `configurable.user_id` (an email or
+     * IdP subject instead of an internal database id); that id remains the
+     * fallback when unset or blank.
+     */
+    userId?: string;
     /**
      * Internal OTLP span attributes to attach to Langfuse observations before
      * export. Intended for collector-side routing/filtering; strip these in the

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

@@ -3,6 +3,7 @@ import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type { MessageContentComplex, RunStepResumeState, ToolErrorData } from './stream';
 import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
+import type { PreparedSubagents } from '@/tools/preparedSubagents';
 import type { RunBreakerScope } from '@/llm/streamLimits';
 import type { HumanInTheLoopConfig } from './hitl';
 import type { LangfuseConfig } from './graph';
@@ -42,6 +43,13 @@ export type EagerEventToolExecutionConfig = {
      * execution with final args.
      */
     excludeToolNames?: string[];
+    /**
+     * Maximum retained early foreground subagent invocations per graph. Defaults
+     * to 4; 0 disables them. Checkpoints, parent tool hooks, background calls and
+     * control-flow graph tools retain normal batch execution. Once a child has
+     * started, a failed/revised model attempt fails instead of automatically retrying.
+     */
+    maxPendingSubagents?: number;
 };
 export type EagerEventToolExecutionOutcome = {
     results: ToolExecuteResult[];
@@ -273,6 +281,8 @@ export type ToolNodeOptions = {
      * controller.
      */
     getRunScope?: () => RunBreakerScope;
+    /** Internal graph-owned prepared invocation registry. */
+    preparedSubagents?: PreparedSubagents;
     /** SDK-owned checkpoint bridge for open run-step lifecycle state. */
     restoreRunStepResumeState?: (state?: RunStepResumeState, config?: RunnableConfig) => void;
     /** SDK-owned checkpoint snapshot for open run-step lifecycle state. */
@@ -439,6 +449,13 @@ export type FileRef = {
     inherited?: true;
 };
 export type FileRefs = FileRef[];
+export type ArtifactDeliveryFailure = {
+    code: 'artifact_delivery_failed';
+    status: 'partial' | 'failed';
+    attempted: number;
+    delivered: number;
+    failed: number;
+};
 export type ExecuteResult = {
     /**
      * Execution session id — the (transient) sandbox run that produced
@@ -449,6 +466,7 @@ export type ExecuteResult = {
     stdout: string;
     stderr: string;
     files?: FileRefs;
+    artifact_delivery?: ArtifactDeliveryFailure;
     /**
      * Durable runtime session id echoed by a stateful Code API backend
      * (hash of tenant+user+hint). Additive; absent on stateless servers.
@@ -1160,6 +1178,13 @@ export type ToolSearchArtifact = {
         total_searched: number;
         pattern: string;
         error?: string;
+        /** Servers that had tools to search, emitted when a server filter matched
+         * nothing so the caller can see what it could have asked for. */
+        available_mcp_servers?: string[];
+        /** Requested servers that matched no registered server. */
+        unmatched_mcp_servers?: string[];
+        /** Requested servers that exist but had no tools left to search. */
+        idle_mcp_servers?: string[];
     };
 };
 /**
@@ -1200,6 +1225,7 @@ export type ProgrammaticExecutionResponse = {
     stdout?: string;
     stderr?: string;
     files?: FileRefs;
+    artifact_delivery?: ArtifactDeliveryFailure;
     /** Durable runtime session echo from a stateful backend (additive). */
     runtime_session_id?: string;
     runtime_status?: 'new' | 'reused';
@@ -1213,6 +1239,7 @@ export type ProgrammaticExecutionArtifact = {
     /** Execution session — see `CodeSessionContext.session_id`. */
     session_id?: string;
     files?: FileRefs;
+    artifact_delivery?: ArtifactDeliveryFailure;
     /** Durable runtime session echo from a stateful backend (additive). */
     runtime_session_id?: string;
     runtime_status?: 'new' | 'reused';
@@ -1267,6 +1294,7 @@ export type CodeExecutionArtifact = {
     /** Execution session — see `CodeSessionContext.session_id`. */
     session_id?: string;
     files?: FileRefs;
+    artifact_delivery?: ArtifactDeliveryFailure;
     /** Durable runtime session echo from a stateful backend (additive). */
     runtime_session_id?: string;
     runtime_status?: 'new' | 'reused';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.7.21",
+  "version": "3.8.0",
   "reova": {
     "enabled": true,
     "endpoint": "https://telemetry.reo.dev/data"

package/src/graphs/Graph.ts

@@ -146,6 +146,7 @@ import {
   findCallback,
   type CallbackEntry,
 } from '@/utils/callbacks';
+import { PreparedSubagents, PreparedSubagentError } from '@/tools/preparedSubagents';
 import { ToolNode as CustomToolNode, toolsCondition } from '@/tools/ToolNode';
 import { shouldTraceToolNodeForLangfuse } from '@/langfuseToolOutputTracing';
 import { createLocalCodingToolBundle } from '@/tools/local/LocalCodingTools';
@@ -898,6 +899,7 @@ export abstract class Graph<
    * Call after a run completes and content has been extracted.
    */
   clearHeavyState(): void {
+    this.preparedSubagents.clear();
     this.config = undefined;
     this.signal = undefined;
     this.callerSignal = undefined;
@@ -1239,6 +1241,8 @@ export abstract class Graph<
     restoreSubagentResumeState(state: SubagentToolNodeResumeState): void;
   }> = new Set();
   private _subagentExecutors = new Set<SubagentExecutor>();
+  readonly preparedSubagents = new PreparedSubagents();
+  protected readonly subagentToolNodes = new Map<string, CustomToolNode<t.BaseGraphState>>();
   public getOrCreateFileCheckpointer(): t.LocalFileCheckpointer | undefined {
     // Return the cached instance unconditionally if one exists. The
     // toolExecution check below decides whether to *create* a new
@@ -1397,16 +1401,16 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
    * paths must not run in that state. */
   protected resolveTrippedBreakerReason(
     breakerSignal: AbortSignal = this.breakerAbort.signal
-  ): StreamLimitExceededError | undefined {
+  ): StreamLimitExceededError | PreparedSubagentError | undefined {
     if (
       breakerSignal.aborted &&
-      breakerSignal.reason instanceof StreamLimitExceededError
+      (breakerSignal.reason instanceof StreamLimitExceededError || breakerSignal.reason instanceof PreparedSubagentError)
     ) {
       return breakerSignal.reason;
     }
     if (
       this.signal?.aborted === true &&
-      this.signal.reason instanceof StreamLimitExceededError
+      (this.signal.reason instanceof StreamLimitExceededError || this.signal.reason instanceof PreparedSubagentError)
     ) {
       return this.signal.reason;
     }
@@ -1581,6 +1585,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
   /* Init */
 
   resetValues(keepContent?: boolean, checkpointScope?: string): void {
+    this.preparedSubagents.clear();
     this.resetSubagentCheckpointThreadIds();
     this.messages = [];
     this.hasRestoredCheckpointMessages = false;
@@ -2717,6 +2722,49 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
 
   /* Graph */
 
+  canPrestartSubagents(agentContext?: AgentContext): boolean {
+    if (
+      this.eagerEventToolExecution?.enabled !== true ||
+      (this.eagerEventToolExecution.maxPendingSubagents ?? 4) <= 0 ||
+      this.compileOptions?.checkpointer != null ||
+      this.humanInTheLoop?.enabled === true ||
+      (this.interruptingToolNames?.length ?? 0) > 0 ||
+      agentContext == null ||
+      !this.subagentToolNodes.has(agentContext.agentId)
+    ) {
+      return false;
+    }
+    const graphTools = agentContext.graphTools as t.GenericTool[] | undefined;
+    return (
+      graphTools?.length === 1 &&
+      graphTools[0].name === Constants.SUBAGENT &&
+      SUBAGENT_REPLAY_CONTROLLER in graphTools[0]
+    );
+  }
+
+  prestartSubagent(
+    call: ToolCall,
+    attempt: string,
+    agentContext?: AgentContext
+  ): void {
+    const config = this.preparedSubagents.getConfig(attempt);
+    if (
+      !this.canPrestartSubagents(agentContext) ||
+      config == null ||
+      agentContext == null
+    ) {
+      return;
+    }
+    this.subagentToolNodes
+      .get(agentContext.agentId)
+      ?.prestartSubagent(
+        call,
+        attempt,
+        config,
+        this.eagerEventToolExecution?.maxPendingSubagents ?? 4
+      );
+  }
+
   initializeTools({
     currentTools,
     currentToolMap,
@@ -2791,6 +2839,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
         hookRegistry: this.hookRegistry,
         humanInTheLoop: this.humanInTheLoop,
         eagerEventToolExecution: this.eagerEventToolExecution,
+        preparedSubagents: this.preparedSubagents,
         codeSessionToolNames: this.codeSessionToolNames,
         eagerEventToolExecutions: this.eagerEventToolExecutions,
         eagerEventToolUsageCount: this.getEagerEventToolUsageCount(
@@ -2816,6 +2865,9 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           StandardGraph.handleToolCallErrorStatic(this, data, metadata),
       });
       this.registerCompiledToolNode(node);
+      if (agentContext != null) {
+        this.subagentToolNodes.set(agentContext.agentId, node);
+      }
       return node;
     }
 
@@ -4092,7 +4144,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
          * succeeding fallback would resolve a run the public contract says
          * must reject. Rethrow before any recovery path.
          */
-        if (primaryError instanceof StreamLimitExceededError) {
+        if (
+          primaryError instanceof StreamLimitExceededError ||
+          primaryError instanceof PreparedSubagentError
+        ) {
           /** Tripped before rethrowing so parallel agent nodes' in-flight
            * model calls and subagents stop while the rejection propagates. */
           attemptBreaker.abort(primaryError);
@@ -4342,7 +4397,10 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
               })
           );
         } catch (fallbackError) {
-          if (fallbackError instanceof StreamLimitExceededError) {
+          if (
+            fallbackError instanceof StreamLimitExceededError ||
+            fallbackError instanceof PreparedSubagentError
+          ) {
             /** Same treatment as the primary path: a fallback stream that
              * trips the breaker must stop parallel agent nodes' model calls
              * and subagents before the rejection propagates. */

package/src/langfuse.ts

@@ -895,6 +895,18 @@ function mergeLangfuseTags(
   return merged.length > 0 ? [...new Set(merged)] : undefined;
 }
 
+/**
+ * The trace's user identity: the host-configured `langfuse.userId` when
+ * present, else the caller's (normally `configurable.user_id`).
+ */
+export function resolveLangfuseTraceUserId(
+  langfuse: t.LangfuseConfig | undefined,
+  userId: string | undefined
+): string | undefined {
+  const configured = langfuse?.userId?.trim();
+  return isPresent(configured) ? configured : userId;
+}
+
 export function getLangfuseTraceName(
   traceMetadata?: LangfuseTraceMetadata,
   fallback: string = 'LibreChat Agent'
@@ -942,7 +954,7 @@ export function createLangfuseHandler({
     return undefined;
   }
   return new ScopedLangfuseCallbackHandler({
-    userId,
+    userId: resolveLangfuseTraceUserId(langfuse, userId),
     sessionId,
     traceMetadata:
       inheritTraceIdentity === true
@@ -972,7 +984,10 @@ function createPropagateAttributeParams({
   inheritTraceIdentity,
 }: LangfuseAttributeParams): PropagateAttributesParams {
   return {
-    userId: inheritTraceIdentity === true ? undefined : userId,
+    userId:
+      inheritTraceIdentity === true
+        ? undefined
+        : resolveLangfuseTraceUserId(langfuse, userId),
     sessionId: inheritTraceIdentity === true ? undefined : sessionId,
     traceName: inheritTraceIdentity === true ? undefined : traceName,
     tags: mergeLangfuseTags(tags, langfuse?.tags),

package/src/llm/invoke.ts

@@ -51,6 +51,7 @@ import {
 } from '@/llm/providers';
 import { ChatModelStreamHandler, dispatchesChatModelStream } from '@/stream';
 import { Constants, ContentTypes, GraphEvents, Providers } from '@/common';
+import { PreparedSubagentError } from '@/tools/preparedSubagents';
 import { assertNotTruncatedToolCall } from '@/llm/truncation';
 import { resolveClientOptionsModel } from '@/llm/request';
 import { safeDispatchCustomEvent } from '@/utils/events';
@@ -702,9 +703,8 @@ export async function attemptInvoke(
     },
   };
   const request = resolveAttemptRequest(params, providerStampedConfig);
-  const configuredModel = providerStampedConfig.metadata?.[
-    Constants.INVOKED_MODEL
-  ];
+  const configuredModel =
+    providerStampedConfig.metadata?.[Constants.INVOKED_MODEL];
   const modelId =
     request.modelId ??
     (typeof configuredModel === 'string' ? configuredModel : undefined);
@@ -745,8 +745,14 @@ export async function attemptInvoke(
   if (leaseTarget != null && generationKey != null) {
     registerActiveStreamLimitGeneration(leaseTarget, generationKey);
   }
+  const prepared =
+    params.context?.eagerEventToolExecution?.enabled === true
+      ? params.context.preparedSubagents
+      : undefined;
+  const preparedAttempt = resolveGenerationKey(stampedConfig.metadata);
+  prepared?.begin(preparedAttempt, stampedConfig);
   try {
-    return await attemptInvokeBody(
+    const result = await attemptInvokeBody(
       {
         request,
         context: params.context,
@@ -755,7 +761,27 @@ export async function attemptInvoke(
       },
       stampedConfig
     );
+    const calls =
+      result.messages?.flatMap((message) =>
+        'tool_calls' in message
+          ? ((message.tool_calls as ToolCall[] | undefined) ?? [])
+          : []
+      ) ?? [];
+    prepared?.finish(preparedAttempt, calls);
+    return result;
+  } catch (error) {
+    prepared?.finish(preparedAttempt, undefined, error);
+    throw error;
   } finally {
+    const chunks = params.context?.eagerEventToolCallChunks;
+    if (prepared != null && chunks != null) {
+      const prefix = `prepared:${preparedAttempt}\u0000`;
+      for (const key of chunks.keys()) {
+        if (key.startsWith(prefix)) {
+          chunks.delete(key);
+        }
+      }
+    }
     if (leaseTarget != null && generationKey != null) {
       releaseStreamLimitGeneration(leaseTarget, generationKey);
     }
@@ -1053,7 +1079,7 @@ async function attemptInvokeBody(
       const signal = config.signal;
       if (
         signal?.aborted === true &&
-        signal.reason instanceof StreamLimitExceededError
+        (signal.reason instanceof StreamLimitExceededError || signal.reason instanceof PreparedSubagentError)
       ) {
         throw signal.reason;
       }
@@ -1290,6 +1316,7 @@ async function attemptInvokeBody(
       const ownAbort =
         restartRoute === 'aborted' &&
         !(error instanceof StreamLimitExceededError) &&
+        !(error instanceof PreparedSubagentError) &&
         config.signal?.aborted !== true;
       if (!ownAbort) {
         throw error;
@@ -1639,7 +1666,7 @@ export async function tryFallbackProviders({
        * a run that must reject. Check before every fallback invocation. */
       if (
         config?.signal?.aborted === true &&
-        config.signal.reason instanceof StreamLimitExceededError
+        (config.signal.reason instanceof StreamLimitExceededError || config.signal.reason instanceof PreparedSubagentError)
       ) {
         throw config.signal.reason;
       }
@@ -1673,7 +1700,7 @@ export async function tryFallbackProviders({
        * provider failure. Continuing would try the remaining fallbacks and a
        * succeeding one would resolve a run that must reject.
        */
-      if (e instanceof StreamLimitExceededError) {
+      if (e instanceof StreamLimitExceededError || e instanceof PreparedSubagentError) {
         throw e;
       }
       /** A parallel sibling's trip aborts this branch's composed signal, and
@@ -1682,7 +1709,7 @@ export async function tryFallbackProviders({
        * abort. Rethrow the breaker's own reason instead. */
       if (
         config?.signal?.aborted === true &&
-        config.signal.reason instanceof StreamLimitExceededError
+        (config.signal.reason instanceof StreamLimitExceededError || config.signal.reason instanceof PreparedSubagentError)
       ) {
         throw config.signal.reason;
       }

package/src/stream.ts

@@ -15,6 +15,7 @@ import {
   requiresStreamLimitAccounting,
   StreamLimitExceededError,
   STREAM_LIMIT_EPOCH_KEY,
+  resolveGenerationKey,
 } from '@/llm/streamLimits';
 import {
   getStreamedToolCallSeal,
@@ -56,6 +57,7 @@ import {
 } from '@/utils/truncation';
 import { resolveToolOutcome, outcomeFieldsFromResult } from '@/tools/intentArg';
 import { TOOL_OUTPUT_REF_PATTERN } from '@/tools/toolOutputReferences';
+import { PreparedSubagentError } from '@/tools/preparedSubagents';
 import { isReasoningContentBlock } from '@/messages/core';
 import { safeDispatchCustomEvent } from '@/utils/events';
 import { composeAbortSignals } from '@/utils/misc';
@@ -1319,6 +1321,65 @@ function startReadyStreamedEagerToolExecutions(args: {
   });
 }
 
+/** Shares provider sealing/parsing with event tools, but never relaxes their batch guard. */
+function startPreparedSubagents(
+  graph: StandardGraph,
+  agentContext: AgentContext | undefined,
+  chunk: Partial<AIMessageChunk>,
+  metadata?: Record<string, unknown>
+): void {
+  const attempt = resolveGenerationKey(metadata);
+  if (
+    (graph as Partial<StandardGraph>).canPrestartSubagents?.(agentContext) !==
+      true ||
+    graph.preparedSubagents.isOpen(attempt) !== true ||
+    graph.hookRegistry?.hasResultAlteringHooks(
+      graph.preparedSubagents.getConfig(attempt)?.configurable?.run_id
+    ) === true
+  ) {
+    return;
+  }
+  let calls: ToolCall[];
+  if (hasOnArrivalToolCallSeal(chunk) && (chunk.tool_calls?.length ?? 0) > 0) {
+    calls = chunk.tool_calls!;
+  } else {
+    const seal = getStreamedToolCallSeal(chunk.response_metadata);
+    const allowSequentialSeal =
+      canPrestartSequentialStreamedToolChunks(agentContext) ||
+      streamedToolCallAdapterAllowsSequentialSeal(chunk.response_metadata);
+    if (!hasExplicitStreamedToolCallSeals(chunk) && !allowSequentialSeal) {
+      return;
+    }
+    const stepKey = `prepared:${attempt}`;
+    recordEagerToolCallChunks({
+      graph,
+      stepKey,
+      toolCallChunks: chunk.tool_call_chunks ?? [],
+      seal,
+    });
+    calls = getStreamedReadyToolCalls({
+      graph,
+      stepKey,
+      toolCallChunks: chunk.tool_call_chunks,
+      seal,
+      allowSequentialSeal,
+    });
+    pruneEagerToolCallChunkStates({
+      graph,
+      stepKey,
+      toolCallIds: new Set(calls.map((call) => call.id!)),
+    });
+  }
+  for (const call of calls) {
+    if (
+      call.name === Constants.SUBAGENT &&
+      !hasToolOutputReference(call.args)
+    ) {
+      graph.prestartSubagent(call, attempt, agentContext);
+    }
+  }
+}
+
 export function getChunkContent({
   chunk,
   provider,
@@ -1597,7 +1658,7 @@ export class ChatModelStreamHandler implements t.EventHandler {
       if (
         eventBreaker != null &&
         eventBreaker.signal.aborted &&
-        eventBreaker.signal.reason instanceof StreamLimitExceededError
+        (eventBreaker.signal.reason instanceof StreamLimitExceededError || eventBreaker.signal.reason instanceof PreparedSubagentError)
       ) {
         throw eventBreaker.signal.reason;
       }
@@ -1743,6 +1804,9 @@ export class ChatModelStreamHandler implements t.EventHandler {
         return;
       }
       throwIfRunBreakerTripped();
+      if (hasOnArrivalToolCallSeal(chunk)) {
+        startPreparedSubagents(graph, agentContext, chunk, metadata);
+      }
       if (hasFinalToolCallSignal(chunk)) {
         startEagerToolExecutions({
           graph,
@@ -1839,6 +1903,11 @@ export class ChatModelStreamHandler implements t.EventHandler {
       }
     }
 
+    if (!hasOnArrivalToolCallSeal(chunk) && !runScopeInvalidated()) {
+      throwIfRunBreakerTripped();
+      startPreparedSubagents(graph, agentContext, chunk, metadata);
+    }
+
     if (isEmptyContent) {
       return;
     }

package/src/tools/ArtifactDelivery.ts

@@ -0,0 +1,50 @@
+import type { ArtifactDeliveryFailure } from '@/types';
+
+export const ARTIFACT_DELIVERY_WARNING_PREFIX = 'Artifact delivery warning:';
+
+function isNonNegativeInteger(value: unknown): value is number {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 0;
+}
+
+export function normalizeArtifactDeliveryFailure(
+  value: unknown
+): ArtifactDeliveryFailure | undefined {
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+    return undefined;
+  }
+
+  const candidate = value as Partial<ArtifactDeliveryFailure>;
+  if (
+    candidate.code !== 'artifact_delivery_failed' ||
+    (candidate.status !== 'partial' && candidate.status !== 'failed') ||
+    !isNonNegativeInteger(candidate.attempted) ||
+    !isNonNegativeInteger(candidate.delivered) ||
+    !isNonNegativeInteger(candidate.failed) ||
+    candidate.failed === 0 ||
+    candidate.attempted !== candidate.delivered + candidate.failed ||
+    (candidate.status === 'failed' && candidate.delivered !== 0) ||
+    (candidate.status === 'partial' && candidate.delivered === 0)
+  ) {
+    return undefined;
+  }
+
+  return {
+    code: candidate.code,
+    status: candidate.status,
+    attempted: candidate.attempted,
+    delivered: candidate.delivered,
+    failed: candidate.failed,
+  };
+}
+
+export function appendArtifactDeliveryWarning(
+  output: string,
+  delivery: ArtifactDeliveryFailure | undefined
+): string {
+  if (delivery == null) {
+    return output;
+  }
+
+  const warning = `${ARTIFACT_DELIVERY_WARNING_PREFIX} ${delivery.failed} of ${delivery.attempted} generated files could not be persisted. Do not assume missing files are available to later calls or downloadable. The code itself ran; do not rerun automatically because it may have had side effects.`;
+  return `${output.trimEnd()}\n${warning}\n`;
+}

package/src/tools/BashExecutor.ts

@@ -18,6 +18,10 @@ import {
   resolveCodeApiAuthHeaders,
   selectRuntimeSessionHint,
 } from './CodeExecutor';
+import {
+  appendArtifactDeliveryWarning,
+  normalizeArtifactDeliveryFailure,
+} from '@/tools/ArtifactDelivery';
 import { logCodeApiDiagnostic } from '@/tools/diagnostics';
 import { resolveFetchProxyAgent } from '@/utils/proxy';
 import { INTENT_PROPERTY } from '@/tools/intentArg';
@@ -300,6 +304,13 @@ function createBashExecutionTool(
           formattedOutput,
           command
         );
+        const artifactDelivery = normalizeArtifactDeliveryFailure(
+          result.artifact_delivery
+        );
+        const outputWithDeliveryWarning = appendArtifactDeliveryWarning(
+          outputWithReminder,
+          artifactDelivery
+        );
         const hasFiles = result.files != null && result.files.length > 0;
         const runtimeEcho =
           result.runtime_session_id != null
@@ -309,15 +320,21 @@ function createBashExecutionTool(
             }
             : {};
         return [
-          appendCodeSessionFileSummary(outputWithReminder, result.files),
+          appendCodeSessionFileSummary(outputWithDeliveryWarning, result.files),
           (hasFiles
             ? {
               session_id: result.session_id,
               files: result.files,
+              ...(artifactDelivery != null
+                ? { artifact_delivery: artifactDelivery }
+                : {}),
               ...runtimeEcho,
             }
             : {
               session_id: result.session_id,
+              ...(artifactDelivery != null
+                ? { artifact_delivery: artifactDelivery }
+                : {}),
               ...runtimeEcho,
             }) satisfies t.CodeExecutionArtifact,
         ];

package/src/tools/CodeExecutor.ts

@@ -5,6 +5,10 @@ import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import type { Readable } from 'node:stream';
 import type { CodeApiMethod } from '@/tools/diagnostics';
 import type * as t from '@/types';
+import {
+  appendArtifactDeliveryWarning,
+  normalizeArtifactDeliveryFailure,
+} from '@/tools/ArtifactDelivery';
 import {
   describeCodeApiError,
   logCodeApiDiagnostic,
@@ -564,6 +568,13 @@ function createCodeExecutionTool(
           formattedOutput,
           code
         );
+        const artifactDelivery = normalizeArtifactDeliveryFailure(
+          result.artifact_delivery
+        );
+        const outputWithDeliveryWarning = appendArtifactDeliveryWarning(
+          outputWithReminder,
+          artifactDelivery
+        );
         const hasFiles = result.files != null && result.files.length > 0;
         /* Echo the durable runtime session (stateful backends only) so hosts
          * can surface a "session active / was reset" signal later. Additive:
@@ -576,15 +587,21 @@ function createCodeExecutionTool(
             }
             : {};
         return [
-          appendCodeSessionFileSummary(outputWithReminder, result.files),
+          appendCodeSessionFileSummary(outputWithDeliveryWarning, result.files),
           (hasFiles
             ? {
               session_id: result.session_id,
               files: result.files,
+              ...(artifactDelivery != null
+                ? { artifact_delivery: artifactDelivery }
+                : {}),
               ...runtimeEcho,
             }
             : {
               session_id: result.session_id,
+              ...(artifactDelivery != null
+                ? { artifact_delivery: artifactDelivery }
+                : {}),
               ...runtimeEcho,
             }) satisfies t.CodeExecutionArtifact,
         ];