@librechat/agents 3.2.32 → 3.2.34

package/dist/esm/hooks/executeHooks.mjs

@@ -1,319 +1,266 @@
-import { matchesQuery } from './matchers.mjs';
-
+import { matchesQuery } from "./matchers.mjs";
+//#region src/hooks/executeHooks.ts
 /** Default per-hook timeout when a matcher doesn't set its own. */
-const DEFAULT_HOOK_TIMEOUT_MS = 30_000;
+const DEFAULT_HOOK_TIMEOUT_MS = 3e4;
 function freshResult() {
-    return {
-        additionalContexts: [],
-        errors: [],
-    };
+	return {
+		additionalContexts: [],
+		errors: []
+	};
 }
 function combineSignals(parent, timeoutMs) {
-    const timeoutSignal = AbortSignal.timeout(timeoutMs);
-    if (parent === undefined) {
-        return timeoutSignal;
-    }
-    return AbortSignal.any([parent, timeoutSignal]);
+	const timeoutSignal = AbortSignal.timeout(timeoutMs);
+	if (parent === void 0) return timeoutSignal;
+	return AbortSignal.any([parent, timeoutSignal]);
 }
 function isTimeout(err) {
-    if (err instanceof Error) {
-        return err.name === 'TimeoutError' || err.name === 'AbortError';
-    }
-    return false;
+	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);
+	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 };
+	let onAbort;
+	const promise = new Promise((_resolve, reject) => {
+		if (signal.aborted) {
+			reject(signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("aborted"));
+			return;
+		}
+		onAbort = () => {
+			reject(signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("aborted"));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+	});
+	const cleanup = () => {
+		if (onAbort !== void 0) {
+			signal.removeEventListener("abort", onAbort);
+			onAbort = void 0;
+		}
+	};
+	return {
+		promise,
+		cleanup
+	};
 }
 async function runHook(hook, input, signal, abortPromise, matcher) {
-    const hookPromise = Promise.resolve().then(() => hook(input, 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),
-        };
-    }
+	const hookPromise = Promise.resolve().then(() => hook(input, signal));
+	try {
+		return {
+			matcher,
+			output: await Promise.race([hookPromise, abortPromise]),
+			error: null,
+			timedOut: false
+		};
+	} catch (err) {
+		return {
+			matcher,
+			output: null,
+			error: describeError(err),
+			timedOut: isTimeout(err)
+		};
+	}
 }
 async function runMatcherHooks(matcher, input, signal) {
-    const abortRace = makeAbortPromise(signal);
-    const tasks = matcher.hooks.map((hook) => runHook(hook, input, signal, abortRace.promise, matcher));
-    try {
-        return await Promise.all(tasks);
-    }
-    finally {
-        abortRace.cleanup();
-    }
+	const abortRace = makeAbortPromise(signal);
+	const tasks = matcher.hooks.map((hook) => runHook(hook, input, signal, abortRace.promise, matcher));
+	try {
+		return await Promise.all(tasks);
+	} finally {
+		abortRace.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);
-    }
+	for (const outcome of outcomes) {
+		if (outcome.error === null) continue;
+		if (outcome.matcher.internal === true) continue;
+		const message = `Hook for ${event} ${outcome.timedOut ? "timed out" : "threw an error"}: ${outcome.error}`;
+		if (logger !== void 0) {
+			logger.warn(message);
+			continue;
+		}
+		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;
-    }
+	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 === void 0) {
+		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;
-        }
-    }
+	if (decision === "block") {
+		if (agg.stopDecision === "block") return;
+		agg.stopDecision = "block";
+		agg.reason = reason;
+		return;
+	}
+	if (agg.stopDecision === void 0) {
+		agg.stopDecision = "continue";
+		if (agg.reason === void 0) 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);
+	if (!("decision" in output) || output.decision === void 0) return;
+	const decision = output.decision;
+	const reason = "reason" in output && typeof output.reason === "string" ? output.reason : void 0;
+	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);
-    }
+	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;
-    }
+	if (output.preventContinuation !== true) return;
+	agg.preventContinuation = true;
+	if (typeof output.stopReason === "string" && agg.stopReason === void 0) agg.stopReason = output.stopReason;
 }
 function applyUpdatedInput(agg, output) {
-    if (!('updatedInput' in output) || output.updatedInput === undefined) {
-        return;
-    }
-    agg.updatedInput = output.updatedInput;
+	if (!("updatedInput" in output) || output.updatedInput === void 0) return;
+	agg.updatedInput = output.updatedInput;
 }
 function applyUpdatedOutput(agg, output) {
-    if (!('updatedOutput' in output) || output.updatedOutput === undefined) {
-        return;
-    }
-    agg.updatedOutput = output.updatedOutput;
+	if (!("updatedOutput" in output) || output.updatedOutput === void 0) return;
+	agg.updatedOutput = output.updatedOutput;
 }
 function applyAllowedDecisions(agg, output) {
-    if (!('allowedDecisions' in output) ||
-        output.allowedDecisions === undefined) {
-        return;
-    }
-    agg.allowedDecisions = output.allowedDecisions;
+	if (!("allowedDecisions" in output) || output.allowedDecisions === void 0) return;
+	agg.allowedDecisions = output.allowedDecisions;
 }
 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;
-        }
-        /**
-         * Skip fire-and-forget outputs entirely: the agent has already
-         * moved on, so an async hook cannot influence the run. Background
-         * work inside the hook body still runs (we don't cancel it), it
-         * just doesn't fold into the aggregate result.
-         */
-        if (output.async === true) {
-            continue;
-        }
-        applyContext(agg, output);
-        applyStopFlag(agg, output);
-        applyDecision(agg, output);
-        applyUpdatedInput(agg, output);
-        applyUpdatedOutput(agg, output);
-        applyAllowedDecisions(agg, output);
-    }
-    return agg;
+	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;
+		/**
+		* Skip fire-and-forget outputs entirely: the agent has already
+		* moved on, so an async hook cannot influence the run. Background
+		* work inside the hook body still runs (we don't cancel it), it
+		* just doesn't fold into the aggregate result.
+		*/
+		if (output.async === true) continue;
+		applyContext(agg, output);
+		applyStopFlag(agg, output);
+		applyDecision(agg, output);
+		applyUpdatedInput(agg, output);
+		applyUpdatedOutput(agg, output);
+		applyAllowedDecisions(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`.
- */
+* 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);
-        }
-        if (matcher.hooks.length === 0) {
-            continue;
-        }
-        const perHookTimeout = matcher.timeout ?? timeoutMs;
-        const matcherSignal = combineSignals(signal, perHookTimeout);
-        tasks.push(runMatcherHooks(matcher, input, matcherSignal));
-    }
-    // --- END SYNC CRITICAL SECTION ---
-    if (tasks.length === 0) {
-        return freshResult();
-    }
-    const outcomes = (await Promise.all(tasks)).flat();
-    reportErrors(outcomes, event, logger);
-    const aggregated = fold(outcomes);
-    /**
-     * Centralized `preventContinuation` propagation: when any hook (across
-     * any callsite — RunStart, PreToolUse, PostToolBatch, SubagentStop,
-     * etc.) returns `preventContinuation: true`, raise a halt signal on
-     * the registry scoped to the run's `sessionId`. `Run.processStream`
-     * polls the signal between stream events using its own id and exits
-     * cleanly, skipping the `Stop` hook (since the run is being halted,
-     * not naturally completing).
-     *
-     * First-write-wins per session inside the registry — a halt already
-     * raised by an earlier hook in the same run is preserved so the
-     * original `reason` / `source` are not clobbered. Hooks fired
-     * without a `sessionId` cannot raise a halt (there's no run for the
-     * loop to poll under), which is fine: every in-tree callsite passes
-     * `sessionId: runId`. Pre-stream callsites in `Run.processStream`
-     * still read `preventContinuation` directly off the result for an
-     * early return because they have not yet entered the stream loop.
-     */
-    if (aggregated.preventContinuation === true && sessionId !== undefined) {
-        registry.haltRun(sessionId, aggregated.stopReason ?? 'preventContinuation', event);
-    }
-    return aggregated;
+	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();
+	const tasks = [];
+	for (const matcher of matchers) {
+		if (!matchesQuery(matcher.pattern, matchQuery)) continue;
+		if (matcher.once === true) registry.removeMatcher(event, matcher, sessionId);
+		if (matcher.hooks.length === 0) continue;
+		const matcherSignal = combineSignals(signal, matcher.timeout ?? timeoutMs);
+		tasks.push(runMatcherHooks(matcher, input, matcherSignal));
+	}
+	if (tasks.length === 0) return freshResult();
+	const outcomes = (await Promise.all(tasks)).flat();
+	reportErrors(outcomes, event, logger);
+	const aggregated = fold(outcomes);
+	/**
+	* Centralized `preventContinuation` propagation: when any hook (across
+	* any callsite — RunStart, PreToolUse, PostToolBatch, SubagentStop,
+	* etc.) returns `preventContinuation: true`, raise a halt signal on
+	* the registry scoped to the run's `sessionId`. `Run.processStream`
+	* polls the signal between stream events using its own id and exits
+	* cleanly, skipping the `Stop` hook (since the run is being halted,
+	* not naturally completing).
+	*
+	* First-write-wins per session inside the registry — a halt already
+	* raised by an earlier hook in the same run is preserved so the
+	* original `reason` / `source` are not clobbered. Hooks fired
+	* without a `sessionId` cannot raise a halt (there's no run for the
+	* loop to poll under), which is fine: every in-tree callsite passes
+	* `sessionId: runId`. Pre-stream callsites in `Run.processStream`
+	* still read `preventContinuation` directly off the result for an
+	* early return because they have not yet entered the stream loop.
+	*/
+	if (aggregated.preventContinuation === true && sessionId !== void 0) registry.haltRun(sessionId, aggregated.stopReason ?? "preventContinuation", event);
+	return aggregated;
 }
-
+//#endregion
 export { DEFAULT_HOOK_TIMEOUT_MS, executeHooks };
-//# sourceMappingURL=executeHooks.mjs.map
+
+//# sourceMappingURL=executeHooks.mjs.map