@librechat/agents 3.3.11 → 3.3.12

package/src/tools/subagent/SubagentExecutor.ts

@@ -28,6 +28,10 @@ import type { AgentContext } from '@/agents/AgentContext';
 import type { StandardGraph } from '@/graphs/Graph';
 import type { HandlerRegistry } from '@/events';
 import { Constants, GraphEvents, Callback, StepTypes } from '@/common';
+import {
+  StreamLimitExceededError,
+  RUN_BREAKER_SCOPE_CONFIG_KEY,
+} from '@/llm/streamLimits';
 import { executeHooks } from '@/hooks';
 
 const DEFAULT_MAX_TURNS = 25;
@@ -157,6 +161,14 @@ export type SubagentExecuteParams = {
   description: string;
   subagentType: string;
   threadId?: string;
+  /**
+   * Breaker controller captured at the parent TOOL BATCH's entry, before
+   * PreToolUse hooks. Preferred over the live scope accessor: a graph reset
+   * during a hook would otherwise bind this child to the NEW run's
+   * controller — reviving it on a fresh signal and letting its trips cancel
+   * unrelated work.
+   */
+  breaker?: AbortController;
   /**
    * Parent-side `tool_call_id` of the `subagent` tool invocation that
    * triggered this execution. Surfaced on {@link SubagentUpdateEvent} so
@@ -214,11 +226,31 @@ export type ChildGraphFactory = (input: StandardGraphInput) => StandardGraph;
 export type SubagentExecutorOptions = {
   configs: Map<string, ResolvedSubagentConfig>;
   parentSignal?: AbortSignal;
+  /** Run-scoped breaker abort shared by every executor of one graph, so a
+   * child tripping a stream limit stops subagents running under OTHER
+   * parallel agent nodes too. An accessor rather than a captured controller:
+   * the graph recreates its controller per run, and each execution must
+   * bind to the controller current when it STARTS — signal and trip target
+   * together, so a straggler from a failed run can neither revive on nor
+   * circuit-break a later run's controller. Absent (tests, minimal hosts),
+   * the executor falls back to its own private controller. */
+  breakerScope?: {
+    controller: () => AbortController;
+  };
   hookRegistry?: HookRegistry;
   parentRunId: string;
   parentAgentId?: string;
   langfuse?: StandardGraphInput['langfuse'];
   tokenCounter?: TokenCounter;
+  /**
+   * Run-level stream circuit breakers, forwarded into every child graph so
+   * a host raising, lowering, or disabling the limits governs subagents too.
+   * Child model calls run through `attemptInvoke`'s local stream handler
+   * (children have no registered dispatcher), which enforces the child
+   * graph's own resolved limits; without this the child would silently
+   * revert to the defaults.
+   */
+  streamLimits?: StandardGraphInput['streamLimits'];
   /** Remaining nesting budget. 0 or negative blocks execution. */
   maxDepth?: number;
   /**
@@ -254,11 +286,20 @@ export type SubagentExecutorOptions = {
 export class SubagentExecutor {
   private readonly configs: Map<string, ResolvedSubagentConfig>;
   private readonly parentSignal?: AbortSignal;
+  /** Aborted when a child trips a stream circuit breaker: parallel sibling
+   * subagents run concurrently on the parent's signal, and rejecting the
+   * batch alone would leave their provider requests streaming after the
+   * safety abort. One-way by design — a tripped breaker ends the run, so no
+   * later child of this executor should start either. Fallback for hosts
+   * that do not supply the graph's shared `breakerScope`. */
+  private readonly childRunAbort = new AbortController();
+  private readonly breakerScope?: SubagentExecutorOptions['breakerScope'];
   private readonly hookRegistry?: HookRegistry;
   private readonly parentRunId: string;
   private readonly parentAgentId?: string;
   private readonly langfuse?: StandardGraphInput['langfuse'];
   private readonly tokenCounter?: TokenCounter;
+  private readonly streamLimits?: StandardGraphInput['streamLimits'];
   private readonly maxDepth: number;
   private readonly createChildGraph: ChildGraphFactory;
   private readonly usageSink?: SubagentUsageSink;
@@ -269,11 +310,13 @@ export class SubagentExecutor {
   constructor(options: SubagentExecutorOptions) {
     this.configs = options.configs;
     this.parentSignal = options.parentSignal;
+    this.breakerScope = options.breakerScope;
     this.hookRegistry = options.hookRegistry;
     this.parentRunId = options.parentRunId;
     this.parentAgentId = options.parentAgentId;
     this.langfuse = options.langfuse;
     this.tokenCounter = options.tokenCounter;
+    this.streamLimits = options.streamLimits;
     this.maxDepth = options.maxDepth ?? 1;
     this.createChildGraph = options.createChildGraph;
     this.usageSink = options.usageSink;
@@ -285,6 +328,23 @@ export class SubagentExecutor {
     }
   }
 
+  /** The breaker controller current for this execution — read per spawn
+   * because the graph recreates its controller each run. */
+  private resolveBreakerController(): AbortController {
+    return this.breakerScope?.controller() ?? this.childRunAbort;
+  }
+
+  /** One signal that fires on the parent's abort or the breaker abort,
+   * collapsed to a single signal when possible (mirrors
+   * `composeAbortSignals` in Graph.ts). */
+  private composeChildSignal(breaker: AbortController): AbortSignal {
+    const child = breaker.signal;
+    if (this.parentSignal == null || this.parentSignal === child) {
+      return child;
+    }
+    return AbortSignal.any([this.parentSignal, child]);
+  }
+
   /** Snapshot of the parent's registry at the moment a subagent is dispatched. */
   private getParentHandlerRegistry(): HandlerRegistry | undefined {
     return this.resolveParentHandlerRegistry?.();
@@ -292,6 +352,15 @@ export class SubagentExecutor {
 
   async execute(params: SubagentExecuteParams): Promise<SubagentExecuteResult> {
     const { description, subagentType, threadId, parentToolCallId } = params;
+    /** Captured ONCE per execution, preferring the controller the parent
+     * tool batch captured at ITS entry (before PreToolUse hooks): a failed
+     * run's graph reset replaces the live controller, and resolving it here
+     * — after the hook awaits — would bind this child to the NEW run's
+     * un-aborted controller: reviving old-run work, or worse, tripping the
+     * new run's breaker from an old child's stream-limit breach. Signal and
+     * trip target both bind to this capture. */
+    const childBreaker = params.breaker ?? this.resolveBreakerController();
+    const childSignal = this.composeChildSignal(childBreaker);
     const config = this.configs.get(subagentType);
 
     if (!config) {
@@ -369,10 +438,11 @@ export class SubagentExecutor {
     const hostUsageSink = this.usageSink;
     const childGraph = this.createChildGraph({
       runId: childRunId,
-      signal: this.parentSignal,
+      signal: childSignal,
       agents: [childInputs],
       langfuse: this.langfuse,
       tokenCounter: this.tokenCounter,
+      streamLimits: this.streamLimits,
       subagentScope: true,
       /**
        * Forwarded so the child graph's own `SubagentExecutor` (created in
@@ -501,7 +571,7 @@ export class SubagentExecutor {
         { messages: [new HumanMessage(description)] },
         {
           recursionLimit: maxTurns * RECURSION_MULTIPLIER,
-          signal: this.parentSignal,
+          signal: childSignal,
           callbacks,
           runName: `subagent:${subagentType}`,
           configurable: {
@@ -511,6 +581,16 @@ export class SubagentExecutor {
         }
       );
     } catch (error) {
+      /** Aborted before any observational work below: parallel siblings — in
+       * this executor and, via the graph-scoped breaker, under other
+       * parallel agent nodes — stream on the composed child signal, and
+       * awaiting forwarding.drain() first would let them consume provider
+       * quota for that entire interval. Trips the ENTRY-captured controller:
+       * after a reset, a straggler must break its own dead run, not the
+       * current one. */
+      if (error instanceof StreamLimitExceededError) {
+        childBreaker.abort(error);
+      }
       const errorMessage = truncateErrorMessage(error);
       if (forwarding) {
         await forwarding.drain();
@@ -525,6 +605,16 @@ export class SubagentExecutor {
         });
       }
       childGraph.clearHeavyState();
+      /**
+       * A tripped stream circuit breaker is a safety abort, not a recoverable
+       * subagent failure: converting it into a tool result would let the
+       * parent keep generating (or spawn another child) after the limit
+       * fired. Rethrown here and passed through ToolNode's error conversion,
+       * so the parent run rejects with the child's limit error.
+       */
+      if (error instanceof StreamLimitExceededError) {
+        throw error;
+      }
       return {
         content: `Subagent error: ${errorMessage}`,
         messages: [],
@@ -956,7 +1046,10 @@ function sanitizeChildConfigurable(
 function isLangGraphRuntimeConfigKey(key: string): boolean {
   return (
     key.startsWith(LANGGRAPH_RUNTIME_CONFIG_PREFIX) ||
-    LANGGRAPH_CHECKPOINT_CONFIG_KEYS.has(key)
+    LANGGRAPH_CHECKPOINT_CONFIG_KEYS.has(key) ||
+    /** The parent batch's breaker scope must not leak into the child
+     * workflow's configurable — children own separate controllers. */
+    key === RUN_BREAKER_SCOPE_CONFIG_KEY
   );
 }
 

package/src/types/graph.ts

@@ -32,6 +32,7 @@ import type {
 } from '@/types/stream';
 import type {
   TokenCounter,
+  StreamLimits,
   StreamPreemption,
   TokenBudgetBreakdown,
 } from '@/types/run';
@@ -357,6 +358,12 @@ export type StandardGraphInput = {
    * this field.
    */
   preemption?: StreamPreemption;
+  /**
+   * Stream circuit breakers, forwarded from `RunConfig.streamLimits` and
+   * resolved once at graph construction. Enforced by the stream handler on
+   * every streamed chunk event. See {@link StreamLimits}.
+   */
+  streamLimits?: StreamLimits;
 };
 
 export type GraphEdge = {

package/src/types/run.ts

@@ -28,7 +28,13 @@ export type BaseGraphConfig = {
 };
 export type LegacyGraphConfig = BaseGraphConfig & {
   type?: 'standard';
-} & Omit<g.StandardGraphInput, 'provider' | 'clientOptions' | 'agents'> &
+} & Omit<
+    g.StandardGraphInput,
+    /** `streamLimits` is excluded because legacy graphs receive limits only
+     * via the top-level `RunConfig.streamLimits`; accepting the field here
+     * would type-check but be silently ignored by `createLegacyGraph`. */
+    'provider' | 'clientOptions' | 'agents' | 'streamLimits'
+  > &
   Omit<g.AgentInputs, 'provider' | 'clientOptions' | 'agentId'>;
 
 /* Supervised graph (opt-in) */
@@ -174,6 +180,41 @@ export type PreemptStats = {
   emptyBoundaries: number;
 };
 
+/**
+ * Circuit breakers for pathological model streams. A malformed generation
+ * can stream a single tool call's arguments for many minutes while they
+ * never become executable (observed live: one 149,923-char SQL argument
+ * streamed for 26 minutes before the 64k output-token ceiling ended the
+ * run). When a limit trips, the run aborts with a `StreamLimitExceededError`
+ * and the in-flight provider request is torn down mid-stream.
+ */
+export interface StreamLimits {
+  /**
+   * Max cumulative UTF-8 bytes a single streamed tool call's arguments may
+   * reach before the run is aborted. Defaults to
+   * `DEFAULT_MAX_TOOL_CALL_ARG_BYTES` (64 KiB); `0` disables the guard.
+   */
+  maxToolCallArgBytes?: number;
+  /**
+   * Per-tool overrides for `maxToolCallArgBytes`, keyed by the model-facing
+   * tool name. A matching entry replaces the global cap for that tool's
+   * calls (`0` disables the guard for that tool only). Tools that
+   * legitimately stream whole documents as arguments (e.g. file creation)
+   * can run with a higher cap without loosening every other tool's guard.
+   * Calls whose tool name has not yet arrived on the stream use the global
+   * cap; providers send the name in the first chunk, so this only matters
+   * for malformed streams.
+   */
+  maxToolCallArgBytesByTool?: Record<string, number>;
+  /**
+   * Max streamed chunk events a single model generation (turn) may emit
+   * before the run is aborted. Defense in depth against looping or
+   * duplicated provider streams that a byte limit cannot see (e.g. endless
+   * empty chunks). Disabled by default; `0` also disables.
+   */
+  maxDeltaEventsPerTurn?: number;
+}
+
 export type RunConfig = {
   runId: string;
   graphConfig: LegacyGraphConfig | StandardGraphConfig | MultiAgentGraphConfig;
@@ -213,6 +254,13 @@ export type RunConfig = {
    * tool boundary.
    */
   preemption?: StreamPreemption;
+  /**
+   * Circuit breakers for pathological model streams (runaway tool-call
+   * argument generation, looping delta streams). Omit for defaults: the
+   * tool-call argument byte cap is ON by default, the per-turn event cap is
+   * opt-in. See {@link StreamLimits}.
+   */
+  streamLimits?: StreamLimits;
   returnContent?: boolean;
   tokenCounter?: TokenCounter;
   indexTokenCountMap?: Record<string, number>;

package/src/types/tools.ts

@@ -3,6 +3,7 @@ import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { RunnableToolLike } from '@langchain/core/runnables';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
+import type { RunBreakerScope } from '@/llm/streamLimits';
 import type { MessageContentComplex, ToolErrorData } from './stream';
 import type { HumanInTheLoopConfig } from './hitl';
 import type { LangfuseConfig } from './graph';
@@ -259,6 +260,20 @@ export type ToolNodeOptions = {
    * `resolveLocalExecutionTools`.
    */
   fileCheckpointer?: LocalFileCheckpointer;
+  /**
+   * Returns the owning graph's run-scoped breaker signal. Read once per
+   * `run()` invocation and composed into the batch config's `signal`, so
+   * every tool execution in the batch aborts when a stream circuit breaker
+   * trips elsewhere in the run.
+   */
+  getBreakerSignal?: () => AbortSignal | undefined;
+  /**
+   * Returns the owning graph's immutable run scope. Read once per batch,
+   * BEFORE hooks, and threaded to tools that spawn runs (subagents) so a
+   * reset during a hook cannot rebind their children to a newer run's
+   * controller.
+   */
+  getRunScope?: () => RunBreakerScope;
 };
 
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
@@ -523,6 +538,12 @@ export type ToolExecuteBatchRequest = {
   configurable?: Record<string, unknown>;
   /** Runtime metadata from RunnableConfig (includes thread_id, run_id, provider, etc.) */
   metadata?: Record<string, unknown>;
+  /**
+   * Aborts when the run is cancelled or its stream circuit breaker trips.
+   * Handlers SHOULD forward this to their tool executions so in-flight work
+   * stops consuming quota once the run is already failing.
+   */
+  signal?: AbortSignal;
   /** Promise resolver - handler calls this with ALL results */
   resolve: (results: ToolExecuteResult[]) => void;
   /** Promise rejector - handler calls this on fatal error */

package/src/utils/index.ts

@@ -1,6 +1,7 @@
 export * from './graph';
 export * from './llm';
 export * from './misc';
+export * from './proxy';
 export * from './handlers';
 export * from './run';
 export * from './tokens';

package/src/utils/misc.ts

@@ -73,3 +73,22 @@ export function unescapeObject(obj: unknown, key?: string): unknown {
   }
   return obj;
 }
+
+/**
+ * One signal that fires when either input fires. `AbortSignal.any` is skipped
+ * when the inputs collapse to a single signal — the composite is a fresh
+ * object per call, and the common cases (one channel, or the host reusing the
+ * same controller for both) don't need one.
+ */
+export function composeAbortSignals(
+  a: AbortSignal | undefined,
+  b: AbortSignal | undefined
+): AbortSignal | undefined {
+  if (a == null || a === b) {
+    return b;
+  }
+  if (b == null) {
+    return a;
+  }
+  return AbortSignal.any([a, b]);
+}

package/src/utils/proxy.test.ts

@@ -0,0 +1,176 @@
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import { SocksProxyAgent } from 'socks-proxy-agent';
+import { resolveFetchProxyAgent, shouldBypassProxy } from './proxy';
+
+const CODE_ENDPOINT = 'http://codeapi:3112/v1/exec';
+
+describe('shouldBypassProxy', () => {
+  it('is false without a NO_PROXY list', () => {
+    expect(shouldBypassProxy(CODE_ENDPOINT, undefined)).toBe(false);
+    expect(shouldBypassProxy(CODE_ENDPOINT, '  ')).toBe(false);
+  });
+
+  it('matches a bare hostname', () => {
+    expect(shouldBypassProxy(CODE_ENDPOINT, 'codeapi')).toBe(true);
+    expect(shouldBypassProxy(CODE_ENDPOINT, 'other')).toBe(false);
+  });
+
+  it('accepts comma and whitespace separated lists', () => {
+    expect(
+      shouldBypassProxy(CODE_ENDPOINT, 'localhost,codeapi,127.0.0.1')
+    ).toBe(true);
+    expect(shouldBypassProxy(CODE_ENDPOINT, 'localhost codeapi')).toBe(true);
+  });
+
+  it('treats a leading dot as host-and-subdomains', () => {
+    expect(
+      shouldBypassProxy('http://codeapi.internal:3112/v1', '.internal')
+    ).toBe(true);
+    expect(shouldBypassProxy('http://internal:3112/v1', '.internal')).toBe(
+      true
+    );
+    expect(shouldBypassProxy('http://notinternal:3112/v1', '.internal')).toBe(
+      false
+    );
+  });
+
+  it('honours a port suffix only when it matches', () => {
+    expect(shouldBypassProxy(CODE_ENDPOINT, 'codeapi:3112')).toBe(true);
+    expect(shouldBypassProxy(CODE_ENDPOINT, 'codeapi:9999')).toBe(false);
+  });
+
+  it('defaults the port from the scheme when the URL omits it', () => {
+    expect(
+      shouldBypassProxy('https://api.example.com/v1', 'api.example.com:443')
+    ).toBe(true);
+    expect(
+      shouldBypassProxy('http://api.example.com/v1', 'api.example.com:80')
+    ).toBe(true);
+    expect(
+      shouldBypassProxy('https://api.example.com/v1', 'api.example.com:80')
+    ).toBe(false);
+  });
+
+  it('supports the wildcard entry', () => {
+    expect(shouldBypassProxy('https://anything.example.com', '*')).toBe(true);
+  });
+
+  it('does not claim a bypass for an unparsable target', () => {
+    expect(shouldBypassProxy('not a url', '*')).toBe(false);
+  });
+});
+
+describe('resolveFetchProxyAgent', () => {
+  const saved = { ...process.env };
+
+  afterEach(() => {
+    for (const key of ['PROXY', 'NO_PROXY', 'no_proxy']) {
+      delete process.env[key];
+    }
+    Object.assign(process.env, saved);
+  });
+
+  function clearProxyEnv(): void {
+    for (const key of ['PROXY', 'NO_PROXY', 'no_proxy']) {
+      delete process.env[key];
+    }
+  }
+
+  it('returns undefined when no proxy is configured', () => {
+    clearProxyEnv();
+    expect(resolveFetchProxyAgent(CODE_ENDPOINT)).toBeUndefined();
+  });
+
+  /**
+   * The defect this module exists for: HttpsProxyAgent speaks HTTP CONNECT, so
+   * driving a socks5 proxy with it produces "Proxy connection ended before
+   * receiving CONNECT response" rather than a working tunnel.
+   */
+  it('uses a SOCKS agent for socks schemes', () => {
+    clearProxyEnv();
+    process.env.PROXY = 'socks5://127.0.0.1:1080';
+
+    const agent = resolveFetchProxyAgent('https://api.example.com/v1');
+
+    expect(agent).toBeInstanceOf(SocksProxyAgent);
+    expect(agent).not.toBeInstanceOf(HttpsProxyAgent);
+  });
+
+  it.each(['socks://host:1080', 'socks4://host:1080', 'socks5h://host:1080'])(
+    'recognises %s as SOCKS',
+    (proxy) => {
+      clearProxyEnv();
+      process.env.PROXY = proxy;
+      expect(
+        resolveFetchProxyAgent('https://api.example.com/v1')
+      ).toBeInstanceOf(SocksProxyAgent);
+    }
+  );
+
+  it('uses an HTTP agent for http schemes', () => {
+    clearProxyEnv();
+    process.env.PROXY = 'http://proxy.internal:3128';
+
+    expect(resolveFetchProxyAgent('https://api.example.com/v1')).toBeInstanceOf(
+      HttpsProxyAgent
+    );
+  });
+
+  /**
+   * Code execution targets an internal endpoint. Without NO_PROXY support the
+   * feature is unusable for anyone with PROXY set, because the internal host is
+   * not reachable through an external proxy and there is no way to opt out.
+   */
+  it('bypasses the proxy for a NO_PROXY host', () => {
+    clearProxyEnv();
+    process.env.PROXY = 'socks5://127.0.0.1:1080';
+    process.env.NO_PROXY = 'codeapi,localhost';
+
+    expect(resolveFetchProxyAgent(CODE_ENDPOINT)).toBeUndefined();
+  });
+
+  it('still proxies hosts outside NO_PROXY', () => {
+    clearProxyEnv();
+    process.env.PROXY = 'socks5://127.0.0.1:1080';
+    process.env.NO_PROXY = 'codeapi';
+
+    expect(resolveFetchProxyAgent('https://api.example.com/v1')).toBeInstanceOf(
+      SocksProxyAgent
+    );
+  });
+
+  it('honours the lowercase no_proxy spelling', () => {
+    clearProxyEnv();
+    process.env.PROXY = 'http://proxy.internal:3128';
+    process.env.no_proxy = 'codeapi';
+
+    expect(resolveFetchProxyAgent(CODE_ENDPOINT)).toBeUndefined();
+  });
+
+  it('prefers an explicit proxy argument over the environment', () => {
+    clearProxyEnv();
+    process.env.PROXY = 'http://from-env:3128';
+
+    expect(
+      resolveFetchProxyAgent(
+        'https://api.example.com/v1',
+        'socks5://explicit:1080'
+      )
+    ).toBeInstanceOf(SocksProxyAgent);
+  });
+
+  /**
+   * An empty explicit proxy means "no proxy for this call", not "fall back to
+   * the environment" — matching the original `proxy != null && proxy !== ''`
+   * guard, where callers resolve `initParams.proxy ?? process.env.PROXY`
+   * themselves and an empty result disables proxying.
+   */
+  it('treats an empty explicit proxy as no proxy rather than falling back to env', () => {
+    clearProxyEnv();
+    process.env.PROXY = 'http://from-env:3128';
+
+    expect(
+      resolveFetchProxyAgent('https://api.example.com/v1', '')
+    ).toBeUndefined();
+  });
+});

package/src/utils/proxy.ts

@@ -0,0 +1,93 @@
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import { SocksProxyAgent } from 'socks-proxy-agent';
+import type { RequestInit } from 'node-fetch';
+
+type FetchAgent = NonNullable<RequestInit['agent']>;
+
+/**
+ * Whether `targetUrl` is excluded from proxying by a NO_PROXY list.
+ *
+ * Follows the de facto convention: comma or whitespace separated entries, an
+ * optional leading dot meaning "this host and its subdomains", an optional
+ * `:port` suffix that must match when present, and `*` meaning "bypass
+ * everything".
+ */
+export function shouldBypassProxy(
+  targetUrl: string,
+  noProxy?: string
+): boolean {
+  const list = (noProxy ?? '').trim();
+  if (list === '') {
+    return false;
+  }
+
+  let hostname: string;
+  let port: string;
+  try {
+    const url = new URL(targetUrl);
+    hostname = url.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    port = url.port || (url.protocol === 'https:' ? '443' : '80');
+  } catch {
+    /* An unparsable target tells us nothing, so do not claim a bypass. */
+    return false;
+  }
+
+  return list
+    .split(/[\s,]+/)
+    .filter(Boolean)
+    .some((raw) => {
+      if (raw === '*') {
+        return true;
+      }
+      const match = /^(.*?)(?::(\d+))?$/.exec(raw);
+      if (!match) {
+        return false;
+      }
+      const entryHost = (match[1] ?? '').replace(/^\./, '').toLowerCase();
+      const entryPort = match[2];
+      if (entryHost === '') {
+        return false;
+      }
+      if (entryPort != null && entryPort !== port) {
+        return false;
+      }
+      return hostname === entryHost || hostname.endsWith(`.${entryHost}`);
+    });
+}
+
+/**
+ * Build the proxy agent for a `node-fetch` request, or `undefined` when the
+ * request should go direct.
+ *
+ * Two rules that a bare `new HttpsProxyAgent(process.env.PROXY)` gets wrong:
+ *
+ *  - The agent must match the proxy scheme. `HttpsProxyAgent` speaks HTTP
+ *    CONNECT; handing it a `socks5://` URL produces a request the proxy never
+ *    answers in that protocol, surfacing as "Proxy connection ended before
+ *    receiving CONNECT response".
+ *  - NO_PROXY has to be honoured. Code execution targets an internal endpoint
+ *    (`http://codeapi:3112`), and forcing that through an external proxy makes
+ *    the whole feature unusable for anyone who has PROXY set, with no way to
+ *    opt out.
+ *
+ * @param targetUrl Absolute URL the request is going to.
+ * @param proxyUrl Explicit proxy; falls back to the PROXY environment variable.
+ */
+export function resolveFetchProxyAgent(
+  targetUrl: string,
+  proxyUrl?: string
+): FetchAgent | undefined {
+  const proxy = (proxyUrl ?? process.env.PROXY ?? '').trim();
+  if (proxy === '') {
+    return undefined;
+  }
+
+  const noProxy = process.env.NO_PROXY ?? process.env.no_proxy;
+  if (shouldBypassProxy(targetUrl, noProxy)) {
+    return undefined;
+  }
+
+  return /^socks/i.test(proxy)
+    ? (new SocksProxyAgent(proxy) as unknown as FetchAgent)
+    : (new HttpsProxyAgent(proxy) as unknown as FetchAgent);
+}