@librechat/agents 3.8.1 → 3.8.3

package/src/hitl/approvalReview.ts

@@ -0,0 +1,209 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type {
+  ToolApprovalInterruptPayload,
+  ToolApprovalRequest,
+  ToolApprovalReviewConfig,
+} from '@/types/hitl';
+import { stableStringify } from '@/tools/eagerEventExecution';
+import { isToolApprovalInterrupt } from '@/types/hitl';
+
+/**
+ * Private resume-only config entry populated from the checkpointed interrupt.
+ * Hosts must never need to construct or inspect this value.
+ */
+export const TOOL_APPROVAL_REVIEW_CONFIG_KEY =
+  '__librechat_tool_approval_review';
+
+export interface ToolApprovalReviewEvidence {
+  interruptId: string;
+  payload: ToolApprovalInterruptPayload;
+  owner?: string;
+}
+
+export interface ReviewedToolApproval {
+  request: ToolApprovalRequest;
+  reviewConfig: ToolApprovalReviewConfig;
+}
+
+const APPROVAL_DECISIONS = new Set(['approve', 'reject', 'edit', 'respond']);
+
+/** Detach approval payloads from host- or transport-owned object graphs. */
+export function cloneToolApprovalInterruptPayload<T>(payload: T): T {
+  return isToolApprovalInterrupt(payload) ? structuredClone(payload) : payload;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function hasValidApprovalShape(payload: ToolApprovalInterruptPayload): boolean {
+  if (
+    !Array.isArray(payload.action_requests) ||
+    !Array.isArray(payload.review_configs) ||
+    payload.action_requests.length !== payload.review_configs.length
+  ) {
+    return false;
+  }
+
+  const toolCallIds = new Set<string>();
+  return payload.action_requests.every((request, index) => {
+    const reviewConfig = payload.review_configs[index];
+    if (!isRecord(request) || !isRecord(reviewConfig)) {
+      return false;
+    }
+    const toolCallId = request.tool_call_id;
+    const toolName = request.name;
+    const allowedDecisions = reviewConfig.allowed_decisions;
+    if (
+      typeof toolCallId !== 'string' ||
+      toolCallId.length === 0 ||
+      toolCallIds.has(toolCallId) ||
+      typeof toolName !== 'string' ||
+      toolName.length === 0 ||
+      !isRecord(request.arguments) ||
+      (request.description != null &&
+        typeof request.description !== 'string') ||
+      reviewConfig.tool_call_id !== toolCallId ||
+      reviewConfig.action_name !== toolName ||
+      !Array.isArray(allowedDecisions) ||
+      !allowedDecisions.every(
+        (decision) =>
+          typeof decision === 'string' && APPROVAL_DECISIONS.has(decision)
+      )
+    ) {
+      return false;
+    }
+    toolCallIds.add(toolCallId);
+    return true;
+  });
+}
+
+/** Build trusted review evidence from the interrupt restored by `Run`. */
+export function createToolApprovalReviewEvidence(
+  interruptId: string | undefined,
+  payload: unknown,
+  owner?: string
+): ToolApprovalReviewEvidence | undefined {
+  if (
+    typeof interruptId !== 'string' ||
+    interruptId.length === 0 ||
+    !isToolApprovalInterrupt(payload) ||
+    !hasValidApprovalShape(payload)
+  ) {
+    return undefined;
+  }
+  return {
+    interruptId,
+    payload: cloneToolApprovalInterruptPayload(payload),
+    ...(owner == null ? {} : { owner }),
+  };
+}
+
+/** Read only well-shaped evidence from a ToolNode's runnable config. */
+export function getToolApprovalReviewEvidence(
+  config: RunnableConfig,
+  owner?: string
+): ToolApprovalReviewEvidence | undefined {
+  const candidate = config.configurable?.[TOOL_APPROVAL_REVIEW_CONFIG_KEY];
+  if (candidate == null || typeof candidate !== 'object') {
+    return undefined;
+  }
+  const {
+    interruptId,
+    payload,
+    owner: evidenceOwner,
+  } = candidate as {
+    interruptId?: unknown;
+    payload?: unknown;
+    owner?: unknown;
+  };
+  if (
+    evidenceOwner != null &&
+    (typeof evidenceOwner !== 'string' ||
+      (owner != null && owner !== evidenceOwner))
+  ) {
+    return undefined;
+  }
+  return createToolApprovalReviewEvidence(
+    typeof interruptId === 'string' ? interruptId : undefined,
+    payload,
+    typeof evidenceOwner === 'string' ? evidenceOwner : undefined
+  );
+}
+
+export function getReviewedToolApproval(
+  payload: ToolApprovalInterruptPayload | undefined,
+  toolCallId: string | undefined
+): ReviewedToolApproval | undefined {
+  if (payload == null || toolCallId == null || toolCallId === '') {
+    return undefined;
+  }
+  const request = payload.action_requests.find(
+    (candidate) => candidate.tool_call_id === toolCallId
+  );
+  const reviewConfig = payload.review_configs.find(
+    (candidate) => candidate.tool_call_id === toolCallId
+  );
+  if (request == null || reviewConfig == null) {
+    return undefined;
+  }
+  return { request, reviewConfig };
+}
+
+function decisionsEqual(
+  left: ReadonlyArray<string>,
+  right: ReadonlyArray<string>
+): boolean {
+  if (left.length !== right.length) {
+    return false;
+  }
+  const sortedLeft = [...left].sort();
+  const sortedRight = [...right].sort();
+  return sortedLeft.every((value, index) => value === sortedRight[index]);
+}
+
+/**
+ * Bind a resume decision to the exact proposal the reviewer saw. Description
+ * text is deliberately excluded: it explains policy but cannot change the
+ * side effect. Tool identity, normalized arguments and available decisions
+ * are execution-authoritative.
+ */
+export function toolApprovalProposalMatches(
+  current: ReviewedToolApproval,
+  reviewed: ReviewedToolApproval
+): boolean {
+  return (
+    current.request.tool_call_id === reviewed.request.tool_call_id &&
+    current.request.name === reviewed.request.name &&
+    current.reviewConfig.tool_call_id === reviewed.reviewConfig.tool_call_id &&
+    current.reviewConfig.action_name === reviewed.reviewConfig.action_name &&
+    stableStringify(current.request.arguments) ===
+      stableStringify(reviewed.request.arguments) &&
+    decisionsEqual(
+      current.reviewConfig.allowed_decisions,
+      reviewed.reviewConfig.allowed_decisions
+    )
+  );
+}
+
+/** Preserve batch order as part of the decision-to-request binding. */
+export function toolApprovalPayloadMatches(
+  current: ToolApprovalInterruptPayload,
+  reviewed: ToolApprovalInterruptPayload
+): boolean {
+  if (
+    current.action_requests.length !== reviewed.action_requests.length ||
+    current.review_configs.length !== reviewed.review_configs.length
+  ) {
+    return false;
+  }
+  return current.action_requests.every((request, index) => {
+    const currentReviewConfig = current.review_configs[index];
+    const reviewedRequest = reviewed.action_requests[index];
+    const reviewedReviewConfig = reviewed.review_configs[index];
+    return toolApprovalProposalMatches(
+      { request, reviewConfig: currentReviewConfig },
+      { request: reviewedRequest, reviewConfig: reviewedReviewConfig }
+    );
+  });
+}

package/src/hooks/index.ts

@@ -116,3 +116,6 @@ export type {
   PostCompactHookOutput,
 } from './types';
 export type { ExecuteHooksOptions } from './executeHooks';
+
+/** Hosts may opt into stable generation scopes across every ToolNode interrupt type. */
+export const TOOL_APPROVAL_EXECUTION_SCOPE_CAPABLE = true;

package/src/hooks/types.ts

@@ -28,6 +28,12 @@ export const HOOK_EVENTS = [
   'PostCompact',
 ] as const;
 
+/**
+ * Host-owned generation identity, stable across every resume and rebuilt Run.
+ * A new generation must use a new scope, even when it reuses a thread or response
+ * id. Explicit scoping keeps LangGraph task namespaces out of approval owners;
+ * the executing agent id remains part of the owner and cannot change on resume.
+ */
 export const TOOL_APPROVAL_EXECUTION_SCOPE_CONFIG_KEY =
   '__librechat_tool_approval_execution_scope';
 

package/src/run.ts

@@ -22,7 +22,6 @@ import type {
 } from '@langchain/core/messages';
 import type { StringPromptValue } from '@langchain/core/prompt_values';
 import type { RunnableConfig } from '@langchain/core/runnables';
-import { isFadingTier } from '@/messages/fading';
 import type { AggregatedHookResult, HookRegistry } from '@/hooks';
 import type { MultiAgentGraph } from '@/graphs/MultiAgentGraph';
 import type { StandardGraph } from '@/graphs/Graph';
@@ -40,7 +39,6 @@ import {
 } from '@/common';
 import {
   requireValidSubagentResumeManifest,
-  stripSubagentResumeManifest,
   SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY,
   SUBAGENT_RESUME_MANIFEST_CONFIG_KEY,
 } from '@/tools/subagent/SubagentReplay';
@@ -70,6 +68,16 @@ import {
   resolveLangfuseConfig,
   resolveToolOutputTracingConfig,
 } from '@/langfuseConfig';
+import {
+  cloneToolApprovalInterruptPayload,
+  TOOL_APPROVAL_REVIEW_CONFIG_KEY,
+} from '@/hitl/approvalReview';
+import {
+  TOOL_BATCH_REPLAY_KEY,
+  restoreToolReplayConfig,
+  stripToolBatchReplayState,
+  getPublicToolInterruptPayload,
+} from '@/tools/toolBatchReplay';
 import {
   resolveLangfuseDestinationKey,
   resolveLangfuseTraceAnchorParent,
@@ -104,6 +112,7 @@ import { seedRunInitialSessions } from '@/utils/toolSessions';
 import { getTraceIdSeed } from '@/langfuseRuntimeContext';
 import { resolveClientOptionsModel } from '@/llm/request';
 import { createGraph } from '@/graphs/createGraph';
+import { isFadingTier } from '@/messages/fading';
 import { resolveMaxSeals } from '@/llm/preempt';
 import { isBuiltRuntime } from '@/lazyRequire';
 import { initializeModel } from '@/llm/init';
@@ -169,9 +178,7 @@ function materializeStopContinuation(
   return messages;
 }
 
-function advanceCheckpointCursor(
-  config: t.RunStreamConfig
-): t.RunStreamConfig {
+function advanceCheckpointCursor(config: t.RunStreamConfig): t.RunStreamConfig {
   const configurable = { ...config.configurable };
   delete configurable.checkpoint_id;
   delete configurable.checkpoint_map;
@@ -186,9 +193,7 @@ function assertFinalAdmissionSucceeded(result: AggregatedHookResult): void {
     result.errors.length > 0
       ? result.errors.join('; ')
       : 'one or more internal finalizers failed';
-  throw new Error(
-    `StopFinalize terminal admission failed: ${detail}`
-  );
+  throw new Error(`StopFinalize terminal admission failed: ${detail}`);
 }
 
 const CUSTOM_GRAPH_EVENTS = new Set<string>([
@@ -268,9 +273,7 @@ function isLangGraphResumeMapForInterrupt(
 }
 
 function getInterruptHookSessionId(payload: unknown): string | undefined {
-  const publicPayload = stripSubagentResumeManifest(
-    stripRunStepResumeState(payload)
-  );
+  const publicPayload = getPublicToolInterruptPayload(payload);
   if (
     publicPayload == null ||
     typeof publicPayload !== 'object' ||
@@ -423,7 +426,7 @@ function overwriteResumeRunStepState(
   const update = Array.isArray(command.update)
     ? [
       ...command.update.filter(([key]) => key !== 'runStepState'),
-      ['runStepState', overwrite] as [string, unknown],
+        ['runStepState', overwrite] as [string, unknown],
     ]
     : { ...(command.update ?? {}), runStepState: overwrite };
   const resumed = new Command({
@@ -1266,6 +1269,8 @@ export class Run<_T extends t.BaseGraphState> {
       recursionLimit,
       configurable: { ...callerConfig.configurable },
     };
+    delete config.configurable?.[TOOL_APPROVAL_REVIEW_CONFIG_KEY];
+    delete config.configurable?.[TOOL_BATCH_REPLAY_KEY];
     if (!isResume) {
       delete config.configurable?.[SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY];
       delete config.configurable?.[SUBAGENT_RESUME_MANIFEST_CONFIG_KEY];
@@ -1276,6 +1281,10 @@ export class Run<_T extends t.BaseGraphState> {
         config,
         (inputs as Command).update
       );
+      const publicPayload = stripRunStepResumeState(this._interrupt?.payload);
+      if (config.configurable != null) {
+        restoreToolReplayConfig(config.configurable, this._interrupt?.interruptId, publicPayload);
+      }
       if (graph.getStopContinuationExecutionId() === '') {
         graph.startStopContinuationExecution(nanoid());
         overwriteLegacyResumeState = this.hasCheckpointer;
@@ -1514,7 +1523,7 @@ export class Run<_T extends t.BaseGraphState> {
               this._interrupt = {
                 interruptId: first.id ?? '',
                 threadId,
-                payload: first.value,
+                payload: cloneToolApprovalInterruptPayload(first.value),
               };
             }
           }
@@ -1558,7 +1567,8 @@ export class Run<_T extends t.BaseGraphState> {
           stopReason = OUTPUT_TRUNCATED_HALT_REASON;
         }
 
-        const stopMessages = graph.getRunMessages() ?? stateInputs?.messages ?? [];
+        const stopMessages =
+          graph.getRunMessages() ?? stateInputs?.messages ?? [];
         const stopContinuationCount = graph.getStopContinuationCount();
         const continuationBudgetRemaining = Math.max(
           0,
@@ -1881,8 +1891,8 @@ export class Run<_T extends t.BaseGraphState> {
     }
     return {
       ...this._interrupt,
-      payload: stripSubagentResumeManifest(
-        stripRunStepResumeState(this._interrupt.payload)
+      payload: cloneToolApprovalInterruptPayload(
+        getPublicToolInterruptPayload(this._interrupt.payload)
       ),
     } as t.RunInterruptResult<TPayload>;
   }
@@ -2004,16 +2014,20 @@ export class Run<_T extends t.BaseGraphState> {
   ): Promise<t.RunStreamConfig> {
     await this.restoreInterruptFromCheckpoint(callerConfig, resumeUpdate);
     const interrupt = this._interrupt;
-    const resumeManifest = requireValidSubagentResumeManifest(
-      stripRunStepResumeState(interrupt?.payload)
-    );
+    const replayPayload = stripRunStepResumeState(interrupt?.payload);
+    const resumeManifest = requireValidSubagentResumeManifest(replayPayload) ??
+      requireValidSubagentResumeManifest(stripToolBatchReplayState(replayPayload));
     const resumeConfigurable = { ...callerConfig.configurable };
+    delete resumeConfigurable[TOOL_APPROVAL_REVIEW_CONFIG_KEY];
+    delete resumeConfigurable[TOOL_BATCH_REPLAY_KEY];
     delete resumeConfigurable[SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY];
     delete resumeConfigurable[SUBAGENT_RESUME_MANIFEST_CONFIG_KEY];
     resumeConfigurable[SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY] = nanoid();
     if (resumeManifest != null) {
       resumeConfigurable[SUBAGENT_RESUME_MANIFEST_CONFIG_KEY] = resumeManifest;
     }
+    const publicPayload = stripRunStepResumeState(interrupt?.payload);
+    restoreToolReplayConfig(resumeConfigurable, interrupt?.interruptId, publicPayload);
     const manifestConfig = {
       ...callerConfig,
       configurable: resumeConfigurable,
@@ -2130,7 +2144,7 @@ export class Run<_T extends t.BaseGraphState> {
     const threadId = callerConfig.configurable?.thread_id;
     this._interrupt = {
       interruptId: persistedInterrupt.id,
-      payload: persistedInterrupt.value,
+      payload: cloneToolApprovalInterruptPayload(persistedInterrupt.value),
       ...(typeof threadId === 'string' ? { threadId } : {}),
       ...(typeof checkpointId === 'string' ? { checkpointId } : {}),
       ...(typeof checkpointNs === 'string' ? { checkpointNs } : {}),

package/src/tools/BashExecutor.ts

@@ -279,7 +279,7 @@ function createBashExecutionTool(
         };
 
         const proxyAgent = resolveFetchProxyAgent(execEndpoint);
-        if (proxyAgent) {
+        if (proxyAgent != null) {
           fetchOptions.agent = proxyAgent;
         }
         const response = await fetch(execEndpoint, fetchOptions);
@@ -343,7 +343,7 @@ function createBashExecutionTool(
           normalizeCodeApiRequestError(error).message,
           command
         );
-        throw new Error(`Execution error:\n\n${messageWithReminder}`);
+        throw new CodeApiRequestError(`Execution error:\n\n${messageWithReminder}`);
       }
     },
     {

package/src/tools/BashProgrammaticToolCalling.ts

@@ -542,9 +542,11 @@ export function createBashProgrammaticToolCallingTool(
           (error as Error).message,
           code
         );
-        throw new Error(
-          `Bash programmatic execution failed: ${messageWithReminder}`
-        );
+        const message = `Bash programmatic execution failed: ${messageWithReminder}`;
+        if (error instanceof CodeApiRequestError) {
+          throw new CodeApiRequestError(message);
+        }
+        throw new Error(message, { cause: error });
       }
     },
     {

package/src/tools/CodeExecutor.ts

@@ -70,6 +70,7 @@ export function appendFailedExecutionFileReminder(
   code: string
 ): string {
   if (
+    output.includes(CODE_API_CAPABILITY_ERROR_MESSAGE) ||
     !MNT_DATA_PATH_PATTERN.test(code) ||
     output.includes(FAILED_EXECUTION_FILE_REMINDER)
   ) {
@@ -157,10 +158,67 @@ const SAFE_CODE_API_EXECUTION_ERROR_DETAILS: Readonly<
   'stdout length exceeded': 'Execution output exceeded the size limit.',
 };
 
+export const CODE_API_CAPABILITY_ERROR_MESSAGE =
+  'Code execution is not supported by the selected environment.';
+const CODE_API_CAPABILITY_ERROR_GUIDANCE =
+  'This is a permanent capability mismatch. Do not retry this tool in this environment; select a compatible environment or use an available workspace tool.';
+
+const CODE_API_CAPABILITY_LIMITATIONS: Readonly<
+  Partial<Record<string, string>>
+> = {
+  bridge_worker_mismatch:
+    'The selected worker does not support the requested execution capabilities (such as the stateful workspace required by programmatic tool calling).',
+  execution_profile_mismatch:
+    'The selected environment does not provide the requested execution profile.',
+  capability_mismatch:
+    'The selected environment lacks a required execution capability.',
+  unsupported_capability:
+    'The selected environment lacks a required execution capability.',
+  stateful_workspace_unsupported:
+    'The selected worker does not provide a stateful workspace.',
+};
+
+function getCodeApiCapabilityErrorMessage(
+  responseBody: string
+): string | undefined {
+  try {
+    const parsed = JSON.parse(responseBody) as {
+      error?: string;
+      code?: string;
+      message?: string;
+    } | null;
+    const code = parsed?.code ?? parsed?.error;
+    if (typeof code !== 'string') return undefined;
+    const normalizedCode = code.toLowerCase();
+    if (!Object.hasOwn(CODE_API_CAPABILITY_LIMITATIONS, normalizedCode))
+      return undefined;
+    let limitation = CODE_API_CAPABILITY_LIMITATIONS[normalizedCode];
+    if (limitation == null) return undefined;
+    if (
+      normalizedCode === 'bridge_worker_mismatch' &&
+      typeof parsed?.message === 'string' &&
+      /^Bridge worker [A-Za-z0-9._:-]+ does not provide a stateful workspace$/.test(
+        parsed.message
+      )
+    ) {
+      limitation =
+        CODE_API_CAPABILITY_LIMITATIONS.stateful_workspace_unsupported;
+    }
+    return `${CODE_API_CAPABILITY_ERROR_MESSAGE} ${limitation} ${CODE_API_CAPABILITY_ERROR_GUIDANCE}`;
+  } catch {
+    return undefined;
+  }
+}
+
 export class CodeApiRequestError extends Error {
+  readonly retryable: boolean;
+
   constructor(message = CODE_API_UNAVAILABLE_ERROR_MESSAGE) {
     super(message);
     this.name = 'CodeApiRequestError';
+    this.retryable =
+      message.includes(CODE_API_UNAVAILABLE_ERROR_MESSAGE) ||
+      message.includes('Code execution is temporarily rate-limited.');
   }
 }
 
@@ -277,11 +335,7 @@ type CodeApiErrorResponse = {
   body?: NodeJS.ReadableStream | null;
 };
 
-/**
- * Only the 429 branch reads the body, and node-fetch keeps the stream and its
- * socket alive until something does. Repeated backend failures would otherwise
- * accumulate connections holding payloads this module deliberately discards.
- */
+/** Releases unread or incomplete error responses after bounded classification. */
 function discardResponseBody(response: CodeApiErrorResponse): void {
   const body = response.body;
   if (body == null || !('destroy' in body)) {
@@ -298,6 +352,48 @@ function discardResponseBody(response: CodeApiErrorResponse): void {
   }
 }
 
+const MAX_CODE_API_ERROR_BODY_BYTES = 64 * 1024;
+const CODE_API_ERROR_BODY_TIMEOUT_MS = 1_000;
+
+/** Reads only small error envelopes, with a deadline for stalled upstreams. */
+async function readCodeApiErrorBody(
+  response: CodeApiErrorResponse
+): Promise<string> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const read = async (): Promise<string> => {
+      if (response.body != null && Symbol.asyncIterator in response.body) {
+        let bytes = 0;
+        const chunks: Buffer[] = [];
+        for await (const chunk of response.body as AsyncIterable<
+          Buffer | string
+        >) {
+          const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+          bytes += buffer.length;
+          if (bytes > MAX_CODE_API_ERROR_BODY_BYTES) return '';
+          chunks.push(buffer);
+        }
+        return Buffer.concat(chunks).toString('utf8');
+      }
+      const body = await response.text();
+      return Buffer.byteLength(body) <= MAX_CODE_API_ERROR_BODY_BYTES
+        ? body
+        : '';
+    };
+    return await Promise.race([
+      read(),
+      new Promise<string>((resolve) => {
+        timer = setTimeout(() => resolve(''), CODE_API_ERROR_BODY_TIMEOUT_MS);
+      }),
+    ]);
+  } catch {
+    return '';
+  } finally {
+    clearTimeout(timer);
+    discardResponseBody(response);
+  }
+}
+
 export async function buildCodeApiHttpErrorMessage(
   method: CodeApiMethod,
   _endpoint: string,
@@ -305,8 +401,8 @@ export async function buildCodeApiHttpErrorMessage(
   options?: { recoverable?: boolean; profile?: t.CodeApiExecutionProfile }
 ): Promise<string> {
   /* Logged before the body is touched. A non-OK response can leave a chunked
-     body open, and there is no read timeout here, so draining first would
-     withhold the diagnostic indefinitely for exactly the backend it identifies.
+     body open, so logging first preserves the diagnostic even if the bounded
+     classification read times out.
      The body itself is never logged — it is upstream free text that can echo
      the header that was sent — and the endpoint is host-configured, so the
      backend is named by the profile this module chose rather than by its
@@ -325,16 +421,12 @@ export async function buildCodeApiHttpErrorMessage(
       }
     );
   }
-  if (response.status !== 429) {
-    discardResponseBody(response);
+  const responseBody = await readCodeApiErrorBody(response);
+  const capabilityError = getCodeApiCapabilityErrorMessage(responseBody);
+  if (capabilityError != null) {
+    return capabilityError;
   }
   if (response.status === 429) {
-    let responseBody = '';
-    try {
-      responseBody = await response.text();
-    } catch {
-      responseBody = '';
-    }
     const retryAfterSeconds = getRetryAfterSeconds(responseBody);
     return retryAfterSeconds != null
       ? `Code execution is temporarily rate-limited. Retry after ${retryAfterSeconds} seconds.`
@@ -543,7 +635,7 @@ function createCodeExecutionTool(
         };
 
         const proxyAgent = resolveFetchProxyAgent(execEndpoint);
-        if (proxyAgent) {
+        if (proxyAgent != null) {
           fetchOptions.agent = proxyAgent;
         }
         const response = await fetch(execEndpoint, fetchOptions);
@@ -610,7 +702,9 @@ function createCodeExecutionTool(
           normalizeCodeApiRequestError(error).message,
           code
         );
-        throw new Error(`Execution error:\n\n${messageWithReminder}`);
+        throw new CodeApiRequestError(
+          `Execution error:\n\n${messageWithReminder}`
+        );
       }
     },
     {

package/src/tools/ProgrammaticToolCalling.ts

@@ -469,7 +469,7 @@ export async function fetchSessionFiles(
     };
 
     const proxyAgent = resolveFetchProxyAgent(filesEndpoint, proxy);
-    if (proxyAgent) {
+    if (proxyAgent != null) {
       fetchOptions.agent = proxyAgent;
     }
 
@@ -531,7 +531,7 @@ export async function makeRequest(
     };
 
     const proxyAgent = resolveFetchProxyAgent(endpoint, proxy);
-    if (proxyAgent) {
+    if (proxyAgent != null) {
       fetchOptions.agent = proxyAgent;
     }
 
@@ -689,7 +689,7 @@ type ToolInputSchemaKind = {
 function detectSchemaKind(schema: unknown): ToolInputSchemaKind {
   const kind: ToolInputSchemaKind = { object: false, string: false };
 
-  if (!schema || typeof schema !== 'object') {
+  if (schema == null || typeof schema !== 'object') {
     return kind;
   }
 
@@ -704,7 +704,7 @@ function detectSchemaKind(schema: unknown): ToolInputSchemaKind {
   }
 
   const zodDef = (schema as { _def?: unknown })._def;
-  if (!zodDef || typeof zodDef !== 'object') {
+  if (zodDef == null || typeof zodDef !== 'object') {
     return kind;
   }
 
@@ -726,7 +726,7 @@ function detectSchemaKind(schema: unknown): ToolInputSchemaKind {
         type?: unknown;
       }
     ).innerType ?? (zodDef as { schema?: unknown }).schema;
-  if (innerSchema) {
+  if (innerSchema != null) {
     const innerKind = detectSchemaKind(innerSchema);
     kind.object ||= innerKind.object;
     kind.string ||= innerKind.string;
@@ -1221,9 +1221,11 @@ export function createProgrammaticToolCallingTool(
           (error as Error).message,
           code
         );
-        throw new Error(
-          `Programmatic execution failed: ${messageWithReminder}`
-        );
+        const message = `Programmatic execution failed: ${messageWithReminder}`;
+        if (error instanceof CodeApiRequestError) {
+          throw new CodeApiRequestError(message);
+        }
+        throw new Error(message, { cause: error });
       }
     },
     {