@librechat/agents 3.4.0 → 3.4.2

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

@@ -32,8 +32,13 @@ export type BaseGraphState = {
 export type AgentSubgraphState = BaseGraphState & {
     summarizationRequest?: SummarizationNodeInput;
 };
+export type SubagentGraphResult = {
+    agentId: string;
+    message?: BaseMessage;
+};
 export type MultiAgentGraphState = BaseGraphState & {
     agentMessages?: BaseMessage[];
+    subagentResult?: SubagentGraphResult;
 };
 export type IState = BaseGraphState;
 export interface AgentLogEvent {
@@ -223,9 +228,9 @@ export type StandardGraphInput = {
     indexTokenCountMap?: Record<string, number>;
     calibrationRatio?: number;
     /**
-     * Receives a {@link SubagentUsageEvent} for every model call made inside
-     * a subagent child run spawned from this graph (including nested
-     * subagents and child-side summarization calls). Child graphs run via
+     * Receives a {@link SubagentUsageEvent} for every model call that reports
+     * usage metadata inside a subagent child run spawned from this graph
+     * (including nested subagents and child-side summarization calls). Child graphs run via
      * `invoke()` outside the host's `streamEvents` loop, so their
      * `on_chat_model_end` events never reach the run's handler registry —
      * this sink is the only way hosts can observe child token usage for
@@ -256,9 +261,11 @@ export type StandardGraphInput = {
      * every streamed chunk event. See {@link StreamLimits}.
      */
     streamLimits?: StreamLimits;
+    /** Structured lineage for a graph executing as a subagent child. */
+    subagentExecutionContext?: SubagentExecutionContext;
 };
 export type GraphEdge = {
-    /** Agent ID, use a list for multiple sources */
+    /** Agent ID; direct edges use an array as an all-of waiting source group. */
     from: string | string[];
     /** Agent ID, use a list for multiple destinations */
     to: string | string[];
@@ -288,40 +295,180 @@ export type GraphEdge = {
      */
     promptKey?: string;
 };
+export type GraphSubagentEdge = Omit<GraphEdge, 'edgeType' | 'condition' | 'promptKey'> & {
+    edgeType: 'direct';
+    condition?: never;
+    promptKey?: never;
+};
 export type MultiAgentGraphInput = StandardGraphInput & {
     edges: GraphEdge[];
+    /** Captures the designated member's final AI turn in graph state. */
+    resultAgentId?: string;
+    /** Optional per-member Pregel budget when the outer graph has its own topology budget. */
+    memberRecursionLimit?: number;
 };
-/** Configuration for a subagent type that can be spawned by a parent agent. */
-export type SubagentConfig = {
-    /** Identifier used in the tool's `subagent_type` enum (e.g. 'researcher', 'coder'). */
+/** Lightweight identity advertised to the model for a spawnable subagent. */
+export interface SubagentDescriptor {
+    /** Stable identifier used in the tool's `subagent_type` enum (e.g. 'researcher', 'coder'). */
     type: string;
     /** Human-readable display name. */
     name: string;
     /** What this subagent specializes in — shown to the LLM. */
     description: string;
-    /** Full agent config for the child graph. Omit when `self` is true. */
-    agentInputs?: AgentInputs;
-    /** When true, reuse the parent's AgentInputs (context isolation without separate config). */
-    self?: boolean;
+    /**
+     * Opaque, versioned identity of the child configuration. Required when
+     * `resolveAgentInputs` is used and changed whenever its resolved inputs
+     * change incompatibly.
+     */
+    configId?: string;
+}
+/** Lazy descriptor with the durable configuration identity required to resolve it. */
+export interface LazySubagentDescriptor extends SubagentDescriptor {
+    configId: string;
+}
+/** Stable request identifiers exposed to a selected subagent resolver. */
+export interface SubagentResolveRequestContext {
+    conversationId?: string;
+    messageId?: string;
+    parentMessageId?: string;
+}
+/** Stable user identifiers exposed to a selected subagent resolver. */
+export interface SubagentResolveUserContext {
+    id?: string;
+    role?: string;
+    tenantId?: string;
+}
+/** Sanitized host runtime context safe for lazy subagent resolution. */
+export interface SubagentResolveConfigurable {
+    requestBody?: Readonly<SubagentResolveRequestContext>;
+    user?: Readonly<SubagentResolveUserContext>;
+    user_id?: string;
+}
+/** Runtime context supplied when a host lazily resolves a selected subagent. */
+export interface SubagentResolveContext {
+    /** Stable subagent identity selected by the model. */
+    descriptor: Readonly<LazySubagentDescriptor>;
+    /** Stable child execution identity, including across HITL reconstruction. */
+    executionId: string;
+    /** Parent run that dispatched this execution. */
+    parentRunId: string;
+    /** Parent agent that dispatched this execution. */
+    parentAgentId?: string;
+    /** Parent-side tool call that selected the subagent. */
+    parentToolCallId?: string;
+    /** Durable parent conversation thread, when supplied by the host. */
+    threadId?: string;
+    /** Parent/breaker cancellation composed for this child execution. */
+    signal: AbortSignal;
+    /** Stable, sanitized host context from the parent tool invocation. */
+    configurable?: Readonly<SubagentResolveConfigurable>;
+}
+/** Host contract for resolving a selected subagent's full graph inputs. */
+export type SubagentAgentInputsResolver = (context: SubagentResolveContext) => Promise<AgentInputs>;
+interface SubagentConfigBase extends SubagentDescriptor {
     /** Max AGENT→TOOLS cycles before forced stop (default: 25). */
     maxTurns?: number;
     /** Allow this subagent to spawn its own subagents (default: false). */
     allowNested?: boolean;
-};
-/** SubagentConfig with agentInputs guaranteed present (self-spawn resolved). */
-export type ResolvedSubagentConfig = SubagentConfig & {
+}
+export interface SubagentConfig extends SubagentConfigBase {
+    /** Full agent config for the child graph. Omit when `self` is true. */
+    agentInputs?: AgentInputs;
+    /**
+     * Resolve the full child config only after this descriptor is selected.
+     * Eager `agentInputs` take precedence when also supplied. `self` and a
+     * resolver are mutually exclusive and normalization rejects that pairing.
+     *
+     * Resolvers should rebuild inputs from the stable execution context instead
+     * of retaining request-owned state. The SDK keeps resolved inputs in memory
+     * only for the lifetime of the selected execution and supplies cancellation
+     * through `context.signal`. A reconstructed execution may invoke the
+     * resolver again, so the same `context.executionId` must produce equivalent
+     * child inputs. Durable resolver work should be idempotent on
+     * `(context.executionId, context.descriptor.configId)`.
+     */
+    resolveAgentInputs?: SubagentAgentInputsResolver;
+    /** When true, reuse the parent's AgentInputs (context isolation without separate config). */
+    self?: boolean;
+}
+export interface SingleAgentSubagentConfig extends SubagentConfig {
+    kind?: 'agent';
+    agents?: never;
+    edges?: never;
+    entryAgentId?: never;
+    resultAgentId?: never;
+}
+export interface GraphSubagentConfig extends SubagentConfigBase {
+    kind: 'graph';
+    configId?: never;
+    resolveAgentInputs?: never;
+    allowNested?: false;
+    agents: AgentInputs[];
+    /**
+     * Explicit direct DAG edges. Array-valued sources are all-of waiting edges.
+     * Relative message order between parallel branches is implementation-dependent.
+     * Prompted edges are supported in chains or on the final converged result transition.
+     */
+    edges: GraphSubagentEdge[];
+    entryAgentId: string;
+    resultAgentId: string;
+    agentInputs?: never;
+    self?: never;
+}
+/** Any configuration that can be spawned through the subagent tool. */
+export type SubagentConfigEntry = SubagentConfig | GraphSubagentConfig;
+/** Legacy single-agent config with self-spawn resolution completed. */
+export interface ResolvedSubagentConfig extends SubagentConfig {
     agentInputs: AgentInputs;
-};
+}
+/** Explicit alias for graph-aware code that needs to name the legacy variant. */
+export interface ResolvedSingleAgentSubagentConfig extends ResolvedSubagentConfig {
+    kind?: 'agent';
+    agents?: never;
+    edges?: never;
+    entryAgentId?: never;
+    resultAgentId?: never;
+}
+export type ResolvedSubagentConfigEntry = ResolvedSubagentConfig | GraphSubagentConfig;
+/** Lazy single-agent entry accepted after descriptor validation. */
+export interface LazySingleAgentSubagentConfig extends SingleAgentSubagentConfig {
+    configId: string;
+    resolveAgentInputs: SubagentAgentInputsResolver;
+    agentInputs?: never;
+    self?: never;
+}
+/** Single-agent config accepted after eager/self/lazy eligibility checks. */
+export type ExecutableSubagentConfig = ResolvedSubagentConfig | LazySingleAgentSubagentConfig;
+/** Graph-aware config accepted by the executor. Graph configs stay eager. */
+export type ExecutableSubagentConfigEntry = ExecutableSubagentConfig | GraphSubagentConfig;
 /** Lifecycle phase carried on {@link SubagentUpdateEvent}. */
 export type SubagentUpdatePhase = 'start' | 'run_step' | 'run_step_delta' | 'run_step_completed' | 'message_delta' | 'reasoning_delta' | 'stop' | 'error';
+export interface SubagentAncestryEntry {
+    readonly subagentRunId: string;
+    readonly subagentType: string;
+    readonly subagentKind: 'agent' | 'graph';
+    /** Execution subject ID; synthetic for graph subagents. */
+    readonly subagentAgentId: string;
+    readonly parentRunId: string;
+    readonly parentAgentId?: string;
+    readonly parentToolCallId?: string;
+}
+export interface SubagentExecutionContext {
+    readonly rootRunId: string;
+    readonly hookSessionId: string;
+    readonly depth: number;
+    readonly ancestry: readonly SubagentAncestryEntry[];
+}
 /**
  * Wrapper event emitted when a subagent's child graph dispatches activity.
  * Lets hosts show subagent progress in a UI surface separate from the parent
  * conversation without having to untangle events by agent ID.
  */
 export interface SubagentUpdateEvent {
-    /** Parent run ID. */
+    /** Root run ID that owns this execution tree. */
     runId: string;
+    /** Immediate parent run that spawned this child. */
+    parentRunId?: string;
     /** Child run ID (unique per subagent execution). */
     subagentRunId: string;
     /**
@@ -333,8 +480,16 @@ export interface SubagentUpdateEvent {
     parentToolCallId?: string;
     /** Subagent `type` identifier from the SubagentConfig. */
     subagentType: string;
-    /** Child agent ID assigned to this subagent execution. */
+    /** Execution shape. Omitted by older emitters. */
+    subagentKind?: 'agent' | 'graph';
+    /** Execution subject ID; synthetic for graph subagents. */
     subagentAgentId: string;
+    /** Graph member that produced this update, when attributable. */
+    memberAgentId?: string;
+    /** One-based nesting depth beneath the root graph. */
+    depth?: number;
+    /** Root-to-leaf execution lineage, without parsing composed run IDs. */
+    ancestry?: readonly SubagentAncestryEntry[];
     /** Parent agent ID that spawned this subagent. */
     parentAgentId?: string;
     /** Lifecycle phase carried by this update. */
@@ -376,10 +531,20 @@ export interface SubagentUsageEvent {
     provider?: string;
     /** Subagent `type` identifier from the SubagentConfig. */
     subagentType: string;
+    /** Execution shape. Omitted by older emitters. */
+    subagentKind?: 'agent' | 'graph';
     /** Child run ID (unique per subagent execution). */
     subagentRunId: string;
-    /** Child agent ID assigned to this subagent execution. */
+    /** Execution subject ID; synthetic for graph subagents. */
     subagentAgentId: string;
+    /** Graph member whose model call produced this usage. */
+    memberAgentId?: string;
+    /** Immediate parent run that spawned this child. */
+    parentRunId?: string;
+    /** One-based nesting depth beneath the root graph. */
+    depth?: number;
+    /** Root-to-leaf execution lineage, without parsing composed run IDs. */
+    ancestry?: readonly SubagentAncestryEntry[];
     /**
      * ROOT run ID of the host run that owns billing. For nested subagents
      * each forwarding layer rewrites this upward, so events from any depth
@@ -512,7 +677,7 @@ export interface AgentInputs {
     /** Pre-computed tool schema token count (from cache). Skips recalculation when provided. */
     toolSchemaTokens?: number;
     /** Subagent configurations for hierarchical delegation. Each defines a child agent type. */
-    subagentConfigs?: SubagentConfig[];
+    subagentConfigs?: SubagentConfigEntry[];
     /** Maximum subagent nesting depth. Default 1 means top-level agents can spawn subagents but subagents cannot nest further. */
     maxSubagentDepth?: number;
     /**
@@ -524,11 +689,11 @@ export interface AgentInputs {
      * raise a LangGraph `interrupt()` (e.g. a tool built on `askUserQuestion()`) —
      * the host-side event handler runs outside the graph task, where `interrupt()`
      * throws. Do NOT also list these tools in `toolDefinitions` (they would be bound
-     * twice). NOT inherited by SELF-SPAWNED subagent children (their config is a
-     * shallow spread of the parent's inputs, and child graphs compile without a
-     * checkpointer, so an interrupt-capable tool could never pause there) —
-     * `buildChildInputs` scrubs the inherited copy; an EXPLICIT child config that
-     * lists its own `graphTools` keeps them.
+     * twice). NOT inherited by SELF-SPAWNED subagent children: `buildChildInputs`
+     * scrubs the shallow-spread parent copy so parent-scoped direct tools are not
+     * exposed to a child implicitly. An EXPLICIT child config that lists its own
+     * `graphTools` keeps them; with HITL enabled, those tools share the parent's
+     * checkpointer and may pause and resume inside the child graph.
      *
      * Deliberately `GenericTool[]`, not `GraphTools`: the wider union admits
      * schema-only shapes (OpenAI `BindToolsInput`, Google tool objects) that

package/dist/types/types/hitl.d.ts

@@ -97,6 +97,17 @@ export type ToolApprovalDecisionMap = Record<string, ToolApprovalDecision>;
  * below; this type alias is primarily an integration-layer contract.
  */
 export type HumanInterruptType = 'tool_approval' | 'ask_user_question';
+/** Identifies an interrupt that originated inside a checkpointed subagent. */
+export interface SubagentInterruptScope {
+    /** Child execution run id used by subagent update and usage events. */
+    run_id: string;
+    /** Child agent id that owns the interrupted tool call. */
+    agent_id: string;
+    /** Configured subagent type selected by the parent tool call. */
+    subagent_type: string;
+    /** Parent `subagent` tool call that launched this child. */
+    parent_tool_call_id?: string;
+}
 /**
  * Structured payload the SDK passes to `interrupt()` when one or more
  * pending tool calls require host approval. All `ask`-decision tool calls
@@ -110,6 +121,10 @@ export interface ToolApprovalInterruptPayload {
     type: 'tool_approval';
     action_requests: ToolApprovalRequest[];
     review_configs: ToolApprovalReviewConfig[];
+    /** Hook-registry session whose policy raised this interrupt. */
+    hook_session_id?: string;
+    /** Present when the approval request was bridged from a child graph. */
+    subagent?: SubagentInterruptScope;
 }
 /**
  * Pre-defined option the user can pick when answering an

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@librechat/agents",
-  "version": "3.4.0",
+  "version": "3.4.2",
+  "reova": {
+    "enabled": true,
+    "endpoint": "https://telemetry.reo.dev/data"
+  },
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -116,6 +120,8 @@
     "prepublishOnly": "npm run build",
     "build": "tsdown && tsc -p tsconfig.build.json",
     "build:dev": "tsdown",
+    "check:circular-deps": "node config/circular-deps.mjs",
+    "test:circular-deps": "node --test config/circular-deps.test.mjs",
     "sort-imports": "node scripts/sort-imports.ts",
     "sort-imports:check": "node scripts/sort-imports.ts --check",
     "start": "node dist/esm/main.js",
@@ -248,7 +254,7 @@
     "nanoid": "^3.3.7",
     "okapibm25": "^1.4.1",
     "openai": "^6.46.0",
-    "reo-census": "^1.2.10",
+    "reova": "^0.4.1",
     "socks-proxy-agent": "^8.0.5",
     "uuid": "^11.1.1"
   },

package/src/agents/AgentContext.ts

@@ -275,7 +275,7 @@ export class AgentContext {
   /** Original AgentInputs used to create this context — used for self-spawn subagent resolution. */
   _sourceInputs?: t.AgentInputs;
   /** Subagent configurations for hierarchical delegation. */
-  subagentConfigs?: t.SubagentConfig[];
+  subagentConfigs?: t.SubagentConfigEntry[];
   /** Maximum subagent nesting depth. */
   maxSubagentDepth?: number;
   /** Instructions for this agent */