@librechat/agents 3.1.68 → 3.1.71-dev.0

package/src/hooks/types.ts

@@ -0,0 +1,404 @@
+// 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;
+  /**
+   * What triggered compaction. Matches `SummarizationTrigger.type` from the
+   * agent's summarization config. `'default'` means no trigger was
+   * configured and compaction fired because messages were pruned.
+   */
+  trigger:
+    | 'token_ratio'
+    | 'remaining_tokens'
+    | 'messages_to_refine'
+    | 'default'
+    | (string & {});
+}
+
+export interface PostCompactHookInput extends BaseHookInput {
+  hook_event_name: 'PostCompact';
+  summary: string;
+  /**
+   * Number of messages remaining after compaction. The summarize node
+   * returns a `removeAll` signal that clears all messages from state;
+   * the summary itself is injected into the system prompt, not as a
+   * message. This is `0` at the point of hook dispatch.
+   */
+  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,14 @@ 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/SubagentTool';
+export * from './tools/subagent';
+export * from './tools/ReadFile';
+export * from './tools/skillCatalog';
 export * from './tools/ToolSearch';
 export * from './tools/ToolNode';
 export * from './tools/schema';
@@ -25,6 +32,9 @@ export * from './tools/search';
 export * from './common';
 export * from './utils';
 
+/* Hooks */
+export * from './hooks';
+
 /* Types */
 export type * from './types';
 

package/src/messages/format.ts

@@ -797,18 +797,39 @@ function contentPartCharLength(part: MessageContentComplex): number {
   return len;
 }
 
+/** Extracts the skillName from a skill tool_call's args (string or object). */
+function extractSkillName(args: unknown): string | undefined {
+  let parsed: Record<string, unknown> | undefined;
+  if (typeof args === 'string') {
+    try {
+      parsed = JSON.parse(args) as Record<string, unknown>;
+    } catch {
+      /* malformed args — skip */
+    }
+  } else {
+    parsed = args as Record<string, unknown> | undefined;
+  }
+  const name = parsed?.skillName;
+  return typeof name === 'string' && name !== '' ? name : undefined;
+}
+
 /**
  * Formats an array of messages for LangChain, handling tool calls and creating ToolMessage instances.
  *
  * @param payload - The array of messages to format.
  * @param indexTokenCountMap - Optional map of message indices to token counts.
  * @param tools - Optional set of tool names that are allowed in the request.
+ * @param skills - Optional map of skill name to body for reconstructing skill HumanMessages.
  * @returns - Object containing formatted messages and updated indexTokenCountMap if provided.
  */
 export const formatAgentMessages = (
   payload: TPayload,
   indexTokenCountMap?: Record<number, number | undefined>,
-  tools?: Set<string>
+  tools?: Set<string>,
+  /** Pre-resolved skill bodies keyed by skill name. When present, HumanMessages
+   *  are reconstructed after skill ToolMessages to restore skill instructions
+   *  that were only in LangGraph state during the original run. */
+  skills?: Map<string, string>
 ): {
   messages: Array<HumanMessage | AIMessage | SystemMessage | ToolMessage>;
   indexTokenCountMap?: Record<number, number>;
@@ -902,6 +923,7 @@ export const formatAgentMessages = (
      * - Dynamically expand the set when tool_search results are encountered
      */
     let processedMessage = message;
+    let pendingSkillNames: Set<string> | undefined;
     if (discoveredTools) {
       const content = message.content;
       if (content != null && Array.isArray(content)) {
@@ -950,8 +972,17 @@ export const formatAgentMessages = (
           }
 
           if (discoveredTools.has(toolName)) {
-            /** Valid tool - keep it */
             filteredContent.push(part);
+            if (
+              toolName === Constants.SKILL_TOOL &&
+              skills?.size != null &&
+              skills.size > 0
+            ) {
+              const skillName = extractSkillName(part.tool_call.args) ?? '';
+              if (skillName) {
+                (pendingSkillNames ??= new Set()).add(skillName);
+              }
+            }
           } else {
             /** Invalid tool - convert to string for context preservation */
             if (
@@ -1027,6 +1058,25 @@ export const formatAgentMessages = (
       }
     }
 
+    /** When tools filtering is off, still detect skill tool_calls for body reconstruction */
+    if (!discoveredTools && skills?.size != null && skills.size > 0) {
+      const content = processedMessage.content;
+      if (Array.isArray(content)) {
+        for (const part of content) {
+          if (
+            part.type !== ContentTypes.TOOL_CALL ||
+            part.tool_call?.name !== Constants.SKILL_TOOL
+          ) {
+            continue;
+          }
+          const skillName = extractSkillName(part.tool_call.args) ?? '';
+          if (skillName) {
+            (pendingSkillNames ??= new Set()).add(skillName);
+          }
+        }
+      }
+    }
+
     const formattedMessages = formatAssistantMessage(processedMessage);
     if (sourceMessageId != null && sourceMessageId !== '') {
       for (const formattedMessage of formattedMessages) {
@@ -1035,9 +1085,29 @@ export const formatAgentMessages = (
     }
     messages.push(...formattedMessages);
 
-    // Update the index mapping for this assistant message
-    // Store all indices that were created from this original message
+    // Capture index range BEFORE skill body injection so injected
+    // HumanMessages are excluded from the assistant's token distribution.
     const endMessageIndex = messages.length;
+
+    if (pendingSkillNames?.size != null && pendingSkillNames.size > 0) {
+      for (const skillName of pendingSkillNames) {
+        const body = skills?.get(skillName) ?? '';
+        if (body) {
+          messages.push(
+            new HumanMessage({
+              content: body,
+              additional_kwargs: {
+                role: 'user',
+                isMeta: true,
+                source: 'skill',
+                skillName,
+              },
+            })
+          );
+        }
+      }
+    }
+
     const resultIndices = [];
     for (let j = startMessageIndex; j < endMessageIndex; j++) {
       resultIndices.push(j);