@librechat/agents 3.2.68 → 3.3.1

package/dist/types/graphs/Graph.d.ts

@@ -9,7 +9,7 @@ import { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
 import { AgentContext } from '@/agents/AgentContext';
 import { HandlerRegistry } from '@/events';
 export declare abstract class Graph<T extends t.BaseGraphState = t.BaseGraphState, _TNodeName extends string = string> {
-    abstract resetValues(): void;
+    abstract resetValues(keepContent?: boolean, checkpointScope?: string): void;
     abstract initializeTools({ currentTools, currentToolMap, }: {
         currentTools?: t.GraphTools;
         currentToolMap?: t.ToolMap;
@@ -173,9 +173,13 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     overrideModel?: t.ChatModel;
     /** Optional compile options passed into workflow.compile() */
     compileOptions?: t.CompileOptions | undefined;
+    /** Whether the workflow was actually compiled with a checkpointer. */
+    hasCompiledCheckpointer: boolean;
     messages: BaseMessage[];
     /** Cached run messages preserved before clearHeavyState() so getRunMessages() works after cleanup. */
     private cachedRunMessages?;
+    /** Checkpoint scope whose messages match index-keyed tool snapshots. */
+    private originalToolContentCheckpointScope?;
     runId: string | undefined;
     /**
      * Boundary between historical messages (loaded from conversation state)
@@ -200,7 +204,7 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     /** See {@link t.StandardGraphInput.subagentScope}. */
     subagentScope: boolean;
     constructor({ runId, signal, agents, langfuse, tokenCounter, indexTokenCountMap, calibrationRatio, subagentUsageSink, subagentScope, }: t.StandardGraphInput);
-    resetValues(keepContent?: boolean): void;
+    resetValues(keepContent?: boolean, checkpointScope?: string): void;
     clearHeavyState(): void;
     getRunStep(stepId: string): t.RunStep | undefined;
     getAgentContext(metadata: Record<string, unknown> | undefined): AgentContext;
@@ -242,6 +246,15 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
     overrideTestModel(responses: string[], sleep?: number, toolCalls?: ToolCall[]): void;
     getUsageMetadata(finalMessage?: BaseMessage): Partial<UsageMetadata> | undefined;
     cleanupSignalListener(currentModel?: t.ChatModel): void;
+    /**
+     * Applies a context-overflow recovery plan and hands control to the
+     * summarize node, which compacts and then routes straight back here for a
+     * retry against the corrected budget.
+     *
+     * Returning the detour rather than rethrowing is the whole point: the
+     * caller never sees the provider's rejection, only a slightly longer turn.
+     */
+    private beginOverflowRecovery;
     createCallModel(agentId?: string): (state: t.AgentSubgraphState, config?: RunnableConfig) => Promise<Partial<t.AgentSubgraphState>>;
     createAgentNode(agentId: string): t.CompiledAgentWorfklow;
     createWorkflow(): t.CompiledStateWorkflow;
@@ -259,6 +272,7 @@ export declare class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode>
      * @returns undefined for StandardGraph (no parallel groups), or group number for MultiAgentGraph
      */
     protected getParallelGroupIdForAgent(_agentId: string): number | undefined;
+    protected resolveParallelGroupId(agentId: string, metadata?: Record<string, unknown>): number | undefined;
     /**
      * Dispatches a run step to the client, returns the step ID
      */

package/dist/types/graphs/MultiAgentGraph.d.ts

@@ -19,6 +19,7 @@ export declare class MultiAgentGraph extends StandardGraph {
     private startingNodes;
     private directEdges;
     private handoffEdges;
+    private handoffPromptLabels;
     /**
      * Map of agentId to parallel group info.
      * Contains groupId (incrementing number reflecting execution order) for agents in parallel groups.

package/dist/types/langfuseToolOutputTracing.d.ts

@@ -4,6 +4,10 @@ import type { ResolvedLangfuseToolOutputTracingConfig } from '@/langfuseRuntimeC
 import type * as t from '@/types';
 import { LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT, resolveLangfuseConfig } from '@/langfuseConfig';
 export { LANGFUSE_TOOL_OUTPUT_REDACTION_TEXT, resolveLangfuseConfig };
+/** Whether a tool's outputs are excluded from tracing (global disable or
+ *  `redactedToolNames` match). Exported for the activity-label prompt
+ *  builder, whose prompt becomes Langfuse generation input. */
+export declare function shouldRedactTool(toolName: string | undefined, config: ResolvedLangfuseToolOutputTracingConfig): boolean;
 export declare function classifyLangfuseToolNodeSpan(span: ReadableSpan): void;
 export declare function redactLangfuseSpanToolOutputs(span: ReadableSpan, config: ResolvedLangfuseToolOutputTracingConfig): void;
 export declare function createLangfuseSpanProcessor(params?: LangfuseSpanProcessorParams, runLangfuse?: t.LangfuseConfig, agentLangfuse?: t.LangfuseConfig): SpanProcessor;

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/format.d.ts

@@ -178,4 +178,26 @@ export declare function shiftIndexTokenCountMap(indexTokenCountMap: Record<numbe
  * @returns The messages array with tool sequences converted to buffer strings if necessary
  */
 export declare function ensureThinkingBlockInMessages(messages: BaseMessage[], _provider: Providers, config?: RunnableConfig, runStartIndex?: number): BaseMessage[];
+/**
+ * Folds tool_use / tool_result content into plain text for an agent that binds
+ * no tools.
+ *
+ * In a multi-agent graph, a tool-less destination still inherits the prior
+ * agent's conversation history, which can contain toolUse/toolResult blocks.
+ * Because it binds no tools, the model is invoked with no tool schema — and
+ * Bedrock's Converse API rejects any request that carries toolUse/toolResult
+ * blocks without a top-level toolConfig ("The toolConfig field must be defined
+ * when using toolUse and toolResult content blocks"). Adding a dummy toolConfig
+ * is not an option: AWS requires at least one tool, and it would expose a
+ * capability the destination was intentionally denied.
+ *
+ * Each tool-call turn plus its trailing tool results (ToolMessages or
+ * `tool_result` content blocks) is collapsed into a single `[Previous tool
+ * interaction]` HumanMessage that preserves the tool name, arguments and result
+ * as text (image blocks are kept as-is). Runs in a single pass: non-tool
+ * messages pass through, `result` is allocated lazily on the first fold, and the
+ * original array is returned unchanged when it holds no tool content (the common
+ * fresh-tool-less-agent case).
+ */
+export declare function foldToolBlocksForToollessAgent(messages: BaseMessage[], config?: RunnableConfig): BaseMessage[];
 export {};

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/prompts/activityLabel.d.ts

@@ -0,0 +1,31 @@
+import type { ResolvedLangfuseToolOutputTracingConfig } from '@/langfuseRuntimeContext';
+import type { ActivityLabelToolEntry } from '@/types/activityLabel';
+/**
+ * Default system prompt for fast-model activity labeling.
+ *
+ * Style synthesized from Claude Code's tool-use summary prompt (git-subject
+ * register, past tense, distinctive nouns) and claude.ai's observed group
+ * headers (5–9 words describing a mixed reasoning + tool block, e.g.
+ * "Synthesized version data and curated comparative framework").
+ */
+export declare const ACTIVITY_LABEL_PROMPT = "Write a short label describing what this block of agent activity accomplished. It appears as the header of a collapsed activity group in a chat UI.\n\nRules:\n- 5 to 9 words, past-tense verb first\n- Name the most distinctive subject (file, API, topic); drop articles and filler\n- Describe outcomes, not mechanics; if something failed, say so plainly\n- Output only the label \u2014 no quotes, no punctuation at the end, no preamble\n\nExamples:\n- Searched Node.js release notes and changelogs\n- Compared runtime versions across official sources\n- Fixed failing auth middleware tests\n- Read project config and dependency manifests\n- Attempted database migration, hit permission errors";
+/** Truncates a serialized value for the label prompt. */
+export declare function truncateForLabel(value: string, maxLength: number): string;
+export type BuildActivityLabelPromptParams = {
+    entries: ActivityLabelToolEntry[];
+    charLimit: number;
+    thinkingExcerpts?: string[];
+    lastAssistantText?: string;
+    /**
+     * Resolved tool-output tracing policy. The label prompt becomes Langfuse
+     * generation input, so outputs/errors excluded from tracing (global
+     * disable or `redactedToolNames`) must never appear in it — the same
+     * redaction the span processor applies to structured tool observations.
+     */
+    redaction?: ResolvedLangfuseToolOutputTracingConfig;
+};
+/**
+ * Builds the user prompt for a fast-model activity label. Pure — exported
+ * for direct testing of redaction and truncation behavior.
+ */
+export declare function buildActivityLabelPrompt({ entries, charLimit, thinkingExcerpts, lastAssistantText, redaction, }: BuildActivityLabelPromptParams): string;

package/dist/types/run.d.ts

@@ -39,6 +39,10 @@ export declare class Run<_T extends t.BaseGraphState> {
      * lets callers assert the type they expect.
      */
     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;
@@ -207,4 +211,16 @@ export declare class Run<_T extends t.BaseGraphState> {
         language?: string;
         title?: string;
     }>;
+    /**
+     * Generates a short activity label for a completed tool/reasoning block
+     * using a fast model. Mirrors `generateTitle`'s Langfuse wiring so the
+     * call is traced under the conversation's session (sessionId from
+     * `chainOptions.configurable.thread_id`) with its own tags — never as an
+     * orphan trace. The payload contains no human messages by design: intent
+     * comes from `lastAssistantText`, content from reasoning excerpts and
+     * tool entries.
+     */
+    generateActivityLabel({ provider, clientOptions, entries, thinkingExcerpts, lastAssistantText, prompt, charLimit, chainOptions, traceSeed, agentId, }: t.RunActivityLabelOptions): Promise<{
+        label?: string;
+    }>;
 }

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/activityLabel.d.ts

@@ -0,0 +1,53 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { ClientOptions } from '@/types/llm';
+import type { Providers } from '@/common';
+/** One tool call's contribution to the label payload (host-assembled). */
+export type ActivityLabelToolEntry = {
+    toolName: string;
+    toolInput: unknown;
+    toolOutput?: unknown;
+    error?: string;
+    status: 'success' | 'error';
+};
+/**
+ * Options for `Run.generateActivityLabel`. The payload deliberately contains
+ * NO human messages: intent context comes from the assistant's own last text
+ * (Claude Code's pattern) and the block's reasoning excerpts (claude.ai's
+ * pattern) — user text stays out of this low-scrutiny pathway entirely.
+ *
+ * This SDK defines NO activity-label graph event and never dispatches one.
+ * Label lifecycle streaming is entirely host-owned: a host claims its own
+ * content slots and emits on its own transport, with a payload shape only
+ * it defines. The SDK surface here is exactly this method plus the
+ * `activity_label` content type's formatter exclusions.
+ */
+export type RunActivityLabelOptions = {
+    provider: Providers;
+    clientOptions?: ClientOptions;
+    /**
+     * Agent that executed the labeled batch. Selects that agent's Langfuse
+     * overlay (trace metadata AND tool-output redaction policy) instead of
+     * the graph default — a stricter per-agent policy must not be bypassed
+     * by labeling work the default agent never performed.
+     */
+    agentId?: string;
+    entries: ActivityLabelToolEntry[];
+    /** Truncated reasoning excerpts from the block being labeled. */
+    thinkingExcerpts?: string[];
+    /** Assistant's last text before the block (~200 chars), as intent context. */
+    lastAssistantText?: string;
+    /** Override for the default label system prompt. */
+    prompt?: string;
+    /** Per-entry serialization cap for the prompt. Default 600. */
+    charLimit?: number;
+    /** LangChain runnable config carrier (signal, callbacks, thread/user ids). */
+    chainOptions?: Partial<RunnableConfig> & {
+        configurable?: Record<string, unknown>;
+    };
+    /**
+     * Seed for deterministic Langfuse trace ids (e.g. `${runId}-${slotIndex}`)
+     * so each batch's label gets a distinct, reproducible trace. When omitted,
+     * a per-run sequence keeps batches from collapsing into one trace.
+     */
+    traceSeed?: string;
+};

package/dist/types/types/index.d.ts

@@ -7,3 +7,4 @@ export * from './skill';
 export * from './stream';
 export * from './tools';
 export * from './summarize';
+export * from './activityLabel';

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;
@@ -138,6 +139,8 @@ export interface ExtendedMessageContent {
     type?: string;
     text?: string;
     input?: string;
+    /** Tool-call arguments on a v1 standard-content `tool_call` block. */
+    args?: ToolCallPart['args'];
     index?: string | number;
     id?: string;
     name?: string;

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>;
+}[];