@librechat/agents 3.1.68 → 3.1.71-dev.0

package/src/hooks/executeHooks.ts

@@ -0,0 +1,375 @@
+// src/hooks/executeHooks.ts
+import type { Logger } from 'winston';
+import type { HookRegistry } from './HookRegistry';
+import type {
+  HookInput,
+  HookEvent,
+  HookOutput,
+  HookMatcher,
+  ToolDecision,
+  StopDecision,
+  HookCallback,
+  AggregatedHookResult,
+} from './types';
+import { matchesQuery } from './matchers';
+
+/** Default per-hook timeout when a matcher doesn't set its own. */
+export const DEFAULT_HOOK_TIMEOUT_MS = 30_000;
+
+/**
+ * Options for a single `executeHooks` call. The `input` drives everything —
+ * the event name is read from `input.hook_event_name`, matchers are looked
+ * up against that event, and each hook receives `input` directly.
+ */
+export interface ExecuteHooksOptions {
+  registry: HookRegistry;
+  input: HookInput;
+  /** Scope lookup to this session (in addition to global matchers). */
+  sessionId?: string;
+  /** Query string matched against each matcher's pattern (tool name, etc.). */
+  matchQuery?: string;
+  /** Parent AbortSignal — combined with per-hook timeout into the hook signal. */
+  signal?: AbortSignal;
+  /** Default per-hook timeout; overridden by `matcher.timeout` when present. */
+  timeoutMs?: number;
+  /** Optional winston logger for non-internal hook errors. */
+  logger?: Logger;
+}
+
+type WideMatcher = HookMatcher<HookEvent>;
+type WideCallback = HookCallback<HookEvent>;
+
+interface HookOutcome {
+  matcher: WideMatcher;
+  output: HookOutput | null;
+  error: string | null;
+  timedOut: boolean;
+}
+
+function freshResult(): AggregatedHookResult {
+  return {
+    additionalContexts: [],
+    errors: [],
+  };
+}
+
+function combineSignals(
+  parent: AbortSignal | undefined,
+  timeoutMs: number
+): AbortSignal {
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  if (parent === undefined) {
+    return timeoutSignal;
+  }
+  return AbortSignal.any([parent, timeoutSignal]);
+}
+
+function isTimeout(err: unknown): boolean {
+  if (err instanceof Error) {
+    return err.name === 'TimeoutError' || err.name === 'AbortError';
+  }
+  return false;
+}
+
+function describeError(err: unknown): string {
+  if (err instanceof Error) {
+    return err.message !== '' ? err.message : err.name;
+  }
+  return String(err);
+}
+
+function makeAbortPromise(signal: AbortSignal): {
+  promise: Promise<never>;
+  cleanup: () => void;
+} {
+  let onAbort: (() => void) | undefined;
+  const promise = new Promise<never>((_resolve, reject) => {
+    if (signal.aborted) {
+      reject(
+        signal.reason instanceof Error ? signal.reason : new Error('aborted')
+      );
+      return;
+    }
+    onAbort = (): void => {
+      reject(
+        signal.reason instanceof Error ? signal.reason : new Error('aborted')
+      );
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+  });
+  const cleanup = (): void => {
+    if (onAbort !== undefined) {
+      signal.removeEventListener('abort', onAbort);
+      onAbort = undefined;
+    }
+  };
+  return { promise, cleanup };
+}
+
+async function runHook(
+  hook: WideCallback,
+  input: HookInput,
+  signal: AbortSignal,
+  matcher: WideMatcher
+): Promise<HookOutcome> {
+  const hookPromise = Promise.resolve().then(() => hook(input, signal));
+  const { promise: abortPromise, cleanup } = makeAbortPromise(signal);
+  try {
+    const output = await Promise.race([hookPromise, abortPromise]);
+    return { matcher, output, error: null, timedOut: false };
+  } catch (err) {
+    return {
+      matcher,
+      output: null,
+      error: describeError(err),
+      timedOut: isTimeout(err),
+    };
+  } finally {
+    cleanup();
+  }
+}
+
+function reportErrors(
+  outcomes: readonly HookOutcome[],
+  event: HookEvent,
+  logger: Logger | undefined
+): void {
+  for (const outcome of outcomes) {
+    if (outcome.error === null) {
+      continue;
+    }
+    if (outcome.matcher.internal === true) {
+      continue;
+    }
+    const label = outcome.timedOut ? 'timed out' : 'threw an error';
+    const message = `Hook for ${event} ${label}: ${outcome.error}`;
+    if (logger !== undefined) {
+      logger.warn(message);
+      continue;
+    }
+    // eslint-disable-next-line no-console
+    console.warn(message);
+  }
+}
+
+function applyToolDecision(
+  agg: AggregatedHookResult,
+  decision: ToolDecision,
+  reason: string | undefined
+): void {
+  if (decision === 'deny') {
+    if (agg.decision === 'deny') {
+      return;
+    }
+    agg.decision = 'deny';
+    agg.reason = reason;
+    return;
+  }
+  if (decision === 'ask') {
+    if (agg.decision === 'deny' || agg.decision === 'ask') {
+      return;
+    }
+    agg.decision = 'ask';
+    agg.reason = reason;
+    return;
+  }
+  if (agg.decision === undefined) {
+    agg.decision = 'allow';
+    agg.reason = reason;
+  }
+}
+
+function applyStopDecision(
+  agg: AggregatedHookResult,
+  decision: StopDecision,
+  reason: string | undefined
+): void {
+  if (decision === 'block') {
+    if (agg.stopDecision === 'block') {
+      return;
+    }
+    agg.stopDecision = 'block';
+    agg.reason = reason;
+    return;
+  }
+  if (agg.stopDecision === undefined) {
+    agg.stopDecision = 'continue';
+    if (agg.reason === undefined) {
+      agg.reason = reason;
+    }
+  }
+}
+
+function applyDecision(agg: AggregatedHookResult, output: HookOutput): void {
+  if (!('decision' in output) || output.decision === undefined) {
+    return;
+  }
+  const decision = output.decision;
+  const reason =
+    'reason' in output && typeof output.reason === 'string'
+      ? output.reason
+      : undefined;
+  if (decision === 'deny' || decision === 'ask' || decision === 'allow') {
+    applyToolDecision(agg, decision, reason);
+    return;
+  }
+  applyStopDecision(agg, decision, reason);
+}
+
+function applyContext(agg: AggregatedHookResult, output: HookOutput): void {
+  if (
+    typeof output.additionalContext === 'string' &&
+    output.additionalContext.length > 0
+  ) {
+    agg.additionalContexts.push(output.additionalContext);
+  }
+}
+
+function applyStopFlag(agg: AggregatedHookResult, output: HookOutput): void {
+  if (output.preventContinuation !== true) {
+    return;
+  }
+  agg.preventContinuation = true;
+  if (typeof output.stopReason === 'string' && agg.stopReason === undefined) {
+    agg.stopReason = output.stopReason;
+  }
+}
+
+function applyUpdatedInput(
+  agg: AggregatedHookResult,
+  output: HookOutput
+): void {
+  if (!('updatedInput' in output) || output.updatedInput === undefined) {
+    return;
+  }
+  agg.updatedInput = output.updatedInput;
+}
+
+function applyUpdatedOutput(
+  agg: AggregatedHookResult,
+  output: HookOutput
+): void {
+  if (!('updatedOutput' in output) || output.updatedOutput === undefined) {
+    return;
+  }
+  agg.updatedOutput = output.updatedOutput;
+}
+
+function fold(outcomes: readonly HookOutcome[]): AggregatedHookResult {
+  const agg = freshResult();
+  for (const outcome of outcomes) {
+    if (outcome.error !== null) {
+      if (outcome.matcher.internal !== true) {
+        agg.errors.push(outcome.error);
+      }
+      continue;
+    }
+    const output = outcome.output;
+    if (output === null) {
+      continue;
+    }
+    applyContext(agg, output);
+    applyStopFlag(agg, output);
+    applyDecision(agg, output);
+    applyUpdatedInput(agg, output);
+    applyUpdatedOutput(agg, output);
+  }
+  return agg;
+}
+
+/**
+ * Fires every matcher registered against `input.hook_event_name`, folding
+ * their results per `deny > ask > allow` precedence and accumulating
+ * context/errors.
+ *
+ * ## Parallelism and determinism
+ *
+ * All matching hooks fire simultaneously and are awaited via `Promise.all`,
+ * which preserves input-array order in its returned results. The fold
+ * therefore iterates outcomes in **registration order** — outer loop over
+ * matchers as they sit in the registry (global first, then session), inner
+ * loop over each matcher's `hooks` array. Last-writer-wins fields
+ * (`updatedInput`, `updatedOutput`) are deterministic in that order, even
+ * though hooks may complete in arbitrary wall-clock order.
+ *
+ * Consumers that need a single authoritative rewrite should still scope
+ * `updatedInput`/`updatedOutput` to one hook per matcher to avoid subtle
+ * precedence bugs when matchers are added in a different order than
+ * expected.
+ *
+ * ## Timeouts and cancellation
+ *
+ * Each matcher receives **one shared `AbortSignal`** derived from the
+ * caller's parent signal combined with `matcher.timeout` (falling back to
+ * `opts.timeoutMs`, default {@link DEFAULT_HOOK_TIMEOUT_MS}). Sharing the
+ * signal across hooks in a matcher collapses N timer allocations into
+ * one, which matters on the PreToolUse hot path where a matcher with
+ * several hooks fires on every tool call. Each hook call is raced
+ * against the shared signal, so even a hook that ignores the signal is
+ * force-unblocked when the timeout fires. Timeout/abort errors are
+ * swallowed into the aggregated result's `errors` array (non-fatal by
+ * default).
+ *
+ * ## Internal matchers
+ *
+ * A matcher with `internal: true` is excluded from both the `errors` array
+ * and the logger output. Use it for infrastructure hooks whose failures
+ * should not pollute user-visible diagnostics.
+ *
+ * ## Once semantics — atomic at-most-once
+ *
+ * A matcher with `once: true` is removed from the registry **before any
+ * hook runs**, inside the synchronous prefix of `executeHooks` (between
+ * `getMatchers` and the first `await`). Because Node's event loop serialises
+ * sync work, two concurrent `executeHooks` calls can never both observe
+ * and dispatch the same `once` matcher — whichever call runs its sync
+ * prefix first consumes it, and the loser sees an empty bucket.
+ *
+ * Trade-off: if every hook in a `once` matcher throws, the matcher is
+ * still gone. "Once" here means "at most one dispatch, ever", not "at
+ * most one successful execution with retry on failure". Hosts that need
+ * retry semantics should register a normal matcher and self-unregister
+ * via the `unregister` callback returned from `registry.register`.
+ */
+export async function executeHooks(
+  opts: ExecuteHooksOptions
+): Promise<AggregatedHookResult> {
+  const {
+    registry,
+    input,
+    sessionId,
+    matchQuery,
+    signal,
+    timeoutMs = DEFAULT_HOOK_TIMEOUT_MS,
+    logger,
+  } = opts;
+  const event = input.hook_event_name;
+  const matchers = registry.getMatchers(event, sessionId);
+  if (matchers.length === 0) {
+    return freshResult();
+  }
+
+  // --- SYNC CRITICAL SECTION: once-matcher removal must complete before any await ---
+  const tasks: Promise<HookOutcome>[] = [];
+  for (const matcher of matchers) {
+    if (!matchesQuery(matcher.pattern, matchQuery)) {
+      continue;
+    }
+    if (matcher.once === true) {
+      registry.removeMatcher(event, matcher, sessionId);
+    }
+    const perHookTimeout = matcher.timeout ?? timeoutMs;
+    const matcherSignal = combineSignals(signal, perHookTimeout);
+    for (const hook of matcher.hooks) {
+      tasks.push(runHook(hook, input, matcherSignal, matcher));
+    }
+  }
+  // --- END SYNC CRITICAL SECTION ---
+  if (tasks.length === 0) {
+    return freshResult();
+  }
+
+  const outcomes = await Promise.all(tasks);
+  reportErrors(outcomes, event, logger);
+  return fold(outcomes);
+}

package/src/hooks/index.ts

@@ -0,0 +1,57 @@
+// src/hooks/index.ts
+//
+// Hook lifecycle system for `@librechat/agents`. Re-exported from
+// `src/index.ts` and consumed by `Run.processStream` (RunStart,
+// UserPromptSubmit, Stop, StopFailure), `ToolNode.dispatchToolEvents`
+// (PreToolUse, PostToolUse, PostToolUseFailure, PermissionDenied),
+// `createSummarizeNode` (PreCompact, PostCompact), and
+// `SubagentExecutor.execute` (SubagentStart, SubagentStop).
+export { HookRegistry } from './HookRegistry';
+export { executeHooks, DEFAULT_HOOK_TIMEOUT_MS } from './executeHooks';
+export {
+  matchesQuery,
+  hasNestedQuantifier,
+  MAX_PATTERN_LENGTH,
+  MAX_CACHE_SIZE,
+} from './matchers';
+export { HOOK_EVENTS } from './types';
+export type {
+  HookEvent,
+  HookInput,
+  HookOutput,
+  HookCallback,
+  HookMatcher,
+  HooksByEvent,
+  HookInputByEvent,
+  HookOutputByEvent,
+  BaseHookInput,
+  BaseHookOutput,
+  ToolDecision,
+  StopDecision,
+  AggregatedHookResult,
+  RunStartHookInput,
+  UserPromptSubmitHookInput,
+  PreToolUseHookInput,
+  PostToolUseHookInput,
+  PostToolUseFailureHookInput,
+  PermissionDeniedHookInput,
+  SubagentStartHookInput,
+  SubagentStopHookInput,
+  StopHookInput,
+  StopFailureHookInput,
+  PreCompactHookInput,
+  PostCompactHookInput,
+  RunStartHookOutput,
+  UserPromptSubmitHookOutput,
+  PreToolUseHookOutput,
+  PostToolUseHookOutput,
+  PostToolUseFailureHookOutput,
+  PermissionDeniedHookOutput,
+  SubagentStartHookOutput,
+  SubagentStopHookOutput,
+  StopHookOutput,
+  StopFailureHookOutput,
+  PreCompactHookOutput,
+  PostCompactHookOutput,
+} from './types';
+export type { ExecuteHooksOptions } from './executeHooks';

package/src/hooks/matchers.ts

@@ -0,0 +1,280 @@
+// src/hooks/matchers.ts
+
+/**
+ * Upper bound on hook-matcher pattern length. Patterns longer than this
+ * are rejected outright — the goal is a cheap cap on pathological inputs
+ * (repeated quantifiers, huge alternation groups) without pulling in a
+ * safe-regex dependency.
+ *
+ * Legitimate matchers are almost always under 50 characters (tool names,
+ * short alternations, simple prefix anchors); 512 leaves generous
+ * headroom while preventing 10KB regexes.
+ */
+export const MAX_PATTERN_LENGTH = 512;
+
+/**
+ * Upper bound on the compilation cache. Chosen to comfortably hold every
+ * distinct pattern a single multi-tenant run is likely to see (tools,
+ * agent types, basename filters) without growing without bound.
+ *
+ * Under hosts that register unique patterns per tenant, LRU eviction
+ * keeps the working set bounded — cold patterns are re-compiled on next
+ * use, which is the correct cost trade-off for long-running processes
+ * that must not leak memory.
+ */
+export const MAX_CACHE_SIZE = 256;
+
+interface CacheEntry {
+  regex: RegExp | null;
+}
+
+/**
+ * Module-level LRU cache keyed by pattern string. Map iteration order is
+ * insertion order in ECMAScript, so refreshing an entry's position means
+ * "delete then re-set". On overflow we evict the first key (least
+ * recently used).
+ *
+ * Failed compiles are cached as `{ regex: null }` so a malformed pattern
+ * does not re-enter the compiler — and so a tenant spamming bad patterns
+ * doesn't burn CPU on every call.
+ */
+const patternCache: Map<string, CacheEntry> = new Map();
+
+/**
+ * Threshold above which `touchCacheEntry` actually performs the LRU
+ * refresh. Below this watermark the cache has zero eviction pressure, so
+ * the delete+set on every hit would be pure overhead. Above it we refresh
+ * properly so hot patterns survive evictions. 75% of capacity is the
+ * standard sweet spot.
+ */
+const LRU_REFRESH_THRESHOLD = Math.floor((MAX_CACHE_SIZE * 3) / 4);
+
+function touchCacheEntry(pattern: string, entry: CacheEntry): void {
+  if (patternCache.size < LRU_REFRESH_THRESHOLD) {
+    return;
+  }
+  patternCache.delete(pattern);
+  patternCache.set(pattern, entry);
+}
+
+function setCacheEntry(pattern: string, entry: CacheEntry): void {
+  if (patternCache.size >= MAX_CACHE_SIZE) {
+    const oldestKey = patternCache.keys().next().value;
+    if (oldestKey !== undefined) {
+      patternCache.delete(oldestKey);
+    }
+  }
+  patternCache.set(pattern, entry);
+}
+
+interface QuantifierFrame {
+  hasBacktrackRisk: boolean;
+}
+
+function skipGroupSyntaxPrefix(pattern: string, start: number): number {
+  if (start >= pattern.length || pattern[start] !== '?') {
+    return start;
+  }
+  let i = start + 1;
+  if (i >= pattern.length) {
+    return i;
+  }
+  const modifier = pattern[i];
+  if (modifier === ':' || modifier === '=' || modifier === '!') {
+    return i + 1;
+  }
+  if (modifier !== '<') {
+    return i;
+  }
+  i++;
+  if (i < pattern.length && (pattern[i] === '=' || pattern[i] === '!')) {
+    return i + 1;
+  }
+  while (i < pattern.length && pattern[i] !== '>') {
+    i++;
+  }
+  if (i < pattern.length) {
+    i++;
+  }
+  return i;
+}
+
+/**
+ * Cheap syntactic detector for the most common catastrophic-backtracking
+ * shape: a quantified group that contains another quantifier (e.g.
+ * `(a+)+`, `(.*)*`, `(\w+)+$`, `(?:(a+))+`). This is the "nested
+ * quantifier" class of ReDoS — runs in polynomial-or-worse time on
+ * adversarial inputs.
+ *
+ * The scan walks the pattern linearly using an explicit stack of group
+ * frames. For each group it tracks whether the group's contents include
+ * "backtrack risk" — meaning a direct quantifier OR a nested group that
+ * carries risk up. When a group closes with a trailing quantifier AND its
+ * frame carries backtrack risk, the pattern is flagged. Risk propagates
+ * to the enclosing frame when a child group closes (whether the child
+ * itself was quantified or not), so `(?:(a+))+` — equivalent to `(a+)+`
+ * — is flagged correctly even though the outer non-capturing wrapper is
+ * one level removed from the inner quantifier.
+ *
+ * ## Group-syntax prefixes
+ *
+ * Non-capturing groups (`(?:`), lookaheads (`(?=`, `(?!`), lookbehinds
+ * (`(?<=`, `(?<!`), and named groups (`(?<name>`) are skipped over at
+ * the `(` so their `?` is not misread as a quantifier. Without this,
+ * `(?:pre_)?tool_name` would be incorrectly rejected because the scanner
+ * would see the group-syntax `?` as a quantifier at depth 1.
+ *
+ * ## Heuristic, not a proof
+ *
+ * This catches the common forms but not all. Ambiguous-alternation ReDoS
+ * like `(a|a)+` is not detected. Pathologically long patterns are also
+ * caught by {@link MAX_PATTERN_LENGTH}. Hosts that accept user-supplied
+ * patterns must still validate upstream.
+ */
+export function hasNestedQuantifier(pattern: string): boolean {
+  const stack: QuantifierFrame[] = [];
+  let i = 0;
+  while (i < pattern.length) {
+    const ch = pattern[i];
+    if (ch === '\\') {
+      i += 2;
+      continue;
+    }
+    if (ch === '[') {
+      i = findCharClassEnd(pattern, i) + 1;
+      continue;
+    }
+    if (ch === '(') {
+      stack.push({ hasBacktrackRisk: false });
+      i = skipGroupSyntaxPrefix(pattern, i + 1);
+      continue;
+    }
+    if (ch === ')') {
+      const frame = stack.pop();
+      if (frame === undefined) {
+        i++;
+        continue;
+      }
+      const next = pattern[i + 1];
+      const isQuantifier =
+        next === '*' || next === '+' || next === '?' || next === '{';
+      if (isQuantifier && frame.hasBacktrackRisk) {
+        return true;
+      }
+      if (stack.length > 0 && (frame.hasBacktrackRisk || isQuantifier)) {
+        stack[stack.length - 1].hasBacktrackRisk = true;
+      }
+      i++;
+      continue;
+    }
+    if (ch === '*' || ch === '+' || ch === '?' || ch === '{') {
+      if (stack.length > 0) {
+        stack[stack.length - 1].hasBacktrackRisk = true;
+      }
+    }
+    i++;
+  }
+  return false;
+}
+
+function findCharClassEnd(pattern: string, start: number): number {
+  let i = start + 1;
+  while (i < pattern.length) {
+    const ch = pattern[i];
+    if (ch === '\\') {
+      i += 2;
+      continue;
+    }
+    if (ch === ']') {
+      return i;
+    }
+    i++;
+  }
+  return pattern.length - 1;
+}
+
+function compile(pattern: string): RegExp | null {
+  const cached = patternCache.get(pattern);
+  if (cached !== undefined) {
+    touchCacheEntry(pattern, cached);
+    return cached.regex;
+  }
+  if (pattern.length > MAX_PATTERN_LENGTH) {
+    setCacheEntry(pattern, { regex: null });
+    return null;
+  }
+  if (hasNestedQuantifier(pattern)) {
+    setCacheEntry(pattern, { regex: null });
+    return null;
+  }
+  try {
+    const regex = new RegExp(pattern);
+    setCacheEntry(pattern, { regex });
+    return regex;
+  } catch {
+    setCacheEntry(pattern, { regex: null });
+    return null;
+  }
+}
+
+/**
+ * Tests whether a hook matcher pattern matches the given query string.
+ *
+ * ## Semantics
+ *
+ * - `undefined` or empty `pattern` matches any query (wildcard). This is
+ *   the intended shape for events that do not supply a query string at
+ *   all (`RunStart`, `Stop`, etc.) — register such matchers without a
+ *   pattern.
+ * - `undefined` or empty `query` with a non-empty `pattern` never matches.
+ *   Setting a pattern on a query-less event is therefore inert: the
+ *   matcher will simply never fire. This is intentional — it keeps
+ *   query-based filtering out of event types where "query" has no meaning,
+ *   and is documented on `HookMatcher.pattern`.
+ * - Otherwise, the pattern is compiled once (via a bounded LRU cache) and
+ *   tested against the query.
+ * - Invalid regex patterns never throw — a failed compile is cached as
+ *   "never matches" so a single malformed pattern cannot take out a whole
+ *   `executeHooks` batch.
+ *
+ * ## ReDoS mitigations
+ *
+ * Patterns compile through three cheap gates before reaching `new RegExp`:
+ *
+ * 1. {@link MAX_PATTERN_LENGTH} length cap rejects oversized inputs.
+ * 2. {@link hasNestedQuantifier} rejects the most common catastrophic-
+ *    backtracking shape (quantified group containing a quantifier).
+ * 3. Successful compiles are cached in a bounded LRU so repeated calls
+ *    never re-enter the regex compiler.
+ *
+ * These are a floor, not a ceiling. Hosts that accept user-supplied
+ * patterns should still validate upstream. The design report §3.8 routes
+ * persistable hooks through a host-side compiler before they reach this
+ * module.
+ */
+export function matchesQuery(
+  pattern: string | undefined,
+  query: string | undefined
+): boolean {
+  if (pattern === undefined || pattern === '') {
+    return true;
+  }
+  if (query === undefined || query === '') {
+    return false;
+  }
+  const regex = compile(pattern);
+  if (regex === null) {
+    return false;
+  }
+  return regex.test(query);
+}
+
+/** Clears the regex compilation cache. Intended for test isolation. */
+export function clearMatcherCache(): void {
+  patternCache.clear();
+}
+
+/** Returns the current size of the compilation cache. Intended for tests. */
+export function getMatcherCacheSize(): number {
+  return patternCache.size;
+}