@openrouter/agent 0.7.2 → 0.9.0

package/esm/lib/hooks-schemas.js

@@ -0,0 +1,238 @@
+import * as z4 from 'zod/v4';
+//#region Hook Names & Definition Shape
+//
+// HookName, HookDefinition, and HookRegistry live HERE (with the schemas
+// they key/describe) rather than in hooks-types.ts, so the dependency
+// between the two modules stays one-directional (hooks-types -> hooks-
+// schemas) and no import cycle exists. hooks-types re-exports them, so the
+// public import surface is unchanged.
+export const HookName = {
+    PreToolUse: 'PreToolUse',
+    PostToolUse: 'PostToolUse',
+    PostToolUseFailure: 'PostToolUseFailure',
+    UserPromptSubmit: 'UserPromptSubmit',
+    Stop: 'Stop',
+    PermissionRequest: 'PermissionRequest',
+    SessionStart: 'SessionStart',
+    SessionEnd: 'SessionEnd',
+    PostModelCall: 'PostModelCall',
+    DoomLoopDetected: 'DoomLoopDetected',
+};
+//#endregion
+//#region Payload Schemas + Derived Types
+//
+// Each payload/result type is DERIVED from its Zod schema (single source of
+// truth) so the static types can never drift from what the runtime actually
+// validates -- the same discipline custom hooks get via `zodInfer` in
+// hooks-manager.ts. `Readonly<...>` matches the immutability contract
+// handlers are given (top-level, like the previous hand-written interfaces).
+//
+// Note: payloads deliberately do NOT carry `sessionId`. The session id is
+// ambient context, not event data -- handlers read it from
+// `context.sessionId` (LifecycleHookContext), which the manager populates
+// via `setSessionId()`.
+export const PreToolUsePayloadSchema = z4.object({
+    toolName: z4.string(),
+    toolInput: z4.record(z4.string(), z4.unknown()),
+});
+export const PostToolUsePayloadSchema = z4.object({
+    toolName: z4.string(),
+    toolInput: z4.record(z4.string(), z4.unknown()),
+    toolOutput: z4.unknown(),
+    durationMs: z4.number(),
+});
+export const PostToolUseFailurePayloadSchema = z4.object({
+    toolName: z4.string(),
+    toolInput: z4.record(z4.string(), z4.unknown()),
+    error: z4.unknown(),
+});
+export const StopPayloadSchema = z4.object({
+    reason: z4.enum([
+        'max_turns',
+    ]),
+});
+export const PermissionRequestPayloadSchema = z4.object({
+    toolName: z4.string(),
+    toolInput: z4.record(z4.string(), z4.unknown()),
+    riskLevel: z4.enum([
+        'low',
+        'medium',
+        'high',
+    ]),
+});
+export const UserPromptSubmitPayloadSchema = z4.object({
+    prompt: z4.string(),
+});
+export const SessionStartPayloadSchema = z4.object({
+    config: z4.record(z4.string(), z4.unknown()).optional(),
+});
+const ModelCallUsageSchema = z4.object({
+    inputTokens: z4.number(),
+    outputTokens: z4.number(),
+    totalTokens: z4.number(),
+    cachedTokens: z4.number(),
+    reasoningTokens: z4.number(),
+    cost: z4.number().optional(),
+});
+const SessionUsageTotalsSchema = ModelCallUsageSchema.extend({
+    modelCalls: z4.number(),
+});
+export const SessionEndPayloadSchema = z4.object({
+    reason: z4.enum([
+        'user',
+        'error',
+        'max_turns',
+        'complete',
+        'doom_loop',
+    ]),
+    totalUsage: SessionUsageTotalsSchema.optional(),
+});
+export const PostModelCallPayloadSchema = z4.object({
+    sessionId: z4.string(),
+    responseId: z4.string(),
+    model: z4.string(),
+    durationMs: z4.number(),
+    turnType: z4.enum([
+        'initial',
+        'resume',
+        'tool_round',
+        'final',
+        'retry',
+    ]),
+    turnNumber: z4.number(),
+    usage: ModelCallUsageSchema.optional(),
+});
+export const DoomLoopDetectedPayloadSchema = z4.object({
+    /** Which detector fired: identical client/server tool calls, or repeated text. */
+    detector: z4.enum([
+        'tool-fingerprint',
+        'server-tool-fingerprint',
+        'text-repetition',
+        'text-streak',
+    ]),
+    /** The ladder action the engine resolved for this streak. */
+    action: z4.enum([
+        'observe',
+        'steer',
+        'escalate',
+        'block',
+        'stop',
+    ]),
+    /** Consecutive repetition count that crossed a ladder rung. */
+    streak: z4.number(),
+    /** Deterministic fingerprint of the repeated unit (call identity or text). */
+    fingerprint: z4.string(),
+    /** Present for tool-fingerprint verdicts. */
+    toolName: z4.string().optional(),
+    /** Present for tool-fingerprint verdicts: the repeated call's arguments. */
+    toolInput: z4.record(z4.string(), z4.unknown()).optional(),
+    /** Explanation used for block outputs / steer messages. */
+    message: z4.string(),
+});
+//#endregion
+//#region Result Schemas + Derived Types
+export const PreToolUseResultSchema = z4.object({
+    mutatedInput: z4.record(z4.string(), z4.unknown()).optional(),
+    block: z4
+        .union([
+        z4.boolean(),
+        z4.string(),
+    ])
+        .optional(),
+});
+export const StopResultSchema = z4.object({
+    forceResume: z4.boolean().optional(),
+    appendPrompt: z4.string().optional(),
+});
+export const PermissionRequestResultSchema = z4.object({
+    decision: z4.enum([
+        'allow',
+        'deny',
+        'ask_user',
+    ]),
+    reason: z4.string().optional(),
+});
+export const UserPromptSubmitResultSchema = z4.object({
+    mutatedPrompt: z4.string().optional(),
+    reject: z4
+        .union([
+        z4.boolean(),
+        z4.string(),
+    ])
+        .optional(),
+});
+export const DoomLoopDetectedResultSchema = z4.object({
+    /**
+     * Override the engine's resolved action for THIS event — de-escalate
+     * (`'observe'` on a would-be block) or escalate (`'stop'` immediately).
+     * When several handlers override, the last override wins. Text verdicts
+     * cannot be blocked (the tokens are already emitted); an `overrideAction:
+     * 'block'` on a text verdict downgrades to `'observe'`. An
+     * `overrideAction: 'escalate'` is honored only when an `escalation`
+     * config exists and budget remains; otherwise it downgrades to
+     * `'observe'`.
+     */
+    overrideAction: z4
+        .enum([
+        'observe',
+        'steer',
+        'escalate',
+        'block',
+        'stop',
+    ])
+        .optional(),
+});
+const VoidResultSchema = z4.void();
+//#endregion
+//#region Built-in Hook Registry
+// Keyed by the HookName enum object (not string literals) and typed as
+// Record<HookName, ...> so adding a name to HookName without registering
+// schemas here is a compile error.
+export const BUILT_IN_HOOKS = {
+    [HookName.PreToolUse]: {
+        payload: PreToolUsePayloadSchema,
+        result: PreToolUseResultSchema,
+    },
+    [HookName.PostToolUse]: {
+        payload: PostToolUsePayloadSchema,
+        result: VoidResultSchema,
+    },
+    [HookName.PostToolUseFailure]: {
+        payload: PostToolUseFailurePayloadSchema,
+        result: VoidResultSchema,
+    },
+    [HookName.UserPromptSubmit]: {
+        payload: UserPromptSubmitPayloadSchema,
+        result: UserPromptSubmitResultSchema,
+    },
+    [HookName.Stop]: {
+        payload: StopPayloadSchema,
+        result: StopResultSchema,
+    },
+    [HookName.PermissionRequest]: {
+        payload: PermissionRequestPayloadSchema,
+        result: PermissionRequestResultSchema,
+    },
+    [HookName.SessionStart]: {
+        payload: SessionStartPayloadSchema,
+        result: VoidResultSchema,
+    },
+    [HookName.SessionEnd]: {
+        payload: SessionEndPayloadSchema,
+        result: VoidResultSchema,
+    },
+    PostModelCall: {
+        payload: PostModelCallPayloadSchema,
+        result: VoidResultSchema,
+    },
+    [HookName.DoomLoopDetected]: {
+        payload: DoomLoopDetectedPayloadSchema,
+        result: DoomLoopDetectedResultSchema,
+    },
+};
+export const BUILT_IN_HOOK_NAMES = new Set(Object.keys(BUILT_IN_HOOKS));
+// NOTE: void-result hooks are detected by schema shape (`isVoidSchema` in
+// hooks-manager.ts), not by a name list, so custom hooks with `result:
+// z.void()` behave identically to the built-in void hooks.
+//#endregion
+//# sourceMappingURL=hooks-schemas.js.map

package/esm/lib/hooks-schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks-schemas.js","sourceRoot":"","sources":["../../src/lib/hooks-schemas.ts"],"names":[],"mappings":"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"}

package/esm/lib/hooks-types.d.ts

@@ -0,0 +1,178 @@
+import type { DoomLoopDetectedPayload, DoomLoopDetectedResult, PermissionRequestPayload, PermissionRequestResult, PostModelCallPayload, PostToolUseFailurePayload, PostToolUsePayload, PreToolUsePayload, PreToolUseResult, SessionEndPayload, SessionStartPayload, StopPayload, StopResult, UserPromptSubmitPayload, UserPromptSubmitResult } from './hooks-schemas.js';
+import { HookName } from './hooks-schemas.js';
+export type { HookDefinition, HookRegistry } from './hooks-schemas.js';
+export { HookName } from './hooks-schemas.js';
+/**
+ * Context provided to every lifecycle-hook handler invocation.
+ *
+ * - `signal` is aborted if the manager's `abortInflight()` is called while the
+ *   emit is still running. Handlers that kick off background work via
+ *   {@link AsyncOutput} should observe the signal for cancellation.
+ */
+export interface LifecycleHookContext {
+    readonly signal: AbortSignal;
+    readonly hookName: string;
+    /**
+     * The current session id. This is the single source for session identity in
+     * handlers -- payloads deliberately do not repeat it. The engine threads it
+     * per emit (safe for a manager shared across concurrent runs); direct
+     * `emit()` callers get the manager-level default from `setSessionId()`
+     * unless they pass a per-emit override.
+     */
+    readonly sessionId: string;
+}
+/**
+ * Returned by a handler to signal fire-and-forget mode.
+ *
+ * The chain proceeds immediately without waiting for completion. Any background
+ * work the handler has kicked off should be attached as `work` so the manager
+ * can track it for `drain()` and enforce the `asyncTimeout`.
+ *
+ * The handler is expected to construct and return this object synchronously (or
+ * resolve to it quickly). The `work` promise is the detached work to track.
+ */
+export interface AsyncOutput {
+    readonly async: true;
+    /**
+     * Background work the manager should track for `drain()` and time out after
+     * `asyncTimeout` ms. Omit if there is no work to track.
+     */
+    readonly work?: Promise<unknown>;
+    /** Milliseconds before the async handler is aborted. Default: 30000 */
+    readonly asyncTimeout?: number;
+}
+declare const DEFAULT_ASYNC_TIMEOUT = 30000;
+export { DEFAULT_ASYNC_TIMEOUT };
+/**
+ * A handler may return a sync result, an async signal, or void.
+ */
+export type HookReturn<R> = R | AsyncOutput | void;
+/**
+ * A hook handler receives the validated payload and context.
+ */
+export type HookHandler<P, R> = (payload: P, context: LifecycleHookContext) => HookReturn<R> | Promise<HookReturn<R>>;
+/**
+ * Matcher for tool-scoped hooks. Filters handler invocation by tool name.
+ */
+export type ToolMatcher = string | RegExp | ((toolName: string) => boolean);
+/**
+ * An entry registered for a specific hook.
+ */
+export interface HookEntry<P, R> {
+    readonly handler: HookHandler<P, R>;
+    readonly matcher?: ToolMatcher;
+    readonly filter?: (payload: P) => boolean;
+}
+/**
+ * Result of emitting a hook through the handler chain.
+ */
+export interface EmitResult<R, P> {
+    /**
+     * Sync results from handlers that returned a hook-specific value.
+     *
+     * INVARIANT: every entry passed the hook's result schema (invalid results
+     * are skipped or thrown per the error policy, never collected), so
+     * consumers can rely on the static type `R` without re-narrowing. For
+     * void-result hooks (no schema) entries are opaque and `R` is `undefined`
+     * -- treat them accordingly.
+     */
+    readonly results: R[];
+    /** Handles to detached async handler work. */
+    readonly pending: Promise<void>[];
+    /** The payload after all mutation piping has been applied. */
+    readonly finalPayload: P;
+    /** True if any handler triggered a block/reject short-circuit. */
+    readonly blocked: boolean;
+    /**
+     * True if any handler's result actually piped a mutation into the payload
+     * (e.g. PreToolUse `mutatedInput`, UserPromptSubmit `mutatedPrompt`).
+     * Callers should use this rather than comparing `finalPayload` references,
+     * since payload validation may clone the object even when no handler
+     * mutated it.
+     */
+    readonly mutated: boolean;
+}
+export interface HooksManagerOptions {
+    /**
+     * If true, a throwing handler or a schema-validation failure stops the chain
+     * and propagates the error. If false (default), the error is logged as a
+     * warning and execution continues.
+     */
+    readonly throwOnHandlerError?: boolean;
+}
+export type { DoomLoopDetectedPayload, DoomLoopDetectedResult, ModelCallUsage, PermissionRequestPayload, PermissionRequestResult, PostModelCallPayload, PostToolUseFailurePayload, PostToolUsePayload, PreToolUsePayload, PreToolUseResult, SessionEndPayload, SessionStartPayload, SessionUsageTotals, StopPayload, StopResult, UserPromptSubmitPayload, UserPromptSubmitResult, } from './hooks-schemas.js';
+export interface BuiltInHookDefinitions {
+    PreToolUse: {
+        payload: PreToolUsePayload;
+        result: PreToolUseResult;
+    };
+    PostToolUse: {
+        payload: PostToolUsePayload;
+        /** Observation-only hook: handlers have no meaningful result. */
+        result: undefined;
+    };
+    PostToolUseFailure: {
+        payload: PostToolUseFailurePayload;
+        /** Observation-only hook: handlers have no meaningful result. */
+        result: undefined;
+    };
+    UserPromptSubmit: {
+        payload: UserPromptSubmitPayload;
+        result: UserPromptSubmitResult;
+    };
+    Stop: {
+        payload: StopPayload;
+        result: StopResult;
+    };
+    PermissionRequest: {
+        payload: PermissionRequestPayload;
+        result: PermissionRequestResult;
+    };
+    SessionStart: {
+        payload: SessionStartPayload;
+        /** Observation-only hook: handlers have no meaningful result. */
+        result: undefined;
+    };
+    SessionEnd: {
+        payload: SessionEndPayload;
+        /** Observation-only hook: handlers have no meaningful result. */
+        result: undefined;
+    };
+    PostModelCall: {
+        payload: PostModelCallPayload;
+        /** Observation-only hook: handlers have no meaningful result. */
+        result: undefined;
+    };
+    DoomLoopDetected: {
+        payload: DoomLoopDetectedPayload;
+        result: DoomLoopDetectedResult;
+    };
+}
+/**
+ * Inline hook config passed directly to callModel.
+ * Only supports built-in hooks. For custom hooks, use a HooksManager instance.
+ */
+export type InlineHookConfig = {
+    [K in keyof BuiltInHookDefinitions]?: HookEntry<BuiltInHookDefinitions[K]['payload'], BuiltInHookDefinitions[K]['result']>[];
+};
+/**
+ * Checks if a value is an AsyncOutput signal (see {@link AsyncOutputSchema}).
+ */
+export declare function isAsyncOutput(value: unknown): value is AsyncOutput;
+/**
+ * Per-hook chain behavior: which result fields pipe mutations back into the
+ * payload, and which result field short-circuits the chain.
+ *
+ * Keyed by {@link HookName} so a typo'd hook name is a compile error rather
+ * than a silent no-behavior lookup. Hooks absent from this table are
+ * observation-only: their handlers' results are collected but never alter
+ * the payload or stop the chain. Custom hooks never participate.
+ */
+export interface HookBehavior {
+    /** result field name -> payload field it replaces (mutation piping) */
+    readonly mutations?: Readonly<Record<string, string>>;
+    /** result field that short-circuits the chain when `true` or a non-empty string */
+    readonly blockField?: string;
+}
+export declare const HOOK_BEHAVIOR: Readonly<Partial<Record<HookName, HookBehavior>>>;
+//# sourceMappingURL=hooks-types.d.ts.map

package/esm/lib/hooks-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks-types.d.ts","sourceRoot":"","sources":["../../src/lib/hooks-types.ts"],"names":[],"mappings":"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"}

package/esm/lib/hooks-types.js

@@ -0,0 +1,45 @@
+import * as z4 from 'zod/v4';
+import { HookName } from './hooks-schemas.js';
+// HookName / HookDefinition / HookRegistry are declared in hooks-schemas.ts
+// next to the schemas they describe; re-exported here so the public import
+// surface is unchanged and the module dependency stays one-directional
+// (hooks-types -> hooks-schemas, no cycle).
+export { HookName } from './hooks-schemas.js';
+const DEFAULT_ASYNC_TIMEOUT = 30000;
+export { DEFAULT_ASYNC_TIMEOUT };
+//#endregion
+//#region Helper Types
+/**
+ * Strict schema for an {@link AsyncOutput} signal: `async` must be literally
+ * `true`, `work`/`asyncTimeout` must match their declared types, and any
+ * foreign key fails the parse. A handler that accidentally returns
+ * `{ async: true, mutatedInput: {...} }` is therefore treated as a result
+ * (so the mutation is not silently discarded), not as fire-and-forget.
+ */
+const AsyncOutputSchema = z4.strictObject({
+    async: z4.literal(true),
+    work: z4.instanceof(Promise).optional(),
+    asyncTimeout: z4.number().optional(),
+});
+/**
+ * Checks if a value is an AsyncOutput signal (see {@link AsyncOutputSchema}).
+ */
+export function isAsyncOutput(value) {
+    return AsyncOutputSchema.safeParse(value).success;
+}
+export const HOOK_BEHAVIOR = Object.freeze({
+    [HookName.PreToolUse]: Object.freeze({
+        mutations: Object.freeze({
+            mutatedInput: 'toolInput',
+        }),
+        blockField: 'block',
+    }),
+    [HookName.UserPromptSubmit]: Object.freeze({
+        mutations: Object.freeze({
+            mutatedPrompt: 'prompt',
+        }),
+        blockField: 'reject',
+    }),
+});
+//#endregion
+//# sourceMappingURL=hooks-types.js.map

package/esm/lib/hooks-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks-types.js","sourceRoot":"","sources":["../../src/lib/hooks-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,QAAQ,CAAC;AAkB7B,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAK9C,4EAA4E;AAC5E,2EAA2E;AAC3E,uEAAuE;AACvE,4CAA4C;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AA6C9C,MAAM,qBAAqB,GAAG,KAAM,CAAC;AAErC,OAAO,EAAE,qBAAqB,EAAE,CAAC;AAwKjC,YAAY;AAEZ,sBAAsB;AAEtB;;;;;;GAMG;AACH,MAAM,iBAAiB,GAAG,EAAE,CAAC,YAAY,CAAC;IACxC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACvB,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,QAAQ,EAAE;IACvC,YAAY,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACrC,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,KAAc;IAC1C,OAAO,iBAAiB,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC;AACpD,CAAC;AAkBD,MAAM,CAAC,MAAM,aAAa,GAAsD,MAAM,CAAC,MAAM,CAAC;IAC5F,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC;QACnC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC;YACvB,YAAY,EAAE,WAAW;SAC1B,CAAC;QACF,UAAU,EAAE,OAAO;KACpB,CAAC;IACF,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC;QACzC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC;YACvB,aAAa,EAAE,QAAQ;SACxB,CAAC;QACF,UAAU,EAAE,QAAQ;KACrB,CAAC;CACH,CAAC,CAAC;AAEH,YAAY"}