@librechat/agents 3.1.67 → 3.1.68-dev.1

package/src/types/graph.ts

@@ -18,7 +18,13 @@ import type {
 import type { RunnableConfig, Runnable } from '@langchain/core/runnables';
 import type { ChatGenerationChunk } from '@langchain/core/outputs';
 import type { GoogleAIToolType } from '@langchain/google-common';
-import type { ToolMap, ToolEndEvent, GenericTool, LCTool } from '@/types/tools';
+import type {
+  ToolMap,
+  ToolEndEvent,
+  GenericTool,
+  LCTool,
+  ToolExecuteBatchRequest,
+} from '@/types/tools';
 import type { Providers, Callback, GraphNodeKeys } from '@/common';
 import type { StandardGraph, MultiAgentGraph } from '@/graphs';
 import type { ClientOptions } from '@/types/llm';
@@ -105,7 +111,9 @@ export interface EventHandler {
       | SummarizeStartEvent
       | SummarizeDeltaEvent
       | SummarizeCompleteEvent
+      | SubagentUpdateEvent
       | AgentLogEvent
+      | ToolExecuteBatchRequest
       | { result: ToolEndEvent },
     metadata?: Record<string, unknown>,
     graph?: StandardGraph | MultiAgentGraph
@@ -388,6 +396,73 @@ export type MultiAgentGraphInput = StandardGraphInput & {
   edges: GraphEdge[];
 };
 
+/** 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'). */
+  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;
+  /** 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 & {
+  agentInputs: AgentInputs;
+};
+
+/** Lifecycle phase carried on {@link SubagentUpdateEvent}. */
+export type SubagentUpdatePhase =
+  | 'start'
+  | 'run_step'
+  | 'run_step_delta'
+  | 'run_step_completed'
+  | 'message_delta'
+  | 'reasoning_delta'
+  | 'stop'
+  | 'error';
+
+/**
+ * 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. */
+  runId: string;
+  /** Child run ID (unique per subagent execution). */
+  subagentRunId: string;
+  /**
+   * Parent-side `tool_call_id` for the `subagent` tool invocation that
+   * triggered this run. Stable for the duration of the child; lets hosts
+   * correlate updates deterministically instead of inferring by ordering.
+   * Omitted when the executor was invoked outside of a tool-call context.
+   */
+  parentToolCallId?: string;
+  /** Subagent `type` identifier from the SubagentConfig. */
+  subagentType: string;
+  /** Child agent ID assigned to this subagent execution. */
+  subagentAgentId: string;
+  /** Parent agent ID that spawned this subagent. */
+  parentAgentId?: string;
+  /** Lifecycle phase carried by this update. */
+  phase: SubagentUpdatePhase;
+  /** Underlying event payload (shape depends on phase). */
+  data?: unknown;
+  /** Short human-readable description. Hosts can render this directly. */
+  label?: string;
+  /** ISO timestamp for ordering / display. */
+  timestamp: string;
+}
+
 export interface AgentInputs {
   agentId: string;
   /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */
@@ -431,6 +506,10 @@ export interface AgentInputs {
   maxToolResultChars?: number;
   /** 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[];
+  /** Maximum subagent nesting depth. Default 1 means top-level agents can spawn subagents but subagents cannot nest further. */
+  maxSubagentDepth?: number;
 }
 
 export interface ContextPruningConfig {

package/src/types/index.ts

@@ -2,6 +2,7 @@
 export * from './graph';
 export * from './llm';
 export * from './run';
+export * from './skill';
 export * from './stream';
 export * from './tools';
 export * from './summarize';

package/src/types/run.ts

@@ -11,6 +11,8 @@ import type * as s from '@/types/stream';
 import type * as e from '@/common/enum';
 import type * as g from '@/types/graph';
 import type * as l from '@/types/llm';
+import type { ToolSessionMap } from '@/types/tools';
+import type { HookRegistry } from '@/hooks';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type ZodObjectAny = z.ZodObject<any, any, any, any>;
@@ -112,6 +114,18 @@ export type RunConfig = {
   runId: string;
   graphConfig: LegacyGraphConfig | StandardGraphConfig | MultiAgentGraphConfig;
   customHandlers?: Record<string, g.EventHandler>;
+  /**
+   * Pre-constructed hook registry for this run. Hooks fire at lifecycle
+   * points in `processStream` (RunStart, UserPromptSubmit, Stop,
+   * StopFailure) and around tool calls (PreToolUse, PostToolUse,
+   * PostToolUseFailure, PermissionDenied).
+   *
+   * Pass `undefined` (the default) to skip all hook dispatch. When a
+   * registry is provided, the run attaches it to the `Graph` so internal
+   * nodes can fire hooks too, and clears the session in the `finally`
+   * block to prevent leaks.
+   */
+  hooks?: HookRegistry;
   returnContent?: boolean;
   tokenCounter?: TokenCounter;
   indexTokenCountMap?: Record<string, number>;
@@ -126,6 +140,12 @@ export type RunConfig = {
   calibrationRatio?: number;
   /** Skip post-stream cleanup (clearHeavyState) — useful for tests that inspect graph state after processStream */
   skipCleanup?: boolean;
+  /**
+   * Initial session state to seed the Graph's ToolSessionMap.
+   * Used to carry over code environment sessions from skill file priming
+   * at run start, so ToolNode can inject session_id + files into tool calls.
+   */
+  initialSessions?: ToolSessionMap;
 };
 
 export type ProvidedCallbacks =

package/src/types/skill.ts

@@ -0,0 +1,11 @@
+// src/types/skill.ts
+
+/** Minimal skill metadata for catalog assembly. The host provides these from its own data layer. */
+export type SkillCatalogEntry = {
+  /** Kebab-case identifier (what the model passes to SkillTool) */
+  name: string;
+  /** One-line description for the catalog listing */
+  description: string;
+  /** Optional human-readable label (UI only, not shown to model) */
+  displayTitle?: string;
+};

package/src/types/tools.ts

@@ -2,8 +2,8 @@
 import type { StructuredToolInterface } from '@langchain/core/tools';
 import type { RunnableToolLike } from '@langchain/core/runnables';
 import type { ToolCall } from '@langchain/core/messages/tool';
-import type { ToolErrorData } from './stream';
-import { EnvVar } from '@/common';
+import type { HookRegistry } from '@/hooks';
+import type { MessageContentComplex, ToolErrorData } from './stream';
 
 /** Replacement type for `import type { ToolCall } from '@langchain/core/messages/tool'` in order to have stringified args typed */
 export type CustomToolCall = {
@@ -49,6 +49,12 @@ export type ToolNodeOptions = {
   agentId?: string;
   /** Tool names that must be executed directly (via runTool) even in event-driven mode (e.g., graph-managed handoff tools) */
   directToolNames?: Set<string>;
+  /**
+   * Hook registry for PreToolUse/PostToolUse lifecycle hooks.
+   * Only fires for event-driven tool calls (`dispatchToolEvents`). Tools
+   * routed through `directToolNames` bypass hook dispatch entirely.
+   */
+  hookRegistry?: HookRegistry;
   /** Max context tokens for the agent — used to compute tool result truncation limits. */
   maxContextTokens?: number;
   /**
@@ -81,9 +87,7 @@ export type CodeExecutionToolParams =
   | {
       session_id?: string;
       user_id?: string;
-      apiKey?: string;
       files?: CodeEnvFile[];
-      [EnvVar.CODE_API_KEY]?: string;
     };
 
 export type FileRef = {
@@ -186,6 +190,26 @@ export type ToolExecuteBatchRequest = {
   reject: (error: Error) => void;
 };
 
+/**
+ * A message injected into graph state by any tool execution handler.
+ * Generic mechanism: any tool returning `injectedMessages` in its `ToolExecuteResult`
+ * will have these appended to state after the ToolMessage for this call.
+ */
+export type InjectedMessage = {
+  /** 'user' for skill body injection, 'system' for context hints.
+   *  Both are converted to HumanMessage at runtime; the original role
+   *  is preserved in additional_kwargs.role. */
+  role: 'user' | 'system';
+  /** Message content: string for simple text, array for complex multi-part content */
+  content: string | MessageContentComplex[];
+  /** When true, the message is framework-internal: not shown in UI, not counted as a user turn */
+  isMeta?: boolean;
+  /** Origin tag for downstream consumers (UI, pruner, compaction) */
+  source?: 'skill' | 'hook' | 'system';
+  /** Only set when source is 'skill', for compaction preservation */
+  skillName?: string;
+};
+
 /** Result for a single tool call in event-driven execution */
 export type ToolExecuteResult = {
   /** Matches ToolCallRequest.id */
@@ -198,6 +222,13 @@ export type ToolExecuteResult = {
   status: 'success' | 'error';
   /** Error message if status is 'error' */
   errorMessage?: string;
+  /**
+   * Messages to inject into graph state after the ToolMessage for this call.
+   * Placed after tool results to respect provider message ordering (tool_call -> tool_result adjacency).
+   * The host's message formatter may merge injected user messages with the preceding tool_result turn.
+   * Generic mechanism: any tool execution handler can use this.
+   */
+  injectedMessages?: InjectedMessage[];
 };
 
 /** Map of tool names to tool definitions */
@@ -213,7 +244,6 @@ export type McpNameFormat = 'full' | 'base';
 
 /** Parameters for creating a Tool Search tool */
 export type ToolSearchParams = {
-  apiKey?: string;
   toolRegistry?: LCToolRegistry;
   onlyDeferred?: boolean;
   baseUrl?: string;
@@ -223,7 +253,6 @@ export type ToolSearchParams = {
   mcpServer?: string | string[];
   /** Format for MCP tool names: 'full' (tool_mcp_server) or 'base' (tool only). Default: 'full' */
   mcpNameFormat?: McpNameFormat;
-  [key: string]: unknown;
 };
 
 /** Simplified tool metadata for search purposes */
@@ -318,12 +347,16 @@ export type ProgrammaticExecutionArtifact = {
   files?: FileRefs;
 };
 
+/** Parameters for creating a bash execution tool (same API as CodeExecutor, bash-only) */
+export type BashExecutionToolParams = CodeExecutionToolParams;
+
+/** Parameters for creating a bash programmatic tool calling tool (same API as PTC, bash-only) */
+export type BashProgrammaticToolCallingParams = ProgrammaticToolCallingParams;
+
 /**
  * Initialization parameters for the PTC tool
  */
 export type ProgrammaticToolCallingParams = {
-  /** Code API key (or use CODE_API_KEY env var) */
-  apiKey?: string;
   /** Code API base URL (or use CODE_BASEURL env var) */
   baseUrl?: string;
   /** Safety limit for round-trips (default: 20) */
@@ -332,8 +365,6 @@ export type ProgrammaticToolCallingParams = {
   proxy?: string;
   /** Enable debug logging (or set PTC_DEBUG=true env var) */
   debug?: boolean;
-  /** Environment variable key for API key */
-  [key: string]: unknown;
 };
 
 // ============================================================================