@librechat/agents 3.4.0 → 3.4.2

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

@@ -30,6 +30,31 @@ export declare class CohereReranker extends BaseReranker {
     } & t.HttpAgentConfig);
     rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
 }
+/**
+ * Calls the public `danny-avila/rag_api` `/v1/rerank` endpoint (the
+ * `fast-v1` profile). Auth is supplied per call by a token supplier (a
+ * short-lived JWT minted by the host app) rather than a static key. A
+ * reranker failure must never throw into the search flow: on a missing
+ * base URL/token supplier, a timeout (covering token acquisition as well as
+ * the request), a non-2xx response, or any malformed payload, this falls back
+ * to the candidates' original order via {@link BaseReranker.getDefaultRanking}.
+ */
+export declare class RagApiReranker extends BaseReranker {
+    private baseUrl?;
+    private tokenSupplier?;
+    private profile;
+    private timeout;
+    private httpAgent?;
+    private httpsAgent?;
+    constructor({ baseUrl, tokenSupplier, profile, timeout, logger, httpAgent, httpsAgent, }: {
+        baseUrl?: string;
+        tokenSupplier?: t.RagApiTokenSupplier;
+        profile?: string;
+        timeout?: number;
+        logger?: t.Logger;
+    } & t.HttpAgentConfig);
+    rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
+}
 export declare class InfinityReranker extends BaseReranker {
     constructor(logger?: t.Logger);
     rerank(query: string, documents: string[], topK?: number): Promise<t.Highlight[]>;
@@ -42,6 +67,9 @@ export declare const createReranker: (config: {
     jinaApiKey?: string;
     jinaApiUrl?: string;
     cohereApiKey?: string;
+    ragApiUrl?: string;
+    ragApiTokenSupplier?: t.RagApiTokenSupplier;
+    ragApiProfile?: string;
     rerankerTimeout?: number;
     logger?: t.Logger;
 } & t.HttpAgentConfig) => BaseReranker | undefined;

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

@@ -18,7 +18,7 @@ export interface BaseSearchProviderConfig extends HttpAgentConfig {
 }
 export type SearchProvider = 'serper' | 'searxng' | 'tavily' | 'keenable' | 'crw';
 export type ScraperProvider = 'firecrawl' | 'serper' | 'tavily' | 'crw' | 'keenable';
-export type RerankerType = 'infinity' | 'jina' | 'cohere' | 'none';
+export type RerankerType = 'infinity' | 'jina' | 'cohere' | 'rag-api' | 'none';
 export interface Highlight {
     score: number;
     text: string;
@@ -298,6 +298,34 @@ export interface CohereRerankerResponse {
         };
     };
 }
+/** Mints a short-lived JWT per call; rag_api tokens are never cached or
+ * reused across requests by the reranker itself. Receives the rerank
+ * deadline's `AbortSignal` so a supplier minting its token over the network
+ * can cancel that request when the deadline fires instead of leaving it
+ * running past its caller. The argument is optional: zero-argument suppliers
+ * remain valid. */
+export type RagApiTokenSupplier = (signal?: AbortSignal) => string | Promise<string>;
+export interface RagApiRerankCandidate {
+    id: string;
+    text: string;
+    base_score: number;
+}
+export interface RagApiRerankRequestBody {
+    profile: string;
+    query: string;
+    candidates: RagApiRerankCandidate[];
+    top_n: number;
+}
+export interface RagApiRerankResult {
+    id: string;
+    index: number;
+    score: number;
+}
+export interface RagApiRerankResponse {
+    profile: string;
+    model: string;
+    results: RagApiRerankResult[];
+}
 export type SafeSearchLevel = 0 | 1 | 2;
 export type Logger = WinstonLogger;
 export interface SearchToolConfig extends SearchConfig, ProcessSourcesConfig, FirecrawlConfig {
@@ -316,6 +344,15 @@ export interface SearchToolConfig extends SearchConfig, ProcessSourcesConfig, Fi
     jinaApiKey?: string;
     jinaApiUrl?: string;
     cohereApiKey?: string;
+    /** Base URL of the public `rag_api` service (`RAG_API_URL` env fallback).
+     * Requests post to `${ragApiUrl}/v1/rerank`. */
+    ragApiUrl?: string;
+    /** Resolves a short-lived rag_api JWT immediately before each rerank call.
+     * Required for the `'rag-api'` reranker type — without it, reranking falls
+     * back to default (unranked) ordering. */
+    ragApiTokenSupplier?: RagApiTokenSupplier;
+    /** rag_api rerank profile. Defaults to `'fast-v1'`. */
+    ragApiProfile?: string;
     rerankerType?: RerankerType;
     /** Timeout (ms) for rerank API requests. Defaults to 10,000. */
     rerankerTimeout?: number;

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

@@ -0,0 +1,171 @@
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { SubagentResumeExecution } from './SubagentReplay';
+export type SubagentExecutionAddressInput = {
+    threadId?: string;
+    parentToolCallId: string;
+    parentConfigurable?: Record<string, unknown>;
+};
+export type SubagentExecutionAddress = Readonly<{
+    key: string;
+    baseChildThreadId: string;
+    branchChildThreadId: string;
+    currentChildRunId: string;
+    explicitResumeAttempt: boolean;
+    parentToolCallId: string;
+    resumeAttemptId: string;
+}>;
+export type SubagentExecutionIdentity = Readonly<{
+    childRunId: string;
+    childThreadId: string;
+    approvalExecutionScope: string;
+}>;
+export interface SubagentExecutionPreparationLease {
+    readonly ownsCheckpoint: boolean;
+    readonly ownsCreatedCheckpoint: boolean;
+    readonly ownsApprovalScope: boolean;
+    readonly ownsCreatedApprovalScope: boolean;
+    assertOwned(): void;
+    markCheckpointCreated(cleanup: () => Promise<void>): void;
+    markApprovalScopeCreated(cleanup: () => Promise<void>): void;
+    release(): void;
+    rollback(cause: unknown, cleanup?: (lease: SubagentExecutionPreparationLease) => Promise<void>): Promise<never>;
+}
+export type PreparedSubagentExecutionIdentity = Readonly<{
+    identity: SubagentExecutionIdentity;
+    lease: SubagentExecutionPreparationLease;
+    commit?: (lease: SubagentExecutionPreparationLease) => void;
+    rollback?: (lease: SubagentExecutionPreparationLease) => Promise<void>;
+}>;
+export type SubagentDefinitionBinding = Readonly<{
+    subagentType?: string;
+    configId?: string;
+}>;
+export type SubagentInvocationBinding = Readonly<{
+    description: string;
+    subagentType: string;
+    configId?: string;
+}>;
+export type SubagentSettlementBinding = Readonly<{
+    definitionAuthority: 'provisional' | 'effective';
+    fingerprint: string;
+    invocation: SubagentInvocationBinding;
+    subagentType?: string;
+    configId?: string;
+}>;
+export type SubagentExecutionPhase = 'registered' | 'active' | 'interrupted' | 'failed' | 'completed' | 'invalidated';
+export interface ExecutionSnapshot<TResult, TResolvedConfig, TActiveRun> {
+    readonly address: SubagentExecutionAddress;
+    readonly phase: SubagentExecutionPhase;
+    readonly identity?: SubagentExecutionIdentity;
+    readonly binding?: SubagentDefinitionBinding;
+    readonly invocation?: SubagentInvocationBinding;
+    readonly settlement?: SubagentSettlementBinding;
+    readonly resumeExecution?: SubagentResumeExecution;
+    readonly activeRun?: TActiveRun;
+    readonly completedResult?: TResult;
+    readonly resolvedConfig?: TResolvedConfig;
+    readonly started: boolean;
+    readonly completed: boolean;
+    readonly resolvingIdentity: boolean;
+    readonly resolving: boolean;
+    readonly executing: boolean;
+    readonly settling: boolean;
+    readonly settled: boolean;
+}
+export type SubagentExecutionRegistryOptions = {
+    parentRunId: string;
+    parentAgentId?: string;
+    durable: boolean;
+};
+type ResumeSelection = {
+    parentToolCallIds?: ReadonlySet<string>;
+    config?: RunnableConfig;
+};
+export declare function getSubagentApprovalExecutionScope(childRunId: string, resumeAttemptId: string): string;
+export declare class SubagentExecutionInvalidatedError extends Error {
+    constructor();
+}
+export declare class SubagentDefinitionBindingError extends Error {
+    constructor();
+}
+export declare class SubagentInvocationBindingError extends Error {
+    constructor();
+}
+export declare class SubagentSettlementBindingError extends Error {
+    constructor();
+}
+/** In-process source of truth for one Durable Subagent Execution. */
+export declare class SubagentExecutionRecord<TResult, TResolvedConfig, TActiveRun, TSettledOutput = never> {
+    readonly address: SubagentExecutionAddress;
+    private identityValue?;
+    private bindingValue?;
+    private bindingAuthority?;
+    private invocationValue?;
+    private settlementValue?;
+    private settledOutputValue?;
+    private resumeExecutionValue?;
+    private activeRunValue?;
+    private completedResultValue?;
+    private resolvedConfigValue?;
+    private pendingIdentityResolution?;
+    private pendingConfigResolution?;
+    private pendingExecution?;
+    private pendingSettlement?;
+    private phaseValue;
+    private startedValue;
+    private completedValue;
+    private settledValue;
+    constructor(address: SubagentExecutionAddress, resumeExecution?: SubagentResumeExecution);
+    get snapshot(): ExecutionSnapshot<TResult, TResolvedConfig, TActiveRun>;
+    get identity(): SubagentExecutionIdentity | undefined;
+    get binding(): SubagentDefinitionBinding | undefined;
+    get resumeExecution(): SubagentResumeExecution | undefined;
+    get invocation(): SubagentInvocationBinding | undefined;
+    get activeRun(): TActiveRun | undefined;
+    get settlement(): SubagentSettlementBinding | undefined;
+    get settledOutput(): TSettledOutput | undefined;
+    get completedResult(): TResult | undefined;
+    get resolvedConfig(): TResolvedConfig | undefined;
+    get started(): boolean;
+    get completed(): boolean;
+    assertUsable(signal?: AbortSignal): void;
+    attachResumeExecution(resumeExecution?: SubagentResumeExecution): void;
+    bindIdentity(identity: SubagentExecutionIdentity): void;
+    resolveIdentity(resolve: () => Promise<PreparedSubagentExecutionIdentity>): Promise<SubagentExecutionIdentity>;
+    bindDefinition(binding: SubagentDefinitionBinding, authority: 'provisional' | 'effective'): void;
+    resolveConfig(resolve: () => Promise<TResolvedConfig>, signal: AbortSignal): Promise<TResolvedConfig>;
+    execute(invocation: SubagentInvocationBinding, execute: () => Promise<TResult>): Promise<TResult>;
+    settle(settlement: SubagentSettlementBinding, settledOutput: TSettledOutput, persist: () => Promise<void>): Promise<void>;
+    activate(activeRun: TActiveRun): TActiveRun;
+    markStarted(): void;
+    markInterrupted(): void;
+    markFailed(): void;
+    markCompleted(result: TResult): void;
+    releaseActiveRun(): TActiveRun | undefined;
+    releaseResolvedConfig(): void;
+    invalidate(): void;
+    private bindInvocation;
+    private assertCurrentIdentityResolution;
+    private transitionTo;
+}
+/** Owns canonical addressing, record selection, and invalidation. */
+export declare class SubagentExecutionRegistry<TResult, TResolvedConfig, TActiveRun, TSettledOutput = never> {
+    private readonly options;
+    private readonly recordsByAddress;
+    private readonly checkpointThreadIds;
+    private readonly preparationResourceOwners;
+    private nextPreparationToken;
+    constructor(options: SubagentExecutionRegistryOptions);
+    open(input: SubagentExecutionAddressInput): SubagentExecutionRecord<TResult, TResolvedConfig, TActiveRun, TSettledOutput>;
+    remove(record: SubagentExecutionRecord<TResult, TResolvedConfig, TActiveRun, TSettledOutput>): void;
+    beginIdentityPreparation(record: SubagentExecutionRecord<TResult, TResolvedConfig, TActiveRun, TSettledOutput>, identity: SubagentExecutionIdentity): SubagentExecutionPreparationLease;
+    selectForResume(selection?: ResumeSelection): SubagentExecutionRecord<TResult, TResolvedConfig, TActiveRun, TSettledOutput>[];
+    rememberCheckpointThread(...threadIds: string[]): void;
+    getCheckpointThreadIds(getNestedThreadIds?: (activeRun: TActiveRun) => ReadonlyArray<string>): string[];
+    resetCheckpointThreadIds(): void;
+    retireResumeSources(current: SubagentExecutionRecord<TResult, TResolvedConfig, TActiveRun, TSettledOutput>, sourceThreadIds: ReadonlySet<string>, retire: (source: SubagentExecutionRecord<TResult, TResolvedConfig, TActiveRun, TSettledOutput>) => void): void;
+    clear(dispose?: (record: SubagentExecutionRecord<TResult, TResolvedConfig, TActiveRun, TSettledOutput>) => void): void;
+    private selectScopedRecords;
+    private createAddress;
+}
+export {};

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

@@ -1,13 +1,20 @@
-import type { BaseMessage } from '@langchain/core/messages';
-import type { AgentInputs, StandardGraphInput, ResolvedSubagentConfig, SubagentConfig, SubagentUsageSink, TokenCounter } from '@/types';
+import { BaseMessage } from '@langchain/core/messages';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { ToolCall } from '@langchain/core/messages/tool';
+import type { MultiAgentGraphState, HumanInTheLoopConfig, StandardGraphInput, ExecutableSubagentConfigEntry, SubagentExecutionContext, SubagentUsageSink, TokenCounter } from '@/types';
+import type { SubagentResumeManifest, SettledSubagentToolOutput } from './SubagentReplay';
 import type { HookRegistry } from '@/hooks';
-import type { AgentContext } from '@/agents/AgentContext';
+import type { GraphFactory } from '@/graphs/graphFactory';
 import type { StandardGraph } from '@/graphs/Graph';
 import type { HandlerRegistry } from '@/events';
+export { buildChildInputs, isGraphSubagentConfig, normalizeSubagentConfigs, normalizeSubagentConfigEntries, resolveSubagentConfigs, resolveSubagentConfigEntries, } from './childGraphConfig';
+export declare const DEFAULT_SUBAGENT_DESCRIPTION = "No task description provided";
 export type SubagentExecuteParams = {
     description: string;
     subagentType: string;
     threadId?: string;
+    /** Signal attached to this specific parent tool invocation. */
+    signal?: AbortSignal;
     /**
      * Breaker controller captured at the parent TOOL BATCH's entry, before
      * PreToolUse hooks. Preferred over the live scope accessor: a graph reset
@@ -34,11 +41,12 @@ export type SubagentExecuteParams = {
      *
      * Inheritance details (verified empirically against LangGraph):
      *   - host-set keys propagate as-is into the child's tool dispatches;
-     *   - `thread_id` propagates (with `childRunId` as a fallback when
-     *     parent did not supply one) — matches the "subagent is part of
-     *     the same conversation" mental model and aligns with the
-     *     `sessionId: this.parentRunId` convention this executor already
-     *     uses for `SubagentStart` / `SubagentStop` hooks;
+     *   - with nested HITL enabled, `thread_id` is replaced with a stable
+     *     child checkpoint id derived from the parent's durable thread id,
+     *     checkpoint fork, parent agent id, and spawning tool call id so parent
+     *     and child checkpoints cannot collide, sibling parent forks stay
+     *     isolated, and reconstruction returns to the same child checkpoint;
+     *     parent-scoped hook lookup remains keyed by the inherited `run_id`;
      *   - `parent_run_id` propagates when the host put it on parent's
      *     configurable;
      *   - `run_id` is *overwritten by the LangGraph runtime* at child
@@ -68,7 +76,7 @@ export type SubagentExecuteResult = {
  */
 export type ChildGraphFactory = (input: StandardGraphInput) => StandardGraph;
 export type SubagentExecutorOptions = {
-    configs: Map<string, ResolvedSubagentConfig>;
+    configs: ReadonlyMap<string, ExecutableSubagentConfigEntry>;
     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
@@ -84,6 +92,8 @@ export type SubagentExecutorOptions = {
     hookRegistry?: HookRegistry;
     parentRunId: string;
     parentAgentId?: string;
+    /** Root identity, policy session, and lineage inherited by a child graph. */
+    executionContext?: SubagentExecutionContext;
     langfuse?: StandardGraphInput['langfuse'];
     tokenCounter?: TokenCounter;
     /**
@@ -95,6 +105,11 @@ export type SubagentExecutorOptions = {
      * revert to the defaults.
      */
     streamLimits?: StandardGraphInput['streamLimits'];
+    humanInTheLoop?: HumanInTheLoopConfig;
+    /** Shared durable saver used to recover outer tool lifecycle results before
+     * parent hooks re-enter after a process rebuild. Narrowed structurally at
+     * construction because graph compile options also permit framework flags. */
+    checkpointer?: unknown;
     /** Remaining nesting budget. 0 or negative blocks execution. */
     maxDepth?: number;
     /**
@@ -103,6 +118,9 @@ export type SubagentExecutorOptions = {
      * module dependency.
      */
     createChildGraph: ChildGraphFactory;
+    /** Preferred polymorphic child constructor. The legacy standard-only
+     * factory remains required for source compatibility. */
+    createChildGraphByKind?: GraphFactory;
     /**
      * Parent's event handler registry. When provided, child-graph events are
      * forwarded through this registry so hosts can:
@@ -140,12 +158,18 @@ export declare class SubagentExecutor {
     private readonly hookRegistry?;
     private readonly parentRunId;
     private readonly parentAgentId?;
+    private readonly executionContext;
     private readonly langfuse?;
     private readonly tokenCounter?;
     private readonly streamLimits?;
+    private readonly humanInTheLoop?;
+    private readonly checkpointer?;
     private readonly maxDepth;
     private readonly createChildGraph;
+    private readonly createChildGraphByKind?;
     private readonly usageSink?;
+    private readonly executions;
+    private replayCheckpointWorkflow?;
     private readonly resolveParentHandlerRegistry?;
     constructor(options: SubagentExecutorOptions);
     /** The breaker controller current for this execution — read per spawn
@@ -157,7 +181,39 @@ export declare class SubagentExecutor {
     private composeChildSignal;
     /** Snapshot of the parent's registry at the moment a subagent is dispatched. */
     private getParentHandlerRegistry;
+    private bindExecutionDefinition;
+    /** Resolve one lazy descriptor per stable child execution. Concurrent
+     * duplicate dispatches share the same in-flight resolution; HITL re-entry
+     * on this executor reuses the resolved config until the child settles. */
+    private resolveExecutionConfig;
+    /**
+     * Keeps the original child thread as an immutable resume source once a
+     * different parent Run reconstructs it. Each rebuilt parent gets a private
+     * checkpoint fork, while the persisted child run ID remains stable for
+     * activity and usage correlation across the interrupt boundary.
+     */
+    private resolveChildExecutionIdentity;
+    private createChildExecutionIdentity;
+    private prepareIdentity;
+    private prepareCheckpointFork;
+    private checkpointThreadExists;
+    /** Captures one exact checkpoint head per namespace for a child thread. */
+    private getLatestCheckpointSnapshot;
+    /** Copies exact checkpoint lineages, including pending task writes. */
+    private forkCheckpointSnapshot;
+    private createResumeManifest;
+    getResumeManifest(parentToolCallIds?: ReadonlySet<string>, config?: RunnableConfig): Promise<SubagentResumeManifest | undefined>;
+    getChildCheckpointThreadIds(): string[];
+    resetCheckpointThreadIds(): void;
+    private getGraphChildCheckpointThreadIds;
+    private clearChildGraph;
+    clearHeavyState(): void;
+    private getResumeCheckpointMarker;
+    getSettledToolOutput(call: ToolCall, config: RunnableConfig): Promise<SettledSubagentToolOutput | undefined>;
+    persistSettledToolOutput(call: ToolCall, config: RunnableConfig, settled: SettledSubagentToolOutput): Promise<void>;
+    private persistChildCheckpointMarker;
     execute(params: SubagentExecuteParams): Promise<SubagentExecuteResult>;
+    private executeOnce;
     /**
      * Emits a single {@link GraphEvents.ON_SUBAGENT_UPDATE} envelope through the
      * parent's handler registry. Silent no-op when no parent registry is set.
@@ -185,6 +241,11 @@ export declare function sanitizeForwardedSubagentUpdateData(eventName: string, d
  * a compact status ticker without parsing the raw payload.
  */
 export declare function summarizeEvent(eventName: string, data: unknown): string;
+/**
+ * Reads only the result member captured by MultiAgentGraph. Worker output is
+ * never used as a fallback when the designated result member is textless.
+ */
+export declare function filterGraphSubagentResult(state: MultiAgentGraphState, resultAgentId: string): string;
 /**
  * Walk messages from last to first, returning the text content of the most
  * recent AIMessage that has any. Non-text blocks (tool_use, thinking,
@@ -199,30 +260,3 @@ export declare function summarizeEvent(eventName: string, data: unknown): string
  * any text.
  */
 export declare function filterSubagentResult(messages: BaseMessage[]): string;
-/**
- * Resolve self-spawn configs by filling in agentInputs from the parent context.
- * Returns configs with agentInputs guaranteed present. Throws on duplicate
- * `type` values to prevent silent config shadowing.
- */
-export declare function resolveSubagentConfigs(configs: SubagentConfig[], parentContext: AgentContext): ResolvedSubagentConfig[];
-/**
- * Build child AgentInputs from a resolved config, stripping nesting and
- * (optionally) event-driven fields. When `allowNested: true`, the child's
- * `maxSubagentDepth` is decremented so that depth is consumed as the call
- * chain deepens across graph boundaries — the parent's executor-level check
- * alone cannot see into the child graph's separate executor.
- *
- * When `keepToolDefinitions` is `true`, the child retains the parent's
- * `toolDefinitions` so event-driven tools remain usable. This is only safe
- * when the caller has wired a forwarder for `ON_TOOL_EXECUTE` to a
- * registered handler — otherwise the child will hang on tool dispatch.
- *
- * @remarks Advanced utility: exported primarily for testing and by
- * {@link SubagentExecutor}. Host applications configuring subagents should
- * not need to call this directly — it is invoked internally when a subagent
- * tool is dispatched. The depth-countdown contract (parent's `maxDepth` in,
- * child's decremented `maxSubagentDepth` on the returned inputs) is the
- * mechanism that bounds nesting across graph boundaries; callers must
- * respect it.
- */
-export declare function buildChildInputs(config: ResolvedSubagentConfig, childAgentId: string, parentMaxDepth: number, keepToolDefinitions?: boolean): AgentInputs;

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

@@ -0,0 +1,85 @@
+import type { ToolCall, ToolMessage } from '@langchain/core/messages/tool';
+import type { RunnableConfig } from '@langchain/core/runnables';
+import type { ToolOutputReferenceState } from '@/tools/toolOutputReferences';
+import type { ToolApprovalReplaySnapshot } from '@/hooks';
+import type { ToolSessionContext } from '@/types';
+export declare const SUBAGENT_RESUME_MANIFEST_CONFIG_KEY = "__librechat_subagent_resume_manifest";
+export declare const SUBAGENT_RESUME_ATTEMPT_CONFIG_KEY = "__librechat_subagent_resume_attempt";
+export declare const SUBAGENT_PARENT_BATCH_CONFIG_KEY = "__librechat_subagent_parent_batch";
+export interface SubagentCheckpointReference {
+    threadId: string;
+    checkpointId: string;
+    checkpointNs: string;
+}
+export interface SubagentToolCallStepReference {
+    toolCallId: string;
+    stepId: string;
+}
+export interface SubagentToolSessionReference {
+    toolName: string;
+    context: ToolSessionContext;
+}
+export interface SubagentToolNodeResumeState {
+    stateKey: string;
+    toolUsageCounts: Array<{
+        toolName: string;
+        count: number;
+    }>;
+    directPathTurns: Array<{
+        toolCallId: string;
+        turn: number;
+    }>;
+}
+export interface SubagentEagerToolUsageState {
+    agentId: string;
+    toolUsageCounts: Array<{
+        toolName: string;
+        count: number;
+    }>;
+}
+export interface SubagentGraphResumeState {
+    toolCallSteps: SubagentToolCallStepReference[];
+    toolSessions: SubagentToolSessionReference[];
+    toolNodes: SubagentToolNodeResumeState[];
+    eagerToolUsage: SubagentEagerToolUsageState[];
+    eagerToolSuppressions: string[];
+    toolOutputReferences?: ToolOutputReferenceState;
+}
+/** Private checkpoint payload linking a parent pause to an exact child state. */
+export interface SubagentResumeExecution {
+    parentToolCallId: string;
+    childRunId: string;
+    /** Effective child type bound when this execution first ran. */
+    subagentType?: string;
+    /** Lazy child revision bound when this execution first resolved. */
+    configId?: string;
+    approvalExecutionScope: string;
+    checkpoints: SubagentCheckpointReference[];
+    graphState: SubagentGraphResumeState;
+    approvalReplays: ToolApprovalReplaySnapshot[];
+    descendant?: SubagentResumeManifest;
+}
+/** Private checkpoint payload linking a parent pause to every child state. */
+export interface SubagentResumeManifest {
+    version: 1;
+    executions: SubagentResumeExecution[];
+}
+export declare function getSubagentResumeManifest(payload: unknown): SubagentResumeManifest | undefined;
+export declare function requireValidSubagentResumeManifest(payload: unknown): SubagentResumeManifest | undefined;
+export declare function attachSubagentResumeManifest(payload: unknown, manifest: SubagentResumeManifest): object;
+export declare function stripSubagentResumeManifest(payload: unknown): unknown;
+export declare const SUBAGENT_REPLAY_CONTROLLER: unique symbol;
+export type SettledSubagentToolOutput = {
+    output: ToolMessage;
+    additionalContexts: string[];
+    resolvedArgs?: Record<string, unknown>;
+    referenceContent?: string;
+};
+export interface SubagentReplayController {
+    getResumeManifest?(parentToolCallIds?: ReadonlySet<string>, config?: RunnableConfig): Promise<SubagentResumeManifest | undefined>;
+    getSettledOutput(call: ToolCall, config: RunnableConfig): Promise<SettledSubagentToolOutput | undefined>;
+    persistSettledOutput(call: ToolCall, config: RunnableConfig, settled: SettledSubagentToolOutput): Promise<void>;
+}
+export type ReplayableSubagentTool = {
+    [SUBAGENT_REPLAY_CONTROLLER]?: SubagentReplayController;
+};

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

@@ -0,0 +1,37 @@
+import type { AgentInputs, ExecutableSubagentConfig, ExecutableSubagentConfigEntry, GraphEdge, GraphSubagentConfig, ResolvedSubagentConfig, ResolvedSubagentConfigEntry, SubagentConfig, SubagentConfigEntry } from '@/types';
+import type { AgentContext } from '@/agents/AgentContext';
+type ChildGraphPlanBase = {
+    subjectAgentId: string;
+    checkpointNodeId: string;
+    agents: AgentInputs[];
+    memberInputs: ReadonlyMap<string, AgentInputs>;
+};
+export type ChildGraphPlan = (ChildGraphPlanBase & {
+    kind: 'agent';
+}) | (ChildGraphPlanBase & {
+    kind: 'graph';
+    edges: GraphEdge[];
+    entryAgentId: string;
+    resultAgentId: string;
+});
+type CreateChildGraphPlanParams = {
+    config: ResolvedSubagentConfigEntry;
+    executionSuffix: string;
+    parentAgentId?: string;
+    parentMaxDepth: number;
+    keepToolDefinitions: boolean;
+};
+export declare function isGraphSubagentConfig(config: SubagentConfigEntry): config is GraphSubagentConfig;
+export declare function validateGraphSubagentConfig(config: unknown): void;
+/** Normalize eager, self, lazy, and graph subagent entries for advertisement. */
+export declare function normalizeSubagentConfigEntries(configs: SubagentConfigEntry[], parentContext: AgentContext): ExecutableSubagentConfigEntry[];
+/** Resolve self-spawn inputs and validate explicit graph configs. */
+export declare function resolveSubagentConfigEntries(configs: SubagentConfigEntry[], parentContext: AgentContext): ResolvedSubagentConfigEntry[];
+/** Resolve legacy single-agent configs with the original public signature. */
+export declare function resolveSubagentConfigs(configs: SubagentConfig[], parentContext: AgentContext): ResolvedSubagentConfig[];
+/** Normalize legacy single-agent configs while rejecting graph entries. */
+export declare function normalizeSubagentConfigs(configs: SubagentConfig[], parentContext: AgentContext): ExecutableSubagentConfig[];
+export declare function buildChildInputs(config: ResolvedSubagentConfig, childAgentId: string, parentMaxDepth: number, keepToolDefinitions?: boolean): AgentInputs;
+export declare function buildGraphChildInputs(config: GraphSubagentConfig, parentMaxDepth: number, keepToolDefinitions?: boolean): AgentInputs[];
+export declare function createChildGraphPlan({ config, executionSuffix, parentAgentId, parentMaxDepth, keepToolDefinitions, }: CreateChildGraphPlanParams): ChildGraphPlan;
+export {};

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

@@ -1,2 +1,2 @@
-export { SubagentExecutor, filterSubagentResult, resolveSubagentConfigs, buildChildInputs, summarizeEvent, } from './SubagentExecutor';
+export { DEFAULT_SUBAGENT_DESCRIPTION, SubagentExecutor, filterSubagentResult, filterGraphSubagentResult, isGraphSubagentConfig, normalizeSubagentConfigs, normalizeSubagentConfigEntries, resolveSubagentConfigs, resolveSubagentConfigEntries, buildChildInputs, summarizeEvent, } from './SubagentExecutor';
 export type { SubagentExecuteParams, SubagentExecuteResult, SubagentExecutorOptions, ChildGraphFactory, } from './SubagentExecutor';

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

@@ -0,0 +1,4 @@
+export declare const DEFAULT_SUBAGENT_MAX_TURNS = 25;
+export declare const SUBAGENT_RECURSION_MULTIPLIER = 3;
+export declare const MAX_GRAPH_SUBAGENT_MEMBERS = 32;
+export declare const MAX_GRAPH_SUBAGENT_TURNS: number;

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

@@ -53,6 +53,14 @@ export type ToolOutputReferenceRegistryOptions = {
      */
     maxActiveRuns?: number;
 };
+export interface ToolOutputReferenceState {
+    entries: Array<{
+        key: string;
+        value: string;
+    }>;
+    turnCounter: number;
+    warnedNonStringTools: string[];
+}
 /**
  * Result of resolving placeholders in tool args.
  */
@@ -189,6 +197,10 @@ export declare class ToolOutputReferenceRegistry {
      * completed.
      */
     snapshot(runId: string | undefined): ToolOutputResolveView;
+    /** Captures the checkpoint-safe state needed to resume one run bucket. */
+    snapshotState(runId: string | undefined): ToolOutputReferenceState;
+    /** Restores a checkpointed run bucket under the current resume scope. */
+    restoreState(runId: string | undefined, state: ToolOutputReferenceState): void;
     private resolveAgainst;
     private transform;
     private replaceInString;