@warlock.js/ai 4.8.2 → 4.9.1

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

@@ -1 +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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"}
+{"version":3,"file":"pii.mjs","names":[],"sources":["../../../../../../../../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

@@ -1,6 +1,6 @@
 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
+//#region ../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

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

@@ -1 +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"}
+{"version":3,"file":"topic.d.mts","names":[],"sources":["../../../../../../../../ai/src/guard/detectors/topic.ts"],"mappings":";;;;;;;AAsEA;;;;;;;;AAAyE;;;;;;;;;;iBAAzD,KAAA,CAAM,OAAA,EAAS,kBAAA,GAAqB,qBAAqB"}

package/esm/guard/detectors/topic.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/guard/detectors/topic.ts
+//#region ../ai/src/guard/detectors/topic.ts
 /** Detector name, used as the namespace prefix on every {@link GuardrailMatch.rule}. */
 const DETECTOR_NAME = "topic";
 /**

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

@@ -1 +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"}
+{"version":3,"file":"topic.mjs","names":[],"sources":["../../../../../../../../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

@@ -1,6 +1,6 @@
 import { GuardrailViolationError, GuardrailViolationErrorOptions } from "../errors/guardrail-violation-error.mjs";
 
-//#region ../@warlock.js/ai/src/guard/errors.d.ts
+//#region ../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

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

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

package/esm/guard/errors.mjs

@@ -1,6 +1,6 @@
 import { GuardrailViolationError } from "../errors/guardrail-violation-error.mjs";
 
-//#region ../@warlock.js/ai/src/guard/errors.ts
+//#region ../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

package/esm/guard/errors.mjs.map

@@ -1 +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"}
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../../../../../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

@@ -1,7 +1,7 @@
 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
+//#region ../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

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

@@ -1 +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"}
+{"version":3,"file":"guard.d.mts","names":[],"sources":["../../../../../../../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"}

package/esm/guard/guard.mjs

@@ -3,7 +3,7 @@ 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
+//#region ../ai/src/guard/guard.ts
 /** Default middleware name when the caller supplies none. */
 const DEFAULT_NAME = "guardrail";
 /**

package/esm/guard/guard.mjs.map

@@ -1 +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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"}
+{"version":3,"file":"guard.mjs","names":[],"sources":["../../../../../../../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

@@ -1,7 +1,7 @@
 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
+//#region ../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

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

@@ -1 +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"}
+{"version":3,"file":"guardrail.d.mts","names":[],"sources":["../../../../../../../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

@@ -5,7 +5,7 @@ import { moderation } from "./detectors/moderation.mjs";
 import "./detectors/index.mjs";
 import { guard } from "./guard.mjs";
 
-//#region ../@warlock.js/ai/src/guard/guardrail.ts
+//#region ../ai/src/guard/guardrail.ts
 /**
 * The `ai.guardrail` value: the {@link guard} factory with the detector
 * factories assigned onto it. Built once and shared.

package/esm/guard/guardrail.mjs.map

@@ -1 +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"}
+{"version":3,"file":"guardrail.mjs","names":[],"sources":["../../../../../../../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

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/human/contracts/approval.type.d.ts
+//#region ../ai/src/human/contracts/approval.type.d.ts
 /**
  * What a human can do to a gated tool call.
  *

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

@@ -1 +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"}
+{"version":3,"file":"approval.type.d.mts","names":[],"sources":["../../../../../../../../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

@@ -1,7 +1,7 @@
 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
+//#region ../ai/src/human/contracts/human-approval.type.d.ts
 /**
  * Options for `ai.human.approval(options)` — the `tool.before`
  * approval-gate middleware factory.

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

@@ -1 +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"}
+{"version":3,"file":"human-approval.type.d.mts","names":[],"sources":["../../../../../../../../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/interrupt-store.contract.d.mts

@@ -1,6 +1,6 @@
 import { ApprovalRequest } from "./approval.type.mjs";
 
-//#region ../@warlock.js/ai/src/human/contracts/interrupt-store.contract.d.ts
+//#region ../ai/src/human/contracts/interrupt-store.contract.d.ts
 /**
  * Lifecycle status of a persisted interrupt.
  *

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

@@ -1 +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"}
+{"version":3,"file":"interrupt-store.contract.d.mts","names":[],"sources":["../../../../../../../../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"}

package/esm/human/contracts/resume.type.d.mts

@@ -4,7 +4,7 @@ import { AgentExecuteOptions } from "../../contracts/agent/agent-options.type.mj
 import { ApprovalDecision } from "./approval.type.mjs";
 import { InterruptStore } from "./interrupt-store.contract.mjs";
 
-//#region ../@warlock.js/ai/src/human/contracts/resume.type.d.ts
+//#region ../ai/src/human/contracts/resume.type.d.ts
 /**
  * Options for `ai.human.resume(interruptId, decision, options)` — the
  * out-of-process resume entry point behind durable human-in-the-loop

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

@@ -1 +1 @@
-{"version":3,"file":"resume.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/human/contracts/resume.type.ts"],"mappings":";;;;;;;;;AA0BA;;;;;;;;;;;;;;;;;;UAAiB,aAAA;EA0BsB;;AAAO;AAgB9C;EArCE,KAAA,EAAO,cAAA;EAqCe;;;;;EA9BtB,KAAA,GAAQ,aAAA,CAAc,OAAA;EA8BC;;;;;EAvBvB,KAAA;EA+Ba;;;;;EAxBb,cAAA,GAAiB,mBAAA,CAAoB,OAAA;AAAA;;;;;;;;;;;;;;KAgB3B,YAAA;EAEN,IAAA;EAEA,WAAA;EAEA,QAAA,EAAU,gBAAA;EAEV,MAAA,GAAS,WAAA,CAAY,OAAA;AAAA;EAGrB,IAAA;EAEA,WAAA;AAAA"}
+{"version":3,"file":"resume.type.d.mts","names":[],"sources":["../../../../../../../../ai/src/human/contracts/resume.type.ts"],"mappings":";;;;;;;;;AA0BA;;;;;;;;;;;;;;;;;;UAAiB,aAAA;EA0BsB;;AAAO;AAgB9C;EArCE,KAAA,EAAO,cAAA;EAqCe;;;;;EA9BtB,KAAA,GAAQ,aAAA,CAAc,OAAA;EA8BC;;;;;EAvBvB,KAAA;EA+Ba;;;;;EAxBb,cAAA,GAAiB,mBAAA,CAAoB,OAAA;AAAA;;;;;;;;;;;;;;KAgB3B,YAAA;EAEN,IAAA;EAEA,WAAA;EAEA,QAAA,EAAU,gBAAA;EAEV,MAAA,GAAS,WAAA,CAAY,OAAA;AAAA;EAGrB,IAAA;EAEA,WAAA;AAAA"}

package/esm/human/errors.d.mts

@@ -1,6 +1,6 @@
 import { AIError, AIErrorOptions } from "../errors/ai-error.mjs";
 
-//#region ../@warlock.js/ai/src/human/errors.d.ts
+//#region ../ai/src/human/errors.d.ts
 /**
  * Stable, machine-readable codes this package raises.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/human/errors.ts"],"mappings":";;;;;AAaA;;;;AAA0B;AAO1B;;;KAPY,cAAA;AASC;AAyBb;;;;AAzBa,KAFD,8BAAA,GAAiC,cAAc;EA6BzC,yDA3BhB,WAAW;AAAA;;;;AA6BgE;AAa7E;;;;;;;;AAIU;AAmBV;;;;;;;;;cAxCa,uBAAA,SAAgC,OAAO;EA+Cd;EAAA,SA7CpB,WAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,8BAAA;AAAA;;;;;;KAanC,4BAAA,GAA+B,cAAc;2DAEvD,MAAA;EAEA,QAAA;AAAA;;;;;;;;;;;;;;;;;cAmBW,qBAAA,SAA8B,OAAO;;WAEhC,MAAA;;WAGA,QAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,4BAAA;AAAA"}
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../../../../../../../ai/src/human/errors.ts"],"mappings":";;;;;AAaA;;;;AAA0B;AAO1B;;;KAPY,cAAA;AASC;AAyBb;;;;AAzBa,KAFD,8BAAA,GAAiC,cAAc;EA6BzC,yDA3BhB,WAAW;AAAA;;;;AA6BgE;AAa7E;;;;;;;;AAIU;AAmBV;;;;;;;;;cAxCa,uBAAA,SAAgC,OAAO;EA+Cd;EAAA,SA7CpB,WAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,8BAAA;AAAA;;;;;;KAanC,4BAAA,GAA+B,cAAc;2DAEvD,MAAA;EAEA,QAAA;AAAA;;;;;;;;;;;;;;;;;cAmBW,qBAAA,SAA8B,OAAO;;WAEhC,MAAA;;WAGA,QAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,4BAAA;AAAA"}

package/esm/human/errors.mjs

@@ -1,6 +1,6 @@
 import { AIError } from "../errors/ai-error.mjs";
 
-//#region ../@warlock.js/ai/src/human/errors.ts
+//#region ../ai/src/human/errors.ts
 /**
 * A durable approval handler suspended the run rather than denying the
 * call.

package/esm/human/errors.mjs.map

@@ -1 +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"}
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../../../../../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/human/human-approval.d.mts

@@ -1,6 +1,6 @@
 import { AgentMiddleware } from "../contracts/middleware/middleware.contract.mjs";
 import { HumanApprovalOptions } from "./contracts/human-approval.type.mjs";
-//#region ../@warlock.js/ai/src/human/human-approval.d.ts
+//#region ../ai/src/human/human-approval.d.ts
 /**
  * Human-in-the-loop approval gate for an agent's tool calls — the
  * middleware behind `ai.human.approval(options)`.

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

@@ -1 +1 @@
-{"version":3,"file":"human-approval.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/human/human-approval.ts"],"mappings":";;;;;;AAyKA;;;;;;;;AAA6E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAA7D,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,eAAe"}
+{"version":3,"file":"human-approval.d.mts","names":[],"sources":["../../../../../../../ai/src/human/human-approval.ts"],"mappings":";;;;;;AAyKA;;;;;;;;AAA6E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAA7D,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,eAAe"}

package/esm/human/human-approval.mjs

@@ -3,7 +3,7 @@ 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
+//#region ../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. */

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

@@ -1 +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"}
+{"version":3,"file":"human-approval.mjs","names":[],"sources":["../../../../../../../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/human/policy.d.mts

@@ -1,5 +1,5 @@
 import { InterruptPolicy, PolicyContext } from "./contracts/approval.type.mjs";
-//#region ../@warlock.js/ai/src/human/policy.d.ts
+//#region ../ai/src/human/policy.d.ts
 /**
  * Verdict of evaluating an {@link InterruptPolicy} against a single
  * pending tool call.

package/esm/human/policy.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"policy.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/human/policy.ts"],"mappings":";;;;;AAeA;;;;AAKM;AAoDN;;;;;UAzDiB,aAAA;EA4DD;EA1Dd,gBAAA;EAwDQ;EArDR,IAAI;AAAA;;;;AAuDU;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAHA,cAAA,CACd,MAAA,EAAQ,eAAA,EACR,OAAA,EAAS,aAAA,GACR,aAAA"}
+{"version":3,"file":"policy.d.mts","names":[],"sources":["../../../../../../../ai/src/human/policy.ts"],"mappings":";;;;;AAeA;;;;AAKM;AAoDN;;;;;UAzDiB,aAAA;EA4DD;EA1Dd,gBAAA;EAwDQ;EArDR,IAAI;AAAA;;;;AAuDU;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAHA,cAAA,CACd,MAAA,EAAQ,eAAA,EACR,OAAA,EAAS,aAAA,GACR,aAAA"}

package/esm/human/policy.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/human/policy.ts
+//#region ../ai/src/human/policy.ts
 /**
 * A verdict that lets a call through untouched. Frozen and shared so the
 * (common) skip path allocates nothing.

package/esm/human/policy.mjs.map

@@ -1 +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"}
+{"version":3,"file":"policy.mjs","names":[],"sources":["../../../../../../../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"}

package/esm/human/register.mjs

@@ -5,7 +5,7 @@ import { pg } from "./stores/pg.mjs";
 import { redis } from "./stores/redis.mjs";
 import "./stores/index.mjs";
 
-//#region ../@warlock.js/ai/src/human/register.ts
+//#region ../ai/src/human/register.ts
 /**
 * The assembled `ai.human.*` namespace — the human-in-the-loop surface
 * mounted onto the shared `ai` object in `../ai`.

package/esm/human/register.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"register.mjs","names":["interruptMemory","interruptPg","interruptRedis"],"sources":["../../../../../../../@warlock.js/ai/src/human/register.ts"],"sourcesContent":["import { humanApproval } from \"./human-approval\";\nimport { resume } from \"./resume\";\nimport { interruptMemory, interruptPg, interruptRedis } from \"./stores\";\n\n/**\n * The assembled `ai.human.*` namespace — the human-in-the-loop surface\n * mounted onto the shared `ai` object in `../ai`.\n *\n * - `approval(options)` — the `tool.before` approval-gate middleware.\n * - `resume(id, decision, options)` — out-of-process durable resume.\n * - `interrupt.{memory,pg,redis}()` — the\n *   {@link import(\"./contracts\").InterruptStore} factories (memory ships\n *   real; pg/redis lazily import their optional-peer driver).\n *\n * Declared as a standalone object so `../ai` can spread it onto the `ai`\n * literal and pin the `Ai.human` member to this exact shape with no casts.\n * Lives here (not inlined into `../ai`) to keep the human factories grouped\n * with the rest of the human module and avoid `../ai` reaching into each\n * store/middleware file directly.\n */\nexport const human = {\n  approval: humanApproval,\n  resume,\n  interrupt: {\n    memory: interruptMemory,\n    pg: interruptPg,\n    redis: interruptRedis,\n  },\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAoBA,MAAa,QAAQ;CACnB,UAAU;CACV;CACA,WAAW;EACDA;EACJC;EACGC;CACT;AACF"}
+{"version":3,"file":"register.mjs","names":["interruptMemory","interruptPg","interruptRedis"],"sources":["../../../../../../../ai/src/human/register.ts"],"sourcesContent":["import { humanApproval } from \"./human-approval\";\nimport { resume } from \"./resume\";\nimport { interruptMemory, interruptPg, interruptRedis } from \"./stores\";\n\n/**\n * The assembled `ai.human.*` namespace — the human-in-the-loop surface\n * mounted onto the shared `ai` object in `../ai`.\n *\n * - `approval(options)` — the `tool.before` approval-gate middleware.\n * - `resume(id, decision, options)` — out-of-process durable resume.\n * - `interrupt.{memory,pg,redis}()` — the\n *   {@link import(\"./contracts\").InterruptStore} factories (memory ships\n *   real; pg/redis lazily import their optional-peer driver).\n *\n * Declared as a standalone object so `../ai` can spread it onto the `ai`\n * literal and pin the `Ai.human` member to this exact shape with no casts.\n * Lives here (not inlined into `../ai`) to keep the human factories grouped\n * with the rest of the human module and avoid `../ai` reaching into each\n * store/middleware file directly.\n */\nexport const human = {\n  approval: humanApproval,\n  resume,\n  interrupt: {\n    memory: interruptMemory,\n    pg: interruptPg,\n    redis: interruptRedis,\n  },\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAoBA,MAAa,QAAQ;CACnB,UAAU;CACV;CACA,WAAW;EACDA;EACJC;EACGC;CACT;AACF"}

package/esm/human/resume-seed.mjs

@@ -1,4 +1,4 @@
-//#region ../@warlock.js/ai/src/human/resume-seed.ts
+//#region ../ai/src/human/resume-seed.ts
 /**
 * Process-local registry of decisions pre-seeded for a durable re-run.
 *