@librechat/agents 3.1.68 → 3.1.71-dev.0

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, ToolOutputReferencesConfig } 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,20 @@ 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;
+  /**
+   * Run-scoped tool output reference configuration. When `enabled` is
+   * `true`, tool outputs are registered under stable keys
+   * (`tool<idx>turn<turn>`) and subsequent tool calls can pipe previous
+   * outputs into their arguments via `{{tool<idx>turn<turn>}}`
+   * placeholders. Disabled by default so existing runs are unaffected.
+   */
+  toolOutputReferences?: ToolOutputReferencesConfig;
 };
 
 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,9 @@
 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 { ToolOutputReferenceRegistry } from '@/tools/toolOutputReferences';
+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 +50,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;
   /**
@@ -56,6 +63,22 @@ export type ToolNodeOptions = {
    * When provided, takes precedence over the value computed from maxContextTokens.
    */
   maxToolResultChars?: number;
+  /**
+   * Run-scoped tool output reference configuration. When `enabled` is
+   * `true`, ToolNode registers successful outputs and substitutes
+   * `{{tool<idx>turn<turn>}}` placeholders found in string args.
+   *
+   * Ignored when `toolOutputRegistry` is also provided (host-supplied
+   * registry wins).
+   */
+  toolOutputReferences?: ToolOutputReferencesConfig;
+  /**
+   * Pre-constructed registry instance shared across ToolNodes for the
+   * run. Graphs pass the same registry to every ToolNode they compile
+   * so cross-agent `{{tool<i>turn<n>}}` substitutions resolve. Takes
+   * precedence over `toolOutputReferences` when both are set.
+   */
+  toolOutputRegistry?: ToolOutputReferenceRegistry;
 };
 
 export type ToolNodeConstructorParams = ToolRefs & ToolNodeOptions;
@@ -81,9 +104,7 @@ export type CodeExecutionToolParams =
   | {
       session_id?: string;
       user_id?: string;
-      apiKey?: string;
       files?: CodeEnvFile[];
-      [EnvVar.CODE_API_KEY]?: string;
     };
 
 export type FileRef = {
@@ -186,6 +207,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,11 +239,72 @@ 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 */
 export type LCToolRegistry = Map<string, LCTool>;
 
+/**
+ * Run-scoped configuration for tool output references.
+ *
+ * When enabled, each successful tool result is registered under a stable
+ * key (`tool<idx>turn<turn>`). Later tool calls can pipe a previous
+ * output into their arguments by including the literal placeholder
+ * `{{tool<idx>turn<turn>}}` anywhere in a string argument; ToolNode
+ * substitutes it with the stored output immediately before invoking
+ * the tool.
+ *
+ * The registry stores the *raw, untruncated* tool output (subject to
+ * its own size caps) so a later substitution can pipe the full payload
+ * into the next tool even when the LLM only saw a head+tail-truncated
+ * preview in `ToolMessage.content`. Size limits are decoupled from the
+ * LLM-visible truncation budget and default to 5 MB total.
+ *
+ * Known limitations:
+ *  - Tools that return a `ToolMessage` with array-type content
+ *    (multi-part content blocks such as text + image) are not
+ *    registered and cannot be cited via `{{tool<i>turn<n>}}`. A
+ *    warning is logged so the missing reference is visible.
+ *  - When a `PostToolUse` hook replaces `ToolMessage.content`, the
+ *    *post-hook* content is what gets stored in the registry (and
+ *    what the model sees), so `{{…}}` substitutions deliver the
+ *    hooked output rather than the raw tool return. This matches the
+ *    hook's "authoritative" role for output shaping.
+ */
+export type ToolOutputReferencesConfig = {
+  /** Enable the registry and placeholder substitution. Defaults to `false`. */
+  enabled?: boolean;
+  /**
+   * Maximum characters stored (and substituted) per registered output.
+   * Applied to the *raw* output before storage. Defaults to
+   * `HARD_MAX_TOOL_RESULT_CHARS` (~400 KB) — matching the
+   * LLM-visible tool-result truncation budget, which is also a safe
+   * payload size for shell `ARG_MAX` limits when a `{{…}}` expansion
+   * gets piped into a bash `command`. Hosts that want to preserve
+   * fuller fidelity (for example for non-bash API consumers) can
+   * raise this up to `maxTotalSize` (defaults to 5 MB) — be aware
+   * that large single-output substitutions may exceed shell
+   * argument-size limits on typical Linux/macOS.
+   */
+  maxOutputSize?: number;
+  /**
+   * Hard cap on total characters retained across all registered outputs
+   * for the run. When exceeded, the oldest entries are evicted FIFO
+   * until the total fits. The effective per-output cap is
+   * `min(maxOutputSize, maxTotalSize)` so a single stored output can
+   * never exceed the aggregate bound. Defaults to
+   * `calculateMaxTotalToolOutputSize(maxOutputSize)` (5 MB).
+   */
+  maxTotalSize?: number;
+};
+
 export type ProgrammaticCache = { toolMap: ToolMap; toolDefs: LCTool[] };
 
 /** Search mode: code_interpreter uses external sandbox, local uses safe substring matching */
@@ -213,7 +315,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 +324,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 +418,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 +436,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;
 };
 
 // ============================================================================

package/src/utils/__tests__/truncation.test.ts

@@ -0,0 +1,66 @@
+import { describe, it, expect } from '@jest/globals';
+import {
+  HARD_MAX_TOOL_RESULT_CHARS,
+  HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE,
+  calculateMaxToolResultChars,
+  calculateMaxTotalToolOutputSize,
+} from '@/utils/truncation';
+
+describe('truncation helpers', () => {
+  describe('calculateMaxToolResultChars', () => {
+    it('returns the hard cap when context tokens are missing', () => {
+      expect(calculateMaxToolResultChars()).toBe(HARD_MAX_TOOL_RESULT_CHARS);
+      expect(calculateMaxToolResultChars(undefined)).toBe(
+        HARD_MAX_TOOL_RESULT_CHARS
+      );
+      expect(calculateMaxToolResultChars(0)).toBe(HARD_MAX_TOOL_RESULT_CHARS);
+      expect(calculateMaxToolResultChars(-100)).toBe(
+        HARD_MAX_TOOL_RESULT_CHARS
+      );
+    });
+
+    it('computes 30% of context-window characters for normal inputs', () => {
+      // 100k tokens * 0.3 = 30k tokens * 4 chars/token = 120k chars
+      expect(calculateMaxToolResultChars(100_000)).toBe(120_000);
+    });
+
+    it('clamps to the hard cap for large context windows', () => {
+      // 1M tokens * 0.3 * 4 = 1.2M chars, exceeds 400k cap
+      expect(calculateMaxToolResultChars(1_000_000)).toBe(
+        HARD_MAX_TOOL_RESULT_CHARS
+      );
+    });
+  });
+
+  describe('calculateMaxTotalToolOutputSize', () => {
+    it('returns the absolute hard cap when no per-output is provided', () => {
+      expect(calculateMaxTotalToolOutputSize()).toBe(
+        HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE
+      );
+      expect(calculateMaxTotalToolOutputSize(0)).toBe(
+        HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE
+      );
+      expect(calculateMaxTotalToolOutputSize(-1)).toBe(
+        HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE
+      );
+    });
+
+    it('doubles the per-output cap by default', () => {
+      expect(calculateMaxTotalToolOutputSize(100_000)).toBe(200_000);
+      expect(calculateMaxTotalToolOutputSize(1)).toBe(2);
+    });
+
+    it('clamps the doubled value to HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE', () => {
+      // 4M * 2 = 8M, exceeds 5M
+      expect(calculateMaxTotalToolOutputSize(4_000_000)).toBe(
+        HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE
+      );
+      // Right at the boundary: 2.5M * 2 = 5M (no clamp).
+      expect(calculateMaxTotalToolOutputSize(2_500_000)).toBe(5_000_000);
+      // Just past it: 2_500_001 * 2 = 5_000_002 -> clamped.
+      expect(calculateMaxTotalToolOutputSize(2_500_001)).toBe(
+        HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE
+      );
+    });
+  });
+});

package/src/utils/truncation.ts

@@ -12,6 +12,16 @@
  */
 export const HARD_MAX_TOOL_RESULT_CHARS = 400_000;
 
+/**
+ * Absolute hard cap on the aggregate size (characters) of all registered
+ * tool outputs kept for `{{tool<i>turn<n>}}` substitution. Set at 5 MB
+ * because the registry stores *raw, untruncated* tool output — full
+ * fidelity for piping into downstream bash/jq — so the budget needs
+ * enough headroom to keep a handful of large responses without
+ * ballooning unbounded.
+ */
+export const HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE = 5_000_000;
+
 /**
  * Computes the dynamic max tool result size based on the model's context window.
  * Uses 30% of the context window (in estimated characters, ~4 chars/token)
@@ -32,6 +42,26 @@ export function calculateMaxToolResultChars(
   );
 }
 
+/**
+ * Computes the default aggregate size (characters) for the tool output
+ * reference registry based on the per-output budget. Mirrors
+ * `calculateMaxToolResultChars`'s shape: a multiple of the per-output
+ * cap, clamped to `HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE`.
+ *
+ * @param maxOutputSize - Per-output maximum characters (e.g., the
+ *   ToolNode's `maxToolResultChars`). When omitted or non-positive,
+ *   falls back to the absolute total cap.
+ * @returns Maximum total characters retained across the registry.
+ */
+export function calculateMaxTotalToolOutputSize(
+  maxOutputSize?: number
+): number {
+  if (maxOutputSize == null || maxOutputSize <= 0) {
+    return HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE;
+  }
+  return Math.min(maxOutputSize * 2, HARD_MAX_TOTAL_TOOL_OUTPUT_SIZE);
+}
+
 /**
  * Truncates a tool-call input (the arguments/payload of a tool_use block)
  * using head+tail strategy. Returns an object with `_truncated` (the