@warlock.js/core 4.7.0 → 4.8.1

package/esm/ai/src/guard/detectors/topic.mjs

@@ -1,99 +0,0 @@
-//#region ../@warlock.js/ai/src/guard/detectors/topic.ts
-/** Detector name, used as the namespace prefix on every {@link GuardrailMatch.rule}. */
-const DETECTOR_NAME = "topic";
-/**
-* Locate the first occurrence of `term` in `text`. A `string` matches
-* case-insensitively as a substring; a `RegExp` is tested as-is (its own
-* flags decide case-sensitivity). Returns the inclusive `[start, end]`
-* span on a hit, or `undefined` when the term is absent.
-*/
-function locate(text, term) {
-	if (typeof term === "string") {
-		if (term.length === 0) return;
-		const index = text.toLowerCase().indexOf(term.toLowerCase());
-		if (index === -1) return;
-		return [index, index + term.length - 1];
-	}
-	const match = new RegExp(term.source, term.flags.replace(/[gy]/g, "")).exec(text);
-	if (match === null) return;
-	return [match.index, match.index + match[0].length - 1];
-}
-/** A human-readable label for a deny/allow term, used in the match rule + reason. */
-function describeTerm(term) {
-	return typeof term === "string" ? term : term.source;
-}
-/**
-* Build the built-in **topic filter** (`ai.guardrail.topic`) — a
-* zero-runtime-dependency {@link GuardrailDetector} that gates text against a
-* deny list, an allow list, or both.
-*
-* - **`deny`** — any term that appears triggers `onMatch`. A `string`
-*   matches case-insensitively as a substring; a `RegExp` is tested as-is.
-*   The deny list is checked first; the first hit decides the verdict.
-* - **`allow`** — when set, text matching **none** of the allow terms
-*   triggers `onMatch` (an allow-list miss). Text matching at least one
-*   allow term passes the allow gate.
-*
-* `onMatch` is `"block"` (default) or `"flag"`. With neither list supplied
-* the detector is a no-op that always allows.
-*
-* @example
-* ai.guardrail.topic({ deny: ["medical advice", /diagnos\w+/i] });
-*
-* @example
-* // Stay on-topic: anything not about billing is flagged.
-* ai.guardrail.topic({ allow: ["billing", "invoice", "refund"], onMatch: "flag" });
-*/
-function topic(options) {
-	const deny = options.deny ?? [];
-	const allow = options.allow ?? [];
-	const onMatch = options.onMatch ?? "block";
-	return {
-		name: DETECTOR_NAME,
-		check(text) {
-			for (const term of deny) {
-				const span = locate(text, term);
-				if (span !== void 0) {
-					const label = describeTerm(term);
-					const match = {
-						rule: `${DETECTOR_NAME}.deny.${label}`,
-						span,
-						label
-					};
-					return verdict(onMatch, options.reason ?? `Denied topic matched: ${label}.`, [match]);
-				}
-			}
-			if (allow.length > 0) {
-				if (!allow.some((term) => locate(text, term) !== void 0)) {
-					const match = {
-						rule: `${DETECTOR_NAME}.allow.miss`,
-						label: "allow-miss"
-					};
-					return verdict(onMatch, options.reason ?? "Text matched none of the allowed topics.", [match]);
-				}
-			}
-			return { type: "allow" };
-		}
-	};
-}
-/**
-* Fold the resolved action into a `block` or `flag` verdict. Topic never
-* redacts — it cannot meaningfully rewrite a whole-text policy miss — so the
-* action is constrained to `"block" | "flag"` at the type level.
-*/
-function verdict(action, reason, matches) {
-	if (action === "block") return {
-		type: "block",
-		reason,
-		matches
-	};
-	return {
-		type: "flag",
-		reason,
-		matches
-	};
-}
-
-//#endregion
-export { topic };
-//# sourceMappingURL=topic.mjs.map

package/esm/ai/src/guard/detectors/topic.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"topic.mjs","names":[],"sources":["../../../../../../../../../../@warlock.js/ai/src/guard/detectors/topic.ts"],"sourcesContent":["import type {\n  GuardrailMatch,\n  GuardrailVerdict,\n  SyncGuardrailDetector,\n  TopicFilterOptions,\n} from \"../contracts\";\n\n/** Detector name, used as the namespace prefix on every {@link GuardrailMatch.rule}. */\nconst DETECTOR_NAME = \"topic\";\n\n/**\n * Locate the first occurrence of `term` in `text`. A `string` matches\n * case-insensitively as a substring; a `RegExp` is tested as-is (its own\n * flags decide case-sensitivity). Returns the inclusive `[start, end]`\n * span on a hit, or `undefined` when the term is absent.\n */\nfunction locate(text: string, term: string | RegExp): readonly [number, number] | undefined {\n  if (typeof term === \"string\") {\n    if (term.length === 0) {\n      return undefined;\n    }\n\n    const index = text.toLowerCase().indexOf(term.toLowerCase());\n\n    if (index === -1) {\n      return undefined;\n    }\n\n    return [index, index + term.length - 1];\n  }\n\n  // RegExp: run a non-global copy so a caller-supplied `/g` term cannot leak\n  // `lastIndex` between calls and so `.exec` reports a deterministic first hit.\n  const probe = new RegExp(term.source, term.flags.replace(/[gy]/g, \"\"));\n  const match = probe.exec(text);\n\n  if (match === null) {\n    return undefined;\n  }\n\n  return [match.index, match.index + match[0].length - 1];\n}\n\n/** A human-readable label for a deny/allow term, used in the match rule + reason. */\nfunction describeTerm(term: string | RegExp): string {\n  return typeof term === \"string\" ? term : term.source;\n}\n\n/**\n * Build the built-in **topic filter** (`ai.guardrail.topic`) — a\n * zero-runtime-dependency {@link GuardrailDetector} that gates text against a\n * deny list, an allow list, or both.\n *\n * - **`deny`** — any term that appears triggers `onMatch`. A `string`\n *   matches case-insensitively as a substring; a `RegExp` is tested as-is.\n *   The deny list is checked first; the first hit decides the verdict.\n * - **`allow`** — when set, text matching **none** of the allow terms\n *   triggers `onMatch` (an allow-list miss). Text matching at least one\n *   allow term passes the allow gate.\n *\n * `onMatch` is `\"block\"` (default) or `\"flag\"`. With neither list supplied\n * the detector is a no-op that always allows.\n *\n * @example\n * ai.guardrail.topic({ deny: [\"medical advice\", /diagnos\\w+/i] });\n *\n * @example\n * // Stay on-topic: anything not about billing is flagged.\n * ai.guardrail.topic({ allow: [\"billing\", \"invoice\", \"refund\"], onMatch: \"flag\" });\n */\nexport function topic(options: TopicFilterOptions): SyncGuardrailDetector {\n  const deny = options.deny ?? [];\n  const allow = options.allow ?? [];\n  const onMatch = options.onMatch ?? \"block\";\n\n  return {\n    name: DETECTOR_NAME,\n    check(text: string): GuardrailVerdict {\n      // Deny list: the first present term decides the verdict.\n      for (const term of deny) {\n        const span = locate(text, term);\n\n        if (span !== undefined) {\n          const label = describeTerm(term);\n          const match: GuardrailMatch = {\n            rule: `${DETECTOR_NAME}.deny.${label}`,\n            span,\n            label,\n          };\n          const reason = options.reason ?? `Denied topic matched: ${label}.`;\n\n          return verdict(onMatch, reason, [match]);\n        }\n      }\n\n      // Allow list: matching NONE of the terms is a miss → trigger onMatch.\n      if (allow.length > 0) {\n        const matchedAny = allow.some(term => locate(text, term) !== undefined);\n\n        if (!matchedAny) {\n          const match: GuardrailMatch = {\n            rule: `${DETECTOR_NAME}.allow.miss`,\n            label: \"allow-miss\",\n          };\n          const reason =\n            options.reason ?? \"Text matched none of the allowed topics.\";\n\n          return verdict(onMatch, reason, [match]);\n        }\n      }\n\n      return { type: \"allow\" };\n    },\n  };\n}\n\n/**\n * Fold the resolved action into a `block` or `flag` verdict. Topic never\n * redacts — it cannot meaningfully rewrite a whole-text policy miss — so the\n * action is constrained to `\"block\" | \"flag\"` at the type level.\n */\nfunction verdict(\n  action: \"block\" | \"flag\",\n  reason: string,\n  matches: readonly GuardrailMatch[],\n): GuardrailVerdict {\n  if (action === \"block\") {\n    return { type: \"block\", reason, matches };\n  }\n\n  return { type: \"flag\", reason, matches };\n}\n"],"mappings":";;AAQA,MAAM,gBAAgB;;;;;;;AAQtB,SAAS,OAAO,MAAc,MAA8D;CAC1F,IAAI,OAAO,SAAS,UAAU;EAC5B,IAAI,KAAK,WAAW,GAClB;EAGF,MAAM,QAAQ,KAAK,YAAY,CAAC,CAAC,QAAQ,KAAK,YAAY,CAAC;EAE3D,IAAI,UAAU,IACZ;EAGF,OAAO,CAAC,OAAO,QAAQ,KAAK,SAAS,CAAC;CACxC;CAKA,MAAM,QAAQ,IADI,OAAO,KAAK,QAAQ,KAAK,MAAM,QAAQ,SAAS,EAAE,CAClD,CAAC,CAAC,KAAK,IAAI;CAE7B,IAAI,UAAU,MACZ;CAGF,OAAO,CAAC,MAAM,OAAO,MAAM,QAAQ,MAAM,EAAE,CAAC,SAAS,CAAC;AACxD;;AAGA,SAAS,aAAa,MAA+B;CACnD,OAAO,OAAO,SAAS,WAAW,OAAO,KAAK;AAChD;;;;;;;;;;;;;;;;;;;;;;;AAwBA,SAAgB,MAAM,SAAoD;CACxE,MAAM,OAAO,QAAQ,QAAQ,CAAC;CAC9B,MAAM,QAAQ,QAAQ,SAAS,CAAC;CAChC,MAAM,UAAU,QAAQ,WAAW;CAEnC,OAAO;EACL,MAAM;EACN,MAAM,MAAgC;GAEpC,KAAK,MAAM,QAAQ,MAAM;IACvB,MAAM,OAAO,OAAO,MAAM,IAAI;IAE9B,IAAI,SAAS,QAAW;KACtB,MAAM,QAAQ,aAAa,IAAI;KAC/B,MAAM,QAAwB;MAC5B,MAAM,GAAG,cAAc,QAAQ;MAC/B;MACA;KACF;KAGA,OAAO,QAAQ,SAFA,QAAQ,UAAU,yBAAyB,MAAM,IAEhC,CAAC,KAAK,CAAC;IACzC;GACF;GAGA,IAAI,MAAM,SAAS,GAGjB;QAAI,CAFe,MAAM,MAAK,SAAQ,OAAO,MAAM,IAAI,MAAM,MAE/C,GAAG;KACf,MAAM,QAAwB;MAC5B,MAAM,GAAG,cAAc;MACvB,OAAO;KACT;KAIA,OAAO,QAAQ,SAFb,QAAQ,UAAU,4CAEY,CAAC,KAAK,CAAC;IACzC;;GAGF,OAAO,EAAE,MAAM,QAAQ;EACzB;CACF;AACF;;;;;;AAOA,SAAS,QACP,QACA,QACA,SACkB;CAClB,IAAI,WAAW,SACb,OAAO;EAAE,MAAM;EAAS;EAAQ;CAAQ;CAG1C,OAAO;EAAE,MAAM;EAAQ;EAAQ;CAAQ;AACzC"}

package/esm/ai/src/guard/errors.mjs

@@ -1,18 +0,0 @@
-import { GuardrailViolationError } from "../errors/guardrail-violation-error.mjs";
-
-//#region ../@warlock.js/ai/src/guard/errors.ts
-/**
-* Curated install string thrown by the optional `moderation` detector on
-* first `check()` when the `openai` peer is absent. Mirrors ai-panoptic's
-* `LANGFUSE_INSTALL_INSTRUCTIONS`.
-*/
-const OPENAI_INSTALL_INSTRUCTIONS = `
-The @warlock.js/ai moderation detector requires the optional "openai" peer.
-Install it with:
-
-  npm install openai
-`.trim();
-
-//#endregion
-export { OPENAI_INSTALL_INSTRUCTIONS };
-//# sourceMappingURL=errors.mjs.map

package/esm/ai/src/guard/errors.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/guard/errors.ts"],"sourcesContent":["/**\n * Error surface for `@warlock.js/ai`.\n *\n * **No new error class.** A `block` verdict reuses the existing\n * `@warlock.js/ai` {@link GuardrailViolationError} verbatim — its category\n * (`\"guardrail\"`) and `phase` field already model exactly what a guard\n * needs, and `phase` is widened by this package to include `\"tool\"` (a\n * source-compatible third value). Re-exported here so the future `guard()`\n * factory has one import site for the typed abort it throws.\n *\n * The optional `moderation` detector's missing-peer failure is an\n * *infrastructure* fault, not a content violation, so it throws a plain\n * `Error` carrying {@link OPENAI_INSTALL_INSTRUCTIONS} (the langfuse-style\n * lazy-import pattern) rather than an `AIError`.\n */\nexport { GuardrailViolationError } from \"../errors/guardrail-violation-error\";\nexport type { GuardrailViolationErrorOptions } from \"../errors/guardrail-violation-error\";\n\n/**\n * Curated install string thrown by the optional `moderation` detector on\n * first `check()` when the `openai` peer is absent. Mirrors ai-panoptic's\n * `LANGFUSE_INSTALL_INSTRUCTIONS`.\n */\nexport const OPENAI_INSTALL_INSTRUCTIONS = `\nThe @warlock.js/ai moderation detector requires the optional \"openai\" peer.\nInstall it with:\n\n  npm install openai\n`.trim();\n"],"mappings":";;;;;;;;AAuBA,MAAa,8BAA8B;;;;;EAKzC,KAAK"}

package/esm/ai/src/guard/guard.mjs

@@ -1,209 +0,0 @@
-import { GuardrailViolationError } from "../errors/guardrail-violation-error.mjs";
-import { extractUserText } from "../middleware/utils/extract-user-text.mjs";
-import { forTool } from "../middleware/helpers/for-tool.mjs";
-import "./errors.mjs";
-
-//#region ../@warlock.js/ai/src/guard/guard.ts
-/** Default middleware name when the caller supplies none. */
-const DEFAULT_NAME = "guardrail";
-/**
-* The `ctx.state` key under which a guard records its `flag` verdicts. The
-* value is an append-only array of {@link FlagRecord}, namespaced by the
-* middleware name so two guards on the same agent never collide and a
-* downstream observer (panoptic, the caller) can read the annotations
-* post-run.
-*/
-function flagsKey(name) {
-	return `${name}.flags`;
-}
-/**
-* Append a `flag` record onto the namespaced `ctx.state` array, creating it
-* on first write. Never throws — recording is best-effort annotation.
-*/
-function recordFlag(ctx, name, record) {
-	const key = flagsKey(name);
-	const existing = ctx.state.get(key);
-	const flags = Array.isArray(existing) ? existing : [];
-	flags.push(record);
-	ctx.state.set(key, flags);
-}
-/**
-* Run a phase's detector array over `text`, in registration order, and fold
-* the verdicts into a single {@link PhaseOutcome}.
-*
-* **Short-circuit.** The first non-`allow`/non-`flag` verdict (a `redact` or
-* `block`) decides the outcome and stops the fold — outer detectors never run
-* after one objects, matching the install-array ordering. `flag` verdicts are
-* recorded into `ctx.state` and the fold continues (allow-but-annotate).
-*
-* **Phase-aware redact downgrade.** A `redact` verdict is only honoured where
-* the seam supports rewrite-and-continue:
-* - `"output"` — `trip.after` may return a replacement `ModelResponse`, so the
-*   rewritten text is threaded out.
-* - `"input"`  — the core `trip.before` hook can only short-circuit (return a
-*   response) or throw; it has **no** rewrite-and-continue seam, so an input
-*   `redact` is downgraded to a `block` rather than silently passing the
-*   un-redacted prompt through. (Documented on {@link GuardOptions.input}.)
-* - `"tool"`   — silently rewriting tool arguments changes the call's
-*   side-effects unpredictably, so a tool `redact` is downgraded to a `block`
-*   (`tool-arg-redaction-unsupported`) rather than mutating what the tool runs.
-*
-* **Fail-open on detector fault.** A detector's `check()` rejecting is an
-* infrastructure fault, not a content violation — it is recorded as a `flag`
-* (`<detector>.error`) and the fold continues, so a moderation-API outage does
-* not abort every agent run.
-*/
-async function runDetectors(detectors, text, phase, ctx, name) {
-	for (const detector of detectors) {
-		let verdict;
-		try {
-			verdict = await detector.check(text, {
-				phase,
-				ctx
-			});
-		} catch (error) {
-			recordFlag(ctx, name, {
-				detector: detector.name,
-				phase,
-				reason: `detector "${detector.name}" threw: ${error instanceof Error ? error.message : String(error)}`,
-				matches: []
-			});
-			continue;
-		}
-		if (verdict.type === "allow") continue;
-		if (verdict.type === "flag") {
-			recordFlag(ctx, name, {
-				detector: detector.name,
-				phase,
-				reason: verdict.reason,
-				matches: verdict.matches
-			});
-			continue;
-		}
-		if (verdict.type === "redact") {
-			if (phase === "output") return {
-				type: "redact",
-				text: verdict.text
-			};
-			return {
-				type: "block",
-				reason: phase === "tool" ? "tool-arg-redaction-unsupported" : verdict.reason,
-				matches: verdict.matches,
-				escalate: false
-			};
-		}
-		return {
-			type: "block",
-			reason: verdict.reason,
-			matches: verdict.matches,
-			escalate: verdict.escalate ?? false
-		};
-	}
-	return { type: "allow" };
-}
-/**
-* Realize a `block` outcome: fire the escalation seam (when the verdict asked
-* for it) and throw the typed {@link GuardrailViolationError} on `result.error`.
-* Never returns — always throws.
-*
-* The core `GuardrailViolationError.phase` is typed `"input" | "output"`; this
-* package widens the surfaced `phase` with `"tool"` (a source-compatible third
-* value), so the construction site asserts the wider value through the options
-* shape the error already accepts at runtime.
-*/
-async function block(outcome, phase, ctx, name, escalation) {
-	if (outcome.escalate) await escalation?.onBlock?.({
-		phase,
-		reason: outcome.reason,
-		matches: outcome.matches,
-		ctx
-	});
-	throw new GuardrailViolationError(`guardrail "${name}" rejected ${phase} — ${outcome.reason}`, {
-		phase,
-		reason: outcome.reason,
-		guardrail: name
-	});
-}
-/**
-* Build the composed **guardrail middleware** (surfaced as
-* `ai.guardrail(options)`) — one {@link AgentMiddleware} that runs the
-* configured detectors at three hook points and maps each
-* {@link GuardrailVerdict} onto the pipeline's throw / return / record
-* mechanics:
-*
-* - **`input`** detectors run at `trip.before` over the outbound prompt
-*   (`extractUserText(ctx.messages)`). `block` / `flag` only — the core
-*   `trip.before` seam cannot rewrite-and-continue, so a `redact` verdict here
-*   is downgraded to a `block`.
-* - **`output`** detectors run at `trip.after` over `response.content`. Full
-*   `allow` / `redact` / `block` / `flag` support — a `redact` returns a
-*   replacement `ModelResponse` with the rewritten `content`.
-* - **`tool`** detectors run at `tool.before` over `JSON.stringify(toolArgs)`.
-*   `block` / `flag`; a `redact` is downgraded to a `block`
-*   (`tool-arg-redaction-unsupported`). Scoped to `toolNames` via the core
-*   `forTool(toolNames, mw)` helper when set.
-*
-* **Verdict → action.** Detectors run in registration order; the first
-* `redact` / `block` short-circuits the phase. `block` throws a
-* {@link GuardrailViolationError} on `result.error` (never out of the
-* pipeline); `flag` records the match into `ctx.state` under `<name>.flags`
-* and continues; a `{ type: "block", escalate: true }` verdict awaits
-* `escalation.onBlock` before throwing. A detector that *throws* is treated as
-* an infra fault and fails open (recorded as a flag, run continues).
-*
-* @param options - The {@link GuardOptions}: per-phase detector arrays,
-*   optional `toolNames` scope, `escalation` seam, and `name` override.
-* @returns One {@link AgentMiddleware} to pass into `ai.agent({ middleware: [...] })`.
-*
-* @example
-* const policy = ai.guardrail({
-*   name: "compliance",
-*   input: [ai.guardrail.injection({ onMatch: "block" })],
-*   output: [ai.guardrail.pii({ onMatch: "redact", mask: "[REDACTED:{label}]" })],
-*   tool: [ai.guardrail.pii({ onMatch: "block" })],
-*   toolNames: ["send_email"],
-*   escalation: { async onBlock(e) { await reviewQueue.enqueue(e); } },
-* });
-*
-* const agent = ai.agent({ model, tools: [sendEmail], middleware: [policy] });
-*/
-function guard(options) {
-	const name = options.name ?? DEFAULT_NAME;
-	const input = options.input ?? [];
-	const output = options.output ?? [];
-	const tool = options.tool ?? [];
-	const escalation = options.escalation;
-	const middleware = {
-		name,
-		trip: {
-			async before(ctx) {
-				if (input.length === 0) return;
-				const prompt = extractUserText(ctx.messages);
-				if (!prompt) return;
-				const outcome = await runDetectors(input, prompt, "input", ctx, name);
-				if (outcome.type === "block") await block(outcome, "input", ctx, name, escalation);
-			},
-			async after(ctx, response) {
-				if (output.length === 0 || !response.content) return;
-				const outcome = await runDetectors(output, response.content, "output", ctx, name);
-				if (outcome.type === "block") await block(outcome, "output", ctx, name, escalation);
-				if (outcome.type === "redact") return {
-					...response,
-					content: outcome.text
-				};
-			}
-		}
-	};
-	if (tool.length > 0) middleware.tool = { async before(ctx) {
-		const args = JSON.stringify(ctx.request.input);
-		if (!args) return;
-		const outcome = await runDetectors(tool, args, "tool", ctx, name);
-		if (outcome.type === "block") await block(outcome, "tool", ctx, name, escalation);
-	} };
-	if (options.toolNames !== void 0 && middleware.tool) return forTool(options.toolNames, middleware);
-	return middleware;
-}
-
-//#endregion
-export { guard };
-//# sourceMappingURL=guard.mjs.map

package/esm/ai/src/guard/guard.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"guard.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/guard/guard.ts"],"sourcesContent":["import { extractUserText } from \"../middleware/utils/extract-user-text\";\nimport { forTool } from \"../middleware/helpers/for-tool\";\nimport type { AgentMiddleware } from \"../contracts/middleware/middleware.contract\";\nimport type {\n  MiddlewareToolContext,\n  MiddlewareTripContext,\n} from \"../contracts/middleware/middleware-context.type\";\nimport type { ModelResponse } from \"../contracts/model.contract\";\nimport type {\n  GuardOptions,\n  GuardrailDetector,\n  GuardrailEscalation,\n  GuardrailMatch,\n  GuardrailPhase,\n  GuardrailVerdict,\n} from \"./contracts\";\nimport { GuardrailViolationError } from \"./errors\";\n\n/** Default middleware name when the caller supplies none. */\nconst DEFAULT_NAME = \"guardrail\";\n\n/**\n * The `ctx.state` key under which a guard records its `flag` verdicts. The\n * value is an append-only array of {@link FlagRecord}, namespaced by the\n * middleware name so two guards on the same agent never collide and a\n * downstream observer (panoptic, the caller) can read the annotations\n * post-run.\n */\nfunction flagsKey(name: string): string {\n  return `${name}.flags`;\n}\n\n/**\n * One flagged match recorded into `ctx.state`. Mirrors the\n * {@link GuardrailVerdict} `flag` shape plus the phase it fired at, so an\n * observer can reconstruct *what* tripped *where* without re-running the\n * detector.\n */\nexport interface FlagRecord {\n  /** The detector that produced the flag. */\n  readonly detector: string;\n  /** Where the detector was running. */\n  readonly phase: GuardrailPhase;\n  /** The detector's human-readable reason. */\n  readonly reason: string;\n  /** The matches the detector recorded. */\n  readonly matches: readonly GuardrailMatch[];\n}\n\n/**\n * Append a `flag` record onto the namespaced `ctx.state` array, creating it\n * on first write. Never throws — recording is best-effort annotation.\n */\nfunction recordFlag(\n  ctx: MiddlewareTripContext,\n  name: string,\n  record: FlagRecord,\n): void {\n  const key = flagsKey(name);\n  const existing = ctx.state.get(key);\n  const flags = Array.isArray(existing) ? (existing as FlagRecord[]) : [];\n\n  flags.push(record);\n  ctx.state.set(key, flags);\n}\n\n/**\n * The outcome of folding a phase's detector array — what the hook should do\n * with the inspected text once every detector has had its say.\n *\n * - `allow`  — no detector objected; the hook continues untouched.\n * - `redact` — a detector returned rewritten `text`; the hook substitutes it\n *   (output / tool phases only — see {@link runDetectors}).\n * - `block`  — a detector rejected; the hook throws a\n *   {@link GuardrailViolationError} carrying `reason` / `matches` / `escalate`.\n *\n * `flag` verdicts never reach this type — they are recorded into `ctx.state`\n * as a side effect inside {@link runDetectors} and do not short-circuit the\n * fold, so a flagged-but-otherwise-clean run resolves to `allow`.\n */\ntype PhaseOutcome =\n  | { readonly type: \"allow\" }\n  | { readonly type: \"redact\"; readonly text: string }\n  | {\n      readonly type: \"block\";\n      readonly reason: string;\n      readonly matches?: readonly GuardrailMatch[];\n      readonly escalate: boolean;\n    };\n\n/**\n * Run a phase's detector array over `text`, in registration order, and fold\n * the verdicts into a single {@link PhaseOutcome}.\n *\n * **Short-circuit.** The first non-`allow`/non-`flag` verdict (a `redact` or\n * `block`) decides the outcome and stops the fold — outer detectors never run\n * after one objects, matching the install-array ordering. `flag` verdicts are\n * recorded into `ctx.state` and the fold continues (allow-but-annotate).\n *\n * **Phase-aware redact downgrade.** A `redact` verdict is only honoured where\n * the seam supports rewrite-and-continue:\n * - `\"output\"` — `trip.after` may return a replacement `ModelResponse`, so the\n *   rewritten text is threaded out.\n * - `\"input\"`  — the core `trip.before` hook can only short-circuit (return a\n *   response) or throw; it has **no** rewrite-and-continue seam, so an input\n *   `redact` is downgraded to a `block` rather than silently passing the\n *   un-redacted prompt through. (Documented on {@link GuardOptions.input}.)\n * - `\"tool\"`   — silently rewriting tool arguments changes the call's\n *   side-effects unpredictably, so a tool `redact` is downgraded to a `block`\n *   (`tool-arg-redaction-unsupported`) rather than mutating what the tool runs.\n *\n * **Fail-open on detector fault.** A detector's `check()` rejecting is an\n * infrastructure fault, not a content violation — it is recorded as a `flag`\n * (`<detector>.error`) and the fold continues, so a moderation-API outage does\n * not abort every agent run.\n */\nasync function runDetectors(\n  detectors: readonly GuardrailDetector[],\n  text: string,\n  phase: GuardrailPhase,\n  ctx: MiddlewareTripContext,\n  name: string,\n): Promise<PhaseOutcome> {\n  for (const detector of detectors) {\n    let verdict: GuardrailVerdict;\n\n    try {\n      verdict = await detector.check(text, { phase, ctx });\n    } catch (error) {\n      // Infra fault — fail open: record and continue, never abort the run.\n      recordFlag(ctx, name, {\n        detector: detector.name,\n        phase,\n        reason: `detector \"${detector.name}\" threw: ${\n          error instanceof Error ? error.message : String(error)\n        }`,\n        matches: [],\n      });\n\n      continue;\n    }\n\n    if (verdict.type === \"allow\") {\n      continue;\n    }\n\n    if (verdict.type === \"flag\") {\n      recordFlag(ctx, name, {\n        detector: detector.name,\n        phase,\n        reason: verdict.reason,\n        matches: verdict.matches,\n      });\n\n      continue;\n    }\n\n    if (verdict.type === \"redact\") {\n      if (phase === \"output\") {\n        return { type: \"redact\", text: verdict.text };\n      }\n\n      // Input / tool phases have no safe rewrite-and-continue seam — downgrade\n      // to a block so the un-redacted text is never threaded through.\n      const reason =\n        phase === \"tool\"\n          ? \"tool-arg-redaction-unsupported\"\n          : verdict.reason;\n\n      return {\n        type: \"block\",\n        reason,\n        matches: verdict.matches,\n        escalate: false,\n      };\n    }\n\n    // verdict.type === \"block\"\n    return {\n      type: \"block\",\n      reason: verdict.reason,\n      matches: verdict.matches,\n      escalate: verdict.escalate ?? false,\n    };\n  }\n\n  return { type: \"allow\" };\n}\n\n/**\n * Realize a `block` outcome: fire the escalation seam (when the verdict asked\n * for it) and throw the typed {@link GuardrailViolationError} on `result.error`.\n * Never returns — always throws.\n *\n * The core `GuardrailViolationError.phase` is typed `\"input\" | \"output\"`; this\n * package widens the surfaced `phase` with `\"tool\"` (a source-compatible third\n * value), so the construction site asserts the wider value through the options\n * shape the error already accepts at runtime.\n */\nasync function block(\n  outcome: Extract<PhaseOutcome, { type: \"block\" }>,\n  phase: GuardrailPhase,\n  ctx: MiddlewareTripContext,\n  name: string,\n  escalation: GuardrailEscalation | undefined,\n): Promise<never> {\n  if (outcome.escalate) {\n    await escalation?.onBlock?.({\n      phase,\n      reason: outcome.reason,\n      matches: outcome.matches,\n      ctx,\n    });\n  }\n\n  throw new GuardrailViolationError(\n    `guardrail \"${name}\" rejected ${phase} — ${outcome.reason}`,\n    {\n      // `phase` is widened to include \"tool\"; the error carries it verbatim.\n      phase: phase as \"input\" | \"output\",\n      reason: outcome.reason,\n      guardrail: name,\n    },\n  );\n}\n\n/**\n * Build the composed **guardrail middleware** (surfaced as\n * `ai.guardrail(options)`) — one {@link AgentMiddleware} that runs the\n * configured detectors at three hook points and maps each\n * {@link GuardrailVerdict} onto the pipeline's throw / return / record\n * mechanics:\n *\n * - **`input`** detectors run at `trip.before` over the outbound prompt\n *   (`extractUserText(ctx.messages)`). `block` / `flag` only — the core\n *   `trip.before` seam cannot rewrite-and-continue, so a `redact` verdict here\n *   is downgraded to a `block`.\n * - **`output`** detectors run at `trip.after` over `response.content`. Full\n *   `allow` / `redact` / `block` / `flag` support — a `redact` returns a\n *   replacement `ModelResponse` with the rewritten `content`.\n * - **`tool`** detectors run at `tool.before` over `JSON.stringify(toolArgs)`.\n *   `block` / `flag`; a `redact` is downgraded to a `block`\n *   (`tool-arg-redaction-unsupported`). Scoped to `toolNames` via the core\n *   `forTool(toolNames, mw)` helper when set.\n *\n * **Verdict → action.** Detectors run in registration order; the first\n * `redact` / `block` short-circuits the phase. `block` throws a\n * {@link GuardrailViolationError} on `result.error` (never out of the\n * pipeline); `flag` records the match into `ctx.state` under `<name>.flags`\n * and continues; a `{ type: \"block\", escalate: true }` verdict awaits\n * `escalation.onBlock` before throwing. A detector that *throws* is treated as\n * an infra fault and fails open (recorded as a flag, run continues).\n *\n * @param options - The {@link GuardOptions}: per-phase detector arrays,\n *   optional `toolNames` scope, `escalation` seam, and `name` override.\n * @returns One {@link AgentMiddleware} to pass into `ai.agent({ middleware: [...] })`.\n *\n * @example\n * const policy = ai.guardrail({\n *   name: \"compliance\",\n *   input: [ai.guardrail.injection({ onMatch: \"block\" })],\n *   output: [ai.guardrail.pii({ onMatch: \"redact\", mask: \"[REDACTED:{label}]\" })],\n *   tool: [ai.guardrail.pii({ onMatch: \"block\" })],\n *   toolNames: [\"send_email\"],\n *   escalation: { async onBlock(e) { await reviewQueue.enqueue(e); } },\n * });\n *\n * const agent = ai.agent({ model, tools: [sendEmail], middleware: [policy] });\n */\nexport function guard(options: GuardOptions): AgentMiddleware {\n  const name = options.name ?? DEFAULT_NAME;\n  const input = options.input ?? [];\n  const output = options.output ?? [];\n  const tool = options.tool ?? [];\n  const escalation = options.escalation;\n\n  const middleware: AgentMiddleware = {\n    name,\n    trip: {\n      async before(ctx: MiddlewareTripContext): Promise<void> {\n        if (input.length === 0) {\n          return;\n        }\n\n        const prompt = extractUserText(ctx.messages);\n\n        if (!prompt) {\n          return;\n        }\n\n        const outcome = await runDetectors(input, prompt, \"input\", ctx, name);\n\n        if (outcome.type === \"block\") {\n          await block(outcome, \"input\", ctx, name, escalation);\n        }\n\n        // `allow` (incl. any recorded flags) and a downgraded-but-impossible\n        // input `redact` (already mapped to block above) fall through — the\n        // real model call proceeds with the un-mutated prompt.\n      },\n      async after(\n        ctx: MiddlewareTripContext,\n        response: ModelResponse,\n      ): Promise<void | ModelResponse> {\n        if (output.length === 0 || !response.content) {\n          return;\n        }\n\n        const outcome = await runDetectors(\n          output,\n          response.content,\n          \"output\",\n          ctx,\n          name,\n        );\n\n        if (outcome.type === \"block\") {\n          await block(outcome, \"output\", ctx, name, escalation);\n        }\n\n        if (outcome.type === \"redact\") {\n          // `trip.after` may return a replacement response — thread the\n          // rewritten content back so the caller never sees the original.\n          return { ...response, content: outcome.text };\n        }\n\n        return;\n      },\n    },\n  };\n\n  // Only declare the `tool` hook map when there are tool detectors — an empty\n  // `tool` array would otherwise make `forTool` scoping a no-op cost.\n  if (tool.length > 0) {\n    middleware.tool = {\n      async before(ctx: MiddlewareToolContext): Promise<void> {\n        const args = JSON.stringify(ctx.request.input);\n\n        if (!args) {\n          return;\n        }\n\n        const outcome = await runDetectors(tool, args, \"tool\", ctx, name);\n\n        if (outcome.type === \"block\") {\n          await block(outcome, \"tool\", ctx, name, escalation);\n        }\n\n        // A tool `redact` is downgraded to `block` inside `runDetectors`, so\n        // `redact` is unreachable here; `allow`/`flag` fall through and the\n        // real tool dispatch proceeds.\n      },\n    };\n  }\n\n  // Scope the `tool` hooks to the named tools when requested — `forTool`\n  // leaves `trip` hooks untouched, so input/output detectors still fire for\n  // every trip regardless of which tool is being dispatched.\n  if (options.toolNames !== undefined && middleware.tool) {\n    return forTool(options.toolNames, middleware);\n  }\n\n  return middleware;\n}\n"],"mappings":"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"}

package/esm/ai/src/guard/guardrail.mjs

@@ -1,22 +0,0 @@
-import { injection } from "./detectors/injection.mjs";
-import { pii } from "./detectors/pii.mjs";
-import { topic } from "./detectors/topic.mjs";
-import { moderation } from "./detectors/moderation.mjs";
-import "./detectors/index.mjs";
-import { guard } from "./guard.mjs";
-
-//#region ../@warlock.js/ai/src/guard/guardrail.ts
-/**
-* The `ai.guardrail` value: the {@link guard} factory with the detector
-* factories assigned onto it. Built once and shared.
-*/
-const guardrail = Object.assign(guard, {
-	pii,
-	topic,
-	injection,
-	moderation
-});
-
-//#endregion
-export { guardrail };
-//# sourceMappingURL=guardrail.mjs.map

package/esm/ai/src/guard/guardrail.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"guardrail.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/guard/guardrail.ts"],"sourcesContent":["import type { AgentMiddleware } from \"../contracts/middleware/middleware.contract\";\nimport type {\n  GuardOptions,\n  GuardrailDetector,\n  InjectionDetectorOptions,\n  OpenAiModerationOptions,\n  PiiDetectorOptions,\n  TopicFilterOptions,\n} from \"./contracts\";\nimport { injection, moderation, pii, topic } from \"./detectors\";\nimport { guard } from \"./guard\";\n\n/**\n * The callable `ai.guardrail` surface — the {@link guard} factory with the\n * built-in detector factories attached as methods, so the whole guardrail\n * vocabulary lives under one name:\n *\n * - `ai.guardrail(options)` — build the composed middleware.\n * - `ai.guardrail.pii(o?)` / `.topic(o)` / `.injection(o?)` / `.moderation(o?)`\n *   — build a detector to pass into the factory's `input` / `output` / `tool`\n *   arrays.\n *\n * @example\n * const policy = ai.guardrail({\n *   output: [ai.guardrail.pii({ onMatch: \"redact\" })],\n * });\n */\nexport interface GuardrailFactory {\n  /** Build the composed guardrail {@link AgentMiddleware}. */\n  (options: GuardOptions): AgentMiddleware;\n  /** Built-in PII detector (regex + dictionary, zero runtime dep). */\n  pii(options?: PiiDetectorOptions): GuardrailDetector;\n  /** Built-in topic filter (allow / deny string | RegExp lists). */\n  topic(options: TopicFilterOptions): GuardrailDetector;\n  /** Built-in jailbreak / prompt-injection marker detector. */\n  injection(options?: InjectionDetectorOptions): GuardrailDetector;\n  /** Optional OpenAI-backed moderation detector (lazy `openai` peer). */\n  moderation(options?: OpenAiModerationOptions): GuardrailDetector;\n}\n\n/**\n * The `ai.guardrail` value: the {@link guard} factory with the detector\n * factories assigned onto it. Built once and shared.\n */\nexport const guardrail: GuardrailFactory = Object.assign(guard, {\n  pii,\n  topic,\n  injection,\n  moderation,\n});\n\n// `ai.guardrail` is registered natively on the core `ai` object (in `../ai`),\n// now that the guardrail suite ships inside `@warlock.js/ai`.\n"],"mappings":";;;;;;;;;;;;AA4CA,MAAa,YAA8B,OAAO,OAAO,OAAO;CAC9D;CACA;CACA;CACA;AACF,CAAC"}

package/esm/ai/src/human/errors.mjs

@@ -1,60 +0,0 @@
-import { AIError } from "../errors/ai-error.mjs";
-
-//#region ../@warlock.js/ai/src/human/errors.ts
-/**
-* A durable approval handler suspended the run rather than denying the
-* call.
-*
-* **Role.** The sentinel a durable {@link import("./contracts").ApprovalHandler}
-* throws after persisting a
-* {@link import("./contracts").PendingInterrupt}. The approval
-* middleware recognizes its own sentinel (an `instanceof` check) and
-* re-throws so the agent run unwinds; the dispatch records it as a failed
-* tool call carrying this typed error. The caller reads
-* `error.interruptId` off the surfaced `result.error`, surfaces it to the
-* reviewer, and later calls `ai.human.resume(...)`.
-*
-* Surfaced via `result.error` like every other `AIError` — the middleware
-* never lets it escape `execute()`.
-*
-* @example
-* if (result.error instanceof InterruptSuspendedError) {
-*   await notifyReviewer(result.error.interruptId);
-*   return { status: "awaiting-approval", interruptId: result.error.interruptId };
-* }
-*/
-var InterruptSuspendedError = class extends AIError {
-	constructor(message, options) {
-		super("INTERRUPT_SUSPENDED", message, options);
-		this.name = "InterruptSuspendedError";
-		this.interruptId = options.interruptId;
-	}
-};
-/**
-* A human rejected a gated tool call.
-*
-* **Role.** The typed result of an `{ type: "reject", reason }` decision.
-* The approval middleware throws it from `tool.before`; the agent
-* dispatch records a failed tool call and writes a `role: "tool"`
-* message carrying `reason`, so the **next trip lets the model
-* self-correct** — exactly the existing tool-error feedback path.
-*
-* Surfaced via `result.error` like every other `AIError`.
-*
-* @example
-* if (result.error instanceof ApprovalRejectedError) {
-*   logAudit(`${result.error.toolName} rejected: ${result.error.reason}`);
-* }
-*/
-var ApprovalRejectedError = class extends AIError {
-	constructor(message, options) {
-		super("APPROVAL_REJECTED", message, options);
-		this.name = "ApprovalRejectedError";
-		this.reason = options.reason;
-		this.toolName = options.toolName;
-	}
-};
-
-//#endregion
-export { ApprovalRejectedError, InterruptSuspendedError };
-//# sourceMappingURL=errors.mjs.map

package/esm/ai/src/human/errors.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/human/errors.ts"],"sourcesContent":["import { AIError, type AIErrorOptions } from \"../errors/ai-error\";\nimport type { AIErrorCode } from \"../errors/error-code.type\";\n\n/**\n * Stable, machine-readable codes this package raises.\n *\n * `@warlock.js/ai`'s `AIErrorCode` is a closed union that (by design)\n * does not enumerate satellite-package codes, and this package must not\n * modify the core union. These codes are therefore declared locally and\n * narrowed into the base `AIError` `code` slot at the single `super(...)`\n * call — the runtime string is exactly what a consumer branches on via\n * `error.code`, identical to every other `AIError`.\n */\nexport type HumanErrorCode = \"INTERRUPT_SUSPENDED\" | \"APPROVAL_REJECTED\";\n\n/**\n * Payload for {@link InterruptSuspendedError}. `interruptId` is the key a\n * later `ai.human.resume(interruptId, decision)` call uses to replay the\n * decision against the persisted interrupt.\n */\nexport type InterruptSuspendedErrorOptions = AIErrorOptions & {\n  /** Id of the persisted interrupt awaiting a decision. */\n  interruptId: string;\n};\n\n/**\n * A durable approval handler suspended the run rather than denying the\n * call.\n *\n * **Role.** The sentinel a durable {@link import(\"./contracts\").ApprovalHandler}\n * throws after persisting a\n * {@link import(\"./contracts\").PendingInterrupt}. The approval\n * middleware recognizes its own sentinel (an `instanceof` check) and\n * re-throws so the agent run unwinds; the dispatch records it as a failed\n * tool call carrying this typed error. The caller reads\n * `error.interruptId` off the surfaced `result.error`, surfaces it to the\n * reviewer, and later calls `ai.human.resume(...)`.\n *\n * Surfaced via `result.error` like every other `AIError` — the middleware\n * never lets it escape `execute()`.\n *\n * @example\n * if (result.error instanceof InterruptSuspendedError) {\n *   await notifyReviewer(result.error.interruptId);\n *   return { status: \"awaiting-approval\", interruptId: result.error.interruptId };\n * }\n */\nexport class InterruptSuspendedError extends AIError {\n  /** Id of the persisted interrupt awaiting a human decision. */\n  public readonly interruptId: string;\n\n  public constructor(message: string, options: InterruptSuspendedErrorOptions) {\n    super(\"INTERRUPT_SUSPENDED\" as AIErrorCode, message, options);\n\n    this.name = \"InterruptSuspendedError\";\n    this.interruptId = options.interruptId;\n  }\n}\n\n/**\n * Payload for {@link ApprovalRejectedError}. `reason` is the reviewer's\n * explanation, surfaced to the model on the next trip so it can\n * self-correct; `toolName` names the call that was rejected.\n */\nexport type ApprovalRejectedErrorOptions = AIErrorOptions & {\n  /** The reviewer's explanation for rejecting the call. */\n  reason: string;\n  /** Name of the tool whose call was rejected. */\n  toolName: string;\n};\n\n/**\n * A human rejected a gated tool call.\n *\n * **Role.** The typed result of an `{ type: \"reject\", reason }` decision.\n * The approval middleware throws it from `tool.before`; the agent\n * dispatch records a failed tool call and writes a `role: \"tool\"`\n * message carrying `reason`, so the **next trip lets the model\n * self-correct** — exactly the existing tool-error feedback path.\n *\n * Surfaced via `result.error` like every other `AIError`.\n *\n * @example\n * if (result.error instanceof ApprovalRejectedError) {\n *   logAudit(`${result.error.toolName} rejected: ${result.error.reason}`);\n * }\n */\nexport class ApprovalRejectedError extends AIError {\n  /** The reviewer's explanation for rejecting the call. */\n  public readonly reason: string;\n\n  /** Name of the tool whose call was rejected. */\n  public readonly toolName: string;\n\n  public constructor(message: string, options: ApprovalRejectedErrorOptions) {\n    super(\"APPROVAL_REJECTED\" as AIErrorCode, message, options);\n\n    this.name = \"ApprovalRejectedError\";\n    this.reason = options.reason;\n    this.toolName = options.toolName;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AA+CA,IAAa,0BAAb,cAA6C,QAAQ;CAInD,AAAO,YAAY,SAAiB,SAAyC;EAC3E,MAAM,uBAAsC,SAAS,OAAO;EAE5D,KAAK,OAAO;EACZ,KAAK,cAAc,QAAQ;CAC7B;AACF;;;;;;;;;;;;;;;;;AA8BA,IAAa,wBAAb,cAA2C,QAAQ;CAOjD,AAAO,YAAY,SAAiB,SAAuC;EACzE,MAAM,qBAAoC,SAAS,OAAO;EAE1D,KAAK,OAAO;EACZ,KAAK,SAAS,QAAQ;EACtB,KAAK,WAAW,QAAQ;CAC1B;AACF"}

package/esm/ai/src/human/human-approval.mjs

@@ -1,170 +0,0 @@
-import { generateRunId } from "../utils/generate-run-id.mjs";
-import { ApprovalRejectedError, InterruptSuspendedError } from "./errors.mjs";
-import { evaluatePolicy } from "./policy.mjs";
-import { takeSeededDecision } from "./resume-seed.mjs";
-
-//#region ../@warlock.js/ai/src/human/human-approval.ts
-/** Default middleware name when {@link HumanApprovalOptions.name} is omitted. */
-const DEFAULT_NAME = "human-approval";
-/** Zero usage for a synthetic, no-LLM-spend short-circuit result. */
-const ZERO_USAGE = Object.freeze({
-	input: 0,
-	output: 0,
-	total: 0
-});
-/**
-* Derive the read-only {@link PolicyContext} the policy + request are
-* built from out of the wrapping {@link MiddlewareToolContext}.
-*/
-function toPolicyContext(ctx) {
-	return {
-		toolName: ctx.tool.name,
-		toolDescription: ctx.tool.description,
-		args: ctx.request.input,
-		agentName: ctx.agent.name,
-		tripIndex: ctx.tripIndex,
-		sessionId: ctx.options?.sessionId
-	};
-}
-/**
-* Generate a stable, unique id for a pending interrupt. Shaped
-* `${agentName}.${sessionId ?? "nosession"}.${tripIndex}.${random}` so a
-* reviewer can eyeball the originating run, while the trailing random
-* segment guarantees per-call uniqueness even within one trip.
-*/
-function makeInterruptId(ctx) {
-	const session = ctx.options?.sessionId ?? "nosession";
-	const random = generateRunId("interrupt");
-	return `${ctx.agent.name}.${session}.${ctx.tripIndex}.${random}`;
-}
-/**
-* Build the {@link ApprovalRequest} a human rules on, from the tool
-* context and the policy-derived tags.
-*/
-function buildRequest(ctx, interruptId, tags) {
-	return {
-		interruptId,
-		toolName: ctx.tool.name,
-		toolDescription: ctx.tool.description,
-		args: ctx.request.input,
-		context: {
-			agentName: ctx.agent.name,
-			tripIndex: ctx.tripIndex,
-			sessionId: ctx.options?.sessionId,
-			originalInput: ctx.input,
-			...tags ? { tags } : {}
-		},
-		requestedAt: (/* @__PURE__ */ new Date()).toISOString()
-	};
-}
-/**
-* Synthesize a failed {@link ToolInvokeResult} carrying a typed error.
-*
-* The approval middleware returns this from `tool.before` to
-* **short-circuit** the real tool without throwing: the pipeline treats a
-* defined return as the tool's result, the agent records a failed
-* `ToolCall`, and the model sees `{ error }` on the next trip — exactly
-* the existing tool-error feedback path. Used for both `reject`
-* (`ApprovalRejectedError`) and durable suspend (`InterruptSuspendedError`).
-*/
-function failedResult(error, toolName) {
-	const runId = generateRunId("tool");
-	const nowIso = (/* @__PURE__ */ new Date()).toISOString();
-	return {
-		error,
-		usage: ZERO_USAGE,
-		report: {
-			runId,
-			rootRunId: runId,
-			name: toolName,
-			type: "tool",
-			status: "failed",
-			startedAt: nowIso,
-			endedAt: nowIso,
-			duration: 0,
-			usage: ZERO_USAGE,
-			children: []
-		}
-	};
-}
-/**
-* Human-in-the-loop approval gate for an agent's tool calls — the
-* middleware behind `ai.human.approval(options)`.
-*
-* **Role.** Pauses *before a specific tool call* and routes it to a human
-* who can **approve** (run the real tool unchanged), **reject** (the model
-* sees a typed error and self-corrects), or **edit** (run the tool with
-* reviewer-replaced args). The dangerous subset is chosen by an
-* {@link import("./contracts").InterruptPolicy} (allowlist / denylist /
-* predicate); every other call passes through untouched.
-*
-* **One hook.** Declares only `tool.before`. On each tool dispatch it:
-* 1. evaluates the policy — not gated → returns `void`, the real tool runs;
-* 2. for a gated call, builds an {@link ApprovalRequest} and calls the
-*    {@link import("./contracts").ApprovalHandler};
-* 3. applies the returned {@link ApprovalDecision}:
-*    - `approve` → returns `void`, the real tool runs;
-*    - `reject` → short-circuits a failed `ToolInvokeResult` carrying an
-*      {@link ApprovalRejectedError} (the reviewer's `reason` reaches the
-*      model);
-*    - `edit` → rewrites `ctx.request.input` to the reviewer's args and
-*      returns `void`, so the real tool runs with the edited args (schema
-*      validation still applies — bad edits surface as a tool error).
-*
-* **Durable mode.** When a `store` is configured and the handler throws
-* {@link InterruptSuspendedError} (after persisting the interrupt
-* out-of-band), the middleware catches its **own** sentinel and
-* short-circuits a failed result carrying it — so the caller reads
-* `result.error.interruptId` and later calls
-* `ai.human.resume(interruptId, decision)`. The middleware **never throws
-* out of the pipeline**: every outcome (skip, approve, reject, edit,
-* suspend) returns normally; only a *handler bug* (a non-sentinel throw)
-* propagates, and even then the agent dispatch funnels it onto
-* `result.error` — `execute()` still never throws.
-*
-* @param options - Policy, handler, optional durable store, optional name.
-* @returns An {@link AgentMiddleware} declaring a single `tool.before` hook.
-*
-* @example
-* const support = ai.agent({
-*   model,
-*   tools: [refundCustomer],
-*   middleware: [
-*     humanApproval({
-*       policy: { type: "allowlist", tools: ["refundCustomer"], tags: () => ["money"] },
-*       handler: async (req) => ui.prompt(req), // { type: "edit", args: { amount: 5 } }
-*     }),
-*   ],
-* });
-*/
-function humanApproval(options) {
-	const name = options.name ?? DEFAULT_NAME;
-	const { policy, handler } = options;
-	return {
-		name,
-		tool: { async before(ctx) {
-			const verdict = evaluatePolicy(policy, toPolicyContext(ctx));
-			if (!verdict.requiresApproval) return;
-			const request = buildRequest(ctx, makeInterruptId(ctx), verdict.tags);
-			const seeded = takeSeededDecision(ctx.agent.name);
-			let decision;
-			if (seeded !== void 0) decision = seeded;
-			else try {
-				decision = await handler(request);
-			} catch (thrown) {
-				if (thrown instanceof InterruptSuspendedError) return failedResult(thrown, ctx.tool.name);
-				throw thrown;
-			}
-			if (decision.type === "approve") return;
-			if (decision.type === "reject") return failedResult(new ApprovalRejectedError(`Tool call "${ctx.tool.name}" rejected by reviewer — ${decision.reason}`, {
-				reason: decision.reason,
-				toolName: ctx.tool.name
-			}), ctx.tool.name);
-			ctx.request.input = decision.args;
-		} }
-	};
-}
-
-//#endregion
-export { humanApproval };
-//# sourceMappingURL=human-approval.mjs.map