@directive-run/ai 1.20.2 → 1.21.0

package/dist/guardrails-export-D3pKHiPp.d.cts

@@ -0,0 +1,884 @@
+import { m as GuardrailFn, I as InputGuardrailData, O as OutputGuardrailData, aW as SchemaValidator, T as ToolCallGuardrailData } from './types-DJ09LjZX.cjs';
+import { a as Embedding } from './semantic-cache-DM7ev7NQ.cjs';
+import { Plugin } from '@directive-run/core';
+
+/**
+ * Built-in guardrails for AI adapter — PII, moderation, rate limiting, tool allowlists, schema validation.
+ */
+
+/**
+ * Create a PII detection guardrail that scans input text for personally identifiable
+ * information. Blocks input when PII is detected, or optionally redacts matches and
+ * passes the sanitized text through.
+ *
+ * @param options - Configuration for PII detection: `patterns` sets the RegExp list (defaults to SSN, credit card, email), `redact` replaces matches instead of blocking, `redactReplacement` sets the replacement string (defaults to `"[REDACTED]"`).
+ * @returns An input guardrail that blocks or redacts PII in user input.
+ *
+ * @example
+ * ```typescript
+ * const piiGuardrail = createPIIGuardrail({
+ *   patterns: [
+ *     /\b\d{3}-\d{2}-\d{4}\b/, // SSN
+ *     /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i, // Email
+ *   ],
+ *   redact: true,
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createPIIGuardrail(options: {
+    patterns?: RegExp[];
+    redact?: boolean;
+    redactReplacement?: string;
+}): GuardrailFn<InputGuardrailData>;
+/**
+ * Create a content moderation guardrail that delegates to a user-supplied check function.
+ * Works on both input and output data — the guardrail extracts the text content
+ * automatically and passes it to {@link options.checkFn}.
+ *
+ * @param options - Configuration for content moderation: `checkFn` returns `true` when content should be flagged (supports async), `message` sets the rejection reason (defaults to `"Content flagged by moderation"`).
+ * @returns A guardrail that blocks content flagged by the check function.
+ *
+ * @example
+ * ```typescript
+ * const moderationGuardrail = createModerationGuardrail({
+ *   checkFn: async (text) => {
+ *     const result = await openai.moderations.create({ input: text });
+ *     return result.results[0].flagged;
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createModerationGuardrail(options: {
+    checkFn: (text: string) => boolean | Promise<boolean>;
+    message?: string;
+}): GuardrailFn<InputGuardrailData | OutputGuardrailData>;
+/** Rate limiter with reset capability for testing */
+interface RateLimitGuardrail extends GuardrailFn<InputGuardrailData> {
+    reset(): void;
+}
+/**
+ * Create a rate limit guardrail that tracks token and request counts over a sliding
+ * one-minute window. Returns a {@link RateLimitGuardrail} — a guardrail function with
+ * an additional `reset()` method for testing.
+ *
+ * @param options - Configuration for rate limiting: `maxTokensPerMinute` caps tokens in the sliding window (defaults to `100000`), `maxRequestsPerMinute` caps requests (defaults to `60`).
+ * @returns A rate limit guardrail with an attached `reset()` method.
+ *
+ * @example
+ * ```typescript
+ * const rateLimiter = createRateLimitGuardrail({
+ *   maxTokensPerMinute: 50000,
+ *   maxRequestsPerMinute: 30,
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createRateLimitGuardrail(options: {
+    maxTokensPerMinute?: number;
+    maxRequestsPerMinute?: number;
+}): RateLimitGuardrail;
+/**
+ * Create a tool-call guardrail that restricts which tools an agent may invoke.
+ * Supports allowlist mode, denylist mode, or both — when both are provided, a tool
+ * must appear in the allowlist and not appear in the denylist.
+ *
+ * @param options - Configuration for tool filtering: `allowlist` sets permitted tool names, `denylist` sets blocked tool names, `caseSensitive` controls case matching (defaults to `false`).
+ * @returns A tool-call guardrail that enforces the allowlist/denylist rules.
+ *
+ * @example
+ * ```typescript
+ * const toolGuardrail = createToolGuardrail({
+ *   allowlist: ["search", "calculate"],
+ *   denylist: ["delete_account"],
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createToolGuardrail(options: {
+    allowlist?: string[];
+    denylist?: string[];
+    /** @default false */
+    caseSensitive?: boolean;
+}): GuardrailFn<ToolCallGuardrailData>;
+/**
+ * Create an output guardrail that validates agent output against a schema using
+ * a user-supplied {@link SchemaValidator}. Compatible with any validation library
+ * (Zod, Valibot, ArkType, etc.) via the adapter pattern.
+ *
+ * @param options - Configuration for schema validation: `validate` checks the output against the expected schema, `errorPrefix` is prepended to error messages (defaults to `"Output schema validation failed"`).
+ * @returns An output guardrail that rejects output failing schema validation.
+ *
+ * @example
+ * ```typescript
+ * import { z } from "zod";
+ *
+ * const schemaGuardrail = createOutputSchemaGuardrail({
+ *   validate: (value) => {
+ *     const result = z.object({ answer: z.string() }).safeParse(value);
+ *     return { valid: result.success, errors: result.error?.issues.map(i => i.message) };
+ *   },
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createOutputSchemaGuardrail<T = unknown>(options: {
+    validate: SchemaValidator<T>;
+    errorPrefix?: string;
+}): GuardrailFn<OutputGuardrailData>;
+/**
+ * Create an output guardrail that performs lightweight runtime type checks without
+ * requiring a schema library. Supports `"string"`, `"number"`, `"boolean"`, `"object"`,
+ * and `"array"` with optional size and field constraints.
+ *
+ * @param options - Configuration for type checking: `type` sets the expected JS type, `requiredFields` lists object keys that must exist, `minLength`/`maxLength` constrain array size, `minStringLength`/`maxStringLength` constrain string length.
+ * @returns An output guardrail that rejects output not matching the expected type or constraints.
+ *
+ * @example
+ * ```typescript
+ * const typeGuardrail = createOutputTypeGuardrail({
+ *   type: "object",
+ *   requiredFields: ["id", "name"],
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createOutputTypeGuardrail(options: {
+    type: "string" | "number" | "boolean" | "object" | "array";
+    requiredFields?: string[];
+    minLength?: number;
+    maxLength?: number;
+    minStringLength?: number;
+    maxStringLength?: number;
+}): GuardrailFn<OutputGuardrailData>;
+/**
+ * Create an output guardrail that enforces maximum length constraints on agent output,
+ * measured in characters or estimated tokens.
+ *
+ * @param options - Configuration for length limits: `maxCharacters` caps character count, `maxTokens` caps estimated token count, `estimateTokens` provides a custom token estimator (defaults to `Math.ceil(text.length / 4)`).
+ * @returns An output guardrail that rejects output exceeding the configured length limits.
+ *
+ * @example
+ * ```typescript
+ * const lengthGuardrail = createLengthGuardrail({
+ *   maxCharacters: 5000,
+ *   maxTokens: 1200,
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createLengthGuardrail(options: {
+    /** Maximum characters in output */
+    maxCharacters?: number;
+    /** Maximum estimated tokens in output */
+    maxTokens?: number;
+    /** Custom token estimator (default: chars / 4) */
+    estimateTokens?: (text: string) => number;
+}): GuardrailFn<OutputGuardrailData>;
+/**
+ * Create an output guardrail that blocks content matching any of the provided patterns.
+ * String patterns are escaped and compiled to RegExp; RegExp patterns are used as-is.
+ *
+ * @remarks
+ * A warning is logged when `blockedPatterns` is empty, since an empty list means no
+ * content will ever be filtered.
+ *
+ * @param options - Configuration for content filtering: `blockedPatterns` lists strings or RegExps to match against output, `caseSensitive` controls case matching for string patterns (defaults to `false`).
+ * @returns An output guardrail that rejects output containing any blocked pattern.
+ *
+ * @example
+ * ```typescript
+ * const contentFilter = createContentFilterGuardrail({
+ *   blockedPatterns: [
+ *     /\bpassword\b/i,
+ *     /\bsecret\b/i,
+ *     'internal-only',
+ *   ],
+ * });
+ * ```
+ *
+ * @public
+ */
+declare function createContentFilterGuardrail(options: {
+    /** Patterns to block — strings or RegExp */
+    blockedPatterns: Array<string | RegExp>;
+    /** Case-sensitive matching for string patterns (default: false) */
+    caseSensitive?: boolean;
+}): GuardrailFn<OutputGuardrailData>;
+
+/**
+ * Fact-PII Guardrail — input guardrail at the fact-store boundary
+ *
+ * Closes the source → fact → agent prompt PII bypass surfaced by R5's
+ * red-team / privacy / AI-integration reviewers: `createPIIGuardrail`
+ * only inspects the `data.input` string at runStream entry, so PII that
+ * a source publishes into a fact (a Supabase realtime row carrying a
+ * customer email, a webhook payload with a SSN, an MCP server's
+ * resource notification with a card number) reaches the agent's
+ * prompt — via fact injection — without ever hitting the input
+ * guardrail chain.
+ *
+ * This plugin runs as a Directive plugin (`onFactSet` / `onFactsBatch`),
+ * scans every write to a pii-tagged fact against a sync regex matcher
+ * for the three highest-volume PII categories (SSN, credit card, email),
+ * and either **redacts** the value (the default — safe shipping posture)
+ * or **rejects** the write (throws so the source's publish handler can
+ * surface the violation). Operators wire it once at `createSystem`; no
+ * per-source / per-fact changes are required.
+ *
+ * The async PII detector from `pii-enhanced.ts` is unsuitable here:
+ * `onFactSet` is synchronous and a deferred detection would let the
+ * raw PII reach observers + breakpoints + audit-ledger before the
+ * redaction completed. Built-in matching is therefore inlined as
+ * synchronous regex. Consumers who need richer detection pass a
+ * synchronous `customDetector`.
+ *
+ * ## Observability
+ *
+ * Every detection emits a typed `"guardrail.blocked"` `ObservationEvent`
+ * via `system.observe()` (RFC 0010). Backend wiring (OTel exporters,
+ * `@directive-run/timeline`, audit-ledger plugins) subscribes to the
+ * event stream and gets:
+ *
+ * ```ts
+ * {
+ *   type: "guardrail.blocked",
+ *   plugin: "fact-pii-guardrail",
+ *   key: "<fact-key>",
+ *   kind: "redact" | "alert" | "detect",
+ *   count: <number-of-matches>,
+ *   category: "ssn" | "credit_card" | "email" | <customDetector-type>
+ * }
+ * ```
+ *
+ * The user `onBlocked` callback fires INDEPENDENTLY for backwards
+ * compatibility and ad-hoc paging (Sentry, Honeycomb). Prefer
+ * `system.observe()` for new integrations — observers see every
+ * registered guardrail's activity through the same typed stream.
+ *
+ * `kind: "detect"` distinguishes "couldn't redact" from "chose not
+ * to redact": `Error` instances always surface as `"detect"` because
+ * the walker matches `Error.message` / `Error.cause` but cannot mint
+ * a redacted Error with guaranteed `.stack` parity. A subscriber
+ * counting redactions should sum `kind === "redact" || kind === "detect"`.
+ *
+ * @example Defensive (redact PII writes into pii-tagged facts)
+ * ```ts
+ * import { createSystem, t } from '@directive-run/core';
+ * import { createFactPIIGuardrail } from '@directive-run/ai/guardrails';
+ *
+ * const customer = createModule('customer', {
+ *   schema: {
+ *     facts: {
+ *       email: t.string().meta({ tags: ['pii'] }),
+ *       ssn: t.string().meta({ tags: ['pii'] }),
+ *     },
+ *   },
+ *   sources: {
+ *     supabase: { attach: (publish) => subscribe(publish) },
+ *   },
+ * });
+ *
+ * const system = createSystem({
+ *   module: customer,
+ *   plugins: [
+ *     createFactPIIGuardrail({
+ *       mode: 'redact',
+ *       onBlocked: (key, detected) => {
+ *         console.warn(`[fact-pii] redacted ${detected.length} match(es) in ${key}`);
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @example Monitor-only (alert on every PII match; don't mutate the fact)
+ * ```ts
+ * createFactPIIGuardrail({
+ *   mode: 'alert',
+ *   onBlocked: (key) => Sentry.captureException(new Error(`pii match: ${key}`)),
+ * });
+ * ```
+ *
+ * @example Allow specific keys (not just by tag)
+ * ```ts
+ * createFactPIIGuardrail({
+ *   includeKeys: ['customer.email', 'customer.phone'],
+ * });
+ * ```
+ */
+
+/**
+ * Public match record for a single PII finding. Mirrors `DetectedPII` from
+ * `pii-enhanced.ts` so a downstream guardrail can normalize against either
+ * detection path.
+ */
+interface FactPIIMatch {
+    type: FactPIICategory;
+    value: string;
+    start: number;
+    end: number;
+}
+/** PII categories the built-in synchronous detector covers. */
+type FactPIICategory = "ssn" | "credit_card" | "email";
+/**
+ * Behavior when a pii-tagged fact's incoming value contains detected PII.
+ *
+ * - `"redact"` (default): the fact is rewritten with redacted text (e.g.
+ *   `"[SSN]"`) via a follow-up store write. The system briefly observes
+ *   the raw value during the same microtask the publish landed in, then
+ *   the redacted value overwrites it before any reconcile / agent runs.
+ *   Safe shipping posture for production: the LLM call always sees the
+ *   redacted value.
+ * - `"alert"`: fire `onBlocked` but DO NOT mutate the fact. The raw value
+ *   stays in the store. Use this for monitoring-only deployments where
+ *   the source's transport is already trusted but a regression detector
+ *   is needed (paging ops on every match).
+ *
+ * Note: Directive plugin hooks (`onFactSet`, `onFactsBatch`) are
+ * wrapped by the plugin manager's `safeCall` so a throw from inside the
+ * hook is swallowed. The guardrail therefore cannot reject the write
+ * itself — it can only observe + redact-via-followup-write or alert.
+ * For hard rejection at the publish boundary, a future RFC will add a
+ * pre-commit transform hook on the source primitive.
+ */
+type FactPIIGuardrailMode = "redact" | "alert";
+/**
+ * How to handle Error / AggregateError instances whose `.message`,
+ * `.cause`, or `.errors` carry PII matches.
+ *
+ * - `"redact"` (default in `mode: "redact"`): replace the value in the
+ *   store with a new `Error(redactedMessage)`. The redacted Error
+ *   preserves its `.name` but loses the original class identity
+ *   (subclasses become plain `Error`), `.stack`, `.cause`, and
+ *   `AggregateError.errors`, because those cannot be redacted
+ *   losslessly without re-invoking the original constructor.
+ * - `"preserve"`: keep the original Error in the store. Only fire
+ *   `onBlocked` + emit `guardrail.blocked` with kind `"detect"`. Use
+ *   this for back-compat when downstream code relies on
+ *   `instanceof YourErrorSubclass` or on `.stack` parity. The raw PII
+ *   remains in store under this setting.
+ * - `"alert-only"`: same as `"preserve"` but emit kind `"alert"` so
+ *   observability flags the leak as urgent.
+ */
+type FactPIIErrorMode = "redact" | "preserve" | "alert-only";
+interface FactPIIGuardrailOptions {
+    /** Default: `"redact"` */
+    mode?: FactPIIGuardrailMode;
+    /**
+     * Error / AggregateError handling. Defaults to `"redact"` when top-level
+     * `mode` is `"redact"`, `"alert-only"` when `mode` is `"alert"`. See
+     * {@link FactPIIErrorMode} for the per-option semantics.
+     *
+     * **Migration note:** prior to v1.21, the guardrail did NOT redact
+     * Errors regardless of the top-level `mode`. Consumers depending on
+     * the original Error class identity or `.stack` parity after a block
+     * must opt out by setting `errorMode: "preserve"`.
+     */
+    errorMode?: FactPIIErrorMode;
+    /**
+     * Built-in categories to scan for. Default: all three (`ssn`,
+     * `credit_card`, `email`). Pass `[]` to opt out of the built-ins and
+     * rely entirely on `customDetector`.
+     */
+    types?: readonly FactPIICategory[];
+    /**
+     * Specific fact keys to scan in addition to the auto-detected
+     * `pii`-tagged set. Useful when a consumer can't change the schema's
+     * meta but knows the key should be screened.
+     */
+    includeKeys?: readonly string[];
+    /**
+     * Exclude these fact keys even if they're pii-tagged. Escape hatch for
+     * a key that's already pre-sanitized upstream of the manager.
+     */
+    excludeKeys?: readonly string[];
+    /**
+     * Called whenever the guardrail detects PII and acts on it. Receives the
+     * fact key, the detected matches, and the action that was taken. Fires
+     * AFTER redact + before any throw in `reject` mode. Use this to alert
+     * SREs without coupling the guardrail to a specific logging backend.
+     */
+    onBlocked?: (key: string, detected: readonly FactPIIMatch[], action: FactPIIGuardrailMode) => void;
+    /**
+     * Custom synchronous detector that runs alongside the built-in regex
+     * scanner. The union of detections is acted on. Useful when the
+     * consumer ships a domain-specific PII detector (e.g. internal
+     * account-number format). MUST be synchronous — `onFactSet` cannot
+     * await deferred work.
+     */
+    customDetector?: (text: string) => readonly FactPIIMatch[];
+    /**
+     * Maximum nesting depth to walk when scanning a structured fact
+     * value. Default `4` (raised from `2` to cover Supabase realtime row
+     * shapes and MCP resource notification lists zero-config — those
+     * payloads are `payload.new = [{ email }]` which is four levels:
+     * object → array → object → string). At depth 4 the scanner
+     * inspects top-level strings, recurses into nested objects / arrays,
+     * and recurses three more levels. Each array level burns one depth
+     * slot. Maps and Sets are still NOT walked by the built-in scanner;
+     * PII inside those structures must go through a `customDetector`.
+     *
+     * Real-world common shapes and the `walkDepth` they need:
+     * - **Flat object** (`{ email, ssn }`) — works at any `walkDepth >= 1`.
+     * - **Nested object** (`{ profile: { email } }`) — needs `walkDepth >= 2`
+     *   (covered by the default).
+     * - **Error with cause** (`new Error(m, { cause: prev })`) — the cause
+     *   chain is recursed at `depth - 1`, so `walkDepth >= 2` is needed
+     *   to scan one cause level (covered by the default). Deeper cause
+     *   chains (`cause.cause.cause`) need `walkDepth >= 3`.
+     * - **AggregateError** with nested error PII — `walkDepth >= 2` for
+     *   the first layer; deeper for nested aggregates.
+     * - **Supabase realtime row payload** (`payload.new = [{ email }]`,
+     *   passed as the fact value) — the fact's value is the object
+     *   `{ new: [...] }`, so the chain is object → array → object →
+     *   string and needs `walkDepth: 4`.
+     * - **MCP resource notification list** (`{ resources: [{...}] }`) —
+     *   same shape, needs `walkDepth: 4`.
+     *
+     * For deeper or non-object structures (Maps, Sets, class instances
+     * with getters, Symbol-keyed properties), pass a `customDetector`
+     * that walks the consumer-specific shape and returns concrete
+     * matches.
+     *
+     * **Hard caps for safety:**
+     * - `walkDepth` clamps to `[1, 5]`. Non-finite values (`NaN`,
+     *   `Infinity`, non-number casts) clamp to `1`.
+     * - The walker caps any single array's element count at 10,000
+     *   (warns + truncates). Pass a `customDetector` for larger
+     *   payloads.
+     * - Before walking, the value is passed through `structuredClone`
+     *   to strip any Proxies, exotic getters, Symbol-iterator
+     *   overrides, and functions the consumer might have attached.
+     *   Cyclic inputs throw `DataCloneError` from `structuredClone`
+     *   and the walker treats them as "no match" with a warning.
+     *   Non-cloneable values (functions, DOM nodes, WeakMaps, etc.)
+     *   throw the same way — wire a `customDetector` for those shapes.
+     *
+     * Property iteration uses `Object.entries`, which skips
+     * Symbol-keyed properties and non-enumerable string keys. If you
+     * store PII under a Symbol key (unusual), a `customDetector` is the
+     * right escape hatch.
+     */
+    walkDepth?: number;
+}
+/**
+ * Create a Directive plugin that scans pii-tagged fact writes for PII and
+ * redacts or rejects them at the manager boundary.
+ *
+ * Wire it once at `createSystem({ plugins: [...] })`. The plugin caches
+ * the pii-tagged key set on `onInit` so per-write hooks are O(1) lookups.
+ *
+ * @returns a `Plugin` instance ready to add to `SystemConfig.plugins`.
+ */
+declare function createFactPIIGuardrail(options?: FactPIIGuardrailOptions): Plugin;
+
+/**
+ * Enhanced PII Detection Guardrail
+ *
+ * Provides comprehensive PII detection beyond basic regex patterns:
+ * - Multiple PII types (SSN, credit cards, emails, phones, addresses, names)
+ * - Pluggable detection backends (regex, custom, or external services)
+ * - Context-aware detection (reduces false positives)
+ * - Redaction with reversible or irreversible options
+ *
+ * @example
+ * ```typescript
+ * import { createEnhancedPIIGuardrail } from '@directive-run/ai';
+ *
+ * const guardrail = createEnhancedPIIGuardrail({
+ *   types: ['ssn', 'credit_card', 'email'],
+ *   redact: true,
+ *   detector: 'regex', // or 'custom' with custom detector
+ * });
+ * ```
+ */
+
+/** Supported PII types */
+type PIIType = "ssn" | "credit_card" | "email" | "phone" | "address" | "name" | "date_of_birth" | "passport" | "driver_license" | "ip_address" | "bank_account" | "medical_id" | "national_id";
+/** Detected PII instance */
+interface DetectedPII {
+    type: PIIType;
+    value: string;
+    position: {
+        start: number;
+        end: number;
+    };
+    confidence: number;
+    context?: string;
+}
+/** PII detection result */
+interface PIIDetectionResult {
+    detected: boolean;
+    items: DetectedPII[];
+    typeCounts: Partial<Record<PIIType, number>>;
+    /** Text with PII redacted (if requested) */
+    redactedText?: string;
+}
+/** Custom PII detector interface */
+interface PIIDetector {
+    detect(text: string, types: PIIType[]): Promise<DetectedPII[]>;
+    name: string;
+}
+/** Redaction style */
+type RedactionStyle = 
+/** Replace with [REDACTED] */
+"placeholder"
+/** Replace with type-specific placeholder like [EMAIL] */
+ | "typed"
+/**
+ * Replace with a fixed-width `****` mask plus the last 4 characters
+ * (e.g. `****6789`). Does not preserve or reveal the original length.
+ */
+ | "masked"
+/**
+ * Replace with a deterministic FNV-1a hash.
+ *
+ * **WARNING — this is PSEUDONYMIZATION, not anonymization.** FNV-1a is a
+ * fast, non-cryptographic 32-bit hash. For low-entropy structured PII (SSNs,
+ * card numbers, phone numbers) the output is trivially RE-IDENTIFIABLE via
+ * brute force or a precomputed rainbow table. It MUST NOT be relied on for
+ * GDPR / HIPAA de-identification. Use it only for referential integrity
+ * (correlating the same value across audit logs).
+ */
+ | "hashed";
+/** Redact detected PII from text */
+declare function redactPII(text: string, items: DetectedPII[], style?: RedactionStyle): string;
+/** Options for enhanced PII guardrail */
+interface EnhancedPIIGuardrailOptions {
+    /** PII types to detect (default: all) */
+    types?: PIIType[];
+    /** Detection backend (default: 'regex') */
+    detector?: "regex" | PIIDetector;
+    /** Redact instead of blocking */
+    redact?: boolean;
+    /** Redaction style (default: 'typed') */
+    redactionStyle?: RedactionStyle;
+    /** Minimum confidence to flag (0-1, default: 0.7) */
+    minConfidence?: number;
+    /** Callback when PII is detected */
+    onDetected?: (items: DetectedPII[]) => void;
+    /** Allow specific values (whitelist) */
+    allowlist?: string[];
+    /** Block only if count exceeds threshold */
+    minItemsToBlock?: number;
+    /** Timeout for custom detector in milliseconds (default: 5000) */
+    detectorTimeout?: number;
+}
+/**
+ * Create an enhanced PII detection guardrail.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const guardrail = createEnhancedPIIGuardrail();
+ *
+ * // Redact instead of blocking
+ * const redactGuardrail = createEnhancedPIIGuardrail({
+ *   redact: true,
+ *   redactionStyle: 'masked',
+ * });
+ *
+ * // Custom detection with external service
+ * const customGuardrail = createEnhancedPIIGuardrail({
+ *   detector: myPresidioDetector,
+ *   types: ['ssn', 'credit_card', 'medical_id'],
+ * });
+ * ```
+ */
+declare function createEnhancedPIIGuardrail(options?: EnhancedPIIGuardrailOptions): GuardrailFn<InputGuardrailData>;
+/**
+ * Create an output PII guardrail (for checking agent responses).
+ *
+ * @example
+ * ```typescript
+ * const outputGuardrail = createOutputPIIGuardrail({
+ *   types: ['ssn', 'credit_card'],
+ *   redact: true,
+ * });
+ * ```
+ */
+declare function createOutputPIIGuardrail(options?: EnhancedPIIGuardrailOptions): GuardrailFn<OutputGuardrailData>;
+/**
+ * Detect PII in text without using as a guardrail.
+ * Useful for analysis and logging.
+ *
+ * @example
+ * ```typescript
+ * const result = await detectPII('My SSN is 123-45-6789');
+ * console.log(result.items); // [{ type: 'ssn', value: '123-45-6789', ... }]
+ *
+ * // With custom detector and timeout
+ * const result = await detectPII(text, {
+ *   detector: myPresidioDetector,
+ *   timeout: 10000, // 10 seconds
+ * });
+ * ```
+ */
+declare function detectPII(text: string, options?: {
+    types?: PIIType[];
+    detector?: "regex" | PIIDetector;
+    minConfidence?: number;
+    /** Timeout for custom detectors in milliseconds (default: 5000) */
+    timeout?: number;
+}): Promise<PIIDetectionResult>;
+/**
+ * Detect PII in text and return a result whose `redactedText` is populated.
+ *
+ * This composes {@link detectPII} and {@link redactPII} so callers do not have
+ * to manually wire the two together (and do not have to mutate the detection
+ * result). When no PII is detected, `redactedText` is left `undefined` — it is
+ * deliberately NOT defaulted to the raw input.
+ *
+ * @example
+ * ```typescript
+ * const result = await detectAndRedactPII('My SSN is 123-45-6789', {
+ *   types: ['ssn'],
+ *   style: 'typed',
+ * });
+ * console.log(result.detected);      // true
+ * // ssn is a sensitive-category type, so `typed` emits a generic [REDACTED]
+ * console.log(result.redactedText);  // 'My SSN is [REDACTED]'
+ *
+ * const clean = await detectAndRedactPII('nothing here', { types: ['ssn'] });
+ * console.log(clean.detected);       // false
+ * console.log(clean.redactedText);   // undefined
+ * ```
+ */
+declare function detectAndRedactPII(text: string, options?: {
+    types?: PIIType[];
+    detector?: "regex" | PIIDetector;
+    minConfidence?: number;
+    /** Timeout for custom detectors in milliseconds (default: 5000) */
+    timeout?: number;
+    /** Redaction style applied when PII is detected (default: 'typed') */
+    style?: RedactionStyle;
+}): Promise<PIIDetectionResult>;
+
+/**
+ * Prompt Injection Detection Guardrail
+ *
+ * Detects and blocks prompt injection attacks including:
+ * - Direct injection attempts ("ignore previous instructions")
+ * - Jailbreak patterns ("DAN mode", "pretend you can")
+ * - Indirect injection via external content
+ * - Encoding-based evasion attempts
+ *
+ * @example
+ * ```typescript
+ * import { createPromptInjectionGuardrail } from '@directive-run/ai';
+ *
+ * const guardrail = createPromptInjectionGuardrail({
+ *   strictMode: true,
+ *   onBlocked: (input, patterns) => logSecurityEvent(input, patterns),
+ * });
+ * ```
+ */
+
+/** Pattern with metadata for better debugging */
+interface InjectionPattern {
+    pattern: RegExp;
+    name: string;
+    severity: "low" | "medium" | "high" | "critical";
+    category: InjectionCategory;
+}
+/** Categories of injection attacks */
+type InjectionCategory = "instruction_override" | "jailbreak" | "role_manipulation" | "encoding_evasion" | "delimiter_injection" | "context_manipulation" | "indirect_injection";
+/** Default injection patterns - well-tested and low false-positive rate */
+declare const DEFAULT_INJECTION_PATTERNS: InjectionPattern[];
+/** Strict patterns - more aggressive, may have higher false positives */
+declare const STRICT_INJECTION_PATTERNS: InjectionPattern[];
+/** Detailed detection result */
+interface InjectionDetectionResult {
+    detected: boolean;
+    patterns: Array<{
+        name: string;
+        category: InjectionCategory;
+        severity: InjectionPattern["severity"];
+        match: string;
+        position: number;
+    }>;
+    riskScore: number;
+    sanitizedInput?: string;
+}
+/**
+ * Detect prompt injection patterns in text.
+ * Returns detailed results about what was detected.
+ *
+ * @throws Error if input exceeds MAX_INJECTION_INPUT_LENGTH (100KB)
+ */
+declare function detectPromptInjection(text: string, patterns?: InjectionPattern[]): InjectionDetectionResult;
+/**
+ * Sanitize text by removing detected injection patterns.
+ * Warning: This is a best-effort sanitization, not a security guarantee.
+ *
+ * Uses a single-pass approach to prevent infinite loops where a replacement
+ * could create a new pattern match.
+ */
+declare function sanitizeInjection(text: string, patterns?: InjectionPattern[]): string;
+/** Options for prompt injection guardrail */
+interface PromptInjectionGuardrailOptions {
+    /** Additional patterns to check (added to defaults) */
+    additionalPatterns?: InjectionPattern[];
+    /** Replace default patterns entirely */
+    replacePatterns?: InjectionPattern[];
+    /** Use strict mode with more aggressive detection */
+    strictMode?: boolean;
+    /** Minimum risk score to block (0-100, default: 50) */
+    blockThreshold?: number;
+    /** Attempt to sanitize instead of blocking */
+    sanitize?: boolean;
+    /** Callback when injection is detected */
+    onBlocked?: (input: string, result: InjectionDetectionResult) => void;
+    /** Categories to ignore (e.g., allow 'role_manipulation' for roleplay apps) */
+    ignoreCategories?: InjectionCategory[];
+}
+/**
+ * Create a prompt injection detection guardrail.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const guardrail = createPromptInjectionGuardrail();
+ *
+ * // Strict mode for high-security applications
+ * const strictGuardrail = createPromptInjectionGuardrail({
+ *   strictMode: true,
+ *   blockThreshold: 25,
+ * });
+ *
+ * // Allow role manipulation for roleplay apps
+ * const roleplayGuardrail = createPromptInjectionGuardrail({
+ *   ignoreCategories: ['role_manipulation'],
+ * });
+ * ```
+ */
+declare function createPromptInjectionGuardrail(options?: PromptInjectionGuardrailOptions): GuardrailFn<InputGuardrailData>;
+/**
+ * Mark content as potentially untrusted (from external sources).
+ * This wraps the content with markers that injection detection will scrutinize more closely.
+ *
+ * @example
+ * ```typescript
+ * const userUpload = await readFile(path);
+ * const markedContent = markUntrustedContent(userUpload, 'user-upload');
+ * const prompt = `Summarize this document: ${markedContent}`;
+ * ```
+ */
+declare function markUntrustedContent(content: string, source: string): string;
+/**
+ * Create a guardrail that applies stricter checks to marked untrusted content.
+ *
+ * @example
+ * ```typescript
+ * const guardrail = createUntrustedContentGuardrail({
+ *   baseGuardrail: createPromptInjectionGuardrail({ strictMode: true }),
+ * });
+ * ```
+ */
+declare function createUntrustedContentGuardrail(options: {
+    /** Guardrail to apply to untrusted sections */
+    baseGuardrail?: GuardrailFn<InputGuardrailData>;
+    /** Block if untrusted content contains these patterns */
+    additionalPatterns?: InjectionPattern[];
+}): GuardrailFn<InputGuardrailData>;
+
+/**
+ * Approximate Nearest Neighbor (ANN) Index for Semantic Cache
+ *
+ * Provides pluggable vector search backends for efficient similarity lookups.
+ * Includes a brute-force exact search and a VP-tree (Vantage Point Tree) for
+ * fast approximate nearest neighbor queries.
+ *
+ * @example
+ * ```typescript
+ * import { createSemanticCache } from '@directive-run/ai';
+ * import { createVPTreeIndex } from '@directive-run/ai';
+ *
+ * const index = createVPTreeIndex();
+ *
+ * const cache = createSemanticCache({
+ *   embedder: myEmbedder,
+ *   annIndex: index,
+ * });
+ * ```
+ */
+
+/** Search result from an ANN index */
+interface ANNSearchResult {
+    /** ID of the matched item */
+    id: number;
+    /** Similarity score (0-1, higher is more similar) */
+    similarity: number;
+}
+/** ANN Index interface - pluggable vector search backend */
+interface ANNIndex {
+    /** Add a vector to the index */
+    add(id: number, embedding: Embedding): void;
+    /** Remove a vector from the index */
+    remove(id: number): void;
+    /** Search for the k nearest neighbors */
+    search(query: Embedding, k: number, threshold?: number): ANNSearchResult[];
+    /** Rebuild the index (call after batch additions) */
+    rebuild(): void;
+    /** Get the number of indexed vectors */
+    size(): number;
+    /** Clear the index */
+    clear(): void;
+    /** Check if the index needs to be rebuilt (e.g., after additions/removals) */
+    needsRebuild(): boolean;
+}
+/**
+ * Create a brute-force exact search index.
+ *
+ * O(n) search, O(1) add/remove. Best for small collections (< 10,000 vectors).
+ *
+ * @example
+ * ```typescript
+ * const index = createBruteForceIndex();
+ * index.add(0, [0.1, 0.2, 0.3]);
+ * index.add(1, [0.4, 0.5, 0.6]);
+ *
+ * const results = index.search([0.1, 0.2, 0.3], 1);
+ * // [{ id: 0, similarity: 1.0 }]
+ * ```
+ */
+declare function createBruteForceIndex(): ANNIndex;
+/** VP-Tree index configuration */
+interface VPTreeIndexConfig {
+    /** Optional random number generator for deterministic builds. Returns a number in [0, 1). */
+    random?: () => number;
+}
+/**
+ * Create a VP-Tree (Vantage Point Tree) index for efficient approximate nearest neighbor search.
+ *
+ * O(log n) search on average, requires rebuild after batch additions.
+ * Best for medium collections (1,000 - 100,000 vectors).
+ *
+ * @example
+ * ```typescript
+ * const index = createVPTreeIndex();
+ *
+ * // Add vectors
+ * for (let i = 0; i < embeddings.length; i++) {
+ *   index.add(i, embeddings[i]);
+ * }
+ *
+ * // Build the tree
+ * index.rebuild();
+ *
+ * // Search
+ * const results = index.search(queryEmbedding, 5, 0.9);
+ * ```
+ */
+declare function createVPTreeIndex(vpConfig?: VPTreeIndexConfig): ANNIndex;
+
+export { type ANNIndex as A, detectPII as B, detectPromptInjection as C, DEFAULT_INJECTION_PATTERNS as D, type EnhancedPIIGuardrailOptions as E, type FactPIICategory as F, markUntrustedContent as G, redactPII as H, type InjectionDetectionResult as I, sanitizeInjection as J, type PIIType as P, type RedactionStyle as R, STRICT_INJECTION_PATTERNS as S, type VPTreeIndexConfig as V, type ANNSearchResult as a, type DetectedPII as b, type FactPIIErrorMode as c, type FactPIIGuardrailMode as d, type FactPIIGuardrailOptions as e, type FactPIIMatch as f, type PIIDetectionResult as g, type PIIDetector as h, type PromptInjectionGuardrailOptions as i, type RateLimitGuardrail as j, createBruteForceIndex as k, createContentFilterGuardrail as l, createEnhancedPIIGuardrail as m, createFactPIIGuardrail as n, createLengthGuardrail as o, createModerationGuardrail as p, createOutputPIIGuardrail as q, createOutputSchemaGuardrail as r, createOutputTypeGuardrail as s, createPIIGuardrail as t, createPromptInjectionGuardrail as u, createRateLimitGuardrail as v, createToolGuardrail as w, createUntrustedContentGuardrail as x, createVPTreeIndex as y, detectAndRedactPII as z };