@librechat/agents 3.3.10 → 3.3.12

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

@@ -9,21 +9,25 @@ export declare abstract class BaseReranker {
 export declare class JinaReranker extends BaseReranker {
     private apiUrl;
     private timeout;
-    constructor({ apiKey, apiUrl, timeout, logger, }: {
+    private httpAgent?;
+    private httpsAgent?;
+    constructor({ apiKey, apiUrl, timeout, logger, httpAgent, httpsAgent, }: {
         apiKey?: string;
         apiUrl?: string;
         timeout?: number;
         logger?: t.Logger;
-    });
+    } & t.HttpAgentConfig);
     rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
 }
 export declare class CohereReranker extends BaseReranker {
     private timeout;
-    constructor({ apiKey, timeout, logger, }: {
+    private httpAgent?;
+    private httpsAgent?;
+    constructor({ apiKey, timeout, logger, httpAgent, httpsAgent, }: {
         apiKey?: string;
         timeout?: number;
         logger?: t.Logger;
-    });
+    } & t.HttpAgentConfig);
     rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
 }
 export declare class InfinityReranker extends BaseReranker {
@@ -40,4 +44,4 @@ export declare const createReranker: (config: {
     cohereApiKey?: string;
     rerankerTimeout?: number;
     logger?: t.Logger;
-}) => BaseReranker | undefined;
+} & t.HttpAgentConfig) => BaseReranker | undefined;

package/dist/types/tools/search/serper-scraper.d.ts

@@ -30,6 +30,8 @@ export declare class SerperScraper implements t.BaseScraper {
     private timeout;
     private logger;
     private includeMarkdown;
+    private httpAgent?;
+    private httpsAgent?;
     constructor(config?: t.SerperScraperConfig);
     /**
      * Scrape a single URL

package/dist/types/tools/search/tavily-scraper.d.ts

@@ -9,6 +9,8 @@ export declare class TavilyScraper implements t.BaseScraper {
     private includeImages;
     private includeFavicon;
     private format;
+    private httpAgent?;
+    private httpsAgent?;
     constructor(config?: t.TavilyScraperConfig);
     scrapeUrl(url: string, options?: t.TavilyScrapeOptions): Promise<[string, t.TavilyScrapeResponse]>;
     scrapeUrls(urls: string[], options?: t.TavilyScrapeOptions): Promise<Array<[string, t.TavilyScrapeResponse]>>;

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

@@ -1,7 +1,21 @@
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { Logger as WinstonLogger } from 'winston';
+import type { Agent as HttpsAgent } from 'https';
+import type { Agent as HttpAgent } from 'http';
 import type { BaseReranker } from './rerankers';
 import { DATE_RANGE } from './schema';
+export type { HttpAgent, HttpsAgent };
+export interface HttpAgentConfig {
+    httpAgent?: HttpAgent;
+    httpsAgent?: HttpsAgent;
+}
+/** Transport and credential fields shared by every provider scraper config. */
+export interface BaseSearchProviderConfig extends HttpAgentConfig {
+    apiKey?: string;
+    apiUrl?: string;
+    timeout?: number;
+    logger?: Logger;
+}
 export type SearchProvider = 'serper' | 'searxng' | 'tavily' | 'keenable' | 'crw';
 export type ScraperProvider = 'firecrawl' | 'serper' | 'tavily' | 'crw' | 'keenable';
 export type RerankerType = 'infinity' | 'jina' | 'cohere' | 'none';
@@ -58,7 +72,7 @@ export interface Source {
 }
 export type TavilyTimeRange = 'day' | 'week' | 'month' | 'year';
 export type TavilyTimeRangeInput = TavilyTimeRange | 'h' | 'd' | 'w' | 'm' | 'y';
-export interface TavilySearchOptions {
+export interface TavilySearchOptions extends HttpAgentConfig {
     searchDepth?: 'basic' | 'advanced' | 'fast' | 'ultra-fast';
     maxResults?: number;
     includeImages?: boolean;
@@ -91,7 +105,7 @@ export interface TavilySearchPayload {
     include_favicon?: boolean;
     chunks_per_source?: number;
 }
-export interface CrwSearchOptions {
+export interface CrwSearchOptions extends HttpAgentConfig {
     /** Max results to request (maps to `limit`; clamped 1..20). */
     maxResults?: number;
     /** Add 'images' to the sources array. */
@@ -133,7 +147,7 @@ export interface CrwSearchResponse {
     error?: string;
     error_code?: string;
 }
-export interface SearchConfig {
+export interface SearchConfig extends HttpAgentConfig {
     searchProvider?: SearchProvider;
     serperApiKey?: string;
     searxngInstanceUrl?: string;
@@ -149,7 +163,7 @@ export interface SearchConfig {
     crwApiUrl?: string;
     crwSearchOptions?: CrwSearchOptions;
 }
-export interface KeenableSearchOptions {
+export interface KeenableSearchOptions extends HttpAgentConfig {
     maxResults?: number;
     /** Restrict results to a single domain, e.g. "github.com". */
     site?: string;
@@ -172,17 +186,14 @@ export interface KeenableSearchResult {
 export interface KeenableSearchResponse {
     results?: KeenableSearchResult[];
 }
-export interface KeenableScraperConfig {
-    apiKey?: string;
+export interface KeenableScraperConfig extends BaseSearchProviderConfig {
     /** Override the fetch endpoint base (default: public keyless, keyed when a
      * key is set). Env fallback: KEENABLE_FETCH_URL. */
     apiUrl?: string;
-    timeout?: number;
-    logger?: Logger;
     /** Sent as the X-Keenable-Title attribution header. Defaults to "LibreChat". */
     attributionTitle?: string;
 }
-export type KeenableScrapeOptions = Omit<KeenableScraperConfig, 'apiKey' | 'apiUrl' | 'logger'>;
+export type KeenableScrapeOptions = Omit<KeenableScraperConfig, 'apiKey' | 'apiUrl' | 'logger' | 'httpAgent' | 'httpsAgent'>;
 /** Raw JSON shape returned by GET /v1/fetch{,/public}?url=... */
 export interface KeenableFetchResult {
     url?: string;
@@ -241,18 +252,10 @@ export interface FirecrawlConfig {
     firecrawlVersion?: string;
     firecrawlOptions?: FirecrawlScraperConfig;
 }
-export interface SerperScraperConfig {
-    apiKey?: string;
-    apiUrl?: string;
-    timeout?: number;
-    logger?: Logger;
+export interface SerperScraperConfig extends BaseSearchProviderConfig {
     includeMarkdown?: boolean;
 }
-export interface TavilyScraperConfig {
-    apiKey?: string;
-    apiUrl?: string;
-    timeout?: number;
-    logger?: Logger;
+export interface TavilyScraperConfig extends BaseSearchProviderConfig {
     extractDepth?: 'basic' | 'advanced';
     includeImages?: boolean;
     includeFavicon?: boolean;
@@ -341,13 +344,9 @@ export interface BaseScraper {
     extractMetadata(response: AnyScraperResponse): ScrapeMetadata | GenericScrapeMetadata;
 }
 /** Firecrawl */
-export type FirecrawlScrapeOptions = Omit<FirecrawlScraperConfig, 'apiKey' | 'apiUrl' | 'version' | 'logger'>;
-export interface CrwScraperConfig {
-    apiKey?: string;
-    apiUrl?: string;
+export type FirecrawlScrapeOptions = Omit<FirecrawlScraperConfig, 'apiKey' | 'apiUrl' | 'version' | 'logger' | 'httpAgent' | 'httpsAgent'>;
+export interface CrwScraperConfig extends BaseSearchProviderConfig {
     formats?: string[];
-    timeout?: number;
-    logger?: Logger;
     onlyMainContent?: boolean;
     includeTags?: string[];
     excludeTags?: string[];
@@ -359,9 +358,9 @@ export interface CrwScraperConfig {
     proxy?: string;
     stealth?: boolean;
 }
-export type CrwScrapeOptions = Omit<CrwScraperConfig, 'apiKey' | 'apiUrl' | 'logger'>;
-export type SerperScrapeOptions = Omit<SerperScraperConfig, 'apiKey' | 'apiUrl' | 'logger'>;
-export type TavilyScrapeOptions = Omit<TavilyScraperConfig, 'apiKey' | 'apiUrl' | 'logger'>;
+export type CrwScrapeOptions = Omit<CrwScraperConfig, 'apiKey' | 'apiUrl' | 'logger' | 'httpAgent' | 'httpsAgent'>;
+export type SerperScrapeOptions = Omit<SerperScraperConfig, 'apiKey' | 'apiUrl' | 'logger' | 'httpAgent' | 'httpsAgent'>;
+export type TavilyScrapeOptions = Omit<TavilyScraperConfig, 'apiKey' | 'apiUrl' | 'logger' | 'httpAgent' | 'httpsAgent'>;
 export interface TavilyExtractPayload {
     urls: string[];
     extract_depth: NonNullable<TavilyScraperConfig['extractDepth']>;
@@ -499,13 +498,9 @@ export interface TavilyExtractResult {
     favicon?: string;
     error?: string;
 }
-export interface FirecrawlScraperConfig {
-    apiKey?: string;
-    apiUrl?: string;
+export interface FirecrawlScraperConfig extends BaseSearchProviderConfig {
     version?: string;
     formats?: string[];
-    timeout?: number;
-    logger?: Logger;
     includeTags?: string[];
     excludeTags?: string[];
     waitFor?: number;

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

@@ -8,6 +8,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
@@ -62,11 +70,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;
     /**
@@ -101,16 +129,32 @@ export type SubagentExecutorOptions = {
 export declare class SubagentExecutor {
     private readonly configs;
     private readonly parentSignal?;
+    /** 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;
+    private readonly breakerScope?;
     private readonly hookRegistry?;
     private readonly parentRunId;
     private readonly parentAgentId?;
     private readonly langfuse?;
     private readonly tokenCounter?;
+    private readonly streamLimits?;
     private readonly maxDepth;
     private readonly createChildGraph;
     private readonly usageSink?;
     private readonly resolveParentHandlerRegistry?;
     constructor(options: SubagentExecutorOptions);
+    /** The breaker controller current for this execution — read per spawn
+     * because the graph recreates its controller each run. */
+    private resolveBreakerController;
+    /** 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;
     /** Snapshot of the parent's registry at the moment a subagent is dispatched. */
     private getParentHandlerRegistry;
     execute(params: SubagentExecuteParams): Promise<SubagentExecuteResult>;

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

@@ -7,7 +7,7 @@ import type { GoogleAIToolType } from '@langchain/google-common';
 import type { SummarizationNodeInput, SummarizeCompleteEvent, SummarizationConfig, SummarizeStartEvent, SummarizeDeltaEvent } from '@/types/summarize';
 import type { ToolMap, ToolEndEvent, GenericTool, LCTool, ToolExecuteBatchRequest } from '@/types/tools';
 import type { RunStep, RunStepDeltaEvent, MessageDeltaEvent, ReasoningDeltaEvent } from '@/types/stream';
-import type { TokenCounter, StreamPreemption, TokenBudgetBreakdown } from '@/types/run';
+import type { TokenCounter, StreamLimits, StreamPreemption, TokenBudgetBreakdown } from '@/types/run';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
@@ -250,6 +250,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 = {
     /** Agent ID, use a list for multiple sources */

package/dist/types/types/run.d.ts

@@ -20,7 +20,11 @@ export type BaseGraphConfig = {
 };
 export type LegacyGraphConfig = BaseGraphConfig & {
     type?: 'standard';
-} & Omit<g.StandardGraphInput, 'provider' | 'clientOptions' | 'agents'> & Omit<g.AgentInputs, 'provider' | 'clientOptions' | 'agentId'>;
+} & 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'>;
 export type SupervisedGraphConfig = BaseGraphConfig & {
     type: 'supervised';
     /** Enable supervised router; when false, fall back to standard loop */
@@ -158,6 +162,40 @@ export type PreemptStats = {
     seals: number;
     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;
@@ -197,6 +235,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/dist/types/types/tools.d.ts

@@ -2,6 +2,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';
@@ -249,6 +250,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;
 export type ToolEndEvent = {
@@ -490,6 +505,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/dist/types/utils/index.d.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/dist/types/utils/misc.d.ts

@@ -6,3 +6,10 @@ export declare function parseBooleanEnv(value: string | undefined): boolean | un
  * @returns The unescaped object
  */
 export declare function unescapeObject(obj: unknown, key?: string): unknown;
+/**
+ * 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 declare function composeAbortSignals(a: AbortSignal | undefined, b: AbortSignal | undefined): AbortSignal | undefined;

package/dist/types/utils/proxy.d.ts

@@ -0,0 +1,31 @@
+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 declare function shouldBypassProxy(targetUrl: string, noProxy?: string): boolean;
+/**
+ * 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 declare function resolveFetchProxyAgent(targetUrl: string, proxyUrl?: string): FetchAgent | undefined;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.3.10",
+  "version": "3.3.12",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -249,6 +249,7 @@
     "okapibm25": "^1.4.1",
     "openai": "^6.46.0",
     "reo-census": "^1.2.9",
+    "socks-proxy-agent": "^8.0.5",
     "uuid": "^11.1.1"
   },
   "peerDependencies": {

package/src/__tests__/stream.eagerArgsDivergence.test.ts

@@ -38,6 +38,10 @@ import {
   BEDROCK_CONVERSE_STREAMED_TOOL_CALL_ADAPTER,
   OPENAI_RESPONSES_STREAMED_TOOL_CALL_ADAPTER,
 } from '@/tools/streamedToolCallSeals';
+import {
+  STREAM_LIMIT_EPOCH_KEY,
+  StreamLimitExceededError,
+} from '@/llm/streamLimits';
 import { GraphEvents, Providers, StepTypes } from '@/common';
 import { ChatModelStreamHandler } from '@/stream';
 import { ToolNode } from '@/tools/ToolNode';
@@ -59,6 +63,7 @@ function createGraph(overrides: Partial<StandardGraph> = {}): StandardGraph {
       configurable: { user_id: 'user_1' },
       metadata: { run_id: 'run_1' },
     },
+    breakerAbort: new AbortController(),
     eagerEventToolExecution: { enabled: true },
     eagerEventToolExecutions: new Map(),
     eagerEventToolUsageCount: eagerUsageCount,
@@ -489,6 +494,159 @@ describe('eager args divergence (LibreChat#14371)', () => {
     });
   });
 
+  it('does not prestart eager tools for stale-epoch events', async () => {
+    const graph = createGraph({ breakerEpoch: 5 } as Partial<StandardGraph>);
+    const { toolExecuteCalls } = installToolExecuteResponder();
+    const handler = new ChatModelStreamHandler();
+    const metadata = {
+      langgraph_node: 'agent',
+      [STREAM_LIMIT_EPOCH_KEY]: 4,
+    };
+
+    /** A final tool-call chunk from a failed run handled after resetValues
+     * advanced the epoch: dropped outright, so the dead run's call cannot
+     * dispatch a host tool into the run now using the live controller. */
+    await handler.handle(
+      GraphEvents.CHAT_MODEL_STREAM,
+      {
+        chunk: {
+          content: '',
+          tool_calls: [{ id: 'call_1', name: 'db_query', args: { sql: 'SELECT 1;' } }],
+          response_metadata: { finish_reason: 'tool_calls' },
+        } as unknown as t.StreamChunk,
+      },
+      metadata,
+      graph
+    );
+
+    expect(toolExecuteCalls).toHaveLength(0);
+    expect(graph.eagerEventToolExecutions.size).toBe(0);
+  });
+
+  it('drops eager dispatch when the run scope is replaced during tool-call handling', async () => {
+    const graph = createGraph({
+      runScope: Object.freeze({
+        epoch: 1,
+        controller: new AbortController(),
+      }),
+    } as Partial<StandardGraph>);
+    /** The handler passes its entry checks, then a full reset lands while
+     * handleToolCalls awaits the run-step dispatch. The event now belongs
+     * to a dead run; dispatching eagerly would compose the NEW run's live
+     * controller and config. */
+    const originalDispatch = graph.dispatchRunStep;
+    graph.dispatchRunStep = (async (
+      stepKey: string,
+      details: unknown
+    ): Promise<string> => {
+      const stepId = await (
+        originalDispatch as unknown as (
+          stepKey: string,
+          details: unknown
+        ) => Promise<string>
+      )(stepKey, details);
+      (graph as { runScope: unknown }).runScope = Object.freeze({
+        epoch: 2,
+        controller: new AbortController(),
+      });
+      return stepId;
+    }) as typeof graph.dispatchRunStep;
+    const { toolExecuteCalls } = installToolExecuteResponder();
+    const handler = new ChatModelStreamHandler();
+    const metadata = { langgraph_node: 'agent' };
+
+    await expect(
+      handler.handle(
+        GraphEvents.CHAT_MODEL_STREAM,
+        {
+          chunk: {
+            content: '',
+            tool_calls: [
+              { id: 'call_1', name: 'db_query', args: { sql: 'SELECT 1;' } },
+            ],
+            response_metadata: { finish_reason: 'tool_calls' },
+          } as unknown as t.StreamChunk,
+        },
+        metadata,
+        graph
+      )
+    ).resolves.toBeUndefined();
+    expect(toolExecuteCalls).toHaveLength(0);
+  });
+
+  it('does not prestart eager tools when the breaker trips during tool-call handling', async () => {
+    const graph = createGraph();
+    const trip = new StreamLimitExceededError({
+      kind: 'tool_call_args',
+      limit: 10,
+      observed: 11,
+      toolName: 'db_query',
+    });
+    const originalDispatch = graph.dispatchRunStep;
+    graph.dispatchRunStep = (async (
+      stepKey: string,
+      details: unknown
+    ): Promise<string> => {
+      const stepId = await (
+        originalDispatch as unknown as (
+          stepKey: string,
+          details: unknown
+        ) => Promise<string>
+      )(stepKey, details);
+      graph.breakerAbort.abort(trip);
+      return stepId;
+    }) as typeof graph.dispatchRunStep;
+    const { toolExecuteCalls } = installToolExecuteResponder();
+    const handler = new ChatModelStreamHandler();
+    const metadata = { langgraph_node: 'agent' };
+
+    /** The trip lands while handleToolCalls awaits the run-step dispatch —
+     * after the queued-event guard already passed. The recheck before the
+     * eager path must stop the prestart. */
+    await expect(
+      handler.handle(
+        GraphEvents.CHAT_MODEL_STREAM,
+        {
+          chunk: {
+            content: '',
+            tool_calls: [
+              { id: 'call_1', name: 'db_query', args: { sql: 'SELECT 1;' } },
+            ],
+            response_metadata: { finish_reason: 'tool_calls' },
+          } as unknown as t.StreamChunk,
+        },
+        metadata,
+        graph
+      )
+    ).rejects.toBe(trip);
+    expect(toolExecuteCalls).toHaveLength(0);
+  });
+
+  it('sends a breaker-composed abort signal with eager prestart requests', async () => {
+    const graph = createGraph();
+    const { toolExecuteCalls } = installToolExecuteResponder();
+    const handler = new ChatModelStreamHandler();
+    const metadata = { langgraph_node: 'agent' };
+
+    await streamChunks({
+      handler,
+      graph,
+      metadata,
+      toolCallChunks: toToolCallChunks('call_1', 'db_query', [
+        '{"sql":"SELECT 1;"}',
+      ]),
+    });
+    await streamNextToolIndex({ handler, graph, metadata, callId: 'call_2' });
+
+    expect(toolExecuteCalls).toHaveLength(1);
+    const { signal } = toolExecuteCalls[0];
+    expect(signal).toBeDefined();
+    expect(signal?.aborted).toBe(false);
+
+    graph.breakerAbort.abort(new Error('stream limit breach'));
+    expect(signal?.aborted).toBe(true);
+  });
+
   it('the retry path no longer loops: every round executes normally with canonical args', async () => {
     const metadata = { langgraph_node: 'agent' };
     const guardErrors: string[] = [];

package/src/__tests__/stream.eagerEventExecution.test.ts

@@ -44,6 +44,7 @@ function createGraph(overrides: Partial<StandardGraph> = {}): StandardGraph {
       configurable: { user_id: 'user_1' },
       metadata: { run_id: 'run_1' },
     },
+    breakerAbort: new AbortController(),
     eagerEventToolExecution: { enabled: true },
     eagerEventToolExecutions: new Map(),
     eagerEventToolUsageCount: eagerUsageCount,