@warlock.js/ai 4.3.0 → 4.5.0

package/esm/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/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":"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"}

package/esm/guard/guardrail.d.mts

@@ -0,0 +1,39 @@
+import { AgentMiddleware } from "../contracts/middleware/middleware.contract.mjs";
+import { GuardrailDetector } from "./contracts/guardrail.contract.mjs";
+import { GuardOptions, InjectionDetectorOptions, OpenAiModerationOptions, PiiDetectorOptions, TopicFilterOptions } from "./contracts/guard-options.type.mjs";
+//#region ../@warlock.js/ai/src/guard/guardrail.d.ts
+/**
+ * The callable `ai.guardrail` surface — the {@link guard} factory with the
+ * built-in detector factories attached as methods, so the whole guardrail
+ * vocabulary lives under one name:
+ *
+ * - `ai.guardrail(options)` — build the composed middleware.
+ * - `ai.guardrail.pii(o?)` / `.topic(o)` / `.injection(o?)` / `.moderation(o?)`
+ *   — build a detector to pass into the factory's `input` / `output` / `tool`
+ *   arrays.
+ *
+ * @example
+ * const policy = ai.guardrail({
+ *   output: [ai.guardrail.pii({ onMatch: "redact" })],
+ * });
+ */
+interface GuardrailFactory {
+  /** Build the composed guardrail {@link AgentMiddleware}. */
+  (options: GuardOptions): AgentMiddleware;
+  /** Built-in PII detector (regex + dictionary, zero runtime dep). */
+  pii(options?: PiiDetectorOptions): GuardrailDetector;
+  /** Built-in topic filter (allow / deny string | RegExp lists). */
+  topic(options: TopicFilterOptions): GuardrailDetector;
+  /** Built-in jailbreak / prompt-injection marker detector. */
+  injection(options?: InjectionDetectorOptions): GuardrailDetector;
+  /** Optional OpenAI-backed moderation detector (lazy `openai` peer). */
+  moderation(options?: OpenAiModerationOptions): GuardrailDetector;
+}
+/**
+ * The `ai.guardrail` value: the {@link guard} factory with the detector
+ * factories assigned onto it. Built once and shared.
+ */
+declare const guardrail: GuardrailFactory;
+//#endregion
+export { GuardrailFactory, guardrail };
+//# sourceMappingURL=guardrail.d.mts.map

package/esm/guard/guardrail.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrail.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/guard/guardrail.ts"],"mappings":";;;;;;;;AA2BA;;;;;;;;;;;UAAiB,gBAAA;EAUgC;EAAA,CAR9C,OAAA,EAAS,YAAA,GAAe,eAAA;EAQuC;EANhE,GAAA,CAAI,OAAA,GAAU,kBAAA,GAAqB,iBAAA;EAFlC;EAID,KAAA,CAAM,OAAA,EAAS,kBAAA,GAAqB,iBAAA;EAFpC;EAIA,SAAA,CAAU,OAAA,GAAU,wBAAA,GAA2B,iBAAA;EAJ3C;EAMJ,UAAA,CAAW,OAAA,GAAU,uBAAA,GAA0B,iBAAA;AAAA;;;;;cAOpC,SAAA,EAAW,gBAKtB"}

package/esm/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/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/human/contracts/approval.type.d.mts

@@ -0,0 +1,154 @@
+//#region ../@warlock.js/ai/src/human/contracts/approval.type.d.ts
+/**
+ * What a human can do to a gated tool call.
+ *
+ * The discriminator for the {@link ApprovalDecision} union — `type`,
+ * never `kind`. Each member of the union is keyed on one of these
+ * literals so a reviewer surface can branch exhaustively.
+ *
+ * - `"approve"` — let the real tool run with the model's args unchanged.
+ * - `"reject"`  — short-circuit the call; the model sees a typed error
+ *   (carrying the reviewer's reason) and can self-correct on the next trip.
+ * - `"edit"`    — run the tool, but with reviewer-replaced args.
+ */
+type ApprovalDecisionType = "approve" | "reject" | "edit";
+/**
+ * The read-only run context surfaced to a reviewer alongside an
+ * {@link ApprovalRequest}. Derived from the wrapping
+ * `MiddlewareToolContext` — the reviewer never mutates it.
+ */
+interface ApprovalRequestContext {
+  /** Name of the agent whose tool call is being gated. */
+  agentName: string;
+  /** Zero-based index of the model round-trip that produced the call. */
+  tripIndex: number;
+  /** Originating session id, when the run is part of an orchestrator session. */
+  sessionId?: string;
+  /**
+   * The agent's original input prompt for the run that raised this
+   * interrupt. Captured so a durable `ai.human.resume(...)` re-run can
+   * re-drive the agent with the same prompt without the caller having to
+   * thread it through out-of-band.
+   */
+  originalInput?: string;
+  /**
+   * Author-supplied tags from the policy match (e.g. `"destructive"`,
+   * `"money"`). Lets a reviewer surface group or prioritize requests
+   * without re-deriving the rule that gated the call.
+   */
+  tags?: string[];
+}
+/**
+ * The pending tool call a human is asked to rule on.
+ *
+ * Built by the approval middleware from the `MiddlewareToolContext` the
+ * moment the {@link InterruptPolicy} gates a call. In durable mode it is
+ * also the payload persisted inside a
+ * {@link import("./interrupt-store.contract").PendingInterrupt}, keyed by
+ * {@link ApprovalRequest.interruptId}.
+ */
+interface ApprovalRequest {
+  /**
+   * Stable id for this pending call. Durable mode keys the
+   * `InterruptStore` on it; the caller surfaces it to the reviewer and
+   * later passes it to `ai.human.resume(interruptId, decision)`.
+   */
+  interruptId: string;
+  /** Registered name of the tool the model wants to invoke. */
+  toolName: string;
+  /** Human-facing description from the tool contract, when present. */
+  toolDescription?: string;
+  /** The exact arguments the model produced for the tool. */
+  args: unknown;
+  /** Read-only run context the reviewer sees. */
+  context: ApprovalRequestContext;
+  /** When the request was raised, as an ISO-8601 timestamp. */
+  requestedAt: string;
+}
+/**
+ * A human's ruling on an {@link ApprovalRequest}.
+ *
+ * A discriminated union keyed on `type` (never `kind`):
+ * - `approve` — run the real tool unchanged.
+ * - `reject`  — short-circuit; `reason` is surfaced to the model via the
+ *   typed error so it can self-correct.
+ * - `edit`    — run the tool with `args` replaced; `reason` is optional
+ *   audit context.
+ */
+type ApprovalDecision = {
+  type: "approve";
+} | {
+  type: "reject";
+  reason: string;
+} | {
+  type: "edit";
+  args: unknown;
+  reason?: string;
+};
+/**
+ * Turns an {@link ApprovalRequest} into an {@link ApprovalDecision}.
+ *
+ * Two modes share this one signature:
+ * - **interactive** — resolve the returned promise (or return a decision
+ *   synchronously) when the operator rules; the middleware `await`s it
+ *   in-process.
+ * - **durable** — persist a
+ *   {@link import("./interrupt-store.contract").PendingInterrupt} to the
+ *   configured store, then throw
+ *   {@link import("../errors").InterruptSuspendedError} to suspend the
+ *   run; a later `ai.human.resume(...)` call replays the decision.
+ */
+type ApprovalHandler = (request: ApprovalRequest) => Promise<ApprovalDecision> | ApprovalDecision;
+/**
+ * The minimal read-only view a {@link InterruptPolicy} predicate sees,
+ * derived from the wrapping `MiddlewareToolContext`. Carries only the
+ * fields a gating decision can usefully branch on — the model's args,
+ * the tool identity, and the surrounding run identity.
+ */
+interface PolicyContext {
+  /** Registered name of the tool the model wants to invoke. */
+  toolName: string;
+  /** Human-facing description from the tool contract, when present. */
+  toolDescription?: string;
+  /** The exact arguments the model produced for the tool. */
+  args: unknown;
+  /** Name of the agent whose tool call is being evaluated. */
+  agentName: string;
+  /** Zero-based index of the model round-trip that produced the call. */
+  tripIndex: number;
+  /** Originating session id, when part of an orchestrator session. */
+  sessionId?: string;
+}
+/**
+ * Decides which tool calls require a human.
+ *
+ * A discriminated union keyed on `type` (never `kind`):
+ * - `allowlist` — gate a call **only** when its tool name is listed.
+ * - `denylist`  — gate **every** call **except** the listed tool names.
+ * - `predicate` — gate a call when the author-supplied `requiresApproval`
+ *   returns a truthy value; a `string[]` both gates the call and supplies
+ *   the {@link ApprovalRequestContext.tags}.
+ *
+ * For the list variants, the optional `tags` callback derives the
+ * request tags from the matched tool name.
+ */
+type InterruptPolicy = {
+  type: "allowlist"; /** Tool names that require approval. */
+  tools: string[]; /** Derive request tags from the matched tool name. */
+  tags?: (toolName: string) => string[];
+} | {
+  type: "denylist"; /** Tool names that bypass approval; every other tool is gated. */
+  tools: string[]; /** Derive request tags from the matched tool name. */
+  tags?: (toolName: string) => string[];
+} | {
+  type: "predicate";
+  /**
+   * Return `false` (or an empty result) to skip approval; return
+   * `true` or a `string[]` to require it. A `string[]` doubles as the
+   * request {@link ApprovalRequestContext.tags}.
+   */
+  requiresApproval: (ctx: PolicyContext) => boolean | string[];
+};
+//#endregion
+export { ApprovalDecision, ApprovalDecisionType, ApprovalHandler, ApprovalRequest, ApprovalRequestContext, InterruptPolicy, PolicyContext };
+//# sourceMappingURL=approval.type.d.mts.map

package/esm/human/contracts/approval.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/human/contracts/approval.type.ts"],"mappings":";;AAYA;;;;AAAgC;AAOhC;;;;;;KAPY,oBAAA;;;;AA8BN;AAYN;UAnCiB,sBAAA;;EAEf,SAAA;EAuCA;EApCA,SAAA;EA0CA;EAvCA,SAAA;EA6CA;;;;AAGW;AAab;EArDE,aAAA;;;;;;EAOA,IAAA;AAAA;;;AAiDuC;AAezC;;;;;;UApDiB,eAAA;EAsDgC;;;;;EAhD/C,WAAA;EAgD+B;EA7C/B,QAAA;EA6C+C;EA1C/C,eAAA;EAkD4B;EA/C5B,IAAA;EA+C4B;EA5C5B,OAAA,EAAS,sBAAsB;EAiD/B;EA9CA,WAAA;AAAA;;;;AA0DS;AAgBX;;;;;;KA7DY,gBAAA;EACN,IAAA;AAAA;EACA,IAAA;EAAgB,MAAA;AAAA;EAChB,IAAA;EAAc,IAAA;EAAe,MAAA;AAAA;;AAgFQ;;;;;;;;;;;;KAjE/B,eAAA,IACV,OAAA,EAAS,eAAA,KACN,OAAA,CAAQ,gBAAA,IAAoB,gBAAA;;;;;;;UAQhB,aAAA;;EAEf,QAAA;;EAGA,eAAA;;EAGA,IAAA;;EAGA,SAAA;;EAGA,SAAA;;EAGA,SAAA;AAAA;;;;;;;;;;;;;;KAgBU,eAAA;EAEN,IAAA;EAEA,KAAA;EAEA,IAAA,IAAQ,QAAA;AAAA;EAGR,IAAA;EAEA,KAAA;EAEA,IAAA,IAAQ,QAAA;AAAA;EAGR,IAAA;;;;;;EAMA,gBAAA,GAAmB,GAAA,EAAK,aAAa;AAAA"}

package/esm/human/contracts/human-approval.type.d.mts

@@ -0,0 +1,38 @@
+import { ApprovalHandler, InterruptPolicy } from "./approval.type.mjs";
+import { InterruptStore } from "./interrupt-store.contract.mjs";
+
+//#region ../@warlock.js/ai/src/human/contracts/human-approval.type.d.ts
+/**
+ * Options for `ai.human.approval(options)` — the `tool.before`
+ * approval-gate middleware factory.
+ *
+ * The middleware evaluates {@link HumanApprovalOptions.policy} against
+ * each pending tool call; for gated calls it builds an
+ * {@link import("./approval.type").ApprovalRequest} and routes it to
+ * {@link HumanApprovalOptions.handler}, then applies the returned
+ * {@link import("./approval.type").ApprovalDecision} (approve → continue;
+ * reject → short-circuit a typed error; edit → run with replaced args).
+ */
+interface HumanApprovalOptions {
+  /**
+   * Stable middleware name. Middleware names are validated unique per
+   * agent, so two approval middlewares on one agent need distinct names.
+   * Defaults to `"human-approval"`.
+   */
+  name?: string;
+  /** Which tool calls require a human. */
+  policy: InterruptPolicy;
+  /** How a gated call reaches a human and yields a decision. */
+  handler: ApprovalHandler;
+  /**
+   * Optional durable store. When set **and** the handler throws
+   * {@link import("../errors").InterruptSuspendedError}, the pending
+   * request is persisted here for out-of-process resume via
+   * `ai.human.resume(interruptId, decision)`. Omit for pure interactive
+   * (await-in-process) mode.
+   */
+  store?: InterruptStore;
+}
+//#endregion
+export { HumanApprovalOptions };
+//# sourceMappingURL=human-approval.type.d.mts.map

package/esm/human/contracts/human-approval.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"human-approval.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/human/contracts/human-approval.type.ts"],"mappings":";;;;;;AAcA;;;;;;;;;UAAiB,oBAAA;EASP;;;;;EAHR,IAAA;EAesB;EAZtB,MAAA,EAAQ,eAAA;;EAGR,OAAA,EAAS,eAAA;;;;;;;;EAST,KAAA,GAAQ,cAAA;AAAA"}

package/esm/human/contracts/index.d.mts

@@ -0,0 +1,4 @@
+import { ApprovalDecision, ApprovalDecisionType, ApprovalHandler, ApprovalRequest, ApprovalRequestContext, InterruptPolicy, PolicyContext } from "./approval.type.mjs";
+import { InterruptStore, PendingInterrupt, PendingInterruptStatus, PgClientLike, RedisClientLike } from "./interrupt-store.contract.mjs";
+import { HumanApprovalOptions } from "./human-approval.type.mjs";
+import { ResumeOptions, ResumeResult } from "./resume.type.mjs";

package/esm/human/contracts/interrupt-store.contract.d.mts

@@ -0,0 +1,112 @@
+import { ApprovalRequest } from "./approval.type.mjs";
+
+//#region ../@warlock.js/ai/src/human/contracts/interrupt-store.contract.d.ts
+/**
+ * Lifecycle status of a persisted interrupt.
+ *
+ * `"pending"` until a decision lands; the record is marked
+ * `"resolved"` (then deleted) once `ai.human.resume(...)` applies a
+ * decision. Discriminator is `status` (a closed string union), so a
+ * caller can branch idempotently — a second resume of a `"resolved"`
+ * (or already-deleted) interrupt is a no-op, never a double-apply.
+ */
+type PendingInterruptStatus = "pending" | "resolved";
+/**
+ * A persisted, awaiting-decision interrupt — the durable counterpart of
+ * an in-flight {@link ApprovalRequest}.
+ *
+ * Mirrors the shape the snapshot/checkpoint stores persist: a flat
+ * record keyed by a single id (`interruptId`) that the store round-trips
+ * verbatim. The `request` is everything a reviewer (in another process,
+ * hours later) needs to rule on the call; `status` tracks the lifecycle;
+ * `savedAt` is the ISO-8601 write time.
+ */
+interface PendingInterrupt {
+  /** Stable id; the store keys the record on it. */
+  interruptId: string;
+  /** The pending call the human is asked to rule on. */
+  request: ApprovalRequest;
+  /** `"pending"` until a decision lands; then `"resolved"` and deleted. */
+  status: PendingInterruptStatus;
+  /** When the record was written, as an ISO-8601 timestamp. */
+  savedAt: string;
+}
+/**
+ * Durable store for {@link PendingInterrupt} records — the persistence
+ * seam behind durable human-in-the-loop approval.
+ *
+ * Deliberately shaped like the `@warlock.js/ai`
+ * `SnapshotStore` / `CheckpointStore` contracts (`load` / `save` /
+ * `delete` / optional `list` / `schema`), so a consumer already running
+ * an orchestrator can reuse the **same** `pg.Pool` / redis client for
+ * the interrupt table. Keyed by `interruptId`. Schema is never
+ * auto-migrated — {@link InterruptStore.schema} returns a DDL string the
+ * dev runs through their own migration tooling.
+ *
+ * Implementations: `ai.human.interrupt.{memory,pg,redis}()`. The memory
+ * impl ships first (pure in-process `Map`, zero deps); pg/redis lazily
+ * import their client via {@link PgClientLike} / {@link RedisClientLike}
+ * so neither driver is a hard dependency.
+ */
+interface InterruptStore {
+  /**
+   * Persist a pending interrupt, keyed by its own `interruptId`.
+   * Overwrites any prior record for the same id (a call has exactly one
+   * live interrupt).
+   */
+  save(record: PendingInterrupt): Promise<void>;
+  /**
+   * Load the interrupt for an `interruptId`, or `undefined` when none is
+   * recorded (never raised, or already resolved + deleted).
+   */
+  load(interruptId: string): Promise<PendingInterrupt | undefined>;
+  /**
+   * Drop the interrupt for an `interruptId`. Idempotent — deleting an
+   * absent id is a no-op.
+   */
+  delete(interruptId: string): Promise<void>;
+  /**
+   * List the interrupt ids the store knows, optionally filtered by a
+   * prefix. Optional — stores that can't enumerate (e.g. a key/value
+   * driver with no `SCAN`) omit it.
+   */
+  list?(prefix?: string): Promise<string[]>;
+  /**
+   * Return the DDL string for this store's backing table. The dev runs
+   * it through their migration tool; the framework never auto-migrates.
+   * Stores with no backing table (memory, redis) return an empty string
+   * so callers can treat `schema()` uniformly across drivers.
+   */
+  schema(): string;
+}
+/**
+ * Minimal `pg`-compatible client surface the Postgres
+ * {@link InterruptStore} depends on. Both `pg.Pool` and `pg.Client`
+ * satisfy it — the store only ever calls `query`.
+ *
+ * `@warlock.js/ai` takes **no** hard dependency on `pg`; the dev
+ * installs it (an optional peer) and passes the client in. Structurally
+ * identical to the orchestrator stores' `PgClientLike`, so a single pool
+ * can back the checkpoint/snapshot stores and the interrupt table alike.
+ */
+interface PgClientLike {
+  query(text: string, params?: unknown[]): Promise<{
+    rows: unknown[];
+  }>;
+}
+/**
+ * Minimal `redis`-compatible client surface the Redis
+ * {@link InterruptStore} depends on.
+ *
+ * `@warlock.js/ai` takes **no** hard dependency on `redis`; the dev
+ * installs it (an optional peer) and passes the connected client in. The
+ * store only calls `get` / `set` / `del`.
+ */
+interface RedisClientLike {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+  del(key: string): Promise<number>;
+}
+//#endregion
+export { InterruptStore, PendingInterrupt, PendingInterruptStatus, PgClientLike, RedisClientLike };
+//# sourceMappingURL=interrupt-store.contract.d.mts.map

package/esm/human/contracts/interrupt-store.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interrupt-store.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/human/contracts/interrupt-store.contract.ts"],"mappings":";;;;;AAWA;;;;AAAkC;AAYlC;;KAZY,sBAAA;;;;;;;;;AAuBH;AAoBT;UA/BiB,gBAAA;;EAEf,WAAA;EAmCgC;EAhChC,OAAA,EAAS,eAAA;EAsCkB;EAnC3B,MAAA,EAAQ,sBAAsB;EAgDN;EA7CxB,OAAA;AAAA;;;;;;;;;;;;;;;;;AAqDM;UAjCS,cAAA;EA8CY;;;;;EAxC3B,IAAA,CAAK,MAAA,EAAQ,gBAAA,GAAmB,OAAA;EAyCS;;;AAAc;EAnCvD,IAAA,CAAK,WAAA,WAAsB,OAAA,CAAQ,gBAAA;EA8CL;;;;EAxC9B,MAAA,CAAO,WAAA,WAAsB,OAAA;EA2CJ;;;;;EApCzB,IAAA,EAAM,MAAA,YAAkB,OAAA;EAmCpB;;;;;;EA3BJ,MAAA;AAAA;AA4ByB;;;;;;;;;;AAAA,UAfV,YAAA;EACf,KAAA,CAAM,IAAA,UAAc,MAAA,eAAqB,OAAO;IAAG,IAAA;EAAA;AAAA;;;;;;;;;UAWpC,eAAA;EACf,GAAA,CAAI,GAAA,WAAc,OAAA;EAClB,GAAA,CAAI,GAAA,UAAa,KAAA,aAAkB,IAAA,cAAkB,OAAA;EACrD,GAAA,CAAI,GAAA,WAAc,OAAA;AAAA"}