@librechat/agents 3.1.64 → 3.1.66-dev.0

package/src/hooks/types.ts

@@ -0,0 +1,388 @@
+// src/hooks/types.ts
+import type { BaseMessage } from '@langchain/core/messages';
+
+/**
+ * Closed set of hook lifecycle events supported by the hooks system.
+ *
+ * These mirror the subset of Claude Code's event surface that makes sense
+ * for a library context (no filesystem/CLI-specific events). See
+ * `docs/hooks-design-report.md` §3.2 for the mapping to existing
+ * `@librechat/agents` emission points.
+ */
+export const HOOK_EVENTS = [
+  'RunStart',
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PostToolUse',
+  'PostToolUseFailure',
+  'PermissionDenied',
+  'SubagentStart',
+  'SubagentStop',
+  'Stop',
+  'StopFailure',
+  'PreCompact',
+  'PostCompact',
+] as const;
+
+export type HookEvent = (typeof HOOK_EVENTS)[number];
+
+/** Tool-gating decision; executeHooks folds with `deny > ask > allow` precedence. */
+export type ToolDecision = 'allow' | 'deny' | 'ask';
+
+/** Stop-loop decision; `block` means "do not stop, run another turn". Any `block` wins. */
+export type StopDecision = 'continue' | 'block';
+
+/**
+ * Fields shared by every `HookInput`. Discriminated by `hook_event_name`.
+ *
+ * - `runId` identifies the current agent run and is always present.
+ * - `threadId` identifies the conversation thread when the host has one.
+ * - `agentId` is only set when the hook fires inside a subagent scope.
+ */
+export interface BaseHookInput {
+  runId: string;
+  threadId?: string;
+  agentId?: string;
+}
+
+export interface RunStartHookInput extends BaseHookInput {
+  hook_event_name: 'RunStart';
+  messages: BaseMessage[];
+}
+
+export interface UserPromptSubmitHookInput extends BaseHookInput {
+  hook_event_name: 'UserPromptSubmit';
+  prompt: string;
+  attachments?: BaseMessage[];
+}
+
+/**
+ * Fires before a tool is invoked. Hook may return `deny`/`ask`/`allow` and/or
+ * an `updatedInput` that replaces the tool arguments before invocation.
+ *
+ * `toolInput` is intentionally typed as `Record<string, unknown>` because the
+ * SDK is tool-agnostic — concrete tool argument shapes are only known at the
+ * call site and are narrowed by the host. This is the one escape hatch in
+ * the hook type system.
+ */
+export interface PreToolUseHookInput extends BaseHookInput {
+  hook_event_name: 'PreToolUse';
+  toolName: string;
+  toolInput: Record<string, unknown>;
+  toolUseId: string;
+  stepId?: string;
+  /**
+   * Number of times this tool has been invoked in prior batches within the
+   * current run. Within a single batch of parallel calls, all calls to the
+   * same tool share the same turn value — per-call discrimination within a
+   * batch is not supported in v1.
+   */
+  turn?: number;
+}
+
+export interface PostToolUseHookInput extends BaseHookInput {
+  hook_event_name: 'PostToolUse';
+  toolName: string;
+  toolInput: Record<string, unknown>;
+  toolOutput: unknown;
+  toolUseId: string;
+  stepId?: string;
+  turn?: number;
+}
+
+export interface PostToolUseFailureHookInput extends BaseHookInput {
+  hook_event_name: 'PostToolUseFailure';
+  toolName: string;
+  toolInput: Record<string, unknown>;
+  toolUseId: string;
+  error: string;
+  stepId?: string;
+  turn?: number;
+}
+
+export interface PermissionDeniedHookInput extends BaseHookInput {
+  hook_event_name: 'PermissionDenied';
+  toolName: string;
+  toolInput: Record<string, unknown>;
+  toolUseId: string;
+  reason: string;
+}
+
+export interface SubagentStartHookInput extends BaseHookInput {
+  hook_event_name: 'SubagentStart';
+  parentAgentId?: string;
+  agentId: string;
+  agentType: string;
+  inputs: BaseMessage[];
+}
+
+export interface SubagentStopHookInput extends BaseHookInput {
+  hook_event_name: 'SubagentStop';
+  agentId: string;
+  agentType: string;
+  messages: BaseMessage[];
+}
+
+export interface StopHookInput extends BaseHookInput {
+  hook_event_name: 'Stop';
+  messages: BaseMessage[];
+  stopReason?: string;
+  stopHookActive: boolean;
+}
+
+export interface StopFailureHookInput extends BaseHookInput {
+  hook_event_name: 'StopFailure';
+  error: string;
+  lastAssistantMessage?: BaseMessage;
+}
+
+export interface PreCompactHookInput extends BaseHookInput {
+  hook_event_name: 'PreCompact';
+  messagesBeforeCount: number;
+  trigger: 'threshold' | 'manual' | 'error';
+}
+
+export interface PostCompactHookInput extends BaseHookInput {
+  hook_event_name: 'PostCompact';
+  summary: string;
+  messagesAfterCount: number;
+}
+
+/** Discriminated union of every hook input shape. */
+export type HookInput =
+  | RunStartHookInput
+  | UserPromptSubmitHookInput
+  | PreToolUseHookInput
+  | PostToolUseHookInput
+  | PostToolUseFailureHookInput
+  | PermissionDeniedHookInput
+  | SubagentStartHookInput
+  | SubagentStopHookInput
+  | StopHookInput
+  | StopFailureHookInput
+  | PreCompactHookInput
+  | PostCompactHookInput;
+
+/** Compile-time map from event name to its input shape. */
+export type HookInputByEvent = {
+  RunStart: RunStartHookInput;
+  UserPromptSubmit: UserPromptSubmitHookInput;
+  PreToolUse: PreToolUseHookInput;
+  PostToolUse: PostToolUseHookInput;
+  PostToolUseFailure: PostToolUseFailureHookInput;
+  PermissionDenied: PermissionDeniedHookInput;
+  SubagentStart: SubagentStartHookInput;
+  SubagentStop: SubagentStopHookInput;
+  Stop: StopHookInput;
+  StopFailure: StopFailureHookInput;
+  PreCompact: PreCompactHookInput;
+  PostCompact: PostCompactHookInput;
+};
+
+/**
+ * Fields common to every hook output. Hooks that have nothing to say simply
+ * return `{}` (or omit the fields below).
+ */
+export interface BaseHookOutput {
+  /** Context string to inject into the conversation. Accumulated across hooks. */
+  additionalContext?: string;
+  /** True to prevent the next model turn. Any hook can set this. */
+  preventContinuation?: boolean;
+  /** Reason reported alongside `preventContinuation`. */
+  stopReason?: string;
+}
+
+export type RunStartHookOutput = BaseHookOutput;
+
+export interface UserPromptSubmitHookOutput extends BaseHookOutput {
+  decision?: ToolDecision;
+  reason?: string;
+}
+
+export interface PreToolUseHookOutput extends BaseHookOutput {
+  decision?: ToolDecision;
+  reason?: string;
+  /**
+   * Replacement tool input. Merged into the pending tool call by the host.
+   *
+   * When multiple hooks set `updatedInput` within a single `executeHooks`
+   * call, the last writer in registration order wins (outer loop: matcher
+   * registration order; inner loop: hook position within the matcher). The
+   * winner is deterministic — `Promise.all` preserves input-array order.
+   * Consumers that need a single authoritative rewrite should still scope
+   * `updatedInput` to one hook per matcher to avoid confusing precedence.
+   */
+  updatedInput?: Record<string, unknown>;
+}
+
+export interface PostToolUseHookOutput extends BaseHookOutput {
+  /**
+   * Replacement tool output. Flows through the aggregated result so the
+   * host can substitute it before appending the tool result message.
+   * Ordering semantics match `PreToolUseHookOutput.updatedInput`:
+   * last-writer-wins in registration order.
+   */
+  updatedOutput?: unknown;
+}
+
+export type PostToolUseFailureHookOutput = BaseHookOutput;
+
+export type PermissionDeniedHookOutput = BaseHookOutput;
+
+export interface SubagentStartHookOutput extends BaseHookOutput {
+  decision?: ToolDecision;
+  reason?: string;
+}
+
+export type SubagentStopHookOutput = BaseHookOutput;
+
+export interface StopHookOutput extends BaseHookOutput {
+  decision?: StopDecision;
+  reason?: string;
+}
+
+export type StopFailureHookOutput = BaseHookOutput;
+
+export type PreCompactHookOutput = BaseHookOutput;
+
+export type PostCompactHookOutput = BaseHookOutput;
+
+/** Compile-time map from event name to its output shape. */
+export type HookOutputByEvent = {
+  RunStart: RunStartHookOutput;
+  UserPromptSubmit: UserPromptSubmitHookOutput;
+  PreToolUse: PreToolUseHookOutput;
+  PostToolUse: PostToolUseHookOutput;
+  PostToolUseFailure: PostToolUseFailureHookOutput;
+  PermissionDenied: PermissionDeniedHookOutput;
+  SubagentStart: SubagentStartHookOutput;
+  SubagentStop: SubagentStopHookOutput;
+  Stop: StopHookOutput;
+  StopFailure: StopFailureHookOutput;
+  PreCompact: PreCompactHookOutput;
+  PostCompact: PostCompactHookOutput;
+};
+
+/** Superset output shape used by the executor's fold loop. */
+export type HookOutput =
+  | RunStartHookOutput
+  | UserPromptSubmitHookOutput
+  | PreToolUseHookOutput
+  | PostToolUseHookOutput
+  | PostToolUseFailureHookOutput
+  | PermissionDeniedHookOutput
+  | SubagentStartHookOutput
+  | SubagentStopHookOutput
+  | StopHookOutput
+  | StopFailureHookOutput
+  | PreCompactHookOutput
+  | PostCompactHookOutput;
+
+/**
+ * A hook callback is a plain async function registered against a specific
+ * event. The `signal` is always supplied by `executeHooks` and combines the
+ * batch's parent signal with the per-hook timeout — callbacks that perform
+ * long-running work should observe it.
+ */
+export type HookCallback<E extends HookEvent = HookEvent> = (
+  input: HookInputByEvent[E],
+  signal: AbortSignal
+) => HookOutputByEvent[E] | Promise<HookOutputByEvent[E]>;
+
+/**
+ * A matcher groups one or more callbacks under a shared regex filter and
+ * shared timeout/once/internal flags. The generic `E` ties the callback
+ * types to the event the matcher is registered against.
+ */
+export interface HookMatcher<E extends HookEvent = HookEvent> {
+  /**
+   * Regex pattern matched against the event's primary query string (e.g.
+   * the tool name for `PreToolUse`, the agent type for `SubagentStart`).
+   *
+   * Omitted or empty means "always match". For events that do not supply a
+   * query string (`RunStart`, `Stop`, etc.), only wildcard matchers fire —
+   * a non-empty pattern on such events will never match.
+   *
+   * Patterns are treated as trusted input: `executeHooks` compiles them
+   * with `new RegExp(pattern)` without any sandbox, and a pathological
+   * pattern can block the event loop. Host registration code is expected
+   * to validate or length-bound patterns that originate from user input.
+   */
+  pattern?: string;
+  /** Callbacks that fire when the matcher hits. Executed in parallel. */
+  hooks: HookCallback<E>[];
+  /** Per-matcher timeout in ms. Defaults to the executor's batch timeout. */
+  timeout?: number;
+  /**
+   * Atomically remove the matcher before its first dispatch.
+   *
+   * `executeHooks` claims `once: true` matchers synchronously — between
+   * `getMatchers` and its first `await` — so two concurrent calls cannot
+   * both dispatch the same matcher. Whichever call runs its sync prefix
+   * first wins the matcher; the other sees an empty bucket.
+   *
+   * Semantics are "at most one dispatch, ever" — if every hook in the
+   * matcher throws, the matcher is still gone. Use `once` for
+   * fire-and-forget bootstrapping (registration, telemetry, setup). Hosts
+   * that need retry semantics should register a normal matcher and
+   * self-unregister via the callback returned from `registry.register`.
+   */
+  once?: boolean;
+  /** Internal hooks are excluded from telemetry and non-fatal error logging. */
+  internal?: boolean;
+}
+
+/**
+ * Storage shape for matchers keyed by event. Each event's matcher list is
+ * a generic array parameterized by that event type, so lookup via
+ * `HooksByEvent[E]` preserves type-safe callback signatures.
+ */
+export type HooksByEvent = {
+  [E in HookEvent]?: HookMatcher<E>[];
+};
+
+/**
+ * Aggregated result of a single `executeHooks` call. Fields are populated
+ * according to the fold rules in `executeHooks.ts`.
+ */
+export interface AggregatedHookResult {
+  /** Folded tool-gating decision; `deny > ask > allow`. */
+  decision?: ToolDecision;
+  /** Folded stop decision; any `block` wins. */
+  stopDecision?: StopDecision;
+  /** Reason from the hook that set the winning decision. */
+  reason?: string;
+  /**
+   * Replacement tool input from a `PreToolUse` hook.
+   *
+   * Last-writer-wins in **registration order**: `executeHooks` uses
+   * `Promise.all`, which preserves input-array order, so the fold iterates
+   * outcomes in the same order they were pushed — outer loop over matchers
+   * as they sit in the registry, inner loop over each matcher's `hooks`
+   * array. The winner is therefore deterministic but may not match the
+   * order in which hooks actually completed. Consumers that want a single
+   * authoritative rewrite should still register one `updatedInput`-setting
+   * hook per matcher to avoid subtle precedence bugs.
+   */
+  updatedInput?: Record<string, unknown>;
+  /**
+   * Replacement tool output from a `PostToolUse` hook.
+   *
+   * Same last-writer-wins-in-registration-order semantics as
+   * `updatedInput`. Present only when at least one hook set it; `undefined`
+   * means "use the original tool output".
+   */
+  updatedOutput?: unknown;
+  /** Accumulated `additionalContext` strings from every hook, in order. */
+  additionalContexts: string[];
+  /** True if any hook returned `preventContinuation`. */
+  preventContinuation?: boolean;
+  /**
+   * Reason recorded alongside `preventContinuation`. First winner wins:
+   * once a hook sets both flags, later hooks that also set
+   * `preventContinuation` do not overwrite the reason.
+   */
+  stopReason?: string;
+  /** Error messages from hooks that threw; always present (possibly empty). */
+  errors: string[];
+}

package/src/index.ts

@@ -14,7 +14,12 @@ export * from './summarization';
 /* Tools */
 export * from './tools/Calculator';
 export * from './tools/CodeExecutor';
+export * from './tools/BashExecutor';
 export * from './tools/ProgrammaticToolCalling';
+export * from './tools/BashProgrammaticToolCalling';
+export * from './tools/SkillTool';
+export * from './tools/ReadFile';
+export * from './tools/skillCatalog';
 export * from './tools/ToolSearch';
 export * from './tools/ToolNode';
 export * from './tools/schema';
@@ -25,6 +30,9 @@ export * from './tools/search';
 export * from './common';
 export * from './utils';
 
+/* Hooks */
+export * from './hooks';
+
 /* Types */
 export type * from './types';
 

package/src/llm/anthropic/types.ts

@@ -6,7 +6,7 @@ export type AnthropicMessageDeltaEvent = Anthropic.MessageDeltaEvent;
 export type AnthropicMessageStartEvent = Anthropic.MessageStartEvent;
 
 export type AnthropicToolResponse = {
-  type: 'tool_use';
+  type: 'tool_use' | 'server_tool_use';
   id: string;
   name: string;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any

package/src/llm/anthropic/utils/message_inputs.ts

@@ -144,7 +144,9 @@ export function _convertLangChainToolCallToAnthropic(
     throw new Error('Anthropic requires all tool calls to have an "id".');
   }
   return {
-    type: 'tool_use',
+    type: toolCall.id.startsWith(Constants.ANTHROPIC_SERVER_TOOL_PREFIX)
+      ? 'server_tool_use'
+      : 'tool_use',
     id: toolCall.id,
     name: toolCall.name,
     input: toolCall.args,
@@ -364,87 +366,90 @@ function _formatContent(message: BaseMessage) {
   } else {
     const contentBlocks = content.map((contentPart) => {
       /**
-       * Handle malformed blocks that have server tool fields mixed with text type.
-       * These can occur when server_tool_use blocks get mislabeled during aggregation.
-       * Correct their type ONLY if we can confirm it's a server tool by checking the ID prefix.
-       * Anthropic needs both server_tool_use and web_search_tool_result blocks for citations to work.
+       * Normalize server_tool_use blocks into a clean shape the API accepts.
+       * These blocks may arrive with the correct type (server_tool_use) or mislabeled
+       * as text/tool_use after chunk concatenation or state serialization.
+       * Regardless of current type, if the id starts with 'srvtoolu_' we rebuild
+       * a clean block with only the properties the API expects.
        */
       if (
         'id' in contentPart &&
-        'name' in contentPart &&
-        'input' in contentPart &&
-        contentPart.type === 'text'
+        typeof (contentPart as Record<string, unknown>).id === 'string' &&
+        ((contentPart as Record<string, unknown>).id as string).startsWith(
+          Constants.ANTHROPIC_SERVER_TOOL_PREFIX
+        ) &&
+        'name' in contentPart
       ) {
         const rawPart = contentPart as Record<string, unknown>;
-        const id = rawPart.id as string;
-
-        if (id && id.startsWith(Constants.ANTHROPIC_SERVER_TOOL_PREFIX)) {
-          let input = rawPart.input;
-
-          // Ensure input is an object
-          if (typeof input === 'string') {
-            try {
-              input = JSON.parse(input);
-            } catch {
-              input = {};
-            }
+        let input = rawPart.input;
+        if (typeof input === 'string') {
+          try {
+            input = JSON.parse(input);
+          } catch {
+            input = {};
           }
+        }
+        const corrected: AnthropicServerToolUseBlockParam = {
+          type: 'server_tool_use',
+          id: rawPart.id as string,
+          name: (rawPart.name ?? 'web_search') as 'web_search',
+          input: (input ?? {}) as Record<string, unknown>,
+        };
+        return corrected;
+      }
 
-          const corrected: AnthropicServerToolUseBlockParam = {
-            type: 'server_tool_use',
-            id,
-            name: 'web_search',
-            input: input as Record<string, unknown>,
+      /**
+       * Normalize web_search_tool_result blocks into a clean shape.
+       * Same rationale as above — the block may carry extra properties from
+       * streaming (input, index, etc.) that the API rejects. Rebuild cleanly.
+       */
+      if (
+        'tool_use_id' in contentPart &&
+        typeof (contentPart as Record<string, unknown>).tool_use_id ===
+          'string' &&
+        (
+          (contentPart as Record<string, unknown>).tool_use_id as string
+        ).startsWith(Constants.ANTHROPIC_SERVER_TOOL_PREFIX) &&
+        'content' in contentPart
+      ) {
+        const rawPart = contentPart as Record<string, unknown>;
+        const content = rawPart.content;
+        const isValidContent =
+          Array.isArray(content) ||
+          (content != null &&
+            typeof content === 'object' &&
+            'type' in content &&
+            (content as Record<string, unknown>).type ===
+              'web_search_tool_result_error');
+
+        if (isValidContent) {
+          const corrected: AnthropicWebSearchToolResultBlockParam = {
+            type: 'web_search_tool_result',
+            tool_use_id: rawPart.tool_use_id as string,
+            content:
+              content as AnthropicWebSearchToolResultBlockParam['content'],
           };
-
           return corrected;
         }
-
-        // If it's not a server tool, skip it (return null to filter it out)
         return null;
       }
 
       /**
-       * Handle malformed web_search_tool_result blocks marked as text.
-       * These have tool_use_id and nested content - fix their type instead of filtering.
-       * Only correct if we can confirm it's a web search result by checking the tool_use_id prefix.
-       *
-       * Handles both success results (array content) and error results (object with error_code).
+       * Skip non-server malformed blocks that have tool fields mixed with text type.
        */
+      if (
+        'id' in contentPart &&
+        'name' in contentPart &&
+        'input' in contentPart &&
+        contentPart.type === 'text'
+      ) {
+        return null;
+      }
       if (
         'tool_use_id' in contentPart &&
         'content' in contentPart &&
         contentPart.type === 'text'
       ) {
-        const rawPart = contentPart as Record<string, unknown>;
-        const toolUseId = rawPart.tool_use_id as string;
-        const content = rawPart.content;
-
-        if (
-          toolUseId &&
-          toolUseId.startsWith(Constants.ANTHROPIC_SERVER_TOOL_PREFIX)
-        ) {
-          // Verify content is either an array (success) or error object
-          const isValidContent =
-            Array.isArray(content) ||
-            (content != null &&
-              typeof content === 'object' &&
-              'type' in content &&
-              (content as Record<string, unknown>).type ===
-                'web_search_tool_result_error');
-
-          if (isValidContent) {
-            const corrected: AnthropicWebSearchToolResultBlockParam = {
-              type: 'web_search_tool_result',
-              tool_use_id: toolUseId,
-              content:
-                content as AnthropicWebSearchToolResultBlockParam['content'],
-            };
-            return corrected;
-          }
-        }
-
-        // If it's not a recognized server tool result format, skip it (return null to filter it out)
         return null;
       }
 
@@ -540,6 +545,15 @@ function _formatContent(message: BaseMessage) {
           contentPartCopy.type = 'tool_use';
         }
 
+        if (
+          contentPartCopy.type === 'tool_use' &&
+          'id' in contentPartCopy &&
+          typeof contentPartCopy.id === 'string' &&
+          contentPartCopy.id.startsWith(Constants.ANTHROPIC_SERVER_TOOL_PREFIX)
+        ) {
+          contentPartCopy.type = 'server_tool_use';
+        }
+
         if ('input' in contentPartCopy) {
           // Anthropic tool use inputs should be valid objects, when applicable.
           if (typeof contentPartCopy.input === 'string') {
@@ -594,7 +608,11 @@ function _formatContent(message: BaseMessage) {
         throw new Error('Unsupported message content format');
       }
     });
-    return contentBlocks.filter((block) => block !== null);
+    return contentBlocks.filter(
+      (block) =>
+        block !== null &&
+        !(block.type === 'text' && 'text' in block && block.text === '')
+    );
   }
 }
 
@@ -631,19 +649,26 @@ export function _convertMessagesToAnthropicPayload(
     }
     if (isAIMessage(message) && !!message.tool_calls?.length) {
       if (typeof message.content === 'string') {
+        const clientToolCalls = message.tool_calls.filter(
+          (tc) =>
+            !(
+              tc.id?.startsWith(Constants.ANTHROPIC_SERVER_TOOL_PREFIX) ?? false
+            )
+        );
         if (message.content === '') {
           return {
             role,
-            content: message.tool_calls.map(
-              _convertLangChainToolCallToAnthropic
-            ),
+            content:
+              clientToolCalls.length > 0
+                ? clientToolCalls.map(_convertLangChainToolCallToAnthropic)
+                : [{ type: 'text' as const, text: ' ' }],
           };
         } else {
           return {
             role,
             content: [
-              { type: 'text', text: message.content },
-              ...message.tool_calls.map(_convertLangChainToolCallToAnthropic),
+              { type: 'text' as const, text: message.content },
+              ...clientToolCalls.map(_convertLangChainToolCallToAnthropic),
             ],
           };
         }