@librechat/agents 3.3.0 → 3.3.1

package/dist/types/llm/contextOverflowRecovery.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Recovery policy for provider context-overflow rejections.
+ *
+ * Detection (`@/utils/errors`) answers "was this an overflow, and what did
+ * the provider disclose?". This module answers the follow-up: "what budget
+ * should the retry target?" — deliberately kept as pure functions so the
+ * policy can be reasoned about and tested without a graph.
+ *
+ * On units: `maxContextTokens` is a **provider-space** budget. The pruner
+ * converts it into its own raw estimate space by dividing by the
+ * `calibrationRatio` it learns from reported usage. A provider-reported
+ * ceiling is therefore applied verbatim — converting it here as well would
+ * apply the same correction twice and prune toward roughly `limit / ratio²`,
+ * silently discarding far more history than the overflow called for.
+ *
+ * `observedCalibrationRatio` is returned separately so the caller can seed
+ * the pruner's conversion without folding the same correction into the
+ * provider-space budget.
+ */
+import type { ContextOverflowInfo } from '@/utils/errors';
+import type { Providers } from '@/common';
+/** Bound on forced-compaction retries per agent, per run. */
+export declare const DEFAULT_MAX_OVERFLOW_RECOVERIES = 2;
+export interface OverflowRecoveryPlan {
+    /** Budget the retry should target, in provider token units when known. */
+    budgetTokens?: number;
+    /** What the provider disclosed. Carried through for logging. */
+    info: ContextOverflowInfo;
+    /**
+     * Provider-reported message tokens divided by our own message estimate,
+     * when both are known. Greater than 1 means we under-count relative to this
+     * provider.
+     *
+     * Returned separately so the graph can seed the pruner's calibration;
+     * applying it to this plan's budget as well would double-count. Fixed
+     * instruction overhead is removed before deriving it from
+     * `info.promptTokens`, never `info.requestedTokens`, since several providers
+     * fold the completion allowance into the latter.
+     */
+    observedCalibrationRatio?: number;
+}
+export interface OverflowRecoveryParams {
+    error: unknown;
+    provider: Providers;
+    /** Budget in force when the rejected prompt was built. */
+    maxContextTokens?: number;
+    /** Our own estimate of the prompt we actually sent. */
+    estimatedPromptTokens?: number;
+    /** Provider/local calibration already applied to the prompt estimate. */
+    calibrationRatio?: number;
+    /**
+     * System prompt plus tool schemas — the part of the budget compaction
+     * cannot touch. A corrected budget at or below this leaves no room for
+     * messages, and the summarize node refuses to run, so recovery is declined
+     * rather than entered.
+     */
+    instructionTokens?: number;
+    /** Whether a model-backed summary can compact messages without a pruner. */
+    canSummarize?: boolean;
+    /**
+     * Completion allowance the caller configured. Providers count it against
+     * the same ceiling, so it has to come off the top when the error itself did
+     * not break the total down.
+     */
+    configuredCompletionTokens?: number;
+    /** Recoveries already attempted for this agent in this run. */
+    attemptsSoFar: number;
+    maxAttempts?: number;
+}
+/**
+ * Converts a provider-space retry budget into the units consumed by a pruner
+ * calibrated for another provider while preserving the same raw-token limit.
+ */
+export declare function translateRecoveryBudget(budgetTokens: number | undefined, sourceCalibrationRatio: number | undefined, targetCalibrationRatio: number | undefined): number | undefined;
+/** Applies the conservative shrink used when no provider-space ceiling is usable. */
+export declare function getBlindRecoveryBudget(maxContextTokens: number | undefined): number | undefined;
+/**
+ * Decides whether a failed model call is a recoverable context overflow and,
+ * if so, what budget the retry should be re-pruned against.
+ *
+ * Returns `null` when the error is something compaction cannot fix, or when
+ * the per-run recovery budget is spent — in both cases the caller should let
+ * its normal failure handling proceed.
+ */
+export declare function planContextOverflowRecovery({ error, provider, maxContextTokens, estimatedPromptTokens, calibrationRatio, instructionTokens, canSummarize, configuredCompletionTokens, attemptsSoFar, maxAttempts, }: OverflowRecoveryParams): OverflowRecoveryPlan | null;

package/dist/types/llm/invoke.d.ts

@@ -2,6 +2,7 @@ import { AIMessageChunk } from '@langchain/core/messages';
 import type { RunnableConfig } from '@langchain/core/runnables';
 import type { BaseMessage } from '@langchain/core/messages';
 import type { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
+import type { ContextOverflowContext } from '@/utils/errors';
 import type * as t from '@/types';
 import { Providers } from '@/common';
 import { ChatModelStreamHandler } from '@/stream';
@@ -56,19 +57,47 @@ export declare function attemptInvoke({ model, messages, provider, context, onCh
     context?: InvokeContext;
     onChunk?: OnChunk;
 }, config?: RunnableConfig): Promise<Partial<t.BaseGraphState>>;
+/**
+ * Identifies which fallback produced an error, so a caller planning a
+ * recovery can reason about the client that actually failed rather than the
+ * primary's configuration — their context windows and output allowances
+ * differ, which is the whole reason a fallback exists.
+ */
+export interface FallbackErrorContext {
+    provider: Providers;
+    clientOptions?: t.ClientOptions;
+    maxContextTokens?: number;
+}
+export interface FallbackOverflowCandidate {
+    error: unknown;
+    context: FallbackErrorContext;
+}
+/** Reads back the fallback attribution attached by `tryFallbackProviders`. */
+export declare function getFallbackErrorContext(error: unknown): FallbackErrorContext | undefined;
+/** Returns every fallback overflow retained from an exhausted provider chain. */
+export declare function getFallbackOverflowCandidates(error: unknown): FallbackOverflowCandidate[];
 /**
  * Attempts each fallback provider in order until one succeeds.
- * Throws the last error if all fallbacks fail.
+ *
+ * When every fallback fails, a context overflow among them is thrown in
+ * preference to whichever failure happened to come last. An overflow is the
+ * one failure the caller can act on — it compacts and retries — and losing it
+ * behind a later unrelated error would surface a dead end instead. Ordinary
+ * failures still throw last-error-wins.
  */
-export declare function tryFallbackProviders({ fallbacks, tools, messages, config, primaryError, context, onChunk, }: {
-    fallbacks: Array<{
-        provider: Providers;
-        clientOptions?: t.ClientOptions;
-    }>;
+export declare function tryFallbackProviders({ fallbacks, tools, messages, config, primaryError, context, onChunk, overflowContext, }: {
+    fallbacks: t.FallbackConfig[];
     tools?: t.GraphTools;
     messages: BaseMessage[];
     config?: RunnableConfig;
     primaryError: unknown;
     context?: InvokeContext;
     onChunk?: OnChunk;
+    /**
+     * Prompt-size corroboration for signatures that are not self-describing.
+     * Vertex AI's overflow is a bare `400` with no reason, so without this a
+     * fallback that overflows is indistinguishable from any other 400 and would
+     * be dropped in favour of whichever failure came last.
+     */
+    overflowContext?: ContextOverflowContext;
 }): Promise<Partial<t.BaseGraphState> | undefined>;

package/dist/types/messages/prune.d.ts

@@ -15,6 +15,13 @@ export declare const ORIGINAL_CONTENT_MAX_CHARS = 2000000;
  * recency carry-over bypasses that cap unless re-applied here.
  */
 export declare function enforceOriginalContentCap(map: Map<number, string>): void;
+/** Minimum cumulative calibration ratio — provider can't count fewer tokens
+ *  than our raw estimate (within reason). Prevents divide-by-zero edge cases. */
+export declare const CALIBRATION_RATIO_MIN = 0.5;
+/** Maximum cumulative calibration ratio — sanity cap for the running ratio. */
+export declare const CALIBRATION_RATIO_MAX = 5;
+/** Keeps provider/local token calibration within the shared safe range. */
+export declare function clampCalibrationRatio(ratio: number): number;
 export type PruneMessagesFactoryParams = {
     provider?: Providers;
     maxTokens: number;
@@ -172,8 +179,8 @@ export declare function maskConsumedToolResults(params: {
     /** When provided, original (pre-masking) content is stored here keyed by
      *  message index — only for entries that actually get truncated. */
     originalContentStore?: Map<number, string>;
-    /** Called after storing content with the char length of the stored entry. */
-    onContentStored?: (charLength: number) => void;
+    /** Called after storing a newly captured entry. */
+    onContentStored?: (index: number, content: string) => void;
 }): number;
 /**
  * Pre-flight truncation: truncates oversized ToolMessage content before the
@@ -219,6 +226,7 @@ export declare function createPruneMessages(factoryParams: PruneMessagesFactoryP
     remainingContextTokens?: number;
     contextPressure?: number;
     originalToolContent?: Map<number, string>;
+    newOriginalToolContent?: Map<number, string>;
     calibrationRatio?: number;
     resolvedInstructionOverhead?: number;
     /** Usable budget this call: maxTokens minus output reserve */

package/dist/types/messages/recency.d.ts

@@ -1,4 +1,5 @@
 import type { BaseMessage } from '@langchain/core/messages';
+export declare const DEFAULT_RETAIN_RECENT_TURNS = 2;
 /**
  * Configuration for splitting a message list into a head (to be summarized)
  * and a tail (to be preserved verbatim).

package/dist/types/run.d.ts

@@ -41,6 +41,8 @@ export declare class Run<_T extends t.BaseGraphState> {
     private _interrupt;
     /** Per-run sequence for batch-unique activity-label trace-seed fallbacks. */
     private activityLabelSeq;
+    /** Distinguishes sibling forks started from the same explicit checkpoint. */
+    private checkpointForkSeq;
     private _haltedReason;
     private constructor();
     private createLegacyGraph;

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

@@ -32,8 +32,21 @@ export declare const CodeExecutionToolSchema: {
     };
     readonly required: readonly ["lang", "code"];
 };
+export declare const CODE_API_UNAVAILABLE_ERROR_MESSAGE = "Code execution is temporarily unavailable. Please retry.";
+export declare const CODE_API_AUTHORIZATION_ERROR_MESSAGE = "Code execution is not authorized. Verify access before trying again.";
+export declare const CODE_API_EXECUTION_FAILED_ERROR_MESSAGE = "Code execution failed.";
+export declare const CODE_API_INVALID_REQUEST_ERROR_MESSAGE = "The code execution request was rejected. Please check the tool input and try again.";
+export declare const CODE_API_RATE_LIMITED_ERROR_MESSAGE = "Code execution is temporarily rate-limited. Please retry shortly.";
+export declare class CodeApiRequestError extends Error {
+    constructor(message?: string);
+}
+export declare function normalizeCodeApiRequestError(error: unknown): CodeApiRequestError;
+export declare function buildCodeApiExecutionErrorMessage(response: {
+    error?: unknown;
+    stderr?: unknown;
+}): string;
 export declare function resolveCodeApiAuthHeaders(authHeaders?: t.CodeApiAuthHeaders): Promise<t.CodeApiAuthHeaderMap>;
-export declare function buildCodeApiHttpErrorMessage(method: string, endpoint: string, response: {
+export declare function buildCodeApiHttpErrorMessage(_method: string, _endpoint: string, response: {
     status: number;
     text: () => Promise<string>;
 }): Promise<string>;

package/dist/types/types/llm.d.ts

@@ -103,12 +103,15 @@ export type SharedLLMConfig = {
     provider: Providers;
     _lc_stream_delay?: number;
 };
+export interface FallbackConfig {
+    provider: Providers;
+    clientOptions?: ClientOptions;
+    /** Context window used to corroborate ambiguous fallback overflow errors. */
+    maxContextTokens?: number;
+}
 export type LLMConfig = SharedLLMConfig & ClientOptions & {
     /** Optional provider fallbacks in order of attempt */
-    fallbacks?: Array<{
-        provider: Providers;
-        clientOptions?: ClientOptions;
-    }>;
+    fallbacks?: FallbackConfig[];
 };
 export type ProviderOptionsMap = {
     [Providers.AZURE]: AzureClientOptions;

package/dist/types/types/stream.d.ts

@@ -40,13 +40,14 @@ export type RunStep = {
     runId?: string;
     agentId?: string;
     /**
-     * Group ID - incrementing number (1, 2, 3...) reflecting execution order.
-     * Agents with the same groupId run in parallel and should be rendered together.
-     * undefined means the agent runs sequentially (not part of any parallel group).
+     * Opaque positive safe-integer identifier for parallel execution.
+     * Agents with the same groupId should be rendered together.
+     * Consumers must use content indexes, not groupId ordering, for execution order.
+     * undefined means the agent runs sequentially (not part of a parallel group).
      *
      * Example for: researcher -> [analyst1, analyst2, analyst3] -> summarizer
      * - researcher: undefined (sequential)
-     * - analyst1, analyst2, analyst3: 1 (first parallel group)
+     * - analyst1, analyst2, analyst3: the same groupId (parallel group)
      * - summarizer: undefined (sequential)
      */
     groupId?: number;

package/dist/types/types/summarize.d.ts

@@ -54,6 +54,28 @@ export interface SummarizeResult {
 export interface SummarizationNodeInput {
     remainingContextTokens: number;
     agentId: string;
+    /**
+     * Why the detour was requested.
+     *
+     * - `trigger` (default): the configured summarization trigger fired during
+     *   the pre-call budget check.
+     * - `overflow`: the provider rejected the prompt as too large and the run
+     *   is compacting to recover. When summarization is not enabled, this
+     *   variant performs no model call — the corrected budget alone is what the
+     *   retry needs.
+     */
+    reason?: 'trigger' | 'overflow';
+    /**
+     * Whether an overflow recovery may spend a summarization model call.
+     *
+     * The first recovery deliberately does not: re-pruning against the
+     * corrected budget raises context pressure, which drives the pruner's
+     * existing tool-output compression and masking. That is cheaper, needs no
+     * model call, and cannot lose message content the way a summary can. Only
+     * when deterministic compression proves insufficient does the next attempt
+     * allow the summarizer to run.
+     */
+    allowSummarization?: boolean;
 }
 export interface SummarizeStartEvent {
     agentId: string;

package/dist/types/utils/__tests__/fixtures/contextOverflowSignatures.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Provider error signatures captured from live over-limit requests.
+ *
+ * Every entry below was produced by `src/scripts/context-overflow-probe.ts`
+ * sending a prompt past the model's context window and recording what came
+ * back. Account identifiers and request ids have been replaced with
+ * placeholders; the wording, status codes, and nesting are verbatim.
+ *
+ * Treat these as evidence, not examples: if a provider changes its wording,
+ * re-run the probe and update the fixture rather than loosening the matcher.
+ */
+import { Providers } from '@/common';
+export interface OverflowSignature {
+    provider: Providers;
+    model: string;
+    /** Class the SDK actually threw, for reference in review. */
+    thrownAs: string;
+    /**
+     * Stand-in for the thrown error carrying exactly the fields the classifier
+     * reads. Nested bodies are kept as the strings the SDKs attach.
+     */
+    error: Record<string, unknown>;
+    expected: {
+        kind: 'context_window' | 'request_too_large';
+        limitTokens?: number;
+        requestedTokens?: number;
+    };
+    /** Set when the signature is only decidable with caller-side corroboration. */
+    requiresContextPressure?: boolean;
+}
+export declare const OVERFLOW_SIGNATURES: readonly OverflowSignature[];
+/**
+ * Errors that mention limits, sizes, or tokens but are NOT fixed by
+ * compaction. The first two were captured live alongside the signatures
+ * above; the rest are the adjacent failures a loose matcher would swallow.
+ */
+export declare const NON_OVERFLOW_SIGNATURES: readonly {
+    label: string;
+    error: Record<string, unknown>;
+}[];

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

@@ -1,28 +1,77 @@
+import type { Providers } from '@/common';
 /**
- * Context overflow error detection utilities.
- *
- * Identifies provider-specific error messages that indicate the request
- * exceeded the model's context window. Used by the overflow recovery loop
- * to decide whether to retry with truncation/compaction vs. propagating
- * the error.
+ * Why the request was rejected. Both kinds are fixed by shrinking the
+ * prompt, which is what makes them recoverable; they are distinguished
+ * because only `context_window` tells us the model's true window.
+ */
+export type ContextOverflowKind = 
+/** Input exceeded the model's context window. */
+'context_window'
+/**
+ * A single request exceeded a per-minute token allowance. Waiting cannot
+ * help — the request can never fit the bucket — so this is a payload
+ * problem wearing a 429, not throttling.
  */
+ | 'request_too_large';
+export interface ContextOverflowInfo {
+    kind: ContextOverflowKind;
+    /** Ceiling the provider reported, when it named one. */
+    limitTokens?: number;
+    /**
+     * Token count the provider attributed to the whole request. Several
+     * providers fold the requested completion allowance into this number, so it
+     * is not interchangeable with the prompt size.
+     */
+    requestedTokens?: number;
+    /**
+     * The prompt alone, counted by the provider — set only when the provider
+     * distinguished input from output, either by reporting an input-only figure
+     * or by breaking the total down. Callers comparing provider counts against
+     * their own prompt estimate must use this and not `requestedTokens`, whose
+     * completion component would inflate the comparison.
+     */
+    promptTokens?: number;
+    /** Which layer produced the verdict. Surfaced in logs and asserted in tests. */
+    source: 'langchain' | 'pattern';
+    provider?: Providers;
+}
+export interface ContextOverflowContext {
+    provider?: Providers;
+    /** Our own estimate of the prompt size for the call that failed. */
+    estimatedPromptTokens?: number;
+    /** The budget we believed applied when we built that prompt. */
+    maxContextTokens?: number;
+}
 /**
  * Extracts a human-readable error message from an unknown error value.
  */
 export declare function extractErrorMessage(error: unknown): string;
 /**
- * Returns true if the error message definitively indicates a context
- * overflow / prompt-too-large error from the provider.
+ * Classifies a provider error as a recoverable context overflow, returning
+ * whatever the provider disclosed about the limit and the request size.
+ *
+ * Returns `null` for anything that compaction cannot fix — genuine
+ * throttling, auth, quota, and output-token-cap errors all mention limits
+ * and must not be mistaken for overflow.
+ *
+ * The reported numbers are the point of the return value: they let the
+ * caller retarget the token budget to the provider's real ceiling instead of
+ * retrying blindly against a configured value that was evidently wrong.
+ */
+export declare function getContextOverflowInfo(error: unknown, context?: ContextOverflowContext): ContextOverflowInfo | null;
+/**
+ * Returns true if the error definitively indicates a context overflow.
  *
- * This is the strict check: only matches known, unambiguous phrases.
- * Use this when you want high confidence before taking recovery action.
+ * Accepts either a raw error or a pre-extracted message; passing the error
+ * itself is preferred, since several providers report the decisive detail in
+ * a nested body rather than in `message`.
  */
-export declare function isContextOverflowError(errorMessage?: string): boolean;
+export declare function isContextOverflowError(error?: unknown, context?: ContextOverflowContext): boolean;
 /**
- * Returns true if the error message likely indicates a context overflow.
- * Uses broader heuristic matching (regex) in addition to exact phrases.
+ * Returns true if the error likely indicates a context overflow, adding
+ * body-size and token-count heuristics on top of the definitive patterns.
  *
- * May produce false positives for unusual error messages. Use this when
- * the cost of a false positive (one extra retry) is acceptable.
+ * May produce false positives on unusual messages. Use when the cost of
+ * being wrong is one extra compaction pass.
  */
-export declare function isLikelyContextOverflowError(errorMessage?: string): boolean;
+export declare function isLikelyContextOverflowError(error?: unknown, context?: ContextOverflowContext): boolean;

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

@@ -0,0 +1,3 @@
+export declare function isSecretKey(key: string): boolean;
+/** Recursively removes credentials from structured diagnostic payloads. */
+export declare function redactSecrets(value: unknown, seen?: WeakSet<object>): unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@librechat/agents",
-  "version": "3.3.0",
+  "version": "3.3.1",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -140,6 +140,7 @@
     "search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/search.ts --provider 'bedrock' --name 'Jo' --location 'New York, NY'",
     "tool_search": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/tool_search.ts",
     "bench:cache": "node --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/bench-prompt-cache.ts",
+    "probe:overflow": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/context-overflow-probe.ts",
     "subagent": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/multi-agent-subagent.ts",
     "subagent:events": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/subagent-event-driven-debug.ts",
     "subagent:tools": "node -r dotenv/config --loader ./tsconfig-paths-bootstrap.mjs --experimental-specifier-resolution=node ./src/scripts/subagent-tools-debug.ts",
@@ -205,11 +206,9 @@
       "openai": "$openai"
     },
     "uuid": "$uuid",
-    "fast-xml-parser": "5.7.2",
     "ajv": "6.14.0",
-    "minimatch": "3.1.4",
     "@opentelemetry/core": "^2.9.0",
-    "js-yaml": "^4.2.0"
+    "js-yaml": "^4.3.0"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.103.0",
@@ -235,7 +234,7 @@
     "@scarf/scarf": "^1.4.0",
     "@types/diff": "^7.0.2",
     "ai-tokenizer": "^1.0.6",
-    "axios": "^1.16.0",
+    "axios": "^1.18.1",
     "cheerio": "^1.0.0",
     "diff": "^9.0.0",
     "dotenv": "^16.4.7",
@@ -247,7 +246,7 @@
     "uuid": "^11.1.1"
   },
   "peerDependencies": {
-    "@anthropic-ai/sandbox-runtime": "^0.0.54"
+    "@anthropic-ai/sandbox-runtime": "^0.0.67"
   },
   "peerDependenciesMeta": {
     "@anthropic-ai/sandbox-runtime": {
@@ -259,7 +258,7 @@
     "~/*": "./*"
   },
   "devDependencies": {
-    "@anthropic-ai/sandbox-runtime": "^0.0.54",
+    "@anthropic-ai/sandbox-runtime": "^0.0.67",
     "@anthropic-ai/vertex-sdk": "^0.12.0",
     "@eslint/compat": "^1.2.7",
     "@langchain/langgraph-checkpoint-mongodb": "^1.4.0",
@@ -270,7 +269,7 @@
     "@types/yargs-parser": "^21.0.3",
     "@typescript-eslint/eslint-plugin": "^8.24.0",
     "@typescript-eslint/parser": "^8.24.0",
-    "eslint": "^9.39.1",
+    "eslint": "^9.39.5",
     "eslint-import-resolver-typescript": "^3.7.0",
     "eslint-plugin-import": "^2.31.0",
     "husky": "^9.1.7",