@warlock.js/ai 4.3.0 → 4.5.0

package/esm/guard/detectors/pii.mjs

@@ -0,0 +1,199 @@
+//#region ../@warlock.js/ai/src/guard/detectors/pii.ts
+/** Detector name, used as the namespace prefix on every {@link GuardrailMatch.rule}. */
+const DETECTOR_NAME = "pii";
+/** Placeholder substituted for a matched span when the caller supplies no `mask`. */
+const DEFAULT_MASK = "[REDACTED]";
+/**
+* The built-in PII category regexes. Each is linear (anchored alternations,
+* no nested quantifiers) so it is safe against catastrophic backtracking on
+* adversarial input. All carry the global flag so a single pass over the
+* text yields every occurrence; `lastIndex` is reset per use so a shared
+* instance never leaks state across calls.
+*
+* - `ssn`         — US Social Security number, `123-45-6789` / `123 45 6789`.
+* - `email`       — a pragmatic address shape, not full RFC 5322.
+* - `phone`       — North-American style, optional `+1`, separators, parens.
+* - `credit-card` — 13–16 digit runs, optional space / hyphen grouping.
+* - `ipv4`        — four dotted octets (loosely; out-of-range octets still match).
+*/
+const CATEGORY_PATTERNS = {
+	ssn: /\b\d{3}[-\s]\d{2}[-\s]\d{4}\b/g,
+	email: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g,
+	phone: /(?:\+?1[-.\s]?)?(?:\(\d{3}\)|\d{3})[-.\s]?\d{3}[-.\s]?\d{4}\b/g,
+	"credit-card": /\b(?:\d[ -]?){13,16}\b/g,
+	ipv4: /\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/g
+};
+/** Every built-in category, in a stable scan order. */
+const ALL_CATEGORIES = [
+	"ssn",
+	"email",
+	"phone",
+	"credit-card",
+	"ipv4"
+];
+/**
+* Escape a string for safe interpolation into a `RegExp` source, so an
+* extra dictionary term containing regex metacharacters (`.`, `+`, `(`, …)
+* matches literally rather than as a pattern.
+*/
+function escapeRegExp(term) {
+	return term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Build the `{label}` mask for a hit. The template's `{label}` token is
+* substituted with the hit's category; a template without the token is used
+* verbatim. Falls back to {@link DEFAULT_MASK} when no template is given.
+*/
+function applyMask(template, label) {
+	if (template === void 0) return DEFAULT_MASK;
+	return template.replace(/\{label\}/g, label);
+}
+/**
+* Collect every built-in-category hit in `text` for the requested
+* categories, in document order per category.
+*/
+function scanCategories(text, categories) {
+	const hits = [];
+	for (const category of categories) {
+		const pattern = CATEGORY_PATTERNS[category];
+		pattern.lastIndex = 0;
+		let match = pattern.exec(text);
+		while (match !== null) {
+			hits.push({
+				label: category,
+				start: match.index,
+				end: match.index + match[0].length - 1
+			});
+			if (match[0].length === 0) pattern.lastIndex += 1;
+			match = pattern.exec(text);
+		}
+	}
+	return hits;
+}
+/**
+* Collect every occurrence of each extra dictionary term in `text`,
+* case-insensitively, as `"dictionary"`-labelled hits.
+*/
+function scanDictionary(text, dictionary) {
+	const hits = [];
+	for (const term of dictionary) {
+		if (term.length === 0) continue;
+		const pattern = new RegExp(escapeRegExp(term), "gi");
+		let match = pattern.exec(text);
+		while (match !== null) {
+			hits.push({
+				label: "dictionary",
+				start: match.index,
+				end: match.index + match[0].length - 1
+			});
+			match = pattern.exec(text);
+		}
+	}
+	return hits;
+}
+/**
+* Sort hits by start offset, then drop any hit fully contained in (or
+* duplicating) an already-kept span. Different category regexes can overlap
+* on the same characters (e.g. a credit-card run inside a phone-shaped
+* span); keeping the earliest, widest span makes redaction deterministic
+* and avoids masking a sub-span twice.
+*/
+function dedupeHits(hits) {
+	const sorted = [...hits].sort((a, b) => {
+		if (a.start !== b.start) return a.start - b.start;
+		return b.end - a.end;
+	});
+	const kept = [];
+	for (const hit of sorted) if (!kept.some((existing) => hit.start <= existing.end && hit.end >= existing.start)) kept.push(hit);
+	return kept;
+}
+/**
+* Rewrite `text`, replacing every kept hit's span with its mask. Applied
+* right-to-left so earlier offsets stay valid as later spans are spliced.
+*/
+function redactText(text, hits, mask) {
+	const ordered = [...hits].sort((a, b) => b.start - a.start);
+	let result = text;
+	for (const hit of ordered) {
+		const replacement = applyMask(mask, hit.label);
+		result = result.slice(0, hit.start) + replacement + result.slice(hit.end + 1);
+	}
+	return result;
+}
+/** Fold a {@link RawHit} into the public {@link GuardrailMatch} shape. */
+function toMatch(hit) {
+	return {
+		rule: `${DETECTOR_NAME}.${hit.label}`,
+		span: [hit.start, hit.end],
+		label: hit.label
+	};
+}
+/**
+* Build the built-in **PII detector** (`ai.guardrail.pii`) — a zero-runtime-
+* dependency {@link GuardrailDetector} that scans text for personally
+* identifiable information via a curated set of linear regexes plus an
+* optional exact-string dictionary.
+*
+* Categories (`detect`, default: all): `ssn`, `email`, `phone`,
+* `credit-card`, `ipv4`. `dictionary` adds extra exact terms matched
+* case-insensitively as literal strings (regex metacharacters escaped).
+*
+* On a hit the verdict follows `onMatch` (default `"redact"`):
+*
+* - **`redact`** — every matched span is replaced by the `mask` template
+*   (`{label}` → the matched category, default `"[REDACTED]"`) and the
+*   rewritten text is returned for the factory to substitute. Output and
+*   tool phases honour the rewrite; on the input phase the factory treats a
+*   `redact` verdict as a `block` (the core `trip.before` hook can only
+*   short-circuit, not rewrite-and-continue — see {@link PiiDetectorOptions}).
+* - **`block`** — a hard stop carrying the matches.
+* - **`flag`**  — the content passes but the matches are recorded.
+*
+* Clean text returns `{ type: "allow" }`.
+*
+* @example
+* ai.guardrail({ output: [ai.guardrail.pii()] }); // redact, default mask
+*
+* @example
+* ai.guardrail.pii({
+*   detect: ["ssn", "credit-card"],
+*   onMatch: "redact",
+*   mask: "[PII:{label}]",
+*   dictionary: ["Project Aurora"],
+* });
+*/
+function pii(options = {}) {
+	const categories = options.detect ?? ALL_CATEGORIES;
+	const onMatch = options.onMatch ?? "redact";
+	const dictionary = options.dictionary ?? [];
+	return {
+		name: DETECTOR_NAME,
+		check(text) {
+			const rawHits = [...scanCategories(text, categories), ...scanDictionary(text, dictionary)];
+			if (rawHits.length === 0) return { type: "allow" };
+			const hits = dedupeHits(rawHits);
+			const matches = hits.map(toMatch);
+			const labels = [...new Set(hits.map((hit) => hit.label))].join(", ");
+			if (onMatch === "block") return {
+				type: "block",
+				reason: `PII detected: ${labels}.`,
+				matches
+			};
+			if (onMatch === "flag") return {
+				type: "flag",
+				reason: `PII detected: ${labels}.`,
+				matches
+			};
+			return {
+				type: "redact",
+				text: redactText(text, hits, options.mask),
+				reason: `Redacted PII: ${labels}.`,
+				matches
+			};
+		}
+	};
+}
+
+//#endregion
+export { pii };
+//# sourceMappingURL=pii.mjs.map

package/esm/guard/detectors/pii.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pii.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/guard/detectors/pii.ts"],"sourcesContent":["import type {\n  GuardrailMatch,\n  GuardrailVerdict,\n  PiiCategory,\n  PiiDetectorOptions,\n  SyncGuardrailDetector,\n} from \"../contracts\";\n\n/** Detector name, used as the namespace prefix on every {@link GuardrailMatch.rule}. */\nconst DETECTOR_NAME = \"pii\";\n\n/** Placeholder substituted for a matched span when the caller supplies no `mask`. */\nconst DEFAULT_MASK = \"[REDACTED]\";\n\n/**\n * The built-in PII category regexes. Each is linear (anchored alternations,\n * no nested quantifiers) so it is safe against catastrophic backtracking on\n * adversarial input. All carry the global flag so a single pass over the\n * text yields every occurrence; `lastIndex` is reset per use so a shared\n * instance never leaks state across calls.\n *\n * - `ssn`         — US Social Security number, `123-45-6789` / `123 45 6789`.\n * - `email`       — a pragmatic address shape, not full RFC 5322.\n * - `phone`       — North-American style, optional `+1`, separators, parens.\n * - `credit-card` — 13–16 digit runs, optional space / hyphen grouping.\n * - `ipv4`        — four dotted octets (loosely; out-of-range octets still match).\n */\nconst CATEGORY_PATTERNS: Record<PiiCategory, RegExp> = {\n  ssn: /\\b\\d{3}[-\\s]\\d{2}[-\\s]\\d{4}\\b/g,\n  email: /\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}\\b/g,\n  phone: /(?:\\+?1[-.\\s]?)?(?:\\(\\d{3}\\)|\\d{3})[-.\\s]?\\d{3}[-.\\s]?\\d{4}\\b/g,\n  \"credit-card\": /\\b(?:\\d[ -]?){13,16}\\b/g,\n  ipv4: /\\b\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\b/g,\n};\n\n/** Every built-in category, in a stable scan order. */\nconst ALL_CATEGORIES: readonly PiiCategory[] = [\n  \"ssn\",\n  \"email\",\n  \"phone\",\n  \"credit-card\",\n  \"ipv4\",\n];\n\n/**\n * A raw hit located inside the inspected text, before it is folded into a\n * {@link GuardrailMatch}. `label` is the category (built-in) or\n * `\"dictionary\"` (an extra term); `start` / `end` are inclusive offsets.\n */\ninterface RawHit {\n  readonly label: string;\n  readonly start: number;\n  readonly end: number;\n}\n\n/**\n * Escape a string for safe interpolation into a `RegExp` source, so an\n * extra dictionary term containing regex metacharacters (`.`, `+`, `(`, …)\n * matches literally rather than as a pattern.\n */\nfunction escapeRegExp(term: string): string {\n  return term.replace(/[.*+?^${}()|[\\]\\\\]/g, \"\\\\$&\");\n}\n\n/**\n * Build the `{label}` mask for a hit. The template's `{label}` token is\n * substituted with the hit's category; a template without the token is used\n * verbatim. Falls back to {@link DEFAULT_MASK} when no template is given.\n */\nfunction applyMask(template: string | undefined, label: string): string {\n  if (template === undefined) {\n    return DEFAULT_MASK;\n  }\n\n  return template.replace(/\\{label\\}/g, label);\n}\n\n/**\n * Collect every built-in-category hit in `text` for the requested\n * categories, in document order per category.\n */\nfunction scanCategories(text: string, categories: readonly PiiCategory[]): RawHit[] {\n  const hits: RawHit[] = [];\n\n  for (const category of categories) {\n    const pattern = CATEGORY_PATTERNS[category];\n    pattern.lastIndex = 0;\n\n    let match = pattern.exec(text);\n\n    while (match !== null) {\n      hits.push({\n        label: category,\n        start: match.index,\n        end: match.index + match[0].length - 1,\n      });\n\n      // Guard the zero-length-match case so `exec` can never spin forever.\n      if (match[0].length === 0) {\n        pattern.lastIndex += 1;\n      }\n\n      match = pattern.exec(text);\n    }\n  }\n\n  return hits;\n}\n\n/**\n * Collect every occurrence of each extra dictionary term in `text`,\n * case-insensitively, as `\"dictionary\"`-labelled hits.\n */\nfunction scanDictionary(text: string, dictionary: readonly string[]): RawHit[] {\n  const hits: RawHit[] = [];\n\n  for (const term of dictionary) {\n    if (term.length === 0) {\n      continue;\n    }\n\n    const pattern = new RegExp(escapeRegExp(term), \"gi\");\n    let match = pattern.exec(text);\n\n    while (match !== null) {\n      hits.push({\n        label: \"dictionary\",\n        start: match.index,\n        end: match.index + match[0].length - 1,\n      });\n\n      match = pattern.exec(text);\n    }\n  }\n\n  return hits;\n}\n\n/**\n * Sort hits by start offset, then drop any hit fully contained in (or\n * duplicating) an already-kept span. Different category regexes can overlap\n * on the same characters (e.g. a credit-card run inside a phone-shaped\n * span); keeping the earliest, widest span makes redaction deterministic\n * and avoids masking a sub-span twice.\n */\nfunction dedupeHits(hits: RawHit[]): RawHit[] {\n  const sorted = [...hits].sort((a, b) => {\n    if (a.start !== b.start) {\n      return a.start - b.start;\n    }\n\n    // Same start: keep the wider span first so the narrower one is absorbed.\n    return b.end - a.end;\n  });\n\n  const kept: RawHit[] = [];\n\n  for (const hit of sorted) {\n    const overlaps = kept.some(\n      existing => hit.start <= existing.end && hit.end >= existing.start,\n    );\n\n    if (!overlaps) {\n      kept.push(hit);\n    }\n  }\n\n  return kept;\n}\n\n/**\n * Rewrite `text`, replacing every kept hit's span with its mask. Applied\n * right-to-left so earlier offsets stay valid as later spans are spliced.\n */\nfunction redactText(text: string, hits: RawHit[], mask: string | undefined): string {\n  const ordered = [...hits].sort((a, b) => b.start - a.start);\n  let result = text;\n\n  for (const hit of ordered) {\n    const replacement = applyMask(mask, hit.label);\n    result = result.slice(0, hit.start) + replacement + result.slice(hit.end + 1);\n  }\n\n  return result;\n}\n\n/** Fold a {@link RawHit} into the public {@link GuardrailMatch} shape. */\nfunction toMatch(hit: RawHit): GuardrailMatch {\n  return {\n    rule: `${DETECTOR_NAME}.${hit.label}`,\n    span: [hit.start, hit.end],\n    label: hit.label,\n  };\n}\n\n/**\n * Build the built-in **PII detector** (`ai.guardrail.pii`) — a zero-runtime-\n * dependency {@link GuardrailDetector} that scans text for personally\n * identifiable information via a curated set of linear regexes plus an\n * optional exact-string dictionary.\n *\n * Categories (`detect`, default: all): `ssn`, `email`, `phone`,\n * `credit-card`, `ipv4`. `dictionary` adds extra exact terms matched\n * case-insensitively as literal strings (regex metacharacters escaped).\n *\n * On a hit the verdict follows `onMatch` (default `\"redact\"`):\n *\n * - **`redact`** — every matched span is replaced by the `mask` template\n *   (`{label}` → the matched category, default `\"[REDACTED]\"`) and the\n *   rewritten text is returned for the factory to substitute. Output and\n *   tool phases honour the rewrite; on the input phase the factory treats a\n *   `redact` verdict as a `block` (the core `trip.before` hook can only\n *   short-circuit, not rewrite-and-continue — see {@link PiiDetectorOptions}).\n * - **`block`** — a hard stop carrying the matches.\n * - **`flag`**  — the content passes but the matches are recorded.\n *\n * Clean text returns `{ type: \"allow\" }`.\n *\n * @example\n * ai.guardrail({ output: [ai.guardrail.pii()] }); // redact, default mask\n *\n * @example\n * ai.guardrail.pii({\n *   detect: [\"ssn\", \"credit-card\"],\n *   onMatch: \"redact\",\n *   mask: \"[PII:{label}]\",\n *   dictionary: [\"Project Aurora\"],\n * });\n */\nexport function pii(options: PiiDetectorOptions = {}): SyncGuardrailDetector {\n  const categories = options.detect ?? ALL_CATEGORIES;\n  const onMatch = options.onMatch ?? \"redact\";\n  const dictionary = options.dictionary ?? [];\n\n  return {\n    name: DETECTOR_NAME,\n    check(text: string): GuardrailVerdict {\n      const rawHits = [\n        ...scanCategories(text, categories),\n        ...scanDictionary(text, dictionary),\n      ];\n\n      if (rawHits.length === 0) {\n        return { type: \"allow\" };\n      }\n\n      const hits = dedupeHits(rawHits);\n      const matches = hits.map(toMatch);\n      const labels = [...new Set(hits.map(hit => hit.label))].join(\", \");\n\n      if (onMatch === \"block\") {\n        return {\n          type: \"block\",\n          reason: `PII detected: ${labels}.`,\n          matches,\n        };\n      }\n\n      if (onMatch === \"flag\") {\n        return {\n          type: \"flag\",\n          reason: `PII detected: ${labels}.`,\n          matches,\n        };\n      }\n\n      return {\n        type: \"redact\",\n        text: redactText(text, hits, options.mask),\n        reason: `Redacted PII: ${labels}.`,\n        matches,\n      };\n    },\n  };\n}\n"],"mappings":"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"}

package/esm/guard/detectors/topic.d.mts

@@ -0,0 +1,29 @@
+import { SyncGuardrailDetector } from "../contracts/guardrail.contract.mjs";
+import { TopicFilterOptions } from "../contracts/guard-options.type.mjs";
+//#region ../@warlock.js/ai/src/guard/detectors/topic.d.ts
+/**
+ * Build the built-in **topic filter** (`ai.guardrail.topic`) — a
+ * zero-runtime-dependency {@link GuardrailDetector} that gates text against a
+ * deny list, an allow list, or both.
+ *
+ * - **`deny`** — any term that appears triggers `onMatch`. A `string`
+ *   matches case-insensitively as a substring; a `RegExp` is tested as-is.
+ *   The deny list is checked first; the first hit decides the verdict.
+ * - **`allow`** — when set, text matching **none** of the allow terms
+ *   triggers `onMatch` (an allow-list miss). Text matching at least one
+ *   allow term passes the allow gate.
+ *
+ * `onMatch` is `"block"` (default) or `"flag"`. With neither list supplied
+ * the detector is a no-op that always allows.
+ *
+ * @example
+ * ai.guardrail.topic({ deny: ["medical advice", /diagnos\w+/i] });
+ *
+ * @example
+ * // Stay on-topic: anything not about billing is flagged.
+ * ai.guardrail.topic({ allow: ["billing", "invoice", "refund"], onMatch: "flag" });
+ */
+declare function topic(options: TopicFilterOptions): SyncGuardrailDetector;
+//#endregion
+export { topic };
+//# sourceMappingURL=topic.d.mts.map

package/esm/guard/detectors/topic.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"topic.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/guard/detectors/topic.ts"],"mappings":";;;;;;;AAsEA;;;;;;;;AAAyE;;;;;;;;;;iBAAzD,KAAA,CAAM,OAAA,EAAS,kBAAA,GAAqB,qBAAqB"}

package/esm/guard/detectors/topic.mjs

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

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

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

package/esm/guard/errors.d.mts

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/guard/errors.ts"],"mappings":";;;;;;;;cAuBa,2BAAA"}

package/esm/guard/errors.mjs

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

package/esm/guard/errors.mjs.map

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

package/esm/guard/guard.d.mts

@@ -0,0 +1,67 @@
+import { AgentMiddleware } from "../contracts/middleware/middleware.contract.mjs";
+import { GuardrailMatch, GuardrailPhase } from "./contracts/verdict.type.mjs";
+import { GuardOptions } from "./contracts/guard-options.type.mjs";
+//#region ../@warlock.js/ai/src/guard/guard.d.ts
+/**
+ * One flagged match recorded into `ctx.state`. Mirrors the
+ * {@link GuardrailVerdict} `flag` shape plus the phase it fired at, so an
+ * observer can reconstruct *what* tripped *where* without re-running the
+ * detector.
+ */
+interface FlagRecord {
+  /** The detector that produced the flag. */
+  readonly detector: string;
+  /** Where the detector was running. */
+  readonly phase: GuardrailPhase;
+  /** The detector's human-readable reason. */
+  readonly reason: string;
+  /** The matches the detector recorded. */
+  readonly matches: readonly GuardrailMatch[];
+}
+/**
+ * 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] });
+ */
+declare function guard(options: GuardOptions): AgentMiddleware;
+//#endregion
+export { FlagRecord, guard };
+//# sourceMappingURL=guard.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guard.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/guard/guard.ts"],"mappings":";;;;;;;;AAsCA;;UAAiB,UAAA;EAQ0B;EAAA,SANhC,QAAA;EAEA;EAAA,SAAA,KAAA,EAAO,cAAA;EAEP;EAAA,SAAA,MAAA;EAEkB;EAAA,SAAlB,OAAA,WAAkB,cAAc;AAAA;AA+N3C;;;;;;;;AAA6D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAA7D,iBAAgB,KAAA,CAAM,OAAA,EAAS,YAAA,GAAe,eAAe"}