@openrouter/agent 0.7.1 → 0.8.0

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

@@ -0,0 +1,141 @@
+import type { $ZodType, infer as zodInfer, input as zodInput } from 'zod/v4/core';
+import type { BuiltInHookDefinitions, EmitResult, HookEntry, HookHandler, HookRegistry, HooksManagerOptions } from './hooks-types.js';
+/**
+ * Type-level registry of every hook this manager knows: built-ins plus the
+ * instance's custom hooks. Each entry carries:
+ *
+ * - `payload`: the schema OUTPUT -- what handlers receive and `finalPayload`
+ *   holds (post-validation, transforms/defaults applied)
+ * - `payloadIn`: the schema INPUT -- what `emit()` accepts (differs from
+ *   `payload` for schemas with .transform()/.default()/.coerce). Built-in
+ *   schemas have no transforms, so input == output there.
+ * - `result`: the validated handler result
+ */
+type AllHooks<Custom extends HookRegistry> = {
+    [K in keyof BuiltInHookDefinitions]: {
+        payload: BuiltInHookDefinitions[K]['payload'];
+        payloadIn: BuiltInHookDefinitions[K]['payload'];
+        result: BuiltInHookDefinitions[K]['result'];
+    };
+} & {
+    [K in keyof Custom]: {
+        payload: zodInfer<Custom[K]['payload']>;
+        payloadIn: zodInput<Custom[K]['payload']>;
+        result: zodInfer<Custom[K]['result']>;
+    };
+};
+/**
+ * Module-private key used by `resolveHooks` to call the internal
+ * untyped-registration path without exposing it as a public method on the
+ * class. See {@link getInternalRegistrar} below.
+ */
+declare const INTERNAL_REGISTRAR_KEY: unique symbol;
+type InternalRegistrar = (hookName: string, entry: HookEntry<unknown, unknown>) => () => void;
+/**
+ * Typed, extensible hook system for agent lifecycle events.
+ *
+ * Supports both built-in hooks (PreToolUse, PostToolUse, etc.) and
+ * user-defined custom hooks with full type safety.
+ */
+export declare class HooksManager<Custom extends HookRegistry = Record<string, never>> {
+    private readonly entries;
+    private readonly pendingAsync;
+    private readonly customHooks;
+    private readonly inflightControllers;
+    private readonly throwOnHandlerError;
+    private sessionId;
+    constructor(customHooks?: Custom, options?: HooksManagerOptions);
+    /**
+     * Set the manager-level default session ID exposed as `context.sessionId`
+     * to handler invocations. Payloads deliberately do not carry session
+     * identity.
+     *
+     * This is a single mutable default on the manager instance: when one
+     * manager is shared by concurrent runs, callers MUST pass `sessionId` in
+     * the per-emit context instead (as the engine does), otherwise the last
+     * `setSessionId()` wins and concurrent emits observe the wrong id.
+     */
+    setSessionId(sessionId: string): void;
+    /**
+     * Register a handler for a hook. Returns an unsubscribe function.
+     */
+    on<K extends keyof AllHooks<Custom> & string>(hookName: K, entry: HookEntry<AllHooks<Custom>[K]['payload'], AllHooks<Custom>[K]['result']>): () => void;
+    /**
+     * Remove a specific handler function from a hook.
+     * Returns true if found and removed, false otherwise.
+     */
+    off<K extends keyof AllHooks<Custom> & string>(hookName: K, handler: HookHandler<AllHooks<Custom>[K]['payload'], AllHooks<Custom>[K]['result']>): boolean;
+    /**
+     * Remove all handlers for a specific hook, or all handlers if no name given.
+     */
+    removeAll<K extends keyof AllHooks<Custom> & string>(hookName?: K): void;
+    /**
+     * Validate the payload (and each handler's result) against the registered
+     * Zod schemas, invoke matching handlers, and return results.
+     *
+     * Payload validation failure is treated according to `throwOnHandlerError`:
+     * strict mode re-throws, default mode logs a warning and returns an empty
+     * result without invoking any handlers.
+     */
+    emit<K extends keyof AllHooks<Custom> & string>(hookName: K, payload: AllHooks<Custom>[K]['payloadIn'], emitContext?: {
+        toolName?: string;
+        /**
+         * Session identity for THIS emit's `context.sessionId`, overriding the
+         * manager-level default from `setSessionId()`. Pass it whenever the
+         * manager instance may be shared across concurrent runs.
+         */
+        sessionId?: string;
+    }): Promise<EmitResult<AllHooks<Custom>[K]['result'], AllHooks<Custom>[K]['payload']>>;
+    /**
+     * Await all in-flight async handler work. Used for graceful shutdown.
+     */
+    drain(): Promise<void>;
+    /**
+     * Abort every in-flight `emit()` by firing their context `signal`s. Handlers
+     * that kick off async work should observe `context.signal` to honor this.
+     *
+     * Does not remove pending async work from `pendingAsync` — callers that want
+     * to wait for handlers to wind down should still call `drain()` afterward.
+     */
+    abortInflight(reason?: unknown): void;
+    /**
+     * Check if any handlers are registered for a given hook.
+     */
+    hasHandlers(hookName: string): boolean;
+    /**
+     * Internal registration path used by `resolveHooks` to translate an
+     * InlineHookConfig object into this manager. User code should use `on()`.
+     */
+    [INTERNAL_REGISTRAR_KEY](hookName: string, entry: HookEntry<unknown, unknown>): () => void;
+    private _register;
+    private _definitionFor;
+}
+/**
+ * Internal: return the private registrar of a HooksManager instance. This
+ * lets `resolveHooks` register arbitrary hook names (including unknown ones
+ * from an inline config) without exposing a public bypass of the typed `on()`.
+ *
+ * NOT PART OF THE PUBLIC API.
+ */
+export declare function getInternalRegistrar(manager: HooksManager): InternalRegistrar;
+/**
+ * Detect a `z.void()` schema (zod v4 core). Result validation is skipped for
+ * void-result hooks so side-effect-only handlers can return arbitrary values
+ * without tripping validation -- for built-ins and custom hooks alike.
+ *
+ * Implementation note: `schema._zod.def.type` is zod v4's designated
+ * introspection surface for library authors (every `$ZodType` carries a
+ * `_zod: $ZodTypeInternals` with a stable `def.type` discriminator). A string
+ * check is deliberately preferred over `instanceof $ZodVoid`, which breaks
+ * across duplicated zod module instances (dual-package hazard) and mixed
+ * zod/v4 vs zod/v4-mini usage. Behavior is pinned by tests in
+ * hooks-contract-fixes.test.ts ("void schema detection") so a zod upgrade
+ * that restructures the internals fails loudly instead of silently
+ * re-enabling result validation on void hooks.
+ *
+ * Exported for the pinning tests only; NOT re-exported from the package
+ * index and NOT part of the public API.
+ */
+export declare function isVoidSchema(schema: $ZodType): boolean;
+export {};
+//# sourceMappingURL=hooks-manager.d.ts.map

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

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

package/esm/lib/hooks-manager.js

@@ -0,0 +1,282 @@
+import { safeParse } from 'zod/v4/core';
+import { executeHandlerChain } from './hooks-emit.js';
+import { BUILT_IN_HOOK_NAMES, BUILT_IN_HOOKS } from './hooks-schemas.js';
+//#endregion
+/**
+ * Module-private key used by `resolveHooks` to call the internal
+ * untyped-registration path without exposing it as a public method on the
+ * class. See {@link getInternalRegistrar} below.
+ */
+const INTERNAL_REGISTRAR_KEY = Symbol('HooksManager.internalRegistrar');
+/**
+ * Typed, extensible hook system for agent lifecycle events.
+ *
+ * Supports both built-in hooks (PreToolUse, PostToolUse, etc.) and
+ * user-defined custom hooks with full type safety.
+ */
+export class HooksManager {
+    constructor(customHooks, options) {
+        this.entries = new Map();
+        this.pendingAsync = new Set();
+        this.inflightControllers = new Set();
+        this.sessionId = '';
+        this.throwOnHandlerError = options?.throwOnHandlerError ?? false;
+        // Validate custom hook names: no empty names, no collisions with built-ins.
+        if (customHooks) {
+            for (const name of Object.keys(customHooks)) {
+                if (name === '') {
+                    throw new Error('Custom hook names must be non-empty strings.');
+                }
+                if (BUILT_IN_HOOK_NAMES.has(name)) {
+                    throw new Error(`Custom hook name "${name}" collides with a built-in hook. Choose a different name.`);
+                }
+            }
+            this.customHooks = {
+                ...customHooks,
+            };
+        }
+        else {
+            this.customHooks = {};
+        }
+    }
+    /**
+     * Set the manager-level default session ID exposed as `context.sessionId`
+     * to handler invocations. Payloads deliberately do not carry session
+     * identity.
+     *
+     * This is a single mutable default on the manager instance: when one
+     * manager is shared by concurrent runs, callers MUST pass `sessionId` in
+     * the per-emit context instead (as the engine does), otherwise the last
+     * `setSessionId()` wins and concurrent emits observe the wrong id.
+     */
+    setSessionId(sessionId) {
+        this.sessionId = sessionId;
+    }
+    /**
+     * Register a handler for a hook. Returns an unsubscribe function.
+     */
+    on(hookName, entry) {
+        return this._register(hookName, entry);
+    }
+    /**
+     * Remove a specific handler function from a hook.
+     * Returns true if found and removed, false otherwise.
+     */
+    off(hookName, handler) {
+        const list = this.entries.get(hookName);
+        if (!list) {
+            return false;
+        }
+        const idx = list.findIndex((e) => e.handler === handler);
+        if (idx === -1) {
+            return false;
+        }
+        list.splice(idx, 1);
+        if (list.length === 0) {
+            this.entries.delete(hookName);
+        }
+        return true;
+    }
+    /**
+     * Remove all handlers for a specific hook, or all handlers if no name given.
+     */
+    removeAll(hookName) {
+        if (hookName) {
+            this.entries.delete(hookName);
+        }
+        else {
+            this.entries.clear();
+        }
+    }
+    /**
+     * Validate the payload (and each handler's result) against the registered
+     * Zod schemas, invoke matching handlers, and return results.
+     *
+     * Payload validation failure is treated according to `throwOnHandlerError`:
+     * strict mode re-throws, default mode logs a warning and returns an empty
+     * result without invoking any handlers.
+     */
+    async emit(hookName, payload, emitContext) {
+        // Snapshot the entries list so mutations (on()/off()/unsubscribe) triggered
+        // by a handler during the chain can't shift indices mid-iteration and
+        // silently skip the next handler, or splice in new handlers that were
+        // registered after this emit began.
+        const list = (this.entries.get(hookName) ?? []).slice();
+        // Validate the payload and, on success, feed the PARSED value into the
+        // chain. For schemas with .transform() / .default() / .coerce (or that
+        // strip unknown keys) the parsed output differs from the raw input: emit
+        // accepts the schema INPUT type (`payloadIn`) while handlers and
+        // finalPayload carry the schema OUTPUT (`payload`) -- so handlers must
+        // receive `parsed.data`, not the raw value, or the runtime shape silently
+        // diverges from the static types.
+        let chainPayload = payload;
+        const definition = this._definitionFor(hookName);
+        if (definition) {
+            const parsed = safeParse(definition.payload, payload);
+            if (!parsed.success) {
+                const err = new Error(`[HooksManager] Invalid payload for hook "${hookName}": ${parsed.error.message}`);
+                if (this.throwOnHandlerError) {
+                    throw err;
+                }
+                console.warn(err.message);
+                return {
+                    results: [],
+                    pending: [],
+                    finalPayload: chainPayload,
+                    blocked: false,
+                    mutated: false,
+                };
+            }
+            chainPayload = parsed.data;
+        }
+        const controller = new AbortController();
+        this.inflightControllers.add(controller);
+        const context = {
+            signal: controller.signal,
+            hookName,
+            sessionId: emitContext?.sessionId ?? this.sessionId,
+        };
+        let hasDetachedWork = false;
+        try {
+            // Result validation is skipped for hooks whose result schema is void --
+            // decided by SCHEMA SHAPE, not by a hard-coded name list, so custom
+            // hooks registered with `result: z.void()` behave exactly like the
+            // built-in void hooks (handlers may return arbitrary values that are
+            // collected as opaque results without complaint).
+            const resultSchema = definition && !isVoidSchema(definition.result) ? definition.result : undefined;
+            const result = await executeHandlerChain(list, chainPayload, context, {
+                hookName,
+                throwOnHandlerError: this.throwOnHandlerError,
+                toolName: emitContext?.toolName,
+                resultSchema,
+                // When a handler's fire-and-forget work exceeds its asyncTimeout,
+                // abort this emit's signal so handlers observing context.signal can
+                // cancel the stale work cooperatively.
+                onAsyncTimeout: () => {
+                    controller.abort(new Error('Hook async work timed out'));
+                },
+            });
+            // Track pending async work for drain(); each promise self-removes once
+            // it settles so the set can't grow unbounded across many emits.
+            hasDetachedWork = result.pending.length > 0;
+            if (hasDetachedWork) {
+                let remaining = result.pending.length;
+                for (const p of result.pending) {
+                    this.pendingAsync.add(p);
+                    p.finally(() => {
+                        this.pendingAsync.delete(p);
+                        // The emit's controller must stay registered until the detached
+                        // work settles so abortInflight() can reach fire-and-forget
+                        // handlers that outlive the emit call itself.
+                        remaining--;
+                        if (remaining === 0) {
+                            this.inflightControllers.delete(controller);
+                        }
+                    });
+                }
+            }
+            return result;
+        }
+        finally {
+            // With detached work in flight the controller lives until that work
+            // settles (see above); otherwise it can be dropped now.
+            if (!hasDetachedWork) {
+                this.inflightControllers.delete(controller);
+            }
+        }
+    }
+    /**
+     * Await all in-flight async handler work. Used for graceful shutdown.
+     */
+    async drain() {
+        while (this.pendingAsync.size > 0) {
+            const snapshot = Array.from(this.pendingAsync);
+            await Promise.allSettled(snapshot);
+        }
+    }
+    /**
+     * Abort every in-flight `emit()` by firing their context `signal`s. Handlers
+     * that kick off async work should observe `context.signal` to honor this.
+     *
+     * Does not remove pending async work from `pendingAsync` — callers that want
+     * to wait for handlers to wind down should still call `drain()` afterward.
+     */
+    abortInflight(reason) {
+        for (const controller of this.inflightControllers) {
+            controller.abort(reason);
+        }
+    }
+    /**
+     * Check if any handlers are registered for a given hook.
+     */
+    hasHandlers(hookName) {
+        const list = this.entries.get(hookName);
+        return list !== undefined && list.length > 0;
+    }
+    /**
+     * Internal registration path used by `resolveHooks` to translate an
+     * InlineHookConfig object into this manager. User code should use `on()`.
+     */
+    [INTERNAL_REGISTRAR_KEY](hookName, entry) {
+        return this._register(hookName, entry);
+    }
+    _register(hookName, entry) {
+        const list = this.entries.get(hookName) ?? [];
+        list.push(entry);
+        this.entries.set(hookName, list);
+        return () => {
+            const current = this.entries.get(hookName);
+            if (!current) {
+                return;
+            }
+            const idx = current.indexOf(entry);
+            if (idx !== -1) {
+                current.splice(idx, 1);
+            }
+        };
+    }
+    _definitionFor(hookName) {
+        const builtIn = BUILT_IN_HOOKS[hookName];
+        if (builtIn) {
+            return builtIn;
+        }
+        const custom = this.customHooks[hookName];
+        if (custom) {
+            return custom;
+        }
+        return undefined;
+    }
+}
+/**
+ * Internal: return the private registrar of a HooksManager instance. This
+ * lets `resolveHooks` register arbitrary hook names (including unknown ones
+ * from an inline config) without exposing a public bypass of the typed `on()`.
+ *
+ * NOT PART OF THE PUBLIC API.
+ */
+export function getInternalRegistrar(manager) {
+    return manager[INTERNAL_REGISTRAR_KEY].bind(manager);
+}
+/**
+ * Detect a `z.void()` schema (zod v4 core). Result validation is skipped for
+ * void-result hooks so side-effect-only handlers can return arbitrary values
+ * without tripping validation -- for built-ins and custom hooks alike.
+ *
+ * Implementation note: `schema._zod.def.type` is zod v4's designated
+ * introspection surface for library authors (every `$ZodType` carries a
+ * `_zod: $ZodTypeInternals` with a stable `def.type` discriminator). A string
+ * check is deliberately preferred over `instanceof $ZodVoid`, which breaks
+ * across duplicated zod module instances (dual-package hazard) and mixed
+ * zod/v4 vs zod/v4-mini usage. Behavior is pinned by tests in
+ * hooks-contract-fixes.test.ts ("void schema detection") so a zod upgrade
+ * that restructures the internals fails loudly instead of silently
+ * re-enabling result validation on void hooks.
+ *
+ * Exported for the pinning tests only; NOT re-exported from the package
+ * index and NOT part of the public API.
+ */
+export function isVoidSchema(schema) {
+    const def = schema._zod?.def;
+    return def?.type === 'void';
+}
+//# sourceMappingURL=hooks-manager.js.map

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

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

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

@@ -0,0 +1,12 @@
+import type { ToolMatcher } from './hooks-types.js';
+/**
+ * Evaluate a ToolMatcher against a tool name.
+ *
+ * - `undefined` -> wildcard, matches all tools
+ * - `string` -> exact match
+ * - `RegExp` -> `.test(toolName)`
+ * - `function` -> arbitrary predicate (truthy/falsy returns are coerced to
+ *   boolean so the declared `boolean` return type holds at runtime)
+ */
+export declare function matchesTool(matcher: ToolMatcher | undefined, toolName: string): boolean;
+//# sourceMappingURL=hooks-matchers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hooks-matchers.d.ts","sourceRoot":"","sources":["../../src/lib/hooks-matchers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAevF"}

package/esm/lib/hooks-matchers.js

@@ -0,0 +1,26 @@
+/**
+ * Evaluate a ToolMatcher against a tool name.
+ *
+ * - `undefined` -> wildcard, matches all tools
+ * - `string` -> exact match
+ * - `RegExp` -> `.test(toolName)`
+ * - `function` -> arbitrary predicate (truthy/falsy returns are coerced to
+ *   boolean so the declared `boolean` return type holds at runtime)
+ */
+export function matchesTool(matcher, toolName) {
+    if (matcher === undefined) {
+        return true;
+    }
+    if (typeof matcher === 'string') {
+        return matcher === toolName;
+    }
+    if (matcher instanceof RegExp) {
+        // RegExps with the /g or /y flag advance `lastIndex` on every `.test()`,
+        // so successive emits with the same tool name alternate true/false.
+        // Reset so the matcher behaves statelessly regardless of flag.
+        matcher.lastIndex = 0;
+        return matcher.test(toolName);
+    }
+    return Boolean(matcher(toolName));
+}
+//# sourceMappingURL=hooks-matchers.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hooks-matchers.js","sourceRoot":"","sources":["../../src/lib/hooks-matchers.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,OAAgC,EAAE,QAAgB;IAC5E,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO,OAAO,KAAK,QAAQ,CAAC;IAC9B,CAAC;IACD,IAAI,OAAO,YAAY,MAAM,EAAE,CAAC;QAC9B,yEAAyE;QACzE,oEAAoE;QACpE,+DAA+D;QAC/D,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC;QACtB,OAAO,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC;AACpC,CAAC"}

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

@@ -0,0 +1,17 @@
+import { HooksManager } from './hooks-manager.js';
+import type { InlineHookConfig } from './hooks-types.js';
+/**
+ * Normalize a hooks option into a HooksManager instance.
+ *
+ * - `undefined` -> `undefined` (no hooks)
+ * - `HooksManager` -> passthrough
+ * - Plain object (InlineHookConfig) -> construct HooksManager, register all entries
+ *
+ * The inline config surface is typed to only accept built-in hook names, but
+ * a generic config coerced through `as` can smuggle typos past the compiler
+ * (e.g. `PretoolUse` vs `PreToolUse`) which would silently never fire. We log
+ * a warning for any non-built-in key and skip registration for it. Custom
+ * hooks must be registered through a `HooksManager` instance via `on()`.
+ */
+export declare function resolveHooks(hooks: InlineHookConfig | HooksManager | undefined): HooksManager | undefined;
+//# sourceMappingURL=hooks-resolve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hooks-resolve.d.ts","sourceRoot":"","sources":["../../src/lib/hooks-resolve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAwB,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAExE,OAAO,KAAK,EAAa,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpE;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,gBAAgB,GAAG,YAAY,GAAG,SAAS,GACjD,YAAY,GAAG,SAAS,CA6B1B"}

package/esm/lib/hooks-resolve.js

@@ -0,0 +1,42 @@
+import { getInternalRegistrar, HooksManager } from './hooks-manager.js';
+import { BUILT_IN_HOOK_NAMES } from './hooks-schemas.js';
+/**
+ * Normalize a hooks option into a HooksManager instance.
+ *
+ * - `undefined` -> `undefined` (no hooks)
+ * - `HooksManager` -> passthrough
+ * - Plain object (InlineHookConfig) -> construct HooksManager, register all entries
+ *
+ * The inline config surface is typed to only accept built-in hook names, but
+ * a generic config coerced through `as` can smuggle typos past the compiler
+ * (e.g. `PretoolUse` vs `PreToolUse`) which would silently never fire. We log
+ * a warning for any non-built-in key and skip registration for it. Custom
+ * hooks must be registered through a `HooksManager` instance via `on()`.
+ */
+export function resolveHooks(hooks) {
+    if (!hooks) {
+        return undefined;
+    }
+    if (hooks instanceof HooksManager) {
+        return hooks;
+    }
+    // Inline config -> HooksManager. We register through the internal registrar
+    // so we don't have to constrain `resolveHooks` to the typed `on()` surface
+    // and so user code can't reach this path.
+    const manager = new HooksManager();
+    const register = getInternalRegistrar(manager);
+    for (const [hookName, entries] of Object.entries(hooks)) {
+        if (!entries || !Array.isArray(entries)) {
+            continue;
+        }
+        if (!BUILT_IN_HOOK_NAMES.has(hookName)) {
+            console.warn(`[resolveHooks] Ignoring inline hook entry for unknown hook name "${hookName}". Inline config only supports built-in hooks; register custom hooks via a HooksManager instance.`);
+            continue;
+        }
+        for (const entry of entries) {
+            register(hookName, entry);
+        }
+    }
+    return manager;
+}
+//# sourceMappingURL=hooks-resolve.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hooks-resolve.js","sourceRoot":"","sources":["../../src/lib/hooks-resolve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACxE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAGzD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAkD;IAElD,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,KAAK,YAAY,YAAY,EAAE,CAAC;QAClC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,4EAA4E;IAC5E,2EAA2E;IAC3E,0CAA0C;IAC1C,MAAM,OAAO,GAAG,IAAI,YAAY,EAAE,CAAC;IACnC,MAAM,QAAQ,GAAG,oBAAoB,CAAC,OAAO,CAAC,CAAC;IAC/C,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxD,IAAI,CAAC,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;YACxC,SAAS;QACX,CAAC;QACD,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YACvC,OAAO,CAAC,IAAI,CACV,oEAAoE,QAAQ,mGAAmG,CAChL,CAAC;YACF,SAAS;QACX,CAAC;QACD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;YAC5B,QAAQ,CAAC,QAAQ,EAAE,KAAoC,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}