@dudousxd/nestjs-agent-core 0.15.5 → 0.17.0

package/dist/guardrails/index.d.cts

@@ -0,0 +1,660 @@
+import { A as Actor, I as InputProcessor, O as OutputProcessor, T as ToolHandler } from '../tool-CL9oEytW.cjs';
+import '@standard-schema/spec';
+
+/**
+ * Guardrails: detectors that look at text on its way to or from a model — prompts, answers, tool
+ * arguments, tool results, tool descriptions — and rules that decide what to do when they fire.
+ *
+ * Nothing in this module depends on the agent loop, on NestJS or on a runtime API beyond the
+ * language itself. A process that proxies raw provider traffic uses the detectors, `scan`, `Vault`
+ * and `StreamGuard` directly; `createGuardrails` is the adapter onto the loop's processor seams.
+ */
+/** Where in the traffic a rule applies. */
+type GuardrailStage = 
+/** Prompt + attached context sent to a model (system, user, assistant history). */
+'llm_request'
+/** What the model answered (text and tool-call arguments), streaming included. */
+ | 'llm_response'
+/** Arguments of a tool call, before the tool runs. */
+ | 'tool_args'
+/** What a tool returned, before it flows back into the model (indirect prompt injection). */
+ | 'tool_result'
+/** Tool descriptions and schemas of a remote tool server (tool poisoning). */
+ | 'tool_description';
+declare const GUARDRAIL_STAGES: readonly GuardrailStage[];
+/**
+ * - `allow`: exemption. When it matches (its detectors fire, or it has none), later rules are skipped.
+ * - `log`: record the hit only (a "flag").
+ * - `redact`: replace what was found by placeholders (reversible for values sent to a model).
+ * - `approve`: human-in-the-loop — refuse until someone approves this exact content. A caller that
+ *   has no approval flow of its own treats it as `block`.
+ * - `block`: refuse with the rule's user-facing message.
+ */
+type GuardrailAction = 'allow' | 'log' | 'redact' | 'approve' | 'block';
+/** Severity order used to combine several rules: the most severe wins. */
+declare const ACTION_SEVERITY: Record<GuardrailAction, number>;
+type PiiType = 'email' | 'phone' | 'cpf' | 'cnpj' | 'ssn' | 'credit_card' | 'iban' | 'ip_address';
+declare const PII_TYPES: readonly PiiType[];
+type SecretType = 'openai_key' | 'anthropic_key' | 'aws_access_key' | 'aws_secret_key' | 'github_token' | 'gitlab_token' | 'slack_token' | 'google_api_key' | 'stripe_key' | 'jwt' | 'bearer_token' | 'private_key' | 'generic_secret';
+declare const SECRET_TYPES: readonly SecretType[];
+/** Something a detector found. `value` is the matched text; keep it in-process. */
+interface Finding {
+    /** The detector kind (or a custom detector's name). */
+    detector: string;
+    /** e.g. `pii.credit_card`, `secret.aws_access_key`, `injection.ignore_previous`. */
+    category: string;
+    start: number;
+    end: number;
+    score: number;
+    value: string;
+    /**
+     * Whether the finding can be redacted by replacing its span. `false` for whole-text verdicts
+     * (a moderation or classifier call), which replace the whole segment when redacting.
+     */
+    spanned?: boolean;
+    /**
+     * What a redaction puts in place of this span. Undefined → a vault placeholder (`[EMAIL_1]`).
+     * Detectors whose finding is an instruction rather than a value (injection, tool poisoning) set
+     * this so the text is removed rather than tokenized.
+     */
+    replacement?: string;
+}
+/** Who wrote a piece of text (model request stage). */
+type SegmentSource = 'system' | 'user' | 'assistant' | 'tool';
+/** A piece of text to scan, with where it came from. */
+interface Segment {
+    text: string;
+    source?: SegmentSource;
+    /**
+     * Part of the newest turn. Content that is only in re-sent history is acted upon (redacted
+     * one-way instead of blocked) but its hits are reported as not fresh. Undefined → fresh.
+     */
+    fresh?: boolean;
+}
+/**
+ * What the traffic is about. `stage` is the only field the engine reads itself; `tool` feeds the
+ * `match.tools` globs. Extend it with whatever your rules' `when` predicates need (tenant, actor,
+ * model, destination…).
+ */
+interface GuardContext {
+    stage: GuardrailStage;
+    /** Tool name, on tool stages. */
+    tool?: string;
+}
+/** A detector that runs your own code — NER, a classifier, a moderation endpoint, an LLM judge. */
+interface CustomDetector<C extends GuardContext = GuardContext> {
+    kind: 'custom';
+    /** Identifies the detector in findings and hits (`detector`). Also its memoization key. */
+    name: string;
+    detect(text: string, ctx: C): Finding[] | Promise<Finding[]>;
+}
+/** A detector as configured on a rule. */
+type DetectorSpec<C extends GuardContext = GuardContext> = 
+/** Regex + checksum validators (Luhn, CPF/CNPJ mod 11, IBAN mod 97…). */
+{
+    kind: 'pii';
+    types?: readonly PiiType[];
+}
+/** API keys, tokens and private keys (patterns + entropy). */
+ | {
+    kind: 'secrets';
+    types?: readonly SecretType[];
+}
+/** Prompt-injection / jailbreak heuristics (EN, PT-BR, ES; hidden Unicode; encoded payloads). */
+ | {
+    kind: 'injection';
+    threshold?: number;
+}
+/** Suspicious instructions hidden in tool descriptions (tool poisoning). */
+ | {
+    kind: 'tool_poisoning';
+    threshold?: number;
+}
+/** Your own regular expressions (`(?i)` prefix = case-insensitive). */
+ | {
+    kind: 'regex';
+    patterns: readonly string[];
+    label?: string;
+}
+/** Words or phrases (case- and accent-insensitive, whole words). */
+ | {
+    kind: 'keywords';
+    words: readonly string[];
+    label?: string;
+} | CustomDetector<C>;
+type DetectorKind = DetectorSpec['kind'];
+/** Scope a rule to part of the traffic. Every matcher that is set must match. */
+interface GuardrailMatch {
+    /** Model request stage: which messages are scanned (default all). */
+    sources?: readonly SegmentSource[];
+    /** Tool stages: tool-name globs (`*` any run, `?` one character). Never matches model traffic. */
+    tools?: readonly string[];
+}
+interface GuardrailOptions {
+    /** Shown to the person when the rule blocks or asks for approval. */
+    message?: string;
+    /** What happens when a detector throws: `open` = ignore (default), `closed` = block. */
+    failMode?: 'open' | 'closed';
+    /**
+     * `redact` on `llm_request`: put the original values back into the answer the caller receives
+     * (the model only ever sees placeholders). Default true.
+     */
+    restore?: boolean;
+}
+interface GuardrailRule<C extends GuardContext = GuardContext> {
+    id: string;
+    /** Shown in hits and decisions. Default: `id`. */
+    name?: string;
+    /** Ascending order of evaluation; ties by name. Default 100. */
+    priority?: number;
+    /** Default true. */
+    enabled?: boolean;
+    stages: readonly GuardrailStage[];
+    /** Empty → the rule fires on scope alone (an exemption, or a blanket block). */
+    detectors: readonly DetectorSpec<C>[];
+    action: GuardrailAction;
+    match?: GuardrailMatch;
+    /**
+     * Anything scope-like the engine does not know about — the tenant, the actor's roles, the model
+     * or its destination. Returning false leaves the rule out of this scan.
+     */
+    when?: (ctx: C) => boolean;
+    options?: GuardrailOptions;
+}
+
+/** Dotted-quad IPv4 with every octet in 0-255 and no leading zeros. */
+declare function isIPv4(raw: string): boolean;
+/** Luhn (mod 10) checksum over a digit string. */
+declare function luhnValid(digits: string): boolean;
+/** Card brands by IIN prefix (digits only). Unknown prefixes are not treated as cards. */
+declare function cardBrand(digits: string): string | undefined;
+/** CPF (Brazilian individual taxpayer id): 11 digits, two mod-11 check digits. */
+declare function cpfValid(raw: string): boolean;
+/**
+ * CNPJ (Brazilian company id), numeric or the alphanumeric format in use since July 2026: 12
+ * characters [0-9A-Z] + 2 check digits, each character valued at its ASCII code minus 48.
+ */
+declare function cnpjValid(raw: string): boolean;
+/** US Social Security Number structure (no 000/666/9xx area, no 00 group, no 0000 serial). */
+declare function ssnValid(raw: string): boolean;
+/** IBAN: known country length and ISO 7064 mod 97-10 checksum. */
+declare function ibanValid(raw: string): boolean;
+/** Phone numbers: international (+CC), Brazilian and North American formats with separators. */
+declare function phoneValid(raw: string): boolean;
+/** PII with format + checksum validation. Overlaps are resolved by the caller (longest, earliest). */
+declare function detectPii(text: string, types?: readonly PiiType[]): Finding[];
+
+/** Shannon entropy in bits per character: tells random tokens from words ("password=changeme"). */
+declare function entropy(s: string): number;
+declare function detectSecrets(text: string, types?: readonly SecretType[]): Finding[];
+
+/**
+ * Prompt-injection / jailbreak heuristics. Each signal has a weight; the text's score is the
+ * noisy-OR of the distinct signals that fired (1 - Π(1 - w)), so one strong signal or several weak
+ * ones cross the threshold. English, Portuguese (PT-BR) and Spanish phrasings, role/delimiter
+ * spoofing, hidden Unicode (tag characters, bidi overrides, zero-width runs) and exfiltration
+ * through rendered links/images.
+ */
+interface Signal {
+    id: string;
+    re: RegExp;
+    weight: number;
+}
+declare const INJECTION_SIGNALS: Signal[];
+/** Decodes Unicode tag characters ("ASCII smuggling") back to the ASCII they encode. */
+declare function decodeTagChars(s: string): string;
+interface InjectionResult {
+    score: number;
+    findings: Finding[];
+}
+/** Scores a text; findings are returned only when the score reaches `threshold`. */
+declare function scoreInjection(text: string, threshold?: number): InjectionResult;
+
+interface PoisoningResult {
+    score: number;
+    findings: Finding[];
+}
+declare function scoreToolText(text: string, threshold?: number): PoisoningResult;
+/** The parts of a tool definition a model reads — MCP's `Tool` shape satisfies it. */
+interface ToolDefinitionText {
+    name: string;
+    title?: string | null | undefined;
+    description?: string | null | undefined;
+    inputSchema?: unknown;
+}
+/** Every description the model reads for a tool: its own and its parameters' (nested). */
+declare function toolText(tool: ToolDefinitionText): string;
+
+/** Compiled once per pattern (global flag added), with a bounded cache. */
+declare function compileGuardPattern(pattern: string): RegExp;
+declare function detectRegex(text: string, patterns: readonly string[], label?: string): Finding[];
+/** Lower case without accents, keeping string length stable (one output char per input char). */
+declare function fold(s: string): string;
+/** Whole-word, case- and accent-insensitive keyword/phrase matching. */
+declare function detectKeywords(text: string, words: readonly string[], label?: string): Finding[];
+
+/** Minimal glob: `*` matches any run of characters, `?` a single one. Case-sensitive. */
+declare function globToRegExp(pattern: string): RegExp;
+declare function matchesAny(value: string, patterns: readonly string[] | undefined): boolean;
+
+/**
+ * Reversible tokenization for one request: each distinct sensitive value gets a stable placeholder
+ * (`[EMAIL_1]`, `[CREDIT_CARD_2]`…) in order of first appearance, so a conversation re-sent turn
+ * after turn maps to the same placeholders. The model only sees placeholders; `restore` puts the
+ * values back into what the caller receives.
+ *
+ * Values stay in this object. {@link toJSON} / {@link fromJSON} exist for a caller that must carry a
+ * vault across processes (a durable run resumed elsewhere); wherever that snapshot is stored holds
+ * the raw values, so treat it like the data it came from.
+ */
+declare class Vault {
+    private readonly byValue;
+    private readonly byToken;
+    private readonly counters;
+    /**
+     * Placeholder for `value` under `label` (e.g. `CREDIT_CARD`). Reversible placeholders look like
+     * `[CREDIT_CARD_1]`; one-way ones (tool results, answers, rules with `restore: false`) like
+     * `[REDACTED_CREDIT_CARD_1]`, so they can never be mistaken for a reversible one.
+     */
+    tokenFor(label: string, value: string, restorable: boolean): string;
+    get size(): number;
+    get restorableCount(): number;
+    /** Longest placeholder, for stream hold-back windows. */
+    get maxTokenLength(): number;
+    /** Puts restorable values back. `jsonString`: the text is inside a JSON string literal. */
+    restore(text: string, jsonString?: boolean): string;
+    /** Whether `text` ends with what could be the beginning of a placeholder (streaming). */
+    pendingPrefix(text: string): number;
+    /** Every entry, in the order the placeholders were minted. */
+    toJSON(): VaultSnapshot;
+    /** Rebuilds a vault from {@link toJSON}; placeholders keep their numbers and counters resume. */
+    static fromJSON(snapshot: VaultSnapshot): Vault;
+}
+/** A serializable {@link Vault}. */
+interface VaultSnapshot {
+    entries: Array<{
+        token: string;
+        value: string;
+        restorable: boolean;
+    }>;
+}
+/** `pii.credit_card` -> `CREDIT_CARD`, `secret.openai_key` -> `OPENAI_KEY`, `ner.person` -> `PERSON`. */
+declare function labelFor(category: string): string;
+
+/**
+ * One reported hit. `values` holds the distinct matched values so a caller can fingerprint them
+ * (a keyed hash correlates repeats without storing the value) — never persist them as they are.
+ */
+interface GuardHit {
+    ruleId: string;
+    ruleName: string;
+    action: GuardrailAction;
+    detector: string;
+    category: string;
+    score: number;
+    count: number;
+    /** Distinct values found (at most 20). In-memory only. */
+    values: string[];
+    /** Found in the newest turn (false: only in re-sent history, already reported once). */
+    fresh: boolean;
+    /** `detector_error` hits: what failed, and what the rule's fail mode made of it. */
+    error?: string;
+    failMode?: 'open' | 'closed';
+}
+interface ScanResult {
+    stage: GuardrailStage;
+    /** Most severe action among the rules that fired. */
+    action: GuardrailAction;
+    /** The rule that decided a block / approval, and the message for the person. */
+    decisive?: {
+        id: string;
+        name: string;
+        message: string;
+    };
+    /** Segment texts after redaction (same order as the input). */
+    segments: string[];
+    /** Whether any segment changed. */
+    changed: boolean;
+    hits: GuardHit[];
+    vault: Vault;
+    /** Redacted spans. */
+    redactions: number;
+    latencyMs: number;
+}
+interface ScanOptions {
+    /** Per-stage refusal messages, for rules that set none. */
+    messages?: Partial<Record<GuardrailStage, string>>;
+    /** Refusal message for `approve`, for rules that set none. */
+    approvalMessage?: string;
+    /**
+     * Stages whose redactions are reversible (unless the rule sets `restore: false`). Default
+     * `['llm_request']`: what the caller sent is theirs to get back; what a tool or the model produced
+     * is removed one-way. A caller whose tool results are its own data may add `tool_result`.
+     */
+    restorableStages?: readonly GuardrailStage[];
+}
+declare const DEFAULT_MESSAGES: Record<GuardrailStage, string>;
+declare const DEFAULT_APPROVAL_MESSAGE = "This needs approval under your organization's AI guardrails before it can go ahead.";
+/** What replaces an instruction-like finding: it is removed, not tokenized. */
+declare const INJECTION_REPLACEMENT = "[removed: suspected prompt injection]";
+/** Whether a rule's scope covers the context (stage, tool, `when`). Segments are filtered apart. */
+declare function ruleApplies<C extends GuardContext>(rule: GuardrailRule<C>, ctx: C): boolean;
+declare function orderRules<C extends GuardContext>(rules: readonly GuardrailRule<C>[]): GuardrailRule<C>[];
+/** Runs one detector on one text. A custom detector's throw is the rule's fail mode to decide. */
+declare function runDetector<C extends GuardContext>(spec: DetectorSpec<C>, text: string, ctx: C): Promise<Finding[]>;
+/**
+ * The in-process detectors of a rule set, as one span locator — what a stream window must never
+ * cut through (see `StreamGuard`'s `locate`). Custom detectors are left out: they may be remote.
+ */
+declare function spanLocator<C extends GuardContext>(rules: readonly GuardrailRule<C>[]): ((text: string) => Finding[]) | undefined;
+/**
+ * Non-overlapping spans. Overlapping findings are merged into their union (nothing that any
+ * detector found is left uncovered), labelled by the longer finding (ties: the higher score) —
+ * an injected HTML comment that contains an email address is removed as a whole. With `text`, a
+ * merged span's value is re-read from it.
+ */
+declare function resolveOverlaps(findings: readonly Finding[], text?: string): Finding[];
+declare function applyRedactions(text: string, findings: readonly Finding[], vault: Vault, restorable: boolean): {
+    text: string;
+    count: number;
+};
+/**
+ * Evaluates the rules for one stage over a set of segments. Rules run by ascending priority; an
+ * `allow` rule that fires stops evaluation; otherwise every firing rule contributes and the most
+ * severe action wins (block > approve > redact > log). Detector results are shared between rules.
+ *
+ * Blocking applies to the NEWEST turn: content found only in re-sent history (`fresh: false`) was
+ * already refused once, so it is removed one-way instead — the conversation can go on and the value
+ * still never reaches the model.
+ */
+declare function scan<C extends GuardContext>(rules: readonly GuardrailRule<C>[], ctx: C, segments: readonly Segment[], vault?: Vault, options?: ScanOptions): Promise<ScanResult>;
+
+/**
+ * Text slots of provider and MCP payloads, for a process that proxies them: each slot is a piece of
+ * text to scan plus a setter that writes the (redacted / restored) text back in place.
+ */
+interface Slot {
+    segment: Segment;
+    set(text: string): void;
+    /** The text lives inside a JSON document (tool-call arguments): restored values are escaped. */
+    json?: boolean;
+}
+/** String leaves of a JSON value (tool arguments, structured results). */
+declare function jsonSlots(root: unknown, source: SegmentSource, fresh: boolean, replaceRoot?: (v: string) => void): Slot[];
+/** Slots of an LLM request body: OpenAI chat completions, Anthropic Messages or embeddings. */
+declare function requestSlots(api: 'openai' | 'anthropic', body: Record<string, unknown>): Slot[];
+/** Slots of a non-streaming answer in the caller's format (OpenAI chat completion or Anthropic message). */
+declare function responseSlots(api: 'openai' | 'anthropic', body: unknown): Slot[];
+/** Replaces the answer of a non-streaming response with a refusal (finish reason content_filter). */
+declare function refuseResponse(api: 'openai' | 'anthropic', body: unknown, message: string): unknown;
+/** Slots of an MCP tool result: text content, embedded text resources and structured content. */
+declare function toolResultSlots(result: Record<string, unknown>): Slot[];
+
+/**
+ * Guards a streamed answer in the caller's format (OpenAI chat-completion chunks or Anthropic
+ * Messages events). Text deltas are buffered per channel (the answer text, each tool call's
+ * arguments, each content block) and released in windows: the newest `holdback` characters stay
+ * buffered so a value split across deltas ("4111 1111" … "1111 1111") is seen whole, and a window
+ * never ends inside something a detector found or inside a placeholder being restored. Each
+ * released window is scanned (redaction, moderation…) and has placeholders restored. When a
+ * window is blocked the stream ends with the rule's message and a `content_filter` / `refusal`
+ * finish; the rest of the upstream is consumed (for usage) but not forwarded.
+ */
+interface WindowVerdict {
+    /** Text to release (redacted). */
+    text: string;
+    block?: {
+        message: string;
+    };
+}
+interface StreamGuardOptions {
+    api: 'openai' | 'anthropic';
+    vault: Vault;
+    /** Restore placeholders from the request's redactions into what the caller receives. */
+    restore: boolean;
+    /** Response-stage scan of one window; undefined when no response rule applies. */
+    scan?: (text: string, channel: string) => Promise<WindowVerdict>;
+    /** Spans (local detectors) a window must not cut through. */
+    locate?: (text: string) => Finding[];
+    /** Characters released per window (default 256). */
+    window?: number;
+    /** Characters kept back at the end of the buffer (default 64). */
+    holdback?: number;
+}
+declare class StreamGuard {
+    private readonly opts;
+    private buffer;
+    private readonly decoder;
+    private readonly channels;
+    private readonly window;
+    private readonly holdback;
+    blocked?: {
+        message: string;
+    };
+    private template;
+    private readonly openBlocks;
+    private maxBlock;
+    private done;
+    constructor(opts: StreamGuardOptions);
+    /** Whether the guard changes anything (else the caller can pass bytes straight through). */
+    get active(): boolean;
+    push(chunk: string | Uint8Array): Promise<string>;
+    end(): Promise<string>;
+    private frame;
+    private openaiFrame;
+    private openaiChunk;
+    private openaiBlock;
+    private flushChoice;
+    private anthropicFrame;
+    private flushBlock;
+    private anthropicBlock;
+    private flushAll;
+    private feed;
+    /** Releases a window (everything when `all`), scanned and restored. */
+    private release;
+}
+
+/**
+ * Guardrails on the agent loop's own seams: an {@link InputProcessor} that scans (and redacts) every
+ * prompt — including the tool results riding in it — an {@link OutputProcessor} that scans every
+ * answer and the tool calls it asks for, a tool-handler wrapper, and a tool-definition screen.
+ *
+ * Built only on the processor SPI, so it is a consumer of the loop rather than a part of it: the
+ * same rules and detectors run standalone through `scan` for traffic that never meets the loop.
+ */
+
+/** What a rule's `when` and a custom detector see when the guardrails run inside the loop. */
+interface AgentGuardContext extends GuardContext {
+    /** Undefined only for a tool definition screened outside any turn. */
+    threadId?: string;
+    actor?: Actor;
+    agentName?: string;
+    /** Model step within the run; undefined outside a processor. */
+    step?: number;
+    /** The tool server a screened definition came from (e.g. the MCP server's name). */
+    server?: string;
+}
+type Stages = readonly GuardrailStage[];
+interface PiiShorthand {
+    action: GuardrailAction;
+    types?: readonly PiiType[];
+    /**
+     * Put the original values back into the answer and into tool arguments (the model only sees
+     * placeholders). Covers values from the prompt and from tool results. Default true.
+     */
+    restore?: boolean;
+    stages?: Stages;
+}
+interface SecretsShorthand {
+    action: GuardrailAction;
+    types?: readonly SecretType[];
+    stages?: Stages;
+}
+interface InjectionShorthand {
+    /** Default `block`. */
+    action?: GuardrailAction;
+    /** Noisy-OR score (0-1) at which the heuristics fire. Default 0.5. */
+    threshold?: number;
+    stages?: Stages;
+}
+interface ToolPoisoningShorthand {
+    /** `block` (default) refuses the tool in {@link Guardrails.screenTool}; `log` only reports it. */
+    action?: 'block' | 'log';
+    threshold?: number;
+}
+/** One decision worth auditing. Never carries the matched values themselves. */
+interface GuardrailEvent {
+    stage: GuardrailStage;
+    /** The effective action (`approve` is reported as it was configured, and enforced as a block). */
+    action: GuardrailAction;
+    decisive?: {
+        id: string;
+        name: string;
+        message: string;
+    };
+    /** Hits in the newest content only — history re-sent every step is not reported again. */
+    hits: GuardrailEventHit[];
+    redactions: number;
+    latencyMs: number;
+    context: AgentGuardContext;
+}
+type GuardrailEventHit = Omit<GuardHit, 'values'> & {
+    /** {@link GuardrailsOptions.fingerprint} of each distinct value; empty without one. */
+    fingerprints: string[];
+};
+/** Where a thread's reversible placeholders live between the prompt and the answer. */
+interface VaultStore {
+    load(threadId: string): Vault | undefined | Promise<Vault | undefined>;
+    save(threadId: string, vault: Vault): void | Promise<void>;
+}
+/**
+ * The default {@link VaultStore}: this process's memory, bounded to the most recent threads. A run
+ * resumed in ANOTHER process finds no vault, so its placeholders reach the reader unrestored — the
+ * values still never reach the model. Supply a shared store (with {@link Vault.toJSON}) to restore
+ * across processes; it then holds the raw values.
+ */
+declare class InMemoryVaultStore implements VaultStore {
+    private readonly maxThreads;
+    private readonly vaults;
+    constructor(maxThreads?: number);
+    load(threadId: string): Vault | undefined;
+    save(threadId: string, vault: Vault): void;
+}
+type GuardrailRulesSource = readonly GuardrailRule<AgentGuardContext>[] | ((ctx: AgentGuardContext) => readonly GuardrailRule<AgentGuardContext>[] | Promise<readonly GuardrailRule<AgentGuardContext>[]>);
+interface GuardrailsOptions {
+    /** PII (email, phone, CPF/CNPJ, SSN, cards with Luhn, IBAN, IPv4). */
+    pii?: GuardrailAction | PiiShorthand;
+    /** API keys, tokens and private keys. */
+    secrets?: GuardrailAction | SecretsShorthand;
+    /** Prompt-injection / jailbreak heuristics. */
+    injection?: GuardrailAction | InjectionShorthand;
+    /** Screen tool definitions for hidden instructions — see {@link Guardrails.screenTool}. */
+    toolPoisoning?: boolean | ToolPoisoningShorthand;
+    /**
+     * More rules, evaluated alongside the shorthands. A function is called per scan with the turn's
+     * context, which is the seam for per-tenant policy: look the tenant's rules up by `ctx.actor`.
+     */
+    rules?: GuardrailRulesSource;
+    /** Audit hook. Awaited; a throw is swallowed so an audit sink can never change a decision. */
+    onEvent?: (event: GuardrailEvent) => void | Promise<void>;
+    /** Keyed hash (or any stable digest) of a matched value, reported on events instead of it. */
+    fingerprint?: (value: string) => string;
+    /** Per-stage refusal messages for rules that set none. */
+    messages?: ScanOptions['messages'];
+    /** Where reversible placeholders live between prompt and answer. Default {@link InMemoryVaultStore}. */
+    vaults?: VaultStore;
+    /**
+     * Keep the turn streaming: the output processor declares `incremental` with this lookback, so
+     * the loop releases a prefix while holding the last `lookbackChars` characters. `false` gates the
+     * whole answer instead. Default `{ lookbackChars: 256 }` — wide enough for every built-in
+     * pattern and placeholder; widen it for custom patterns that match longer text.
+     */
+    incremental?: false | {
+        lookbackChars?: number;
+    };
+    /** Processor name (user-visible on a refusal). Default `guardrails`. */
+    name?: string;
+}
+/** A guardrail refused content the loop cannot rewrite around: a prompt, or a tool call. */
+declare class GuardrailBlockedError extends Error {
+    readonly stage: GuardrailStage;
+    /** The message for the person — the rule's own, or the stage default. */
+    readonly userMessage: string;
+    readonly rule?: {
+        id: string;
+        name: string;
+    } | undefined;
+    constructor(stage: GuardrailStage, 
+    /** The message for the person — the rule's own, or the stage default. */
+    userMessage: string, rule?: {
+        id: string;
+        name: string;
+    } | undefined);
+}
+/** The rules the shorthand options stand for. Exported so a caller can inspect or extend them. */
+declare function shorthandRules(options: GuardrailsOptions): GuardrailRule<AgentGuardContext>[];
+/**
+ * Guardrails for the agent loop. Register the two processors, optionally wrap tool handlers, and
+ * hand {@link screenTool} to whatever imports remote tool definitions:
+ *
+ * ```ts
+ * const guardrails = createGuardrails({ pii: 'redact', secrets: 'block', injection: { threshold: 0.6 }, toolPoisoning: true });
+ * AgentModule.forRoot({ inputProcessors: [guardrails.input], outputProcessors: [guardrails.output], … });
+ * ```
+ */
+declare class Guardrails {
+    private readonly options;
+    /** Scans every prompt; redacts in place, withholds tool results, throws on a blocked prompt. */
+    readonly input: InputProcessor;
+    /** Scans every answer and the tool calls it asks for; redacts, restores placeholders, or rejects. */
+    readonly output: OutputProcessor;
+    private readonly shorthand;
+    private readonly vaults;
+    /** Per thread: hits already reported this turn, so re-scans of the same content stay quiet. */
+    private readonly reported;
+    constructor(options?: GuardrailsOptions);
+    /** Every rule in force for `ctx`: the shorthands, then {@link GuardrailsOptions.rules}. */
+    rulesFor(ctx: AgentGuardContext): Promise<GuardrailRule<AgentGuardContext>[]>;
+    /**
+     * Scans arbitrary segments at one stage with the configured rules, reporting through `onEvent`.
+     * What the processors use; also the entry point for traffic that never meets the loop.
+     */
+    scan(ctx: AgentGuardContext, segments: readonly Segment[], vault?: Vault): Promise<ScanResult>;
+    /**
+     * Screens one tool definition (name, title, description, and every description in its input
+     * schema) for hidden instructions. `allowed: false` means a `block`/`approve` rule fired — leave
+     * the tool out of the catalog. Shaped to be handed straight to an MCP importer's screen hook.
+     */
+    screenTool(tool: ToolDefinitionText & {
+        server?: string;
+    }): Promise<{
+        allowed: true;
+    } | {
+        allowed: false;
+        reason: string;
+    }>;
+    /**
+     * Wraps a tool handler so its arguments are guarded where the loop cannot rewrite them: the
+     * thread's placeholders are restored (the model only ever saw `[EMAIL_1]`, the tool needs the
+     * address), then the `tool_args` rules run — `redact` rewrites what the tool receives, `block`
+     * throws a {@link GuardrailBlockedError}, which the model reads as the tool's failure.
+     */
+    wrapTool<I>(toolName: string, handler: ToolHandler<I>): ToolHandler<I>;
+    private contextOf;
+    private processInput;
+    private guardToolResult;
+    private processOutput;
+    private report;
+}
+/** Shorthand for `new Guardrails(options)`. */
+declare function createGuardrails(options?: GuardrailsOptions): Guardrails;
+/**
+ * The tool-poisoning screen alone — no rules, no events. `score` is the noisy-OR of the signals
+ * that fired; `findings` is empty below `threshold` (default 0.5).
+ */
+declare function screenToolDefinition(tool: ToolDefinitionText, threshold?: number): {
+    score: number;
+    findings: Finding[];
+};
+
+export { ACTION_SEVERITY, type AgentGuardContext, type CustomDetector, DEFAULT_APPROVAL_MESSAGE, DEFAULT_MESSAGES, type DetectorKind, type DetectorSpec, type Finding, GUARDRAIL_STAGES, type GuardContext, type GuardHit, type GuardrailAction, GuardrailBlockedError, type GuardrailEvent, type GuardrailEventHit, type GuardrailMatch, type GuardrailOptions, type GuardrailRule, type GuardrailRulesSource, type GuardrailStage, Guardrails, type GuardrailsOptions, INJECTION_REPLACEMENT, INJECTION_SIGNALS, InMemoryVaultStore, type InjectionResult, type InjectionShorthand, PII_TYPES, type PiiShorthand, type PiiType, type PoisoningResult, SECRET_TYPES, type ScanOptions, type ScanResult, type SecretType, type SecretsShorthand, type Segment, type SegmentSource, type Signal, type Slot, StreamGuard, type StreamGuardOptions, type ToolDefinitionText, type ToolPoisoningShorthand, Vault, type VaultSnapshot, type VaultStore, type WindowVerdict, applyRedactions, cardBrand, cnpjValid, compileGuardPattern, cpfValid, createGuardrails, decodeTagChars, detectKeywords, detectPii, detectRegex, detectSecrets, entropy, fold, globToRegExp, ibanValid, isIPv4, jsonSlots, labelFor, luhnValid, matchesAny, orderRules, phoneValid, refuseResponse, requestSlots, resolveOverlaps, responseSlots, ruleApplies, runDetector, scan, scoreInjection, scoreToolText, screenToolDefinition, shorthandRules, spanLocator, ssnValid, toolResultSlots, toolText };