@librechat/agents 3.2.31 → 3.2.33

package/dist/esm/hooks/HookRegistry.mjs

@@ -1,214 +1,190 @@
+//#region src/hooks/HookRegistry.ts
 /**
- * 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();
-    /**
-     * Per-session halt signals. Scoped by `sessionId` (= the run id the
-     * hook fired under) so a host that shares one registry across
-     * concurrent runs cannot leak `preventContinuation` from one run
-     * into another. Without scoping, a halt raised by run A's hook
-     * would trip run B's stream-loop poll on the next iteration —
-     * silently terminating an unrelated run.
-     *
-     * Map storage mirrors the reasoning above for session matchers:
-     * O(1) insertion in hot paths, no spread-on-write.
-     */
-    haltSignals = 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);
-    }
-    /**
-     * Raise a halt signal scoped to `sessionId` (= the run id the hook
-     * fired under). The SDK's run loop polls for this between stream
-     * events with the run's own id. First-write-wins per session: a
-     * halt already raised by an earlier hook in the same run is
-     * preserved so the original `reason` / `source` aren't overwritten.
-     *
-     * Per-session scoping is critical when hosts share one registry
-     * across concurrent runs (e.g. a global policy registered once and
-     * reused). Without it, a `preventContinuation` from run A would
-     * trip run B's stream-loop poll on the next iteration and silently
-     * terminate an unrelated run.
-     *
-     * Called by the SDK after `executeHooks` returns an aggregate with
-     * `preventContinuation: true`. Hosts can also call it directly from
-     * inside a hook callback if they want to halt without going through
-     * the aggregated return value, but `preventContinuation` is the
-     * canonical path.
-     */
-    haltRun(sessionId, reason, source) {
-        if (this.haltSignals.has(sessionId)) {
-            return;
-        }
-        this.haltSignals.set(sessionId, { reason, source });
-    }
-    /**
-     * Returns the halt signal raised by hooks running under `sessionId`,
-     * or `undefined` if no hook in that run has halted. Polled by
-     * `Run.processStream` between stream events using the run's own id.
-     */
-    getHaltSignal(sessionId) {
-        return this.haltSignals.get(sessionId);
-    }
-    /**
-     * Clears the halt signal for `sessionId`. Called by
-     * `Run.processStream` in its `finally` block so a subsequent
-     * invocation of the same Run (e.g. resume) starts with a fresh
-     * halt state. No-op when no signal exists for that session.
-     */
-    clearHaltSignal(sessionId) {
-        this.haltSignals.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;
-    }
-}
+* 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`.
+*/
+var HookRegistry = class {
+	global = {};
+	sessions = /* @__PURE__ */ new Map();
+	/**
+	* Per-session halt signals. Scoped by `sessionId` (= the run id the
+	* hook fired under) so a host that shares one registry across
+	* concurrent runs cannot leak `preventContinuation` from one run
+	* into another. Without scoping, a halt raised by run A's hook
+	* would trip run B's stream-loop poll on the next iteration —
+	* silently terminating an unrelated run.
+	*
+	* Map storage mirrors the reasoning above for session matchers:
+	* O(1) insertion in hot paths, no spread-on-write.
+	*/
+	haltSignals = /* @__PURE__ */ 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 list = ensureList(this.ensureSessionBucket(sessionId), 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 === void 0) return snapshot(globalList);
+		const bucket = this.sessions.get(sessionId);
+		if (bucket === void 0) 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 === void 0) return false;
+		const bucket = this.sessions.get(sessionId);
+		if (bucket === void 0) 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);
+	}
+	/**
+	* Raise a halt signal scoped to `sessionId` (= the run id the hook
+	* fired under). The SDK's run loop polls for this between stream
+	* events with the run's own id. First-write-wins per session: a
+	* halt already raised by an earlier hook in the same run is
+	* preserved so the original `reason` / `source` aren't overwritten.
+	*
+	* Per-session scoping is critical when hosts share one registry
+	* across concurrent runs (e.g. a global policy registered once and
+	* reused). Without it, a `preventContinuation` from run A would
+	* trip run B's stream-loop poll on the next iteration and silently
+	* terminate an unrelated run.
+	*
+	* Called by the SDK after `executeHooks` returns an aggregate with
+	* `preventContinuation: true`. Hosts can also call it directly from
+	* inside a hook callback if they want to halt without going through
+	* the aggregated return value, but `preventContinuation` is the
+	* canonical path.
+	*/
+	haltRun(sessionId, reason, source) {
+		if (this.haltSignals.has(sessionId)) return;
+		this.haltSignals.set(sessionId, {
+			reason,
+			source
+		});
+	}
+	/**
+	* Returns the halt signal raised by hooks running under `sessionId`,
+	* or `undefined` if no hook in that run has halted. Polled by
+	* `Run.processStream` between stream events using the run's own id.
+	*/
+	getHaltSignal(sessionId) {
+		return this.haltSignals.get(sessionId);
+	}
+	/**
+	* Clears the halt signal for `sessionId`. Called by
+	* `Run.processStream` in its `finally` block so a subsequent
+	* invocation of the same Run (e.g. resume) starts with a fresh
+	* halt state. No-op when no signal exists for that session.
+	*/
+	clearHaltSignal(sessionId) {
+		this.haltSignals.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 === void 0) return false;
+		const bucket = this.sessions.get(sessionId);
+		if (bucket === void 0) return false;
+		return readList(bucket, event).length > 0;
+	}
+	ensureSessionBucket(sessionId) {
+		const existing = this.sessions.get(sessionId);
+		if (existing !== void 0) 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;
+	const existing = bucket[event];
+	if (existing !== void 0) return existing;
+	const fresh = [];
+	bucket[event] = fresh;
+	return fresh;
 }
 function readList(bucket, event) {
-    return 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;
+	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`.
- */
+* 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;
+	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.
- */
+* 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();
+	return list.slice();
 }
-
+//#endregion
 export { HookRegistry };
-//# sourceMappingURL=HookRegistry.mjs.map
+
+//# sourceMappingURL=HookRegistry.mjs.map

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

@@ -1 +1 @@
-{"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 * Snapshot of a halt request raised by a hook returning\n * `preventContinuation: true`. The SDK's run loop polls for this between\n * stream events and exits cleanly when set, skipping the `Stop` hook\n * (the run is being halted, not naturally completing). One per registry\n * instance — the first hook to halt wins; subsequent halts are ignored\n * so the original reason isn't clobbered.\n */\nexport interface HookHaltSignal {\n  reason: string;\n  /** Event of the hook that triggered the halt (for diagnostics). */\n  source: HookEvent;\n}\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   * Per-session halt signals. Scoped by `sessionId` (= the run id the\n   * hook fired under) so a host that shares one registry across\n   * concurrent runs cannot leak `preventContinuation` from one run\n   * into another. Without scoping, a halt raised by run A's hook\n   * would trip run B's stream-loop poll on the next iteration —\n   * silently terminating an unrelated run.\n   *\n   * Map storage mirrors the reasoning above for session matchers:\n   * O(1) insertion in hot paths, no spread-on-write.\n   */\n  private readonly haltSignals: Map<string, HookHaltSignal> = 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  /**\n   * Raise a halt signal scoped to `sessionId` (= the run id the hook\n   * fired under). The SDK's run loop polls for this between stream\n   * events with the run's own id. First-write-wins per session: a\n   * halt already raised by an earlier hook in the same run is\n   * preserved so the original `reason` / `source` aren't overwritten.\n   *\n   * Per-session scoping is critical when hosts share one registry\n   * across concurrent runs (e.g. a global policy registered once and\n   * reused). Without it, a `preventContinuation` from run A would\n   * trip run B's stream-loop poll on the next iteration and silently\n   * terminate an unrelated run.\n   *\n   * Called by the SDK after `executeHooks` returns an aggregate with\n   * `preventContinuation: true`. Hosts can also call it directly from\n   * inside a hook callback if they want to halt without going through\n   * the aggregated return value, but `preventContinuation` is the\n   * canonical path.\n   */\n  haltRun(sessionId: string, reason: string, source: HookEvent): void {\n    if (this.haltSignals.has(sessionId)) {\n      return;\n    }\n    this.haltSignals.set(sessionId, { reason, source });\n  }\n\n  /**\n   * Returns the halt signal raised by hooks running under `sessionId`,\n   * or `undefined` if no hook in that run has halted. Polled by\n   * `Run.processStream` between stream events using the run's own id.\n   */\n  getHaltSignal(sessionId: string): HookHaltSignal | undefined {\n    return this.haltSignals.get(sessionId);\n  }\n\n  /**\n   * Clears the halt signal for `sessionId`. Called by\n   * `Run.processStream` in its `finally` block so a subsequent\n   * invocation of the same Run (e.g. resume) starts with a fresh\n   * halt state. No-op when no signal exists for that session.\n   */\n  clearHaltSignal(sessionId: string): void {\n    this.haltSignals.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":"AA6BA;;;;;;;;;;;;;;;;;AAiBG;MACU,YAAY,CAAA;IACN,MAAM,GAAkB,EAAE;AAC1B,IAAA,QAAQ,GAA+B,IAAI,GAAG,EAAE;AACjE;;;;;;;;;;AAUG;AACc,IAAA,WAAW,GAAgC,IAAI,GAAG,EAAE;AAErE;;;AAGG;IACH,QAAQ,CAAsB,KAAQ,EAAE,OAAuB,EAAA;QAC7D,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC;QAC3C,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AACzB,QAAA,OAAO,MAAK;AACV,YAAA,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC;AAC/B,QAAA,CAAC;IACH;AAEA;;;;AAIG;AACH,IAAA,eAAe,CACb,SAAiB,EACjB,KAAQ,EACR,OAAuB,EAAA;QAEvB,MAAM,MAAM,GAAG,IAAI,CAAC,mBAAmB,CAAC,SAAS,CAAC;QAClD,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,EAAE,KAAK,CAAC;QACtC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AACzB,QAAA,OAAO,MAAK;AACV,YAAA,cAAc,CAAC,IAAI,EAAE,OAAO,CAAC;AAC/B,QAAA,CAAC;IACH;AAEA;;;;;AAKG;IACH,WAAW,CACT,KAAQ,EACR,SAAkB,EAAA;QAElB,MAAM,UAAU,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC;AAC/C,QAAA,IAAI,SAAS,KAAK,SAAS,EAAE;AAC3B,YAAA,OAAO,QAAQ,CAAI,UAAU,CAAC;QAChC;QACA,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC;AAC3C,QAAA,IAAI,MAAM,KAAK,SAAS,EAAE;AACxB,YAAA,OAAO,QAAQ,CAAI,UAAU,CAAC;QAChC;QACA,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;AAC3C,QAAA,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE;AAC3B,YAAA,OAAO,QAAQ,CAAI,WAAW,CAAC;QACjC;AACA,QAAA,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE;AAC5B,YAAA,OAAO,QAAQ,CAAI,UAAU,CAAC;QAChC;QACA,OAAO,QAAQ,CAAI,CAAC,GAAG,UAAU,EAAE,GAAG,WAAW,CAAC,CAAC;IACrD;AAEA;;;;AAIG;AACH,IAAA,aAAa,CACX,KAAQ,EACR,OAAuB,EACvB,SAAkB,EAAA;AAElB,QAAA,IAAI,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,CAAC,EAAE;AACzD,YAAA,OAAO,IAAI;QACb;AACA,QAAA,IAAI,SAAS,KAAK,SAAS,EAAE;AAC3B,YAAA,OAAO,KAAK;QACd;QACA,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC;AAC3C,QAAA,IAAI,MAAM,KAAK,SAAS,EAAE;AACxB,YAAA,OAAO,KAAK;QACd;QACA,OAAO,cAAc,CAAC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IACzD;AAEA;;;;AAIG;AACH,IAAA,YAAY,CAAC,SAAiB,EAAA;AAC5B,QAAA,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,SAAS,CAAC;IACjC;AAEA;;;;;;;;;;;;;;;;;;AAkBG;AACH,IAAA,OAAO,CAAC,SAAiB,EAAE,MAAc,EAAE,MAAiB,EAAA;QAC1D,IAAI,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE;YACnC;QACF;AACA,QAAA,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IACrD;AAEA;;;;AAIG;AACH,IAAA,aAAa,CAAC,SAAiB,EAAA;QAC7B,OAAO,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC;IACxC;AAEA;;;;;AAKG;AACH,IAAA,eAAe,CAAC,SAAiB,EAAA;AAC/B,QAAA,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC;IACpC;;IAGA,UAAU,CAAC,KAAgB,EAAE,SAAkB,EAAA;AAC7C,QAAA,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE;AAC3C,YAAA,OAAO,IAAI;QACb;AACA,QAAA,IAAI,SAAS,KAAK,SAAS,EAAE;AAC3B,YAAA,OAAO,KAAK;QACd;QACA,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC;AAC3C,QAAA,IAAI,MAAM,KAAK,SAAS,EAAE;AACxB,YAAA,OAAO,KAAK;QACd;QACA,OAAO,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,MAAM,GAAG,CAAC;IAC3C;AAEQ,IAAA,mBAAmB,CAAC,SAAiB,EAAA;QAC3C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,CAAC;AAC7C,QAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;AAC1B,YAAA,OAAO,QAAQ;QACjB;QACA,MAAM,KAAK,GAAkB,EAAE;QAC/B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC;AACnC,QAAA,OAAO,KAAK;IACd;AACD;AAED,SAAS,UAAU,CACjB,MAAqB,EACrB,KAAgB,EAAA;AAEhB,IAAA,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC;AAC9B,IAAA,IAAI,QAAQ,KAAK,SAAS,EAAE;AAC1B,QAAA,OAAO,QAAQ;IACjB;IACA,MAAM,KAAK,GAA6B,EAAE;AAC1C,IAAA,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK;AACrB,IAAA,OAAO,KAAK;AACd;AAEA,SAAS,QAAQ,CACf,MAAqB,EACrB,KAAgB,EAAA;AAEhB,IAAA,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE;AAC5B;AAEA,SAAS,cAAc,CACrB,IAA8B,EAC9B,OAAuB,EAAA;IAEvB,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AACxC,IAAA,IAAI,GAAG,GAAG,CAAC,EAAE;AACX,QAAA,OAAO,KAAK;IACd;AACA,IAAA,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;AACnB,IAAA,OAAO,IAAI;AACb;AAEA;;;;;;AAMG;AACH,SAAS,KAAK,CACZ,OAAuB,EAAA;AAEvB,IAAA,OAAO,OAA4C;AACrD;AAEA;;;;AAIG;AACH,SAAS,QAAQ,CACf,IAAuC,EAAA;AAEvC,IAAA,OAAO,IAAI,CAAC,KAAK,EAAiC;AACpD;;;;"}
+{"version":3,"file":"HookRegistry.mjs","names":[],"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 * Snapshot of a halt request raised by a hook returning\n * `preventContinuation: true`. The SDK's run loop polls for this between\n * stream events and exits cleanly when set, skipping the `Stop` hook\n * (the run is being halted, not naturally completing). One per registry\n * instance — the first hook to halt wins; subsequent halts are ignored\n * so the original reason isn't clobbered.\n */\nexport interface HookHaltSignal {\n  reason: string;\n  /** Event of the hook that triggered the halt (for diagnostics). */\n  source: HookEvent;\n}\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   * Per-session halt signals. Scoped by `sessionId` (= the run id the\n   * hook fired under) so a host that shares one registry across\n   * concurrent runs cannot leak `preventContinuation` from one run\n   * into another. Without scoping, a halt raised by run A's hook\n   * would trip run B's stream-loop poll on the next iteration —\n   * silently terminating an unrelated run.\n   *\n   * Map storage mirrors the reasoning above for session matchers:\n   * O(1) insertion in hot paths, no spread-on-write.\n   */\n  private readonly haltSignals: Map<string, HookHaltSignal> = 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  /**\n   * Raise a halt signal scoped to `sessionId` (= the run id the hook\n   * fired under). The SDK's run loop polls for this between stream\n   * events with the run's own id. First-write-wins per session: a\n   * halt already raised by an earlier hook in the same run is\n   * preserved so the original `reason` / `source` aren't overwritten.\n   *\n   * Per-session scoping is critical when hosts share one registry\n   * across concurrent runs (e.g. a global policy registered once and\n   * reused). Without it, a `preventContinuation` from run A would\n   * trip run B's stream-loop poll on the next iteration and silently\n   * terminate an unrelated run.\n   *\n   * Called by the SDK after `executeHooks` returns an aggregate with\n   * `preventContinuation: true`. Hosts can also call it directly from\n   * inside a hook callback if they want to halt without going through\n   * the aggregated return value, but `preventContinuation` is the\n   * canonical path.\n   */\n  haltRun(sessionId: string, reason: string, source: HookEvent): void {\n    if (this.haltSignals.has(sessionId)) {\n      return;\n    }\n    this.haltSignals.set(sessionId, { reason, source });\n  }\n\n  /**\n   * Returns the halt signal raised by hooks running under `sessionId`,\n   * or `undefined` if no hook in that run has halted. Polled by\n   * `Run.processStream` between stream events using the run's own id.\n   */\n  getHaltSignal(sessionId: string): HookHaltSignal | undefined {\n    return this.haltSignals.get(sessionId);\n  }\n\n  /**\n   * Clears the halt signal for `sessionId`. Called by\n   * `Run.processStream` in its `finally` block so a subsequent\n   * invocation of the same Run (e.g. resume) starts with a fresh\n   * halt state. No-op when no signal exists for that session.\n   */\n  clearHaltSignal(sessionId: string): void {\n    this.haltSignals.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"],"mappings":"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"}