@warlock.js/ai 4.4.0 → 4.5.0

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"}

package/esm/guard/detectors/injection.mjs

@@ -0,0 +1,254 @@
+//#region ../@warlock.js/ai/src/guard/detectors/injection.ts
+const DETECTOR_NAME = "injection";
+/**
+* Built-in jailbreak / prompt-injection marker phrases. Each entry is a
+* case-insensitive substring (matched lowercased) paired with the rule
+* label surfaced on the {@link GuardrailMatch} (`injection.<label>`).
+*
+* The set targets the canonical override / role-reset / exfiltration
+* patterns rather than trying to be exhaustive — a curated, low-false-
+* positive seed that callers extend with their own `markers`. Phrases are
+* deliberately specific (`"ignore previous instructions"`, not the bare
+* word `"ignore"`) so ordinary prose does not trip the rule.
+*/
+const BUILT_IN_MARKERS = [
+	{
+		phrase: "ignore previous instructions",
+		label: "override"
+	},
+	{
+		phrase: "ignore all previous instructions",
+		label: "override"
+	},
+	{
+		phrase: "ignore the above instructions",
+		label: "override"
+	},
+	{
+		phrase: "disregard previous instructions",
+		label: "override"
+	},
+	{
+		phrase: "disregard all previous instructions",
+		label: "override"
+	},
+	{
+		phrase: "forget previous instructions",
+		label: "override"
+	},
+	{
+		phrase: "forget all previous instructions",
+		label: "override"
+	},
+	{
+		phrase: "ignore your instructions",
+		label: "override"
+	},
+	{
+		phrase: "override your instructions",
+		label: "override"
+	},
+	{
+		phrase: "do not follow your instructions",
+		label: "override"
+	},
+	{
+		phrase: "you are now",
+		label: "role-reset"
+	},
+	{
+		phrase: "act as",
+		label: "role-reset"
+	},
+	{
+		phrase: "pretend to be",
+		label: "role-reset"
+	},
+	{
+		phrase: "developer mode",
+		label: "jailbreak"
+	},
+	{
+		phrase: "jailbreak",
+		label: "jailbreak"
+	},
+	{
+		phrase: "dan mode",
+		label: "jailbreak"
+	},
+	{
+		phrase: "do anything now",
+		label: "jailbreak"
+	},
+	{
+		phrase: "bypass your",
+		label: "jailbreak"
+	},
+	{
+		phrase: "ignore your guidelines",
+		label: "jailbreak"
+	},
+	{
+		phrase: "ignore your safety",
+		label: "jailbreak"
+	},
+	{
+		phrase: "ignore the rules",
+		label: "jailbreak"
+	},
+	{
+		phrase: "without any restrictions",
+		label: "jailbreak"
+	},
+	{
+		phrase: "reveal your system prompt",
+		label: "exfiltration"
+	},
+	{
+		phrase: "print your system prompt",
+		label: "exfiltration"
+	},
+	{
+		phrase: "show your system prompt",
+		label: "exfiltration"
+	},
+	{
+		phrase: "repeat your instructions",
+		label: "exfiltration"
+	},
+	{
+		phrase: "what are your instructions",
+		label: "exfiltration"
+	},
+	{
+		phrase: "reveal your prompt",
+		label: "exfiltration"
+	}
+];
+/**
+* The zero-dependency built-in injection detector — the internal class
+* behind the {@link injection} factory. Scans for jailbreak / prompt-
+* injection marker phrases (built-in set + caller `markers`) and returns a
+* `block` or `flag` verdict (per `onMatch`) listing every match, or `allow`
+* when the text is clean.
+*
+* Detection only: a detector never throws or mutates the pipeline — the
+* `guard()` factory translates the verdict into the trip's throw / record
+* mechanics.
+*/
+var InjectionDetector = class {
+	constructor(options = {}) {
+		this.name = DETECTOR_NAME;
+		this.block = options.onMatch === "block";
+		this.markers = compileMarkers(options.markers ?? []);
+	}
+	/**
+	* Inspect `text` for any built-in or caller marker. Returns `allow` when
+	* none hit, otherwise the configured `block` / `flag` verdict carrying a
+	* {@link GuardrailMatch} per hit (with a `[start, end]` span for literal
+	* substrings; regex hits report a span only when the match is locatable).
+	*/
+	check(text) {
+		const matches = this.scan(text);
+		if (matches.length === 0) return { type: "allow" };
+		const reason = `Detected ${matches.length} prompt-injection marker(s).`;
+		if (this.block) return {
+			type: "block",
+			reason,
+			matches
+		};
+		return {
+			type: "flag",
+			reason,
+			matches
+		};
+	}
+	/** Collect every marker hit in `text`, in marker registration order. */
+	scan(text) {
+		const lowered = text.toLowerCase();
+		const matches = [];
+		for (const marker of this.markers) {
+			if (marker.phrase !== void 0) {
+				const start = lowered.indexOf(marker.phrase);
+				if (start !== -1) matches.push({
+					rule: `${DETECTOR_NAME}.${marker.label}`,
+					label: marker.label,
+					span: [start, start + marker.phrase.length - 1]
+				});
+				continue;
+			}
+			const pattern = marker.pattern;
+			if (pattern === void 0) continue;
+			const result = pattern.exec(text);
+			if (result !== null) {
+				const start = result.index;
+				matches.push({
+					rule: `${DETECTOR_NAME}.${marker.label}`,
+					label: marker.label,
+					span: [start, start + result[0].length - 1]
+				});
+			}
+		}
+		return matches;
+	}
+};
+/**
+* Compile the built-in phrase set plus any caller `markers` into a single
+* ordered list. A caller `string` becomes a lowercased substring matcher
+* (labelled `custom`); a caller `RegExp` is carried as-is (labelled
+* `custom`). Built-ins keep their threat-category label.
+*/
+function compileMarkers(extra) {
+	const compiled = BUILT_IN_MARKERS.map((entry) => ({
+		label: entry.label,
+		phrase: entry.phrase
+	}));
+	for (const marker of extra) {
+		if (typeof marker === "string") {
+			compiled.push({
+				label: "custom",
+				phrase: marker.toLowerCase()
+			});
+			continue;
+		}
+		compiled.push({
+			label: "custom",
+			pattern: marker
+		});
+	}
+	return compiled;
+}
+/**
+* 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"] });
+*/
+function injection(options) {
+	return new InjectionDetector(options);
+}
+
+//#endregion
+export { injection };
+//# sourceMappingURL=injection.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"injection.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/guard/detectors/injection.ts"],"sourcesContent":["import type {\n  GuardrailMatch,\n  GuardrailVerdict,\n  InjectionDetectorOptions,\n  SyncGuardrailDetector,\n} from \"../contracts\";\n\nconst DETECTOR_NAME = \"injection\";\n\n/**\n * Built-in jailbreak / prompt-injection marker phrases. Each entry is a\n * case-insensitive substring (matched lowercased) paired with the rule\n * label surfaced on the {@link GuardrailMatch} (`injection.<label>`).\n *\n * The set targets the canonical override / role-reset / exfiltration\n * patterns rather than trying to be exhaustive — a curated, low-false-\n * positive seed that callers extend with their own `markers`. Phrases are\n * deliberately specific (`\"ignore previous instructions\"`, not the bare\n * word `\"ignore\"`) so ordinary prose does not trip the rule.\n */\nconst BUILT_IN_MARKERS: readonly { readonly phrase: string; readonly label: string }[] = [\n  { phrase: \"ignore previous instructions\", label: \"override\" },\n  { phrase: \"ignore all previous instructions\", label: \"override\" },\n  { phrase: \"ignore the above instructions\", label: \"override\" },\n  { phrase: \"disregard previous instructions\", label: \"override\" },\n  { phrase: \"disregard all previous instructions\", label: \"override\" },\n  { phrase: \"forget previous instructions\", label: \"override\" },\n  { phrase: \"forget all previous instructions\", label: \"override\" },\n  { phrase: \"ignore your instructions\", label: \"override\" },\n  { phrase: \"override your instructions\", label: \"override\" },\n  { phrase: \"do not follow your instructions\", label: \"override\" },\n  { phrase: \"you are now\", label: \"role-reset\" },\n  { phrase: \"act as\", label: \"role-reset\" },\n  { phrase: \"pretend to be\", label: \"role-reset\" },\n  { phrase: \"developer mode\", label: \"jailbreak\" },\n  { phrase: \"jailbreak\", label: \"jailbreak\" },\n  { phrase: \"dan mode\", label: \"jailbreak\" },\n  { phrase: \"do anything now\", label: \"jailbreak\" },\n  { phrase: \"bypass your\", label: \"jailbreak\" },\n  { phrase: \"ignore your guidelines\", label: \"jailbreak\" },\n  { phrase: \"ignore your safety\", label: \"jailbreak\" },\n  { phrase: \"ignore the rules\", label: \"jailbreak\" },\n  { phrase: \"without any restrictions\", label: \"jailbreak\" },\n  { phrase: \"reveal your system prompt\", label: \"exfiltration\" },\n  { phrase: \"print your system prompt\", label: \"exfiltration\" },\n  { phrase: \"show your system prompt\", label: \"exfiltration\" },\n  { phrase: \"repeat your instructions\", label: \"exfiltration\" },\n  { phrase: \"what are your instructions\", label: \"exfiltration\" },\n  { phrase: \"reveal your prompt\", label: \"exfiltration\" },\n];\n\n/**\n * A compiled marker — either a literal substring (matched case-insensitively\n * against the lowercased text) or a caller-supplied `RegExp` (tested as-is).\n * `label` is the namespaced rule suffix (`injection.<label>`); for built-in\n * phrases it is the threat category, for caller markers the index.\n */\ninterface CompiledMarker {\n  readonly label: string;\n  readonly phrase?: string;\n  readonly pattern?: RegExp;\n}\n\n/**\n * The zero-dependency built-in injection detector — the internal class\n * behind the {@link injection} factory. Scans for jailbreak / prompt-\n * injection marker phrases (built-in set + caller `markers`) and returns a\n * `block` or `flag` verdict (per `onMatch`) listing every match, or `allow`\n * when the text is clean.\n *\n * Detection only: a detector never throws or mutates the pipeline — the\n * `guard()` factory translates the verdict into the trip's throw / record\n * mechanics.\n */\nclass InjectionDetector implements SyncGuardrailDetector {\n  public readonly name = DETECTOR_NAME;\n\n  /** The compiled built-in + caller markers, scanned in registration order. */\n  private readonly markers: readonly CompiledMarker[];\n\n  /** Whether a match escalates to `block` (`true`) or stays a `flag`. */\n  private readonly block: boolean;\n\n  public constructor(options: InjectionDetectorOptions = {}) {\n    this.block = options.onMatch === \"block\";\n    this.markers = compileMarkers(options.markers ?? []);\n  }\n\n  /**\n   * Inspect `text` for any built-in or caller marker. Returns `allow` when\n   * none hit, otherwise the configured `block` / `flag` verdict carrying a\n   * {@link GuardrailMatch} per hit (with a `[start, end]` span for literal\n   * substrings; regex hits report a span only when the match is locatable).\n   */\n  public check(text: string): GuardrailVerdict {\n    const matches = this.scan(text);\n\n    if (matches.length === 0) {\n      return { type: \"allow\" };\n    }\n\n    const reason = `Detected ${matches.length} prompt-injection marker(s).`;\n\n    if (this.block) {\n      return { type: \"block\", reason, matches };\n    }\n\n    return { type: \"flag\", reason, matches };\n  }\n\n  /** Collect every marker hit in `text`, in marker registration order. */\n  private scan(text: string): GuardrailMatch[] {\n    const lowered = text.toLowerCase();\n    const matches: GuardrailMatch[] = [];\n\n    for (const marker of this.markers) {\n      if (marker.phrase !== undefined) {\n        const start = lowered.indexOf(marker.phrase);\n\n        if (start !== -1) {\n          matches.push({\n            rule: `${DETECTOR_NAME}.${marker.label}`,\n            label: marker.label,\n            span: [start, start + marker.phrase.length - 1],\n          });\n        }\n\n        continue;\n      }\n\n      // Caller-supplied RegExp — tested against the original (not lowered)\n      // text so author-controlled case sensitivity is preserved.\n      const pattern = marker.pattern;\n\n      if (pattern === undefined) {\n        continue;\n      }\n\n      const result = pattern.exec(text);\n\n      if (result !== null) {\n        const start = result.index;\n\n        matches.push({\n          rule: `${DETECTOR_NAME}.${marker.label}`,\n          label: marker.label,\n          span: [start, start + result[0].length - 1],\n        });\n      }\n    }\n\n    return matches;\n  }\n}\n\n/**\n * Compile the built-in phrase set plus any caller `markers` into a single\n * ordered list. A caller `string` becomes a lowercased substring matcher\n * (labelled `custom`); a caller `RegExp` is carried as-is (labelled\n * `custom`). Built-ins keep their threat-category label.\n */\nfunction compileMarkers(\n  extra: readonly (string | RegExp)[],\n): readonly CompiledMarker[] {\n  const compiled: CompiledMarker[] = BUILT_IN_MARKERS.map((entry) => ({\n    label: entry.label,\n    phrase: entry.phrase,\n  }));\n\n  for (const marker of extra) {\n    if (typeof marker === \"string\") {\n      compiled.push({ label: \"custom\", phrase: marker.toLowerCase() });\n\n      continue;\n    }\n\n    compiled.push({ label: \"custom\", pattern: marker });\n  }\n\n  return compiled;\n}\n\n/**\n * Build the built-in `injection` detector (surfaced as\n * `ai.guardrail.injection(options?)`). Matches a curated set of jailbreak /\n * prompt-injection marker phrases — override (`\"ignore previous\n * instructions\"`), role-reset (`\"you are now\"`), jailbreak (`\"developer\n * mode\"`, `\"do anything now\"`), and exfiltration (`\"reveal your system\n * prompt\"`) — extensible with caller `markers` (case-insensitive substrings\n * or `RegExp`s).\n *\n * Zero runtime dependency: matching is pure string / regex. On a hit the\n * verdict is `flag` by default (record but allow); pass `onMatch: \"block\"`\n * to reject instead — commonly used on the `input` phase, where the core\n * `trip.before` seam supports `block` / `flag` only.\n *\n * @param options - Extra `markers` and the `onMatch` action (`\"flag\"` | `\"block\"`).\n * @returns A {@link SyncGuardrailDetector} for the guard's `input` / `output` / `tool` arrays.\n *\n * @example\n * const guard = ai.guardrail({\n *   input: [ai.guardrail.injection({ onMatch: \"block\" })],\n *   output: [ai.guardrail.injection()], // flag-only on the model's reply\n * });\n *\n * @example\n * // Extend the built-in set with a house rule.\n * ai.guardrail.injection({ markers: [/system\\s*:\\s*override/i, \"sudo mode\"] });\n */\nexport function injection(\n  options?: InjectionDetectorOptions,\n): SyncGuardrailDetector {\n  return new InjectionDetector(options);\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,32 @@
+import { GuardrailDetector } from "../contracts/guardrail.contract.mjs";
+import { OpenAiModerationOptions } from "../contracts/guard-options.type.mjs";
+//#region ../@warlock.js/ai/src/guard/detectors/moderation.d.ts
+/**
+ * Build the optional `moderation` detector (surfaced as
+ * `ai.guardrail.moderation(options?)`), backed by OpenAI's moderation
+ * endpoint. The `openai` SDK is an **optional lazy peer**: importing
+ * `@warlock.js/ai` never forces it to resolve, and the detector throws
+ * a curated install string ({@link OPENAI_INSTALL_INSTRUCTIONS}) on first
+ * `check()` when the peer is absent — mirroring ai-panoptic's lazy Langfuse
+ * exporter.
+ *
+ * On a moderation hit, every flagged category becomes a
+ * {@link GuardrailMatch}; the verdict is `block` when any flagged category is
+ * listed in `blockOn`, otherwise `flag`. A clean result is `allow`.
+ *
+ * @param options - `apiKey` (defaults to `OPENAI_API_KEY`), `model`
+ *   (defaults to `"omni-moderation-latest"`), `blockOn` (categories that
+ *   escalate to `block`), or a pre-built `client` to bypass the lazy import.
+ * @returns A {@link GuardrailDetector} for the guard's `input` / `output` / `tool` arrays.
+ *
+ * @example
+ * const guard = ai.guardrail({
+ *   output: [
+ *     ai.guardrail.moderation({ blockOn: ["violence", "sexual/minors"] }),
+ *   ],
+ * });
+ */
+declare function moderation(options?: OpenAiModerationOptions): GuardrailDetector;
+//#endregion
+export { moderation };
+//# sourceMappingURL=moderation.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"moderation.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/guard/detectors/moderation.ts"],"mappings":";;;;;;;AAoMA;;;;;;;;AAEoB;;;;;;;;;;;;;iBAFJ,UAAA,CACd,OAAA,GAAU,uBAAA,GACT,iBAAiB"}