@librechat/agents 3.1.66-dev.0 → 3.1.67

package/dist/cjs/tools/skillCatalog.cjs

@@ -1,84 +0,0 @@
-'use strict';
-
-const HEADER = '## Available Skills';
-const DEFAULT_CONTEXT_WINDOW_TOKENS = 200_000;
-const DEFAULT_BUDGET_PERCENT = 0.01;
-const DEFAULT_MAX_ENTRY_CHARS = 250;
-const DEFAULT_MIN_DESC_LENGTH = 20;
-const DEFAULT_CHARS_PER_TOKEN = 4;
-/**
- * Formats a skill catalog for injection into agent context.
- * Uses a truncation ladder: full descriptions, proportional truncation, names-only.
- * Returns empty string for empty input.
- */
-function formatSkillCatalog(skills, opts) {
-    if (skills.length === 0)
-        return '';
-    const contextWindowTokens = opts?.contextWindowTokens ?? DEFAULT_CONTEXT_WINDOW_TOKENS;
-    const budgetPercent = opts?.budgetPercent ?? DEFAULT_BUDGET_PERCENT;
-    const maxEntryChars = Math.max(1, opts?.maxEntryChars ?? DEFAULT_MAX_ENTRY_CHARS);
-    const minDescLength = opts?.minDescLength ?? DEFAULT_MIN_DESC_LENGTH;
-    const charsPerToken = opts?.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
-    const budgetChars = Math.floor(contextWindowTokens * budgetPercent * charsPerToken);
-    const capped = skills.map((s) => ({
-        name: s.name,
-        description: s.description.length > maxEntryChars
-            ? s.description.slice(0, maxEntryChars - 1) + '\u2026'
-            : s.description,
-    }));
-    const fullOutput = formatEntries(capped);
-    if (fullOutput.length <= budgetChars)
-        return fullOutput;
-    const headerLen = HEADER.length + 2;
-    const newlineChars = capped.length > 1 ? capped.length - 1 : 0;
-    const availableChars = budgetChars - headerLen - newlineChars;
-    const perEntryOverhead = 4;
-    const nameCharsTotal = capped.reduce((sum, s) => sum + s.name.length + perEntryOverhead, 0);
-    const availableForDescs = availableChars - nameCharsTotal;
-    if (availableForDescs <= 0) {
-        return fitNamesOnly(capped, budgetChars);
-    }
-    const maxDescPerEntry = Math.floor(availableForDescs / capped.length);
-    if (maxDescPerEntry < minDescLength) {
-        return fitNamesOnly(capped, budgetChars);
-    }
-    const truncated = capped.map((s) => ({
-        name: s.name,
-        description: s.description.length > maxDescPerEntry
-            ? s.description.slice(0, maxDescPerEntry - 1) + '\u2026'
-            : s.description,
-    }));
-    const result = formatEntries(truncated);
-    if (result.length <= budgetChars)
-        return result;
-    return fitNamesOnly(capped, budgetChars);
-}
-function formatEntries(entries) {
-    const lines = entries.map((e) => e.description ? `- ${e.name}: ${e.description}` : `- ${e.name}`);
-    return `${HEADER}\n\n${lines.join('\n')}`;
-}
-/** Names-only fallback that drops trailing entries if the list still exceeds budget. */
-function fitNamesOnly(entries, budgetChars) {
-    // Format: "HEADER\n\n- name1\n- name2\n..."
-    // Running sum avoids O(n²) repeated string construction.
-    const prefix = HEADER.length + 2; // "HEADER\n\n"
-    const entryOverhead = 2; // "- "
-    let total = prefix;
-    let fitCount = 0;
-    for (let i = 0; i < entries.length; i++) {
-        const added = (i > 0 ? 1 : 0) + entryOverhead + entries[i].name.length;
-        if (total + added > budgetChars)
-            break;
-        total += added;
-        fitCount = i + 1;
-    }
-    if (fitCount === 0)
-        return '';
-    const namesOnly = entries
-        .slice(0, fitCount)
-        .map((s) => ({ name: s.name, description: '' }));
-    return formatEntries(namesOnly);
-}
-
-exports.formatSkillCatalog = formatSkillCatalog;
-//# sourceMappingURL=skillCatalog.cjs.map

package/dist/cjs/tools/skillCatalog.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"skillCatalog.cjs","sources":["../../../src/tools/skillCatalog.ts"],"sourcesContent":["// src/tools/skillCatalog.ts\nimport type { SkillCatalogEntry } from '@/types';\n\nconst HEADER = '## Available Skills';\nconst DEFAULT_CONTEXT_WINDOW_TOKENS = 200_000;\nconst DEFAULT_BUDGET_PERCENT = 0.01;\nconst DEFAULT_MAX_ENTRY_CHARS = 250;\nconst DEFAULT_MIN_DESC_LENGTH = 20;\nconst DEFAULT_CHARS_PER_TOKEN = 4;\n\nexport type SkillCatalogOptions = {\n  /** Total context window in tokens. Default: 200_000 */\n  contextWindowTokens?: number;\n  /** Fraction of context budget for catalog. Default: 0.01 (1%) */\n  budgetPercent?: number;\n  /** Max chars per entry description. Default: 250 */\n  maxEntryChars?: number;\n  /** Descriptions below this length trigger names-only fallback. Default: 20 */\n  minDescLength?: number;\n  /** Approximate chars per token for budget calculation. Default: 4 */\n  charsPerToken?: number;\n};\n\n/**\n * Formats a skill catalog for injection into agent context.\n * Uses a truncation ladder: full descriptions, proportional truncation, names-only.\n * Returns empty string for empty input.\n */\nexport function formatSkillCatalog(\n  skills: SkillCatalogEntry[],\n  opts?: SkillCatalogOptions\n): string {\n  if (skills.length === 0) return '';\n\n  const contextWindowTokens =\n    opts?.contextWindowTokens ?? DEFAULT_CONTEXT_WINDOW_TOKENS;\n  const budgetPercent = opts?.budgetPercent ?? DEFAULT_BUDGET_PERCENT;\n  const maxEntryChars = Math.max(\n    1,\n    opts?.maxEntryChars ?? DEFAULT_MAX_ENTRY_CHARS\n  );\n  const minDescLength = opts?.minDescLength ?? DEFAULT_MIN_DESC_LENGTH;\n  const charsPerToken = opts?.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;\n\n  const budgetChars = Math.floor(\n    contextWindowTokens * budgetPercent * charsPerToken\n  );\n\n  const capped = skills.map((s) => ({\n    name: s.name,\n    description:\n      s.description.length > maxEntryChars\n        ? s.description.slice(0, maxEntryChars - 1) + '\\u2026'\n        : s.description,\n  }));\n\n  const fullOutput = formatEntries(capped);\n  if (fullOutput.length <= budgetChars) return fullOutput;\n\n  const headerLen = HEADER.length + 2;\n  const newlineChars = capped.length > 1 ? capped.length - 1 : 0;\n  const availableChars = budgetChars - headerLen - newlineChars;\n  const perEntryOverhead = 4;\n  const nameCharsTotal = capped.reduce(\n    (sum, s) => sum + s.name.length + perEntryOverhead,\n    0\n  );\n  const availableForDescs = availableChars - nameCharsTotal;\n\n  if (availableForDescs <= 0) {\n    return fitNamesOnly(capped, budgetChars);\n  }\n\n  const maxDescPerEntry = Math.floor(availableForDescs / capped.length);\n\n  if (maxDescPerEntry < minDescLength) {\n    return fitNamesOnly(capped, budgetChars);\n  }\n\n  const truncated = capped.map((s) => ({\n    name: s.name,\n    description:\n      s.description.length > maxDescPerEntry\n        ? s.description.slice(0, maxDescPerEntry - 1) + '\\u2026'\n        : s.description,\n  }));\n\n  const result = formatEntries(truncated);\n  if (result.length <= budgetChars) return result;\n  return fitNamesOnly(capped, budgetChars);\n}\n\nfunction formatEntries(\n  entries: { name: string; description: string }[]\n): string {\n  const lines = entries.map((e) =>\n    e.description ? `- ${e.name}: ${e.description}` : `- ${e.name}`\n  );\n  return `${HEADER}\\n\\n${lines.join('\\n')}`;\n}\n\n/** Names-only fallback that drops trailing entries if the list still exceeds budget. */\nfunction fitNamesOnly(\n  entries: { name: string }[],\n  budgetChars: number\n): string {\n  // Format: \"HEADER\\n\\n- name1\\n- name2\\n...\"\n  // Running sum avoids O(n²) repeated string construction.\n  const prefix = HEADER.length + 2; // \"HEADER\\n\\n\"\n  const entryOverhead = 2; // \"- \"\n  let total = prefix;\n  let fitCount = 0;\n\n  for (let i = 0; i < entries.length; i++) {\n    const added = (i > 0 ? 1 : 0) + entryOverhead + entries[i].name.length;\n    if (total + added > budgetChars) break;\n    total += added;\n    fitCount = i + 1;\n  }\n\n  if (fitCount === 0) return '';\n  const namesOnly = entries\n    .slice(0, fitCount)\n    .map((s) => ({ name: s.name, description: '' }));\n  return formatEntries(namesOnly);\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/hooks/HookRegistry.mjs

@@ -1,160 +0,0 @@
-/**
- * Run-scoped storage for hook matchers with an additional layer for
- * session-scoped matchers that should be cleaned up between sessions.
- *
- * Hosts construct one registry per `Run` (mirroring how `HandlerRegistry` is
- * scoped) and register global matchers + per-session matchers against it.
- * Registration is strictly additive — nothing in this class mutates a
- * matcher's callbacks or flags after insertion.
- *
- * ## Why `Map<sessionId, MatcherBucket>` and not `Record`
- *
- * LibreChat runs thousands of parallel sessions in one Node process, and
- * hook registration happens inside hot paths (tool loading, agent spawning).
- * A `Record<sessionId, ...>` has to be spread on every insertion, which is
- * O(n) per call and O(n²) total for a batch of parallel registrations. A
- * Map mutates in place, keeping insertions O(1). This mirrors the reasoning
- * Claude Code documents at `utils/hooks/sessionHooks.ts:62`.
- */
-class HookRegistry {
-    global = {};
-    sessions = new Map();
-    /**
-     * Register a matcher for the lifetime of this registry (= one Run).
-     * Returns an unregister function that removes the matcher by reference.
-     */
-    register(event, matcher) {
-        const list = ensureList(this.global, event);
-        list.push(widen(matcher));
-        return () => {
-            removeFromList(list, matcher);
-        };
-    }
-    /**
-     * Register a matcher for a specific session. Cleared automatically when
-     * `clearSession(sessionId)` is called, or can be removed directly via the
-     * returned unregister function.
-     */
-    registerSession(sessionId, event, matcher) {
-        const bucket = this.ensureSessionBucket(sessionId);
-        const list = ensureList(bucket, event);
-        list.push(widen(matcher));
-        return () => {
-            removeFromList(list, matcher);
-        };
-    }
-    /**
-     * Returns all matchers registered for `event`, concatenating global first
-     * and then session-specific (when `sessionId` is supplied). The caller
-     * receives a fresh array, so iterating it is safe even if a matcher is
-     * removed mid-iteration (e.g. via `once: true`).
-     */
-    getMatchers(event, sessionId) {
-        const globalList = readList(this.global, event);
-        if (sessionId === undefined) {
-            return snapshot(globalList);
-        }
-        const bucket = this.sessions.get(sessionId);
-        if (bucket === undefined) {
-            return snapshot(globalList);
-        }
-        const sessionList = readList(bucket, event);
-        if (globalList.length === 0) {
-            return snapshot(sessionList);
-        }
-        if (sessionList.length === 0) {
-            return snapshot(globalList);
-        }
-        return snapshot([...globalList, ...sessionList]);
-    }
-    /**
-     * Removes `matcher` by reference from global storage first, falling back
-     * to the session bucket when `sessionId` is supplied. Used by
-     * `executeHooks` to drop `once: true` matchers after they fire.
-     */
-    removeMatcher(event, matcher, sessionId) {
-        if (removeFromList(readList(this.global, event), matcher)) {
-            return true;
-        }
-        if (sessionId === undefined) {
-            return false;
-        }
-        const bucket = this.sessions.get(sessionId);
-        if (bucket === undefined) {
-            return false;
-        }
-        return removeFromList(readList(bucket, event), matcher);
-    }
-    /**
-     * Drops every session-scoped matcher for `sessionId`. Call this in the
-     * `finally` block around a Run so a `once: true` hook that never fired
-     * cannot leak into the next session on the same registry.
-     */
-    clearSession(sessionId) {
-        this.sessions.delete(sessionId);
-    }
-    /** True if at least one matcher exists for `event` (global + session). */
-    hasHookFor(event, sessionId) {
-        if (readList(this.global, event).length > 0) {
-            return true;
-        }
-        if (sessionId === undefined) {
-            return false;
-        }
-        const bucket = this.sessions.get(sessionId);
-        if (bucket === undefined) {
-            return false;
-        }
-        return readList(bucket, event).length > 0;
-    }
-    ensureSessionBucket(sessionId) {
-        const existing = this.sessions.get(sessionId);
-        if (existing !== undefined) {
-            return existing;
-        }
-        const fresh = {};
-        this.sessions.set(sessionId, fresh);
-        return fresh;
-    }
-}
-function ensureList(bucket, event) {
-    const existing = bucket[event];
-    if (existing !== undefined) {
-        return existing;
-    }
-    const fresh = [];
-    bucket[event] = fresh;
-    return fresh;
-}
-function readList(bucket, event) {
-    return bucket[event] ?? [];
-}
-function removeFromList(list, matcher) {
-    const idx = list.indexOf(widen(matcher));
-    if (idx < 0) {
-        return false;
-    }
-    list.splice(idx, 1);
-    return true;
-}
-/**
- * Widen a per-event matcher to the storage's uniform slot type. Unsound at
- * the type level (function parameters are contravariant) but safe by
- * construction: `HookRegistry.register<E>` only ever puts matchers into the
- * bucket slot for their own event, and reads go through `snapshot<E>`
- * which is only called with the same `E`.
- */
-function widen(matcher) {
-    return matcher;
-}
-/**
- * Narrow a storage list back to a per-event matcher list on the way out.
- * Sound counterpart to `widen`: the list only contains matchers that were
- * registered against `E`, because the public API enforces it on insert.
- */
-function snapshot(list) {
-    return list.slice();
-}
-
-export { HookRegistry };
-//# sourceMappingURL=HookRegistry.mjs.map

package/dist/esm/hooks/HookRegistry.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"HookRegistry.mjs","sources":["../../../src/hooks/HookRegistry.ts"],"sourcesContent":["// src/hooks/HookRegistry.ts\nimport type { HookEvent, HookMatcher } from './types';\n\n/**\n * Internal matcher storage type.\n *\n * Matchers registered via the public `register<E>` API are strictly typed\n * to a single `E`, but the storage needs one uniform slot type per event.\n * We store them as `HookMatcher<HookEvent>` and cast once at the variance\n * boundary — see `ensureList` and `snapshot` below. The invariant (every\n * matcher in `bucket[event]` was registered with that exact event) is\n * enforced by the public API; breaking it requires bypassing the types.\n */\ntype MatcherBucket = Partial<Record<HookEvent, HookMatcher<HookEvent>[]>>;\n\n/**\n * Run-scoped storage for hook matchers with an additional layer for\n * session-scoped matchers that should be cleaned up between sessions.\n *\n * Hosts construct one registry per `Run` (mirroring how `HandlerRegistry` is\n * scoped) and register global matchers + per-session matchers against it.\n * Registration is strictly additive — nothing in this class mutates a\n * matcher's callbacks or flags after insertion.\n *\n * ## Why `Map<sessionId, MatcherBucket>` and not `Record`\n *\n * LibreChat runs thousands of parallel sessions in one Node process, and\n * hook registration happens inside hot paths (tool loading, agent spawning).\n * A `Record<sessionId, ...>` has to be spread on every insertion, which is\n * O(n) per call and O(n²) total for a batch of parallel registrations. A\n * Map mutates in place, keeping insertions O(1). This mirrors the reasoning\n * Claude Code documents at `utils/hooks/sessionHooks.ts:62`.\n */\nexport class HookRegistry {\n  private readonly global: MatcherBucket = {};\n  private readonly sessions: Map<string, MatcherBucket> = new Map();\n\n  /**\n   * Register a matcher for the lifetime of this registry (= one Run).\n   * Returns an unregister function that removes the matcher by reference.\n   */\n  register<E extends HookEvent>(event: E, matcher: HookMatcher<E>): () => void {\n    const list = ensureList(this.global, event);\n    list.push(widen(matcher));\n    return () => {\n      removeFromList(list, matcher);\n    };\n  }\n\n  /**\n   * Register a matcher for a specific session. Cleared automatically when\n   * `clearSession(sessionId)` is called, or can be removed directly via the\n   * returned unregister function.\n   */\n  registerSession<E extends HookEvent>(\n    sessionId: string,\n    event: E,\n    matcher: HookMatcher<E>\n  ): () => void {\n    const bucket = this.ensureSessionBucket(sessionId);\n    const list = ensureList(bucket, event);\n    list.push(widen(matcher));\n    return () => {\n      removeFromList(list, matcher);\n    };\n  }\n\n  /**\n   * Returns all matchers registered for `event`, concatenating global first\n   * and then session-specific (when `sessionId` is supplied). The caller\n   * receives a fresh array, so iterating it is safe even if a matcher is\n   * removed mid-iteration (e.g. via `once: true`).\n   */\n  getMatchers<E extends HookEvent>(\n    event: E,\n    sessionId?: string\n  ): HookMatcher<E>[] {\n    const globalList = readList(this.global, event);\n    if (sessionId === undefined) {\n      return snapshot<E>(globalList);\n    }\n    const bucket = this.sessions.get(sessionId);\n    if (bucket === undefined) {\n      return snapshot<E>(globalList);\n    }\n    const sessionList = readList(bucket, event);\n    if (globalList.length === 0) {\n      return snapshot<E>(sessionList);\n    }\n    if (sessionList.length === 0) {\n      return snapshot<E>(globalList);\n    }\n    return snapshot<E>([...globalList, ...sessionList]);\n  }\n\n  /**\n   * Removes `matcher` by reference from global storage first, falling back\n   * to the session bucket when `sessionId` is supplied. Used by\n   * `executeHooks` to drop `once: true` matchers after they fire.\n   */\n  removeMatcher<E extends HookEvent>(\n    event: E,\n    matcher: HookMatcher<E>,\n    sessionId?: string\n  ): boolean {\n    if (removeFromList(readList(this.global, event), matcher)) {\n      return true;\n    }\n    if (sessionId === undefined) {\n      return false;\n    }\n    const bucket = this.sessions.get(sessionId);\n    if (bucket === undefined) {\n      return false;\n    }\n    return removeFromList(readList(bucket, event), matcher);\n  }\n\n  /**\n   * Drops every session-scoped matcher for `sessionId`. Call this in the\n   * `finally` block around a Run so a `once: true` hook that never fired\n   * cannot leak into the next session on the same registry.\n   */\n  clearSession(sessionId: string): void {\n    this.sessions.delete(sessionId);\n  }\n\n  /** True if at least one matcher exists for `event` (global + session). */\n  hasHookFor(event: HookEvent, sessionId?: string): boolean {\n    if (readList(this.global, event).length > 0) {\n      return true;\n    }\n    if (sessionId === undefined) {\n      return false;\n    }\n    const bucket = this.sessions.get(sessionId);\n    if (bucket === undefined) {\n      return false;\n    }\n    return readList(bucket, event).length > 0;\n  }\n\n  private ensureSessionBucket(sessionId: string): MatcherBucket {\n    const existing = this.sessions.get(sessionId);\n    if (existing !== undefined) {\n      return existing;\n    }\n    const fresh: MatcherBucket = {};\n    this.sessions.set(sessionId, fresh);\n    return fresh;\n  }\n}\n\nfunction ensureList(\n  bucket: MatcherBucket,\n  event: HookEvent\n): HookMatcher<HookEvent>[] {\n  const existing = bucket[event];\n  if (existing !== undefined) {\n    return existing;\n  }\n  const fresh: HookMatcher<HookEvent>[] = [];\n  bucket[event] = fresh;\n  return fresh;\n}\n\nfunction readList(\n  bucket: MatcherBucket,\n  event: HookEvent\n): HookMatcher<HookEvent>[] {\n  return bucket[event] ?? [];\n}\n\nfunction removeFromList<E extends HookEvent>(\n  list: HookMatcher<HookEvent>[],\n  matcher: HookMatcher<E>\n): boolean {\n  const idx = list.indexOf(widen(matcher));\n  if (idx < 0) {\n    return false;\n  }\n  list.splice(idx, 1);\n  return true;\n}\n\n/**\n * Widen a per-event matcher to the storage's uniform slot type. Unsound at\n * the type level (function parameters are contravariant) but safe by\n * construction: `HookRegistry.register<E>` only ever puts matchers into the\n * bucket slot for their own event, and reads go through `snapshot<E>`\n * which is only called with the same `E`.\n */\nfunction widen<E extends HookEvent>(\n  matcher: HookMatcher<E>\n): HookMatcher<HookEvent> {\n  return matcher as unknown as HookMatcher<HookEvent>;\n}\n\n/**\n * Narrow a storage list back to a per-event matcher list on the way out.\n * Sound counterpart to `widen`: the list only contains matchers that were\n * registered against `E`, because the public API enforces it on insert.\n */\nfunction snapshot<E extends HookEvent>(\n  list: readonly HookMatcher<HookEvent>[]\n): HookMatcher<E>[] {\n  return list.slice() as unknown as HookMatcher<E>[];\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/hooks/executeHooks.mjs

@@ -1,273 +0,0 @@
-import { matchesQuery } from './matchers.mjs';
-
-/** Default per-hook timeout when a matcher doesn't set its own. */
-const DEFAULT_HOOK_TIMEOUT_MS = 30_000;
-function freshResult() {
-    return {
-        additionalContexts: [],
-        errors: [],
-    };
-}
-function combineSignals(parent, timeoutMs) {
-    const timeoutSignal = AbortSignal.timeout(timeoutMs);
-    if (parent === undefined) {
-        return timeoutSignal;
-    }
-    return AbortSignal.any([parent, timeoutSignal]);
-}
-function isTimeout(err) {
-    if (err instanceof Error) {
-        return err.name === 'TimeoutError' || err.name === 'AbortError';
-    }
-    return false;
-}
-function describeError(err) {
-    if (err instanceof Error) {
-        return err.message !== '' ? err.message : err.name;
-    }
-    return String(err);
-}
-function makeAbortPromise(signal) {
-    let onAbort;
-    const promise = new Promise((_resolve, reject) => {
-        if (signal.aborted) {
-            reject(signal.reason instanceof Error ? signal.reason : new Error('aborted'));
-            return;
-        }
-        onAbort = () => {
-            reject(signal.reason instanceof Error ? signal.reason : new Error('aborted'));
-        };
-        signal.addEventListener('abort', onAbort, { once: true });
-    });
-    const cleanup = () => {
-        if (onAbort !== undefined) {
-            signal.removeEventListener('abort', onAbort);
-            onAbort = undefined;
-        }
-    };
-    return { promise, cleanup };
-}
-async function runHook(hook, input, signal, matcher) {
-    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, event, logger) {
-    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, decision, reason) {
-    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, decision, reason) {
-    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, output) {
-    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, output) {
-    if (typeof output.additionalContext === 'string' &&
-        output.additionalContext.length > 0) {
-        agg.additionalContexts.push(output.additionalContext);
-    }
-}
-function applyStopFlag(agg, output) {
-    if (output.preventContinuation !== true) {
-        return;
-    }
-    agg.preventContinuation = true;
-    if (typeof output.stopReason === 'string' && agg.stopReason === undefined) {
-        agg.stopReason = output.stopReason;
-    }
-}
-function applyUpdatedInput(agg, output) {
-    if (!('updatedInput' in output) || output.updatedInput === undefined) {
-        return;
-    }
-    agg.updatedInput = output.updatedInput;
-}
-function applyUpdatedOutput(agg, output) {
-    if (!('updatedOutput' in output) || output.updatedOutput === undefined) {
-        return;
-    }
-    agg.updatedOutput = output.updatedOutput;
-}
-function fold(outcomes) {
-    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`.
- */
-async function executeHooks(opts) {
-    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 = [];
-    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);
-}
-
-export { DEFAULT_HOOK_TIMEOUT_MS, executeHooks };
-//# sourceMappingURL=executeHooks.mjs.map

package/dist/esm/hooks/executeHooks.mjs.map

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