@warlock.js/core 4.4.0 → 4.6.0

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

@@ -0,0 +1,209 @@
+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

@@ -0,0 +1 @@
+{"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":";;;;;;;AAmBA,MAAM,eAAe;;;;;;;;AASrB,SAAS,SAAS,MAAsB;CACtC,OAAO,GAAG,KAAK;AACjB;;;;;AAuBA,SAAS,WACP,KACA,MACA,QACM;CACN,MAAM,MAAM,SAAS,IAAI;CACzB,MAAM,WAAW,IAAI,MAAM,IAAI,GAAG;CAClC,MAAM,QAAQ,MAAM,QAAQ,QAAQ,IAAK,WAA4B,CAAC;CAEtE,MAAM,KAAK,MAAM;CACjB,IAAI,MAAM,IAAI,KAAK,KAAK;AAC1B;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,eAAe,aACb,WACA,MACA,OACA,KACA,MACuB;CACvB,KAAK,MAAM,YAAY,WAAW;EAChC,IAAI;EAEJ,IAAI;GACF,UAAU,MAAM,SAAS,MAAM,MAAM;IAAE;IAAO;GAAI,CAAC;EACrD,SAAS,OAAO;GAEd,WAAW,KAAK,MAAM;IACpB,UAAU,SAAS;IACnB;IACA,QAAQ,aAAa,SAAS,KAAK,WACjC,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;IAEvD,SAAS,CAAC;GACZ,CAAC;GAED;EACF;EAEA,IAAI,QAAQ,SAAS,SACnB;EAGF,IAAI,QAAQ,SAAS,QAAQ;GAC3B,WAAW,KAAK,MAAM;IACpB,UAAU,SAAS;IACnB;IACA,QAAQ,QAAQ;IAChB,SAAS,QAAQ;GACnB,CAAC;GAED;EACF;EAEA,IAAI,QAAQ,SAAS,UAAU;GAC7B,IAAI,UAAU,UACZ,OAAO;IAAE,MAAM;IAAU,MAAM,QAAQ;GAAK;GAU9C,OAAO;IACL,MAAM;IACN,QANA,UAAU,SACN,mCACA,QAAQ;IAKZ,SAAS,QAAQ;IACjB,UAAU;GACZ;EACF;EAGA,OAAO;GACL,MAAM;GACN,QAAQ,QAAQ;GAChB,SAAS,QAAQ;GACjB,UAAU,QAAQ,YAAY;EAChC;CACF;CAEA,OAAO,EAAE,MAAM,QAAQ;AACzB;;;;;;;;;;;AAYA,eAAe,MACb,SACA,OACA,KACA,MACA,YACgB;CAChB,IAAI,QAAQ,UACV,MAAM,YAAY,UAAU;EAC1B;EACA,QAAQ,QAAQ;EAChB,SAAS,QAAQ;EACjB;CACF,CAAC;CAGH,MAAM,IAAI,wBACR,cAAc,KAAK,aAAa,MAAM,KAAK,QAAQ,UACnD;EAES;EACP,QAAQ,QAAQ;EAChB,WAAW;CACb,CACF;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,SAAgB,MAAM,SAAwC;CAC5D,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,QAAQ,QAAQ,SAAS,CAAC;CAChC,MAAM,SAAS,QAAQ,UAAU,CAAC;CAClC,MAAM,OAAO,QAAQ,QAAQ,CAAC;CAC9B,MAAM,aAAa,QAAQ;CAE3B,MAAM,aAA8B;EAClC;EACA,MAAM;GACJ,MAAM,OAAO,KAA2C;IACtD,IAAI,MAAM,WAAW,GACnB;IAGF,MAAM,SAAS,gBAAgB,IAAI,QAAQ;IAE3C,IAAI,CAAC,QACH;IAGF,MAAM,UAAU,MAAM,aAAa,OAAO,QAAQ,SAAS,KAAK,IAAI;IAEpE,IAAI,QAAQ,SAAS,SACnB,MAAM,MAAM,SAAS,SAAS,KAAK,MAAM,UAAU;GAMvD;GACA,MAAM,MACJ,KACA,UAC+B;IAC/B,IAAI,OAAO,WAAW,KAAK,CAAC,SAAS,SACnC;IAGF,MAAM,UAAU,MAAM,aACpB,QACA,SAAS,SACT,UACA,KACA,IACF;IAEA,IAAI,QAAQ,SAAS,SACnB,MAAM,MAAM,SAAS,UAAU,KAAK,MAAM,UAAU;IAGtD,IAAI,QAAQ,SAAS,UAGnB,OAAO;KAAE,GAAG;KAAU,SAAS,QAAQ;IAAK;GAIhD;EACF;CACF;CAIA,IAAI,KAAK,SAAS,GAChB,WAAW,OAAO,EAChB,MAAM,OAAO,KAA2C;EACtD,MAAM,OAAO,KAAK,UAAU,IAAI,QAAQ,KAAK;EAE7C,IAAI,CAAC,MACH;EAGF,MAAM,UAAU,MAAM,aAAa,MAAM,MAAM,QAAQ,KAAK,IAAI;EAEhE,IAAI,QAAQ,SAAS,SACnB,MAAM,MAAM,SAAS,QAAQ,KAAK,MAAM,UAAU;CAMtD,EACF;CAMF,IAAI,QAAQ,cAAc,UAAa,WAAW,MAChD,OAAO,QAAQ,QAAQ,WAAW,UAAU;CAG9C,OAAO;AACT"}

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

@@ -0,0 +1,22 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,60 @@
+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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,170 @@
+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

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

@@ -0,0 +1 @@
+{"version":3,"file":"human-approval.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/human/human-approval.ts"],"sourcesContent":["import type { AgentMiddleware } from \"../contracts/middleware/middleware.contract\";\nimport type { MiddlewareToolContext } from \"../contracts/middleware/middleware-context.type\";\nimport type { BaseReport } from \"../contracts/result/base-report.type\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport type { AIError } from \"../errors/ai-error\";\nimport type { ToolInvokeResult } from \"../tool/tool\";\nimport { generateRunId } from \"../utils/generate-run-id\";\nimport type {\n  ApprovalDecision,\n  ApprovalRequest,\n  HumanApprovalOptions,\n  PolicyContext,\n} from \"./contracts\";\nimport { ApprovalRejectedError, InterruptSuspendedError } from \"./errors\";\nimport { evaluatePolicy } from \"./policy\";\nimport { takeSeededDecision } from \"./resume-seed\";\n\n/** Default middleware name when {@link HumanApprovalOptions.name} is omitted. */\nconst DEFAULT_NAME = \"human-approval\";\n\n/** Zero usage for a synthetic, no-LLM-spend short-circuit result. */\nconst ZERO_USAGE: Usage = Object.freeze({ input: 0, output: 0, total: 0 });\n\n/**\n * Mutable view of {@link MiddlewareToolContext.request} used only to\n * apply an `edit` decision. The context types `request.input` as\n * `readonly`, but the agent dispatch reads `request.input` (the SAME\n * object) when it invokes the real tool *after* the `tool.before`\n * pipeline returns — so reassigning it here is how an edited-args\n * decision reaches the tool. This narrow local type makes that one\n * deliberate write explicit instead of casting away the whole context.\n */\ninterface MutableToolRequest {\n  input: unknown;\n}\n\n/**\n * Derive the read-only {@link PolicyContext} the policy + request are\n * built from out of the wrapping {@link MiddlewareToolContext}.\n */\nfunction toPolicyContext(ctx: MiddlewareToolContext): PolicyContext {\n  return {\n    toolName: ctx.tool.name,\n    toolDescription: ctx.tool.description,\n    args: ctx.request.input,\n    agentName: ctx.agent.name,\n    tripIndex: ctx.tripIndex,\n    sessionId: ctx.options?.sessionId,\n  };\n}\n\n/**\n * Generate a stable, unique id for a pending interrupt. Shaped\n * `${agentName}.${sessionId ?? \"nosession\"}.${tripIndex}.${random}` so a\n * reviewer can eyeball the originating run, while the trailing random\n * segment guarantees per-call uniqueness even within one trip.\n */\nfunction makeInterruptId(ctx: MiddlewareToolContext): string {\n  const session = ctx.options?.sessionId ?? \"nosession\";\n  const random = generateRunId(\"interrupt\");\n\n  return `${ctx.agent.name}.${session}.${ctx.tripIndex}.${random}`;\n}\n\n/**\n * Build the {@link ApprovalRequest} a human rules on, from the tool\n * context and the policy-derived tags.\n */\nfunction buildRequest(\n  ctx: MiddlewareToolContext,\n  interruptId: string,\n  tags: string[] | undefined,\n): ApprovalRequest {\n  return {\n    interruptId,\n    toolName: ctx.tool.name,\n    toolDescription: ctx.tool.description,\n    args: ctx.request.input,\n    context: {\n      agentName: ctx.agent.name,\n      tripIndex: ctx.tripIndex,\n      sessionId: ctx.options?.sessionId,\n      originalInput: ctx.input,\n      ...(tags ? { tags } : {}),\n    },\n    requestedAt: new Date().toISOString(),\n  };\n}\n\n/**\n * Synthesize a failed {@link ToolInvokeResult} carrying a typed error.\n *\n * The approval middleware returns this from `tool.before` to\n * **short-circuit** the real tool without throwing: the pipeline treats a\n * defined return as the tool's result, the agent records a failed\n * `ToolCall`, and the model sees `{ error }` on the next trip — exactly\n * the existing tool-error feedback path. Used for both `reject`\n * (`ApprovalRejectedError`) and durable suspend (`InterruptSuspendedError`).\n */\nfunction failedResult(error: AIError, toolName: string): ToolInvokeResult<unknown> {\n  const runId = generateRunId(\"tool\");\n  const nowIso = new Date().toISOString();\n\n  const report: BaseReport = {\n    runId,\n    rootRunId: runId,\n    name: toolName,\n    type: \"tool\",\n    status: \"failed\",\n    startedAt: nowIso,\n    endedAt: nowIso,\n    duration: 0,\n    usage: ZERO_USAGE,\n    children: [],\n  };\n\n  return { error, usage: ZERO_USAGE, report };\n}\n\n/**\n * Human-in-the-loop approval gate for an agent's tool calls — the\n * middleware behind `ai.human.approval(options)`.\n *\n * **Role.** Pauses *before a specific tool call* and routes it to a human\n * who can **approve** (run the real tool unchanged), **reject** (the model\n * sees a typed error and self-corrects), or **edit** (run the tool with\n * reviewer-replaced args). The dangerous subset is chosen by an\n * {@link import(\"./contracts\").InterruptPolicy} (allowlist / denylist /\n * predicate); every other call passes through untouched.\n *\n * **One hook.** Declares only `tool.before`. On each tool dispatch it:\n * 1. evaluates the policy — not gated → returns `void`, the real tool runs;\n * 2. for a gated call, builds an {@link ApprovalRequest} and calls the\n *    {@link import(\"./contracts\").ApprovalHandler};\n * 3. applies the returned {@link ApprovalDecision}:\n *    - `approve` → returns `void`, the real tool runs;\n *    - `reject` → short-circuits a failed `ToolInvokeResult` carrying an\n *      {@link ApprovalRejectedError} (the reviewer's `reason` reaches the\n *      model);\n *    - `edit` → rewrites `ctx.request.input` to the reviewer's args and\n *      returns `void`, so the real tool runs with the edited args (schema\n *      validation still applies — bad edits surface as a tool error).\n *\n * **Durable mode.** When a `store` is configured and the handler throws\n * {@link InterruptSuspendedError} (after persisting the interrupt\n * out-of-band), the middleware catches its **own** sentinel and\n * short-circuits a failed result carrying it — so the caller reads\n * `result.error.interruptId` and later calls\n * `ai.human.resume(interruptId, decision)`. The middleware **never throws\n * out of the pipeline**: every outcome (skip, approve, reject, edit,\n * suspend) returns normally; only a *handler bug* (a non-sentinel throw)\n * propagates, and even then the agent dispatch funnels it onto\n * `result.error` — `execute()` still never throws.\n *\n * @param options - Policy, handler, optional durable store, optional name.\n * @returns An {@link AgentMiddleware} declaring a single `tool.before` hook.\n *\n * @example\n * const support = ai.agent({\n *   model,\n *   tools: [refundCustomer],\n *   middleware: [\n *     humanApproval({\n *       policy: { type: \"allowlist\", tools: [\"refundCustomer\"], tags: () => [\"money\"] },\n *       handler: async (req) => ui.prompt(req), // { type: \"edit\", args: { amount: 5 } }\n *     }),\n *   ],\n * });\n */\nexport function humanApproval(options: HumanApprovalOptions): AgentMiddleware {\n  const name = options.name ?? DEFAULT_NAME;\n  const { policy, handler } = options;\n\n  return {\n    name,\n    tool: {\n      async before(\n        ctx: MiddlewareToolContext,\n      ): Promise<ToolInvokeResult<unknown> | void> {\n        const verdict = evaluatePolicy(policy, toPolicyContext(ctx));\n\n        // Not gated — let the real tool run unchanged.\n        if (!verdict.requiresApproval) {\n          return;\n        }\n\n        const interruptId = makeInterruptId(ctx);\n        const request = buildRequest(ctx, interruptId, verdict.tags);\n\n        // Durable resume: `ai.human.resume(...)` re-runs this same agent\n        // with the human's decision pre-seeded (keyed by agent name). On a\n        // hit we replay the seeded decision exactly once and skip the\n        // author's handler entirely — the gated call resolves to the\n        // ruling instead of pausing again.\n        const seeded = takeSeededDecision(ctx.agent.name);\n\n        let decision: ApprovalDecision;\n\n        if (seeded !== undefined) {\n          decision = seeded;\n        } else {\n          try {\n            decision = await handler(request);\n          } catch (thrown) {\n            // A durable handler signals suspension by throwing our OWN\n            // sentinel after persisting the interrupt. Recognize it and\n            // short-circuit a failed result carrying it — the caller reads\n            // `error.interruptId` and resumes later. Any OTHER throw is a\n            // handler bug; re-throw so the agent dispatch funnels it onto\n            // `result.error` (we never swallow a bug into silent approval).\n            if (thrown instanceof InterruptSuspendedError) {\n              return failedResult(thrown, ctx.tool.name);\n            }\n\n            throw thrown;\n          }\n        }\n\n        if (decision.type === \"approve\") {\n          // Run the real tool with the model's original args.\n          return;\n        }\n\n        if (decision.type === \"reject\") {\n          const error = new ApprovalRejectedError(\n            `Tool call \"${ctx.tool.name}\" rejected by reviewer — ${decision.reason}`,\n            { reason: decision.reason, toolName: ctx.tool.name },\n          );\n\n          return failedResult(error, ctx.tool.name);\n        }\n\n        // `edit` — rewrite the pending args, then let the real tool run.\n        // The agent dispatch reads `request.input` (this same object) when\n        // it invokes the tool after this hook returns, so the reassignment\n        // takes effect. Bad edits still fail the tool's own schema check.\n        (ctx.request as unknown as MutableToolRequest).input = decision.args;\n\n        return;\n      },\n    },\n  };\n}\n"],"mappings":";;;;;;;AAkBA,MAAM,eAAe;;AAGrB,MAAM,aAAoB,OAAO,OAAO;CAAE,OAAO;CAAG,QAAQ;CAAG,OAAO;AAAE,CAAC;;;;;AAmBzE,SAAS,gBAAgB,KAA2C;CAClE,OAAO;EACL,UAAU,IAAI,KAAK;EACnB,iBAAiB,IAAI,KAAK;EAC1B,MAAM,IAAI,QAAQ;EAClB,WAAW,IAAI,MAAM;EACrB,WAAW,IAAI;EACf,WAAW,IAAI,SAAS;CAC1B;AACF;;;;;;;AAQA,SAAS,gBAAgB,KAAoC;CAC3D,MAAM,UAAU,IAAI,SAAS,aAAa;CAC1C,MAAM,SAAS,cAAc,WAAW;CAExC,OAAO,GAAG,IAAI,MAAM,KAAK,GAAG,QAAQ,GAAG,IAAI,UAAU,GAAG;AAC1D;;;;;AAMA,SAAS,aACP,KACA,aACA,MACiB;CACjB,OAAO;EACL;EACA,UAAU,IAAI,KAAK;EACnB,iBAAiB,IAAI,KAAK;EAC1B,MAAM,IAAI,QAAQ;EAClB,SAAS;GACP,WAAW,IAAI,MAAM;GACrB,WAAW,IAAI;GACf,WAAW,IAAI,SAAS;GACxB,eAAe,IAAI;GACnB,GAAI,OAAO,EAAE,KAAK,IAAI,CAAC;EACzB;EACA,8BAAa,IAAI,KAAK,EAAC,CAAC,YAAY;CACtC;AACF;;;;;;;;;;;AAYA,SAAS,aAAa,OAAgB,UAA6C;CACjF,MAAM,QAAQ,cAAc,MAAM;CAClC,MAAM,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;CAetC,OAAO;EAAE;EAAO,OAAO;EAAY;GAZjC;GACA,WAAW;GACX,MAAM;GACN,MAAM;GACN,QAAQ;GACR,WAAW;GACX,SAAS;GACT,UAAU;GACV,OAAO;GACP,UAAU,CAAC;EAG2B;CAAE;AAC5C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDA,SAAgB,cAAc,SAAgD;CAC5E,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,EAAE,QAAQ,YAAY;CAE5B,OAAO;EACL;EACA,MAAM,EACJ,MAAM,OACJ,KAC2C;GAC3C,MAAM,UAAU,eAAe,QAAQ,gBAAgB,GAAG,CAAC;GAG3D,IAAI,CAAC,QAAQ,kBACX;GAIF,MAAM,UAAU,aAAa,KADT,gBAAgB,GACQ,GAAG,QAAQ,IAAI;GAO3D,MAAM,SAAS,mBAAmB,IAAI,MAAM,IAAI;GAEhD,IAAI;GAEJ,IAAI,WAAW,QACb,WAAW;QAEX,IAAI;IACF,WAAW,MAAM,QAAQ,OAAO;GAClC,SAAS,QAAQ;IAOf,IAAI,kBAAkB,yBACpB,OAAO,aAAa,QAAQ,IAAI,KAAK,IAAI;IAG3C,MAAM;GACR;GAGF,IAAI,SAAS,SAAS,WAEpB;GAGF,IAAI,SAAS,SAAS,UAMpB,OAAO,aAAa,IALF,sBAChB,cAAc,IAAI,KAAK,KAAK,2BAA2B,SAAS,UAChE;IAAE,QAAQ,SAAS;IAAQ,UAAU,IAAI,KAAK;GAAK,CAG7B,GAAG,IAAI,KAAK,IAAI;GAO1C,AAAC,IAAI,QAA0C,QAAQ,SAAS;EAGlE,EACF;CACF;AACF"}

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

@@ -0,0 +1,67 @@
+//#region ../@warlock.js/ai/src/human/policy.ts
+/**
+* A verdict that lets a call through untouched. Frozen and shared so the
+* (common) skip path allocates nothing.
+*/
+const SKIP = Object.freeze({ requiresApproval: false });
+/**
+* Normalize an author-supplied tags array into the verdict shape — an
+* empty array is treated as "no tags" so callers never have to
+* distinguish `[]` from `undefined`.
+*/
+function withTags(tags) {
+	if (tags === void 0 || tags.length === 0) return { requiresApproval: true };
+	return {
+		requiresApproval: true,
+		tags
+	};
+}
+/**
+* Decide whether a single pending tool call requires human approval —
+* the pure core behind the `ai.human.approval` middleware's gate.
+*
+* **Pure.** No IO, no throwing, no mutation of `policy` or `context`. The
+* middleware calls this once per tool dispatch and routes to a human only
+* when {@link PolicyVerdict.requiresApproval} is `true`.
+*
+* **The three rule types** ({@link InterruptPolicy}):
+* - `allowlist` — gate the call **only** when its tool name is listed; an
+*   optional `tags(toolName)` callback derives the verdict tags.
+* - `denylist` — gate **every** call **except** the listed tool names;
+*   the same optional `tags(toolName)` callback applies to the gated
+*   (non-listed) name.
+* - `predicate` — gate the call when `requiresApproval(context)` returns a
+*   truthy result. A non-empty `string[]` both gates the call **and**
+*   supplies the verdict tags; `true` gates with no tags; `false` (or an
+*   **empty** array — "no rule matched") lets the call through.
+*
+* @param policy - The interrupt policy to evaluate.
+* @param context - The read-only view of the pending tool call.
+* @returns A {@link PolicyVerdict} — gate-or-skip plus any tags.
+*
+* @example
+* const verdict = evaluatePolicy(
+*   { type: "allowlist", tools: ["refundCustomer"], tags: () => ["money"] },
+*   { toolName: "refundCustomer", args: { amount: 50 }, agentName: "support", tripIndex: 0 },
+* );
+* // → { requiresApproval: true, tags: ["money"] }
+*/
+function evaluatePolicy(policy, context) {
+	if (policy.type === "allowlist") {
+		if (!policy.tools.includes(context.toolName)) return SKIP;
+		return withTags(policy.tags?.(context.toolName));
+	}
+	if (policy.type === "denylist") {
+		if (policy.tools.includes(context.toolName)) return SKIP;
+		return withTags(policy.tags?.(context.toolName));
+	}
+	const outcome = policy.requiresApproval(context);
+	if (outcome === false) return SKIP;
+	if (outcome === true) return { requiresApproval: true };
+	if (outcome.length === 0) return SKIP;
+	return withTags(outcome);
+}
+
+//#endregion
+export { evaluatePolicy };
+//# sourceMappingURL=policy.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"policy.mjs","names":[],"sources":["../../../../../../../../../@warlock.js/ai/src/human/policy.ts"],"sourcesContent":["import type { InterruptPolicy, PolicyContext } from \"./contracts\";\n\n/**\n * Verdict of evaluating an {@link InterruptPolicy} against a single\n * pending tool call.\n *\n * - `requiresApproval` — `true` when the call must be routed to a human\n *   before the real tool runs; `false` when the policy lets it through\n *   untouched.\n * - `tags` — author-supplied labels from the matched rule (e.g.\n *   `\"destructive\"`, `\"money\"`), surfaced verbatim on the resulting\n *   `ApprovalRequest.context.tags`. Only ever present when\n *   `requiresApproval` is `true`; `undefined` when the rule produced no\n *   tags.\n */\nexport interface PolicyVerdict {\n  /** Whether this tool call must be approved by a human. */\n  requiresApproval: boolean;\n\n  /** Author-supplied tags from the matched rule, when any. */\n  tags?: string[];\n}\n\n/**\n * A verdict that lets a call through untouched. Frozen and shared so the\n * (common) skip path allocates nothing.\n */\nconst SKIP: PolicyVerdict = Object.freeze({ requiresApproval: false });\n\n/**\n * Normalize an author-supplied tags array into the verdict shape — an\n * empty array is treated as \"no tags\" so callers never have to\n * distinguish `[]` from `undefined`.\n */\nfunction withTags(tags: string[] | undefined): PolicyVerdict {\n  if (tags === undefined || tags.length === 0) {\n    return { requiresApproval: true };\n  }\n\n  return { requiresApproval: true, tags };\n}\n\n/**\n * Decide whether a single pending tool call requires human approval —\n * the pure core behind the `ai.human.approval` middleware's gate.\n *\n * **Pure.** No IO, no throwing, no mutation of `policy` or `context`. The\n * middleware calls this once per tool dispatch and routes to a human only\n * when {@link PolicyVerdict.requiresApproval} is `true`.\n *\n * **The three rule types** ({@link InterruptPolicy}):\n * - `allowlist` — gate the call **only** when its tool name is listed; an\n *   optional `tags(toolName)` callback derives the verdict tags.\n * - `denylist` — gate **every** call **except** the listed tool names;\n *   the same optional `tags(toolName)` callback applies to the gated\n *   (non-listed) name.\n * - `predicate` — gate the call when `requiresApproval(context)` returns a\n *   truthy result. A non-empty `string[]` both gates the call **and**\n *   supplies the verdict tags; `true` gates with no tags; `false` (or an\n *   **empty** array — \"no rule matched\") lets the call through.\n *\n * @param policy - The interrupt policy to evaluate.\n * @param context - The read-only view of the pending tool call.\n * @returns A {@link PolicyVerdict} — gate-or-skip plus any tags.\n *\n * @example\n * const verdict = evaluatePolicy(\n *   { type: \"allowlist\", tools: [\"refundCustomer\"], tags: () => [\"money\"] },\n *   { toolName: \"refundCustomer\", args: { amount: 50 }, agentName: \"support\", tripIndex: 0 },\n * );\n * // → { requiresApproval: true, tags: [\"money\"] }\n */\nexport function evaluatePolicy(\n  policy: InterruptPolicy,\n  context: PolicyContext,\n): PolicyVerdict {\n  if (policy.type === \"allowlist\") {\n    if (!policy.tools.includes(context.toolName)) {\n      return SKIP;\n    }\n\n    return withTags(policy.tags?.(context.toolName));\n  }\n\n  if (policy.type === \"denylist\") {\n    if (policy.tools.includes(context.toolName)) {\n      return SKIP;\n    }\n\n    return withTags(policy.tags?.(context.toolName));\n  }\n\n  // Predicate: a truthy result gates the call; a `string[]` doubles as the\n  // verdict tags.\n  const outcome = policy.requiresApproval(context);\n\n  if (outcome === false) {\n    return SKIP;\n  }\n\n  if (outcome === true) {\n    return { requiresApproval: true };\n  }\n\n  // `outcome` is a `string[]`. Per the contract, an EMPTY array means \"no\n  // rule matched\" and skips approval; a non-empty array gates the call and\n  // doubles as the verdict tags.\n  if (outcome.length === 0) {\n    return SKIP;\n  }\n\n  return withTags(outcome);\n}\n"],"mappings":";;;;;AA2BA,MAAM,OAAsB,OAAO,OAAO,EAAE,kBAAkB,MAAM,CAAC;;;;;;AAOrE,SAAS,SAAS,MAA2C;CAC3D,IAAI,SAAS,UAAa,KAAK,WAAW,GACxC,OAAO,EAAE,kBAAkB,KAAK;CAGlC,OAAO;EAAE,kBAAkB;EAAM;CAAK;AACxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,SAAgB,eACd,QACA,SACe;CACf,IAAI,OAAO,SAAS,aAAa;EAC/B,IAAI,CAAC,OAAO,MAAM,SAAS,QAAQ,QAAQ,GACzC,OAAO;EAGT,OAAO,SAAS,OAAO,OAAO,QAAQ,QAAQ,CAAC;CACjD;CAEA,IAAI,OAAO,SAAS,YAAY;EAC9B,IAAI,OAAO,MAAM,SAAS,QAAQ,QAAQ,GACxC,OAAO;EAGT,OAAO,SAAS,OAAO,OAAO,QAAQ,QAAQ,CAAC;CACjD;CAIA,MAAM,UAAU,OAAO,iBAAiB,OAAO;CAE/C,IAAI,YAAY,OACd,OAAO;CAGT,IAAI,YAAY,MACd,OAAO,EAAE,kBAAkB,KAAK;CAMlC,IAAI,QAAQ,WAAW,GACrB,OAAO;CAGT,OAAO,SAAS,OAAO;AACzB"}