@warlock.js/ai 4.3.0 → 4.5.0

package/esm/eval/report-junit.mjs

@@ -0,0 +1,60 @@
+//#region ../@warlock.js/ai/src/eval/report-junit.ts
+/**
+* Escape the five XML predefined entities so arbitrary text (case names,
+* failure reasons, agent names) is safe inside an attribute value or
+* element body. Covers `&`, `<`, `>`, `"`, and `'`.
+*/
+function escapeXml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+/**
+* Build the `<failure>` body for a failed case: the joined reasons of
+* every non-passing scorer, falling back to a generic message when a
+* scorer offered no reason (or the failure was an agent error).
+*/
+function failureMessage(entry) {
+	if (entry.result.error) return `agent error: ${entry.result.error.message}`;
+	const reasons = entry.scores.filter((score) => score.passed === false).map((score) => score.reason).filter((reason) => typeof reason === "string" && reason !== "");
+	if (reasons.length > 0) return reasons.join("; ");
+	return "case did not pass";
+}
+/**
+* Serialize an {@link EvalReport} to a JUnit-XML string for CI ingestion.
+*
+* **Role.** A pure, runner-decoupled reporter: one `<testsuite>` whose
+* name is the agent, one `<testcase>` per eval case, a `<failure>` child
+* on each case that did not pass (with the joined scorer reasons), and a
+* `time` attribute carrying the case / suite duration in **seconds**
+* (JUnit's unit; the report stores milliseconds).
+*
+* XML is hand-emitted (no `xml` dependency) and every dynamic value is
+* entity-escaped via {@link escapeXml}.
+*
+* @example
+* await writeFile("./report.junit.xml", toJUnit(report));
+*/
+function toJUnit(report) {
+	const suiteName = escapeXml(report.agentName);
+	const suiteTime = (report.duration / 1e3).toFixed(3);
+	const lines = [];
+	lines.push("<?xml version=\"1.0\" encoding=\"UTF-8\"?>");
+	lines.push(`<testsuite name="${suiteName}" tests="${report.total}" failures="${report.failedCount}" time="${suiteTime}">`);
+	for (const entry of report.cases) {
+		const caseName = escapeXml(entry.case.name);
+		const caseTime = (entry.duration / 1e3).toFixed(3);
+		if (entry.passed) {
+			lines.push(`  <testcase name="${caseName}" classname="${suiteName}" time="${caseTime}"/>`);
+			continue;
+		}
+		const message = failureMessage(entry);
+		lines.push(`  <testcase name="${caseName}" classname="${suiteName}" time="${caseTime}">`);
+		lines.push(`    <failure message="${escapeXml(message)}">${escapeXml(message)}</failure>`);
+		lines.push("  </testcase>");
+	}
+	lines.push("</testsuite>");
+	return lines.join("\n");
+}
+
+//#endregion
+export { toJUnit };
+//# sourceMappingURL=report-junit.mjs.map

package/esm/eval/report-junit.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-junit.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/eval/report-junit.ts"],"sourcesContent":["import type { EvalCaseResult, EvalReport } from \"../contracts/agent/eval.type\";\n\n/**\n * Escape the five XML predefined entities so arbitrary text (case names,\n * failure reasons, agent names) is safe inside an attribute value or\n * element body. Covers `&`, `<`, `>`, `\"`, and `'`.\n */\nfunction escapeXml(value: string): string {\n  return value\n    .replace(/&/g, \"&amp;\")\n    .replace(/</g, \"&lt;\")\n    .replace(/>/g, \"&gt;\")\n    .replace(/\"/g, \"&quot;\")\n    .replace(/'/g, \"&apos;\");\n}\n\n/**\n * Build the `<failure>` body for a failed case: the joined reasons of\n * every non-passing scorer, falling back to a generic message when a\n * scorer offered no reason (or the failure was an agent error).\n */\nfunction failureMessage(entry: EvalCaseResult): string {\n  if (entry.result.error) {\n    return `agent error: ${entry.result.error.message}`;\n  }\n\n  const reasons = entry.scores\n    .filter((score) => score.passed === false)\n    .map((score) => score.reason)\n    .filter((reason): reason is string => typeof reason === \"string\" && reason !== \"\");\n\n  if (reasons.length > 0) {\n    return reasons.join(\"; \");\n  }\n\n  return \"case did not pass\";\n}\n\n/**\n * Serialize an {@link EvalReport} to a JUnit-XML string for CI ingestion.\n *\n * **Role.** A pure, runner-decoupled reporter: one `<testsuite>` whose\n * name is the agent, one `<testcase>` per eval case, a `<failure>` child\n * on each case that did not pass (with the joined scorer reasons), and a\n * `time` attribute carrying the case / suite duration in **seconds**\n * (JUnit's unit; the report stores milliseconds).\n *\n * XML is hand-emitted (no `xml` dependency) and every dynamic value is\n * entity-escaped via {@link escapeXml}.\n *\n * @example\n * await writeFile(\"./report.junit.xml\", toJUnit(report));\n */\nexport function toJUnit(report: EvalReport): string {\n  const suiteName = escapeXml(report.agentName);\n  const suiteTime = (report.duration / 1000).toFixed(3);\n\n  const lines: string[] = [];\n\n  lines.push('<?xml version=\"1.0\" encoding=\"UTF-8\"?>');\n  lines.push(\n    `<testsuite name=\"${suiteName}\" tests=\"${report.total}\" failures=\"${report.failedCount}\" time=\"${suiteTime}\">`,\n  );\n\n  for (const entry of report.cases) {\n    const caseName = escapeXml(entry.case.name);\n    const caseTime = (entry.duration / 1000).toFixed(3);\n\n    if (entry.passed) {\n      lines.push(\n        `  <testcase name=\"${caseName}\" classname=\"${suiteName}\" time=\"${caseTime}\"/>`,\n      );\n\n      continue;\n    }\n\n    const message = failureMessage(entry);\n    lines.push(\n      `  <testcase name=\"${caseName}\" classname=\"${suiteName}\" time=\"${caseTime}\">`,\n    );\n    lines.push(\n      `    <failure message=\"${escapeXml(message)}\">${escapeXml(message)}</failure>`,\n    );\n    lines.push(\"  </testcase>\");\n  }\n\n  lines.push(\"</testsuite>\");\n\n  return lines.join(\"\\n\");\n}\n"],"mappings":";;;;;;AAOA,SAAS,UAAU,OAAuB;CACxC,OAAO,MACJ,QAAQ,MAAM,OAAO,CAAC,CACtB,QAAQ,MAAM,MAAM,CAAC,CACrB,QAAQ,MAAM,MAAM,CAAC,CACrB,QAAQ,MAAM,QAAQ,CAAC,CACvB,QAAQ,MAAM,QAAQ;AAC3B;;;;;;AAOA,SAAS,eAAe,OAA+B;CACrD,IAAI,MAAM,OAAO,OACf,OAAO,gBAAgB,MAAM,OAAO,MAAM;CAG5C,MAAM,UAAU,MAAM,OACnB,QAAQ,UAAU,MAAM,WAAW,KAAK,CAAC,CACzC,KAAK,UAAU,MAAM,MAAM,CAAC,CAC5B,QAAQ,WAA6B,OAAO,WAAW,YAAY,WAAW,EAAE;CAEnF,IAAI,QAAQ,SAAS,GACnB,OAAO,QAAQ,KAAK,IAAI;CAG1B,OAAO;AACT;;;;;;;;;;;;;;;;AAiBA,SAAgB,QAAQ,QAA4B;CAClD,MAAM,YAAY,UAAU,OAAO,SAAS;CAC5C,MAAM,aAAa,OAAO,WAAW,IAAI,CAAE,QAAQ,CAAC;CAEpD,MAAM,QAAkB,CAAC;CAEzB,MAAM,KAAK,4CAAwC;CACnD,MAAM,KACJ,oBAAoB,UAAU,WAAW,OAAO,MAAM,cAAc,OAAO,YAAY,UAAU,UAAU,GAC7G;CAEA,KAAK,MAAM,SAAS,OAAO,OAAO;EAChC,MAAM,WAAW,UAAU,MAAM,KAAK,IAAI;EAC1C,MAAM,YAAY,MAAM,WAAW,IAAI,CAAE,QAAQ,CAAC;EAElD,IAAI,MAAM,QAAQ;GAChB,MAAM,KACJ,qBAAqB,SAAS,eAAe,UAAU,UAAU,SAAS,IAC5E;GAEA;EACF;EAEA,MAAM,UAAU,eAAe,KAAK;EACpC,MAAM,KACJ,qBAAqB,SAAS,eAAe,UAAU,UAAU,SAAS,GAC5E;EACA,MAAM,KACJ,yBAAyB,UAAU,OAAO,EAAE,IAAI,UAAU,OAAO,EAAE,WACrE;EACA,MAAM,KAAK,eAAe;CAC5B;CAEA,MAAM,KAAK,cAAc;CAEzB,OAAO,MAAM,KAAK,IAAI;AACxB"}

package/esm/guard/contracts/guard-options.type.d.mts

@@ -0,0 +1,165 @@
+import { MiddlewareTripContext } from "../../contracts/middleware/middleware-context.type.mjs";
+import { GuardrailAction, GuardrailMatch, GuardrailPhase } from "./verdict.type.mjs";
+import { GuardrailDetector } from "./guardrail.contract.mjs";
+import { OpenAiClientLike } from "./openai-client.contract.mjs";
+
+//#region ../@warlock.js/ai/src/guard/contracts/guard-options.type.d.ts
+/**
+ * The payload handed to {@link GuardrailEscalation.onBlock} when a detector
+ * returns `{ type: "block", escalate: true }`. The factory builds it just
+ * before throwing the `GuardrailViolationError`, so a host can route the
+ * hard block to a human-review surface.
+ */
+interface GuardrailBlockEvent {
+  /** Where the block fired: input prompt, output, or tool args. */
+  readonly phase: GuardrailPhase;
+  /** The detector's human-readable reason. */
+  readonly reason: string;
+  /** The matches that triggered the block, when the detector reported them. */
+  readonly matches?: readonly GuardrailMatch[];
+  /** The live middleware trip context (state, messages, agent, model, signal). */
+  readonly ctx: MiddlewareTripContext;
+}
+/**
+ * Escalation seam for composing a hard block with a human-review surface.
+ *
+ * The callback fires **only** for a verdict of `{ type: "block", escalate:
+ * true }`, awaited *before* the `GuardrailViolationError` is thrown. It is a
+ * plain callback by design — `ai-guard` takes no dependency on the deferred
+ * human-step machinery; the host wires its own review queue / resume loop
+ * inside `onBlock`.
+ */
+interface GuardrailEscalation {
+  /** Route a `{ type: "block", escalate: true }` verdict to a human. */
+  onBlock?(event: GuardrailBlockEvent): void | Promise<void>;
+}
+/**
+ * Configuration for the {@link guard} factory (surfaced as
+ * `ai.guardrail(options)`). Each phase array runs in registration order;
+ * the first non-`allow` verdict decides the action for that phase.
+ *
+ * At least one of `input` / `output` / `tool` should be supplied — a guard
+ * with no detectors is a no-op middleware.
+ */
+interface GuardOptions {
+  /**
+   * Override the middleware name — surfaces on
+   * `GuardrailViolationError.guardrail` and as the `ctx.state` namespace so
+   * operators can tell two guards apart. Default `"guardrail"`.
+   */
+  name?: string;
+  /**
+   * Detectors run on the outbound prompt at `trip.before`.
+   *
+   * **Input redaction is not supported in v1:** the core `trip.before` hook
+   * can only short-circuit, not rewrite-and-continue, so a `redact` verdict
+   * here is treated as a `block`. Input detectors are effectively
+   * `block` / `flag` only.
+   */
+  input?: readonly GuardrailDetector[];
+  /** Detectors run on `response.content` at `trip.after`. Support `redact`. */
+  output?: readonly GuardrailDetector[];
+  /**
+   * Detectors run on `JSON.stringify(toolArgs)` at `tool.before`. A
+   * `redact` verdict here is treated as a `block` (silently rewriting tool
+   * arguments changes side-effects unpredictably).
+   */
+  tool?: readonly GuardrailDetector[];
+  /**
+   * The tool names the `tool` detectors apply to. Omit to apply to every
+   * tool. When set, the middleware's `tool` hooks are scoped via the core
+   * `forTool(toolNames, mw)` helper; `trip` hooks are unaffected.
+   */
+  toolNames?: string | readonly string[];
+  /** Compose a `{ type: "block", escalate: true }` verdict with a human. */
+  escalation?: GuardrailEscalation;
+}
+/**
+ * The PII categories the built-in `pii` detector can scan for. Each is a
+ * linear (anchored, no nested quantifiers) regex — safe against catastrophic
+ * backtracking.
+ */
+type PiiCategory = "ssn" | "email" | "phone" | "credit-card" | "ipv4";
+/**
+ * Options for the built-in `pii` detector (`ai.guardrail.pii`). All built-in
+ * PII matching is regex / exact-string only — zero runtime dependency.
+ */
+interface PiiDetectorOptions {
+  /** Which categories to scan for. Default: every {@link PiiCategory}. */
+  detect?: readonly PiiCategory[];
+  /** What to do on a match. Default `"redact"`. */
+  onMatch?: Extract<GuardrailAction, "redact" | "block" | "flag">;
+  /**
+   * Replacement template used on `redact`. Supports the `{label}` token,
+   * substituted with the matched category — e.g. `"[REDACTED:{label}]"`.
+   * Default masks the matched span with a fixed placeholder.
+   */
+  mask?: string;
+  /** Extra exact-string terms to treat as PII alongside the built-in regexes. */
+  dictionary?: readonly string[];
+}
+/**
+ * Options for the built-in `topic` filter (`ai.guardrail.topic`). Matches a
+ * case-insensitive substring or a `RegExp` against the inspected text.
+ */
+interface TopicFilterOptions {
+  /**
+   * Deny-list terms / phrases. A `string` matches case-insensitively as a
+   * substring; a `RegExp` is tested as-is. Any hit triggers `onMatch`.
+   */
+  deny?: readonly (string | RegExp)[];
+  /**
+   * Allow-list terms / phrases. When set, text matching **none** of these
+   * triggers `onMatch` (an allow-list miss).
+   */
+  allow?: readonly (string | RegExp)[];
+  /** Action on a deny hit (or an allow-list miss). Default `"block"`. */
+  onMatch?: Extract<GuardrailAction, "block" | "flag">;
+  /** Override the verdict's human-readable reason. */
+  reason?: string;
+}
+/**
+ * Options for the built-in `injection` detector (`ai.guardrail.injection`).
+ * Matches a built-in set of jailbreak / prompt-injection marker phrases,
+ * extensible with caller-supplied markers.
+ */
+interface InjectionDetectorOptions {
+  /**
+   * Extra marker phrases beyond the built-in jailbreak / prompt-injection
+   * set. A `string` matches case-insensitively as a substring; a `RegExp`
+   * is tested as-is.
+   */
+  markers?: readonly (string | RegExp)[];
+  /**
+   * Action on a match. Default `"flag"` — callers commonly escalate to
+   * `"block"` on the input phase.
+   */
+  onMatch?: Extract<GuardrailAction, "block" | "flag">;
+}
+/**
+ * Options for the optional `moderation` detector (`ai.guardrail.moderation`),
+ * backed by a lazily-imported `openai` peer. Importing `@warlock.js/ai`
+ * never forces `openai` to resolve; the detector throws a curated install
+ * string on first `check()` when the SDK is absent.
+ */
+interface OpenAiModerationOptions {
+  /**
+   * A pre-built OpenAI-compatible client (any object matching
+   * {@link OpenAiClientLike}, including a real `OpenAI` instance). When
+   * supplied, the detector calls it directly and never imports the SDK —
+   * the bring-your-own-client / test escape hatch.
+   */
+  client?: OpenAiClientLike;
+  /** OpenAI API key. Reads `OPENAI_API_KEY` from the environment when omitted. */
+  apiKey?: string;
+  /** Moderation model to call. Default `"omni-moderation-latest"`. */
+  model?: string;
+  /**
+   * Categories that escalate to `block`; every other flagged category
+   * produces a `flag` verdict instead. Omit to `flag` on any category.
+   */
+  blockOn?: readonly string[];
+}
+//#endregion
+export { GuardOptions, GuardrailBlockEvent, GuardrailEscalation, InjectionDetectorOptions, OpenAiModerationOptions, PiiCategory, PiiDetectorOptions, TopicFilterOptions };
+//# sourceMappingURL=guard-options.type.d.mts.map

package/esm/guard/contracts/guard-options.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guard-options.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/guard/contracts/guard-options.type.ts"],"mappings":";;;;;;;;AAeA;;;;UAAiB,mBAAA;EAQD;EAAA,SANL,KAAA,EAAO,cAAA;EAMmB;EAAA,SAJ1B,MAAA;EAFO;EAAA,SAIP,OAAA,YAAmB,cAAA;EAAnB;EAAA,SAEA,GAAA,EAAK,qBAAA;AAAA;;;AAAqB;AAYrC;;;;;;UAAiB,mBAAA;EAE8B;EAA7C,OAAA,EAAS,KAAA,EAAO,mBAAA,UAA6B,OAAO;AAAA;AAWtD;;;;;;;;AAAA,UAAiB,YAAA;EAMf;;;;;EAAA,IAAA;EAiBgB;;;;;AAQgB;AAQlC;;EAxBE,KAAA,YAAiB,iBAAA;EAwBI;EAtBrB,MAAA,YAAkB,iBAAA;EA4BH;;;;;EAtBf,IAAA,YAAgB,iBAAA;EA0BC;;;;;EApBjB,SAAA;EAoBkB;EAlBlB,UAAA,GAAa,mBAAA;AAAA;;AA0BH;AAOZ;;;KAzBY,WAAA;;;;;UAMK,kBAAA;EAwBf;EAtBA,MAAA,YAAkB,WAAA;EA2BlB;EAzBA,OAAA,GAAU,OAAA,CAAQ,eAAA;EA2BlB;;;;;EArBA,IAAA;EA+Be;EA7Bf,UAAA;AAAA;;;;;UAOe,kBAAA;EA4Bf;;;;EAvBA,IAAA,sBAA0B,MAAA;EA4BO;AAAA;AASnC;;EAhCE,KAAA,sBAA2B,MAAA;EAuCF;EArCzB,OAAA,GAAU,OAAA,CAAQ,eAAA;EAqCT;EAnCT,MAAA;AAAA;;;AA4CO;;;UApCQ,wBAAA;;;;;;EAMf,OAAA,sBAA6B,MAAA;;;;;EAK7B,OAAA,GAAU,OAAA,CAAQ,eAAA;AAAA;;;;;;;UASH,uBAAA;;;;;;;EAOf,MAAA,GAAS,gBAAgB;;EAEzB,MAAA;;EAEA,KAAA;;;;;EAKA,OAAA;AAAA"}

package/esm/guard/contracts/guardrail.contract.d.mts

@@ -0,0 +1,78 @@
+import { MiddlewareTripContext } from "../../contracts/middleware/middleware-context.type.mjs";
+import { GuardrailPhase, GuardrailVerdict } from "./verdict.type.mjs";
+
+//#region ../@warlock.js/ai/src/guard/contracts/guardrail.contract.d.ts
+/**
+ * The stable context every detector receives on each `check()` — the phase
+ * it is running at plus the live middleware trip context.
+ *
+ * A detector reads `phase` to branch on *where* it is running (e.g. an
+ * injection detector escalating to `block` on `"input"` but only `flag` on
+ * `"output"`), and `ctx` for the surrounding run identity (`state`,
+ * `messages`, `agent`, `model`, `signal`). A detector must never mutate
+ * `ctx` — it is a read-only view; the factory owns all pipeline effects.
+ */
+interface GuardrailDetectorContext {
+  /** Where this detector is running: input prompt, output, or tool args. */
+  readonly phase: GuardrailPhase;
+  /** The live middleware trip context (state, messages, agent, model, signal). */
+  readonly ctx: MiddlewareTripContext;
+}
+/**
+ * A guardrail detector — the unit of content intelligence. Inspects a piece
+ * of text and returns a {@link GuardrailVerdict}. Sync or async (an async
+ * `check` routes to an external moderation API).
+ *
+ * A detector has **no** knowledge of hooks, ordering, or `ctx.state`
+ * mutation — the {@link guard} factory is the thin adapter that runs
+ * detectors at the right hook points and translates verdicts into the
+ * pipeline's throw / return / record mechanics.
+ *
+ * @example
+ * const noShouting: GuardrailDetector = {
+ *   name: "no-shouting",
+ *   check(text) {
+ *     return text === text.toUpperCase() && text.length > 0
+ *       ? { type: "flag", reason: "all caps", matches: [{ rule: "no-shouting" }] }
+ *       : { type: "allow" };
+ *   },
+ * };
+ */
+interface GuardrailDetector {
+  /**
+   * Kebab-case identifier, used as the rule prefix in {@link GuardrailMatch}
+   * and surfaced in logs / events — e.g. `"pii"`, `"topic"`, `"injection"`,
+   * `"moderation.openai"`.
+   */
+  readonly name: string;
+  /**
+   * Inspect `text` and return a verdict. Receives the
+   * {@link GuardrailDetectorContext} so it can branch on the phase or read
+   * the surrounding run state.
+   */
+  check(text: string, detectorCtx: GuardrailDetectorContext): GuardrailVerdict | Promise<GuardrailVerdict>;
+}
+/**
+ * A {@link GuardrailDetector} whose `check()` is **synchronous** — it returns a
+ * {@link GuardrailVerdict} directly, never a `Promise`. Used by the built-in
+ * zero-dependency detectors (`pii`, `topic`, `injection`) that inspect text
+ * with pure string / regex matching and have no async work to do.
+ *
+ * Because the return type is covariant, a `SyncGuardrailDetector` is
+ * structurally assignable to {@link GuardrailDetector}: anything that accepts a
+ * `GuardrailDetector` (the guard factory's `input` / `output` / `tool` arrays)
+ * accepts a `SyncGuardrailDetector` unchanged. Callers that hold the concrete
+ * sync type additionally get to read `verdict.type` / `.matches` / `.text`
+ * without awaiting.
+ */
+interface SyncGuardrailDetector extends GuardrailDetector {
+  /**
+   * Inspect `text` and return a verdict synchronously. Receives the
+   * {@link GuardrailDetectorContext} so it can branch on the phase or read
+   * the surrounding run state.
+   */
+  check(text: string, detectorCtx: GuardrailDetectorContext): GuardrailVerdict;
+}
+//#endregion
+export { GuardrailDetector, GuardrailDetectorContext, SyncGuardrailDetector };
+//# sourceMappingURL=guardrail.contract.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"guardrail.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/guard/contracts/guardrail.contract.ts"],"mappings":";;;;;;AAaA;;;;;;;;UAAiB,wBAAA;EAIoB;EAAA,SAF1B,KAAA,EAAO,cAAA;EAyBgB;EAAA,SAvBvB,GAAA,EAAK,qBAAqB;AAAA;;;;;;;;;;;;;;;AAsCW;AAgBhD;;;;;UA/BiB,iBAAA;EA+B+C;;;;;EAAA,SAzBrD,IAAA;EA+BW;;;AAAwD;;EAzB5E,KAAA,CACE,IAAA,UACA,WAAA,EAAa,wBAAA,GACZ,gBAAA,GAAmB,OAAA,CAAQ,gBAAA;AAAA;;;;;;;;;;;;;;UAgBf,qBAAA,SAA8B,iBAAA;;;;;;EAM7C,KAAA,CAAM,IAAA,UAAc,WAAA,EAAa,wBAAA,GAA2B,gBAAA;AAAA"}

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

@@ -0,0 +1,4 @@
+import { GuardrailAction, GuardrailMatch, GuardrailPhase, GuardrailVerdict } from "./verdict.type.mjs";
+import { GuardrailDetector, GuardrailDetectorContext, SyncGuardrailDetector } from "./guardrail.contract.mjs";
+import { OpenAiClientLike, OpenAiModerationCreateBody, OpenAiModerationResponse, OpenAiModerationResult } from "./openai-client.contract.mjs";
+import { GuardOptions, GuardrailBlockEvent, GuardrailEscalation, InjectionDetectorOptions, OpenAiModerationOptions, PiiCategory, PiiDetectorOptions, TopicFilterOptions } from "./guard-options.type.mjs";

package/esm/guard/contracts/openai-client.contract.d.mts

@@ -0,0 +1,51 @@
+//#region ../@warlock.js/ai/src/guard/contracts/openai-client.contract.d.ts
+/**
+ * Minimal structural view of the part of the `openai` SDK the
+ * `moderation` detector actually calls. Declared locally (rather than
+ * importing the SDK's own types) so `@warlock.js/ai` type-checks even
+ * when `openai` is **not** installed — it is an OPTIONAL peer, lazily
+ * imported at runtime. The shape tracks the OpenAI Node SDK v4:
+ * `client.moderations.create({ model, input })` resolves to a response whose
+ * `results[]` each carry a `flagged` boolean and per-category `categories` /
+ * `category_scores` maps.
+ *
+ * Surfacing it as a contract lets a caller pass a ready
+ * {@link OpenAiClientLike} (real `OpenAI` instance, mock, or proxy) on
+ * `OpenAiModerationOptions.client` to bypass the lazy import entirely.
+ */
+/**
+ * A pre-built OpenAI-compatible client — any object exposing
+ * `moderations.create`. Passing one on `OpenAiModerationOptions.client` lets
+ * the detector skip the lazy `import("openai")` entirely (so bring-your-own-
+ * client callers and hermetic tests never need the SDK on disk).
+ */
+interface OpenAiClientLike {
+  readonly moderations: {
+    create(body: OpenAiModerationCreateBody): Promise<OpenAiModerationResponse>;
+  };
+}
+/** Subset of the moderation-create body the detector populates. */
+interface OpenAiModerationCreateBody {
+  /** Moderation model id (e.g. `"omni-moderation-latest"`). */
+  readonly model: string;
+  /** The text to moderate. */
+  readonly input: string;
+}
+/** Subset of the moderation response the detector reads. */
+interface OpenAiModerationResponse {
+  readonly results: readonly OpenAiModerationResult[];
+}
+/**
+ * One moderation result. `flagged` is the SDK's overall verdict; `categories`
+ * maps each policy category to whether it tripped; `category_scores` carries
+ * the per-category confidence, surfaced on each {@link GuardrailMatch.label}'s
+ * companion data when present.
+ */
+interface OpenAiModerationResult {
+  readonly flagged: boolean;
+  readonly categories: Record<string, boolean>;
+  readonly category_scores?: Record<string, number>;
+}
+//#endregion
+export { OpenAiClientLike, OpenAiModerationCreateBody, OpenAiModerationResponse, OpenAiModerationResult };
+//# sourceMappingURL=openai-client.contract.d.mts.map

package/esm/guard/contracts/openai-client.contract.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai-client.contract.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/guard/contracts/openai-client.contract.ts"],"mappings":";;AAqBA;;;;;;;;;;;;;;;AAE8E;AAK9E;;;UAPiB,gBAAA;EAAA,SACN,WAAA;IACP,MAAA,CAAO,IAAA,EAAM,0BAAA,GAA6B,OAAA,CAAQ,wBAAA;EAAA;AAAA;;UAKrC,0BAAA;EAkBA;EAAA,SAhBN,KAAA;;WAEA,KAAK;AAAA;;UAIC,wBAAA;EAAA,SACN,OAAA,WAAkB,sBAAsB;AAAA;;AAYhB;;;;;UAHlB,sBAAA;EAAA,SACN,OAAA;EAAA,SACA,UAAA,EAAY,MAAA;EAAA,SACZ,eAAA,GAAkB,MAAM;AAAA"}

package/esm/guard/contracts/verdict.type.d.mts

@@ -0,0 +1,76 @@
+//#region ../@warlock.js/ai/src/guard/contracts/verdict.type.d.ts
+/**
+ * Where a detector is running. Widens the core guardrail phase
+ * (`"input" | "output"`) with a third value, `"tool"`, for detectors that
+ * inspect the arguments the model produced for a tool call. Reused on the
+ * `GuardrailViolationError.phase` surfaced to callers and on any emitted
+ * escalation event.
+ */
+type GuardrailPhase = "input" | "output" | "tool";
+/**
+ * The four actions a detector can return, the discriminator of
+ * {@link GuardrailVerdict}.
+ *
+ * - `allow`  — content is clean; continue to the next detector.
+ * - `redact` — rewrite the inspected text and continue.
+ * - `block`  — reject the trip / tool call with a `GuardrailViolationError`.
+ * - `flag`   — allow the content but record the match for a downstream observer.
+ *
+ * `type` is always the discriminator — never `kind`.
+ */
+type GuardrailAction = "allow" | "redact" | "block" | "flag";
+/**
+ * A single thing a detector matched inside the inspected text. Surfaced in
+ * logs, events, and on `redact` / `flag` verdicts so an operator can see
+ * *what* tripped a rule without re-running the detector.
+ */
+interface GuardrailMatch {
+  /**
+   * The detector rule that produced the match, namespaced under the
+   * detector — e.g. `"pii.ssn"`, `"topic.deny.medical"`,
+   * `"injection.jailbreak"`.
+   */
+  readonly rule: string;
+  /**
+   * Inclusive `[start, end]` character offsets into the inspected text,
+   * when the detector can locate the match. Omitted for whole-text
+   * verdicts (e.g. an allow-list miss or a moderation-model category).
+   */
+  readonly span?: readonly [start: number, end: number];
+  /**
+   * Free-form category surfaced in logs and events and substituted into a
+   * redaction `mask` template — e.g. `"ssn"`, `"email"`, `"violence"`.
+   */
+  readonly label?: string;
+}
+/**
+ * The verdict a {@link GuardrailDetector} returns from `check()` — a
+ * discriminated union with exactly one {@link GuardrailAction} per shape.
+ * The factory folds a detector array and acts on the first non-`allow`
+ * verdict (short-circuit, in registration order).
+ */
+type GuardrailVerdict = {
+  /** Content is clean; continue to the next detector. */readonly type: "allow";
+} | {
+  /** Rewrite the inspected text and continue. */readonly type: "redact"; /** The inspected text with every match replaced (detector-produced). */
+  readonly text: string; /** Human-readable explanation of what was redacted and why. */
+  readonly reason: string; /** The matches the detector replaced. */
+  readonly matches: readonly GuardrailMatch[];
+} | {
+  /** Reject the trip / tool call. */readonly type: "block"; /** Human-readable reason surfaced on `GuardrailViolationError.reason`. */
+  readonly reason: string; /** The matches that triggered the block, when known. */
+  readonly matches?: readonly GuardrailMatch[];
+  /**
+   * Ask the host to route this block to a human-review surface. When
+   * `true`, the factory awaits `escalation.onBlock` before throwing.
+   * Default `false`.
+   */
+  readonly escalate?: boolean;
+} | {
+  /** Allow the content but record the match for a downstream observer. */readonly type: "flag"; /** Human-readable explanation of what was flagged. */
+  readonly reason: string; /** The matches the detector recorded. */
+  readonly matches: readonly GuardrailMatch[];
+};
+//#endregion
+export { GuardrailAction, GuardrailMatch, GuardrailPhase, GuardrailVerdict };
+//# sourceMappingURL=verdict.type.d.mts.map

package/esm/guard/contracts/verdict.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/guard/contracts/verdict.type.ts"],"mappings":";;AAOA;;;;AAA0B;AAa1B;KAbY,cAAA;;;AAae;AAO3B;;;;;;;;KAPY,eAAA;;AAwBI;AAShB;;;UA1BiB,cAAA;EA+CiB;;;;;EAAA,SAzCvB,IAAA;EA6BI;;;;;EAAA,SAvBJ,IAAA,aAAiB,KAAA,UAAe,GAAA;EAmC5B;;;;EAAA,SA9BJ,KAAA;AAAA;;;AA4CoC;;;;KAnCnC,gBAAA;kEAGG,IAAA;AAAA;0DAIA,IAAA;WAEA,IAAA;WAEA,MAAA;WAEA,OAAA,WAAkB,cAAA;AAAA;8CAIlB,IAAA;WAEA,MAAA;WAEA,OAAA,YAAmB,cAAA;;;;;;WAMnB,QAAA;AAAA;mFAIA,IAAA;WAEA,MAAA;WAEA,OAAA,WAAkB,cAAA;AAAA"}

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

@@ -0,0 +1,4 @@
+import { injection } from "./injection.mjs";
+import { pii } from "./pii.mjs";
+import { topic } from "./topic.mjs";
+import { moderation } from "./moderation.mjs";

package/esm/guard/detectors/index.mjs

@@ -0,0 +1,6 @@
+import { injection } from "./injection.mjs";
+import { pii } from "./pii.mjs";
+import { topic } from "./topic.mjs";
+import { moderation } from "./moderation.mjs";
+
+export {  };

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

@@ -0,0 +1,34 @@
+import { SyncGuardrailDetector } from "../contracts/guardrail.contract.mjs";
+import { InjectionDetectorOptions } from "../contracts/guard-options.type.mjs";
+//#region ../@warlock.js/ai/src/guard/detectors/injection.d.ts
+/**
+ * Build the built-in `injection` detector (surfaced as
+ * `ai.guardrail.injection(options?)`). Matches a curated set of jailbreak /
+ * prompt-injection marker phrases — override (`"ignore previous
+ * instructions"`), role-reset (`"you are now"`), jailbreak (`"developer
+ * mode"`, `"do anything now"`), and exfiltration (`"reveal your system
+ * prompt"`) — extensible with caller `markers` (case-insensitive substrings
+ * or `RegExp`s).
+ *
+ * Zero runtime dependency: matching is pure string / regex. On a hit the
+ * verdict is `flag` by default (record but allow); pass `onMatch: "block"`
+ * to reject instead — commonly used on the `input` phase, where the core
+ * `trip.before` seam supports `block` / `flag` only.
+ *
+ * @param options - Extra `markers` and the `onMatch` action (`"flag"` | `"block"`).
+ * @returns A {@link SyncGuardrailDetector} for the guard's `input` / `output` / `tool` arrays.
+ *
+ * @example
+ * const guard = ai.guardrail({
+ *   input: [ai.guardrail.injection({ onMatch: "block" })],
+ *   output: [ai.guardrail.injection()], // flag-only on the model's reply
+ * });
+ *
+ * @example
+ * // Extend the built-in set with a house rule.
+ * ai.guardrail.injection({ markers: [/system\s*:\s*override/i, "sudo mode"] });
+ */
+declare function injection(options?: InjectionDetectorOptions): SyncGuardrailDetector;
+//#endregion
+export { injection };
+//# sourceMappingURL=injection.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"injection.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/guard/detectors/injection.ts"],"mappings":";;;;;;;AAiNA;;;;;;;;AAEwB;;;;;;;;;;;;;;;iBAFR,SAAA,CACd,OAAA,GAAU,wBAAA,GACT,qBAAqB"}