@librechat/agents 3.1.67-dev.4 → 3.1.68

package/src/hooks/types.ts

@@ -1,404 +0,0 @@
-// 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[];
-}