agent-sanitizer 2.0.0

package/types/instructions.d.mts

@@ -0,0 +1,137 @@
+/**
+ * Decode a run of invisible characters to its likely payload. Recognizes the
+ * two common smuggling encodings — Unicode tag characters (U+E0001–U+E007F map
+ * directly to ASCII) and zero-width binary (ZWSP=0, ZWNJ=1, ZWJ=separator) —
+ * and otherwise reports the raw code points. The tag-character payload is
+ * rendered as a neutral, quoted/escaped `untrusted data, not instructions: "…"`
+ * string (see {@link neutralizeTagBytes}) so the report can never re-inject the
+ * hidden instruction, and only U+E0020–U+E007E map to raw printable ASCII.
+ * @param {string} run
+ * @returns {{ method: string, decoded: string }}
+ */
+export function decodeRun(run: string): {
+    method: string;
+    decoded: string;
+};
+/**
+ * Scan a file's text for hidden-Unicode injection. Reports each long invisible
+ * run (with its decoded payload) plus a single scattered-chars finding when the
+ * non-run invisible count crosses the threshold-evasion floor.
+ * @param {string} content
+ * @returns {Array<{ line: number | null, charCount: number, method: string, decoded: string }>}
+ *   `line` is the 1-based line of a long-run finding, or `null` for the
+ *   whole-file scattered-chars finding (not tied to a single line).
+ */
+export function scanText(content: string): Array<{
+    line: number | null;
+    charCount: number;
+    method: string;
+    decoded: string;
+}>;
+/**
+ * Expand `globs` (relative to `cwd`) to absolute file paths, skipping
+ * `node_modules`. The glob set is the caller's instruction-file convention.
+ *
+ * Containment is enforced per match (see {@link keepContained}): a match whose
+ * glob pattern itself escapes `cwd` — via `..` or an absolute-path glob
+ * outside the tree — THROWS, since reaching outside the tree is a caller
+ * misconfiguration. A match that lexically stays inside `cwd` but resolves
+ * (via an in-tree symlink) to a target outside the tree, or that simply
+ * cannot be resolved (a dangling symlink or unreadable entry inside the
+ * tree), is SKIPPED, so one bad symlink never aborts scanning the rest of the
+ * project.
+ * @param {string[]} globs
+ * @param {{ cwd?: string }} [options]
+ * @returns {string[]}
+ */
+export function findInstructionFiles(globs: string[], { cwd }?: {
+    cwd?: string;
+}): string[];
+/**
+ * Scan every instruction file matched by `globs` and return only those with
+ * findings, each path reported relative to `cwd`. Unreadable/missing files are
+ * skipped. Pure scan — no mutation; pair with {@link cleanFile} to strip.
+ * @param {string[]} globs
+ * @param {{ cwd?: string }} [options]
+ * @returns {Array<{ file: string, findings: ReturnType<typeof scanText> }>}
+ */
+export function scanInstructionFiles(globs: string[], { cwd }?: {
+    cwd?: string;
+}): Array<{
+    file: string;
+    findings: ReturnType<typeof scanText>;
+}>;
+/**
+ * Atomically replace `absPath`'s contents with `data`, preserving `mode`.
+ *
+ * Writes to a sibling temp in the same directory, then `rename`s it over the
+ * original (same dir => same filesystem => the rename is atomic, not a
+ * cross-device copy). The temp name is UNPREDICTABLE (`tmpName()` defaults to
+ * crypto-random) and the temp is created exclusively (O_CREAT|O_EXCL): if the
+ * path already exists — including an attacker-planted symlink at a guessable
+ * temp name — the open fails (EEXIST) and does NOT follow the link to clobber
+ * its target. On the rare collision we fail loud rather than retry into a
+ * different attacker-controlled path.
+ *
+ * Crash-safety (matching the doc claim): the temp fd is `fsync`ed before the
+ * rename and the directory fd is `fsync`ed after it, so a power loss can't leave
+ * the renamed name pointing at unflushed/empty data or lose the rename itself.
+ * The EXACT `mode` is applied with `fchmod` (openSync's create mode is
+ * umask-masked, so it alone would drop bits), and a failed write/sync `unlink`s
+ * the temp before rethrowing so no partial temp leaks. `tmpName` and `remove`
+ * are injectable fault-injection seams for tests (force a known temp path; drive
+ * a cleanup-unlink failure); production callers never pass them.
+ * @param {string} absPath
+ * @param {string} data
+ * @param {number} mode
+ * @param {() => string} [tmpName]
+ * @param {(path: string) => void} [remove]
+ */
+export function atomicReplaceFile(absPath: string, data: string, mode: number, tmpName?: () => string, remove?: (path: string) => void): void;
+/**
+ * Strip payload-capable invisible characters from `absPath` in place. Returns
+ * `true` when the file's bytes actually changed (a payload {@link scanText}
+ * flags was removed), `false` when {@link scanText} reports nothing, and `null`
+ * when scan flagged a payload but {@link stripInvisible} removes nothing — a
+ * fail-closed signal that the flagged run was PRESERVED (e.g. a well-formed
+ * emoji-tag sequence the stripper keeps), so the caller must not treat it as
+ * cleaned. `true` means and only means "bytes changed".
+ *
+ * Contract (scan/clean coherence): clean strips exactly what scan flags. A
+ * write happens ONLY when `scanText` reports a finding, so the "scan, then
+ * clean what scan flagged" workflow never silently rewrites a file scan called
+ * clean. A handful of sub-threshold invisible chars (which scan ignores) are
+ * left untouched — by design, the scanner's definition of a payload is the
+ * single source of truth for what gets removed.
+ *
+ * Refuses to follow symlinks: instruction files must be regular files. The read
+ * fd is opened with `O_NOFOLLOW`, so a symlinked path (which could redirect the
+ * read/write to a target outside the tree) makes the OPEN itself fail — closing
+ * the lstat→open TOCTOU window a separate stat would leave, in which the path
+ * could be swapped to a symlink between the check and the read.
+ *
+ * Non-UTF-8 safety (O9): the file is read as raw BYTES and required to round-trip
+ * losslessly through UTF-8 before any rewrite. `readFileSync(…, "utf-8")`
+ * silently maps invalid bytes to U+FFFD, which a naive strip-and-rewrite would
+ * then persist file-wide — so a non-UTF-8 file fails loud and is left untouched.
+ *
+ * Lost-update / TOCTOU guard: the on-path file is re-checked against the fstat
+ * snapshot taken right after open (inode, size, mtime, and not-a-symlink) before
+ * the rename; a concurrent write or symlink swap between our read and our write
+ * fails loud rather than silently clobbering the other writer.
+ *
+ * The write is atomic (see {@link atomicReplaceFile}): stripped content goes to
+ * a temp file in the same directory which is then `rename`d over the original
+ * (preserving the original file mode), fsync'd for crash-safety.
+ *
+ * Throws if the file cannot be read or written (the caller decides whether an
+ * unwritable contaminated file is fatal or falls back to alerting).
+ * @param {string} absPath
+ * @param {(path: string) => import("node:fs").Stats} [lstat] injectable
+ *   pre-rename recheck stat (fault-injection seam, mirrors
+ *   {@link atomicReplaceFile}'s `tmpName`): lets a test drive the concurrent
+ *   write/symlink-swap that the TOCTOU guard exists to catch, which is otherwise
+ *   unreachable from this fully-synchronous path. Defaults to `lstatSync`.
+ * @returns {boolean}
+ */
+export function cleanFile(absPath: string, lstat?: (path: string) => import("node:fs").Stats): boolean;

package/types/invisible.d.mts

@@ -0,0 +1,98 @@
+/**
+ * True when every ANSI control introducer in `text` belongs to a display-only
+ * SGR color sequence (so stripping the ANSI removed only cosmetic styling,
+ * nothing that could move the cursor, erase, or carry a payload). Recognizes
+ * both the 7-bit `ESC[…m` and 8-bit C1 (`U+009B…m`) SGR encodings.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isSgrOnly(text: string): boolean;
+/**
+ * The agent-facing "Stripped: …" note for a Layer-1 strip: the removed category
+ * labels, the LONG RUN marker when the de-ANSI'd text still holds a
+ * payload-length invisible run, and a pointer to recover the bytes — a hex dump
+ * is ASCII, so it passes through sanitization untouched. The single source of
+ * this note, shared by the `sanitize` convenience entry and the tool-output
+ * pipeline so the two can't drift.
+ * @param {string[]} invisFound CATEGORY codes applyLayer1 reported removing
+ * @param {string} deAnsi ANSI-stripped text (invisible runs intact), for the LONG_RUN probe
+ * @returns {string}
+ */
+export function describeStripped(invisFound: string[], deAnsi: string): string;
+/**
+ * Count the PAYLOAD invisible code points in `text`: those the carve-out would
+ * strip, excluding ZWNJ/ZWJ (and emoji VS16) that do real rendering work.
+ * Consumers that gate on invisible density (e.g. the prompt classifier's scatter
+ * threshold) use this so legitimate dense multilingual prose is not mistaken for
+ * a hidden channel.
+ * @param {string} text
+ * @returns {number}
+ */
+export function countPayloadInvisible(text: string): number;
+/**
+ * The `text` with every carve-out-PRESERVABLE invisible (joiners/selectors/tags/
+ * blank fillers doing real rendering work) replaced by a space, leaving only the
+ * PAYLOAD invisibles in place. The LONG_RUN injection probe runs over this so a
+ * legitimate emoji/flag/variation sequence never trips the "possible injection
+ * payload" marker (alert fatigue), while a genuine hidden run still surfaces.
+ * @param {string} text
+ * @returns {string}
+ */
+export function payloadInvisibleView(text: string): string;
+/**
+ * Strip payload-capable invisible chars and report which categories were
+ * removed. A single leading U+FEFF (BOM) is preserved as a legitimate marker;
+ * interior BOMs and all soft hyphens (U+00AD) are stripped, since either can
+ * encode hidden instructions. ZWNJ/ZWJ survive only in a linguistic context
+ * (see the carve-out above). `found` names exactly the categories stripped, so
+ * a caller never warns about a strip the carve-out skipped.
+ *
+ * `originalText` is the pre-processing text (before any ANSI strip) used ONLY to
+ * decide whether a leading BOM is genuinely leading: an interior BOM that an
+ * ANSI-strip left at index 0 of `text` (e.g. `ESC[m + interior U+FEFF`) must NOT be treated as a
+ * legitimate leading marker. Defaults to `text` for the common single-arg call.
+ * @param {string} text
+ * @param {string} [originalText]
+ * @returns {{ cleaned: string, found: string[] }}
+ */
+export function stripInvisibleWithReport(text: string, originalText?: string): {
+    cleaned: string;
+    found: string[];
+};
+/**
+ * Strip payload-capable invisible chars (cleaned text only). See
+ * stripInvisibleWithReport for the BOM and ZWNJ/ZWJ carve-out semantics.
+ * @param {string} text
+ * @returns {string}
+ */
+export function stripInvisible(text: string): string;
+export const VS: string;
+export const ZERO_WIDTH_MN: "\u034F\u17B4\u17B5";
+export const BLANK_NON_CF: string;
+export const CATEGORY: Readonly<{
+    CF: "cf-format";
+    VARIATION_SELECTORS: "variation-selectors";
+    BLANK_FILLERS: "blank-fillers";
+    ANSI: "ansi";
+    LONE_SURROGATES: "lone-surrogates";
+    HTML_COMMENTS: "html-comments";
+    HIDDEN_HTML: "hidden-html";
+    EXFIL_URLS: "exfil-urls";
+}>;
+/** @type {Readonly<Record<string, string>>} */
+export const CATEGORY_LABELS: Readonly<Record<string, string>>;
+/** @type {Array<[string, RegExp]>} Each entry pairs a CATEGORY code with its detector. */
+export const CHECKS: Array<[string, RegExp]>;
+export const STRIP: RegExp;
+export const SGR_RE: RegExp;
+export const LONG_RUN_THRESHOLD: 10;
+/** Total invisible-char count above which a file/prompt is treated as
+ * payload-capable even without a long run (threshold-evasion catch). */
+export const SCATTERED_THRESHOLD: 30;
+export const LONG_RUN_RE: RegExp;
+export const CONSECUTIVE_JOINER_CAP: 8;
+export const CONSECUTIVE_SELECTOR_CAP: 8;
+export const TOTAL_PRESERVED_JOINER_BUDGET: 16;
+export const PRESERVED_JOINER_PER_VISIBLE: 8;
+export const PRESERVE_HARD_CAP: 64;
+export const LINGUISTIC_SCRIPTS: string[];

package/types/joining-type.d.mts

@@ -0,0 +1,22 @@
+/**
+ * The Unicode Joining_Type of a code point: "C", "D", "R", "L", "T", or "U"
+ * (the non-joining default) for anything not in the cursive tables.
+ * @param {number} cp
+ * @returns {string}
+ */
+export function joiningType(cp: number): string;
+/**
+ * True when `cp` is an Indic virama (the only position where a ZWNJ/ZWJ is
+ * linguistically meaningful in Brahmic scripts).
+ * @param {number} cp
+ * @returns {boolean}
+ */
+export function isVirama(cp: number): boolean;
+/**
+ * GENERATED by scripts/gen-joining-type.mjs from ucd-full@17.0.0 — DO NOT EDIT.
+ *
+ * Unicode Joining_Type and Indic virama range tables backing the ZWNJ/ZWJ
+ * carve-out in invisible.mjs. Regenerate with `pnpm gen:joining-type`;
+ * test/joining-type.test.mjs fails if this drifts from the pinned UCD.
+ */
+export const UNICODE_VERSION: "17.0.0";

package/types/layer1.d.mts

@@ -0,0 +1,35 @@
+/**
+ * Strip ANSI escape sequences to a fixed point. Removing one sequence can
+ * reconstitute another around it (a lone ESC left of `ESC[32m[0m` gains the
+ * trailing `[0m` once the inner sequence is removed, forming a brand-new valid
+ * sequence the single pass would miss), so iterate until stable: every changed
+ * pass consumes at least one ESC introducer, so the pass count is bounded by
+ * the input's ESC count, and ANSI-free text exits after one pass.
+ * @param {string} input
+ * @returns {string}
+ */
+export function stripAnsiFully(input: string): string;
+/**
+ * Layer 1: ANSI + invisible-char strip with a result guaranteed free of every
+ * raw ANSI control introducer (7-bit ESC U+001B and the whole 8-bit C1 control
+ * block U+0080–U+009F: CSI, the DCS/SOS/OSC/PM/APC string introducers, and ST).
+ *
+ * Removing an invisible character can reconstitute an escape its split hid from
+ * the ANSI pass (`ESC`<ZWSP>`[32m` → `ESC[32m`), so strip ANSI again after the
+ * invisible pass — but only when stripInvisible changed something, since
+ * reconstitution is impossible otherwise and the re-strip is a wasted pass on
+ * the hot clean path. The ANSI strip still cannot match an *incomplete*
+ * reconstituted sequence (a lone `ESC[` left when an inner complete sequence is
+ * removed from a nested split), so a final sweep removes every residual raw
+ * introducer outright — that sweep, not the regex matching, is the guarantee
+ * that no control introducer survives. `deAnsi` is the ANSI strip of the
+ * original (invisible runs intact), the scope a LONG_RUN payload check needs.
+ * @param {string} text
+ * @returns {{ cleaned: string, deAnsi: string, found: string[] }}
+ */
+export function applyLayer1(text: string): {
+    cleaned: string;
+    deAnsi: string;
+    found: string[];
+};
+export const LONE_SURROGATE_RE: RegExp;

package/types/output.d.mts

@@ -0,0 +1,195 @@
+/**
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function needsMarkdownPipeline(text: string): boolean;
+/**
+ * Warning fragment for Layer 2's stripped content — counts only, never the
+ * content itself (which would re-inject what was just removed).
+ * @param {{ comments: number, hidden: number }} removed
+ * @returns {string}
+ */
+export function describeRemoved(removed: {
+    comments: number;
+    hidden: number;
+}): string;
+/**
+ * Full warning for Layer 2's preserved-but-reported content (scripting and
+ * resource tags, data: URIs), or "" when there is nothing to report.
+ * @param {{ tags: Record<string, number>, dataSrc: number }} warned
+ * @returns {string}
+ */
+export function describeWarned(warned: {
+    tags: Record<string, number>;
+    dataSrc: number;
+}): string;
+/**
+ * Delete each verbatim span in `spans` from `text`. The secure Layer-5
+ * primitive: a filter can only ask for deletions, so this can never inject
+ * bytes. Returns the new text and how many distinct span-occurrences were
+ * removed (0 when no span was present).
+ * @param {string} text
+ * @param {string[]} spans
+ * @returns {{ text: string, removed: number }}
+ */
+export function deleteVerbatimSpans(text: string, spans: string[]): {
+    text: string;
+    removed: number;
+};
+/**
+ * @typedef {{
+ *   html?: boolean,
+ *   exfilScan?: boolean,
+ *   redact?: (text: string) => Promise<RedactResult|null> | (RedactResult|null),
+ *   filterInjection?: (text: string) => Promise<Layer5Result|null> | (Layer5Result|null),
+ *   sgrCarveOut?: boolean,
+ * }} SanitizeTextOptions
+ */
+/**
+ * Run the configured layers over a single text blob. Layer 1 always runs; the
+ * rest are opt-in via `options`. Layer 4 (`redact`) is the fail-closed path: a
+ * redactor that throws is rethrown wrapped, so the caller suppresses the
+ * output rather than emitting an unvetted value. That fail-closed behavior
+ * also applies to Layer 4's re-scan after a Layer-5 span deletion (see Layer
+ * 5, below) — a redactor failure there fails the whole call closed too.
+ * `reveal` is the pre-Layer-2 text, present only when the HTML splice removed
+ * bytes, so a caller can persist what was hidden for later inspection (see
+ * {@link applyMarkdownPipeline}); the field is omitted otherwise.
+ * @param {string} text
+ * @param {SanitizeTextOptions} [options]
+ * @returns {Promise<{ cleaned: string, warnings: string[], modified: boolean, sgrNote: boolean, reveal?: string }>}
+ */
+export function sanitizeText(text: string, options?: SanitizeTextOptions): Promise<{
+    cleaned: string;
+    warnings: string[];
+    modified: boolean;
+    sgrNote: boolean;
+    reveal?: string;
+}>;
+/**
+ * True only for arrays and PLAIN objects — the two shapes whose contents are
+ * safe to walk via `Object.entries` without silently dropping data. An exotic
+ * object (Map/Set/Date/RegExp/typed array/class instance) carries its data in
+ * internal slots that `Object.entries` does not enumerate, so descending into
+ * one and rebuilding it from its entries corrupts it to `{}` (or an empty
+ * clone). Those pass through as OPAQUE LEAVES instead — unchanged — preserving
+ * the tool-output shape a harness matches on. A null-prototype object is treated
+ * as plain (its own enumerable string keys are the whole story).
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function isWalkableContainer(value: any): boolean;
+/**
+ * Sanitize every string leaf of a tool-output value, preserving its shape (a
+ * structured tool output whose shape changes would be ignored by a harness,
+ * leaking the raw value). Non-string leaves pass through; `warnings`
+ * accumulates across leaves. `sgrNote` is the OR across leaves.
+ *
+ * Fails CLOSED on two hostile shapes that would otherwise throw a `RangeError`
+ * as an unhandled async rejection (a DoS that leaves the output un-sanitized):
+ * nesting past {@link MAX_DEPTH}, and a reference cycle. Either replaces the
+ * offending subtree with a placeholder string + a warning, never passing the
+ * raw subtree through. Keys are also screened for hidden chars (see below).
+ *
+ * `reveals` accumulates each string leaf's pre-Layer-2 text (present only when
+ * the HTML splice removed bytes) so a caller can persist what was hidden — the
+ * structured-output analogue of {@link sanitizeText}'s `reveal`. Same
+ * mutated-accumulator contract as `warnings`.
+ * @param {any} value
+ * @param {SanitizeTextOptions} options
+ * @param {string[]} warnings
+ * @param {string[]} [reveals]
+ * @returns {Promise<{ value: any, modified: boolean, sgrNote: boolean }>}
+ */
+export function sanitizeValue(value: any, options: SanitizeTextOptions, warnings: string[], reveals?: string[]): Promise<{
+    value: any;
+    modified: boolean;
+    sgrNote: boolean;
+}>;
+/**
+ * Compose the model-facing context line for a sanitized/flagged tool output.
+ * `injectionAlert` is the caller's optional trailing alert (e.g. appended only
+ * for untrusted-ingress tools where a semantic-injection filter actually ran).
+ * @param {boolean} modified  output bytes were changed (vs. flagged only)
+ * @param {string[]} warnings
+ * @param {{ injectionAlert?: string }} [options]
+ * @returns {string}
+ */
+export function composeContext(modified: boolean, warnings: string[], { injectionAlert }?: {
+    injectionAlert?: string;
+}): string;
+/**
+ * Replace every string leaf of `value` with `message`, preserving shape so a
+ * fail-closed placeholder matches the tool's output schema. Non-string leaves
+ * pass through.
+ *
+ * Shares {@link sanitizeValue}'s depth/cycle guard for the same reason: this
+ * runs on the fail-closed path (an already-suspect output), so a 200k-deep or
+ * self-referential value must NOT blow the stack here — that would re-open the
+ * very hole suppression exists to close. Past {@link MAX_DEPTH} or on a cycle it
+ * substitutes `message` for the offending subtree (already the suppression
+ * sentinel, so the placeholder is consistent with the rest of the output).
+ * @param {any} value
+ * @param {string} message
+ * @returns {any}
+ */
+export function suppressToolOutput(value: any, message: string): any;
+/**
+ * Closed enum of LIBRARY-OWNED Layer-5 warning codes — the ONLY warning values
+ * the injected `filterInjection` seam may return. This mirrors the `found`-code
+ * contract (`CATEGORY` in ./invisible.mjs): the seam speaks a fixed vocabulary
+ * of codes, and the LIBRARY owns the human-readable string each maps to. Free
+ * text from the filter is REFUSED (see `mapFilterWarning`), because the filter
+ * runs on attacker-influenced content and its output is concatenated into the
+ * model-facing context WITHOUT passing back through Layer 1 — so a compromised
+ * or prompt-injected filter that could emit arbitrary `warning` text would
+ * defeat the "a compromised filter can only remove bytes, never inject" seam
+ * contract. Branch on these codes; the prose below is not part of the contract.
+ * @type {Readonly<{ SPANS_REMOVED: "spans-removed", FILTER_FLAGGED: "filter-flagged", FILTER_ERROR: "filter-error" }>}
+ */
+export const FILTER_WARNING: Readonly<{
+    SPANS_REMOVED: "spans-removed";
+    FILTER_FLAGGED: "filter-flagged";
+    FILTER_ERROR: "filter-error";
+}>;
+/**
+ * Maximum container nesting `sanitizeValue` / `suppressToolOutput` will descend
+ * before failing closed. The JS engine's own call-stack limit is many thousands
+ * of frames deep, so 200 is a wide safety margin below it: a real tool output
+ * never nests this far, while a hostile 200k-deep array (or a self-referential
+ * cycle) would otherwise blow the stack as an UNHANDLED async rejection — the
+ * output then escapes sanitization entirely (fail-open DoS). Past this depth the
+ * subtree is replaced with a placeholder and a warning is recorded, so the
+ * caller still emits a sanitized, flagged result instead of crashing.
+ */
+export const MAX_DEPTH: 200;
+/**
+ * Layer-4 result: the redacted text, the category labels redacted, and an
+ * optional caller-supplied annotation appended to the warning.
+ */
+export type RedactResult = {
+    text: string;
+    found: string[];
+    note?: string;
+};
+/**
+ * A {@link FILTER_WARNING} enum code — the closed vocabulary the Layer-5 seam
+ * may return in `warning`. See FILTER_WARNING for the meanings.
+ */
+export type FilterWarningCode = "spans-removed" | "filter-flagged" | "filter-error";
+/**
+ * Layer-5 result: verbatim spans to delete (the only mutation a filter may
+ * request) and/or a warning CODE (never free text — the library owns the
+ * message). Null means the filter made no finding.
+ */
+export type Layer5Result = {
+    removeSpans?: string[];
+    warning?: FilterWarningCode;
+};
+export type SanitizeTextOptions = {
+    html?: boolean;
+    exfilScan?: boolean;
+    redact?: (text: string) => Promise<RedactResult | null> | (RedactResult | null);
+    filterInjection?: (text: string) => Promise<Layer5Result | null> | (Layer5Result | null);
+    sgrCarveOut?: boolean;
+};

package/types/prompt.d.mts

@@ -0,0 +1,28 @@
+/**
+ * Human-facing block reason: what was detected, the thresholds, a code-point
+ * sample of the long run (if any), and how to recover.
+ * @param {string[]} categories
+ * @param {number} invisibleCount
+ * @param {string | null} longRunSample
+ * @returns {string}
+ */
+export function formatReason(categories: string[], invisibleCount: number, longRunSample: string | null): string;
+/**
+ * Pure verdict for a user prompt: pass through, pass with an SGR note, or
+ * block. `strip` (the ANSI stripper, defaulting to the package's
+ * {@link stripAnsiFully}) runs on every prompt so invisibles smuggled *inside*
+ * an ANSI sequence (an OSC string) are stripped before the invisible-char
+ * thresholds are counted; it is injectable so a host can substitute its own
+ * stripper or exercise the fail-closed path.
+ * @param {string} prompt
+ * @param {(s: string) => string} [strip]
+ * @returns {{action:"pass"} | {action:"note"} | {action:"block", reason:string}}
+ */
+export function classifyPrompt(prompt: string, strip?: (s: string) => string): {
+    action: "pass";
+} | {
+    action: "note";
+} | {
+    action: "block";
+    reason: string;
+};

package/types/rehydrate.d.mts

@@ -0,0 +1,54 @@
+/**
+ * Re-anchor an Edit/Write input composed from a sanitized file view back onto
+ * the on-disk bytes (secrets rehydrated, stripped invisible runs re-attached).
+ * Returns the rewritten input plus a model-facing context line, a deny with an
+ * instructive reason when the input is unresolvable or would expose a secret,
+ * or null when there is nothing to do. Throws only on internal error (the
+ * caller fails closed).
+ *
+ * `io` is the injected I/O (file read + redactor map/plain). `hint` is the
+ * redaction-placeholder prefix (defaults to {@link DEFAULT_HINT}); override it
+ * only if the injected redactor emits a different placeholder shape.
+ * @param {string} tool
+ * @param {any} toolInput
+ * @param {RehydrateIo} io
+ * @param {{ hint?: string }} [options]
+ * @returns {Promise<{updatedInput: any, context: string} | {deny: string} | null>}
+ */
+export function rehydrateRedacted(tool: string, toolInput: any, io: RehydrateIo, { hint }?: {
+    hint?: string;
+}): Promise<{
+    updatedInput: any;
+    context: string;
+} | {
+    deny: string;
+} | null>;
+export const DEFAULT_HINT: "[REDACTED";
+/**
+ * Map-mode response from the redactor: either the mappable view (text + ordered
+ * (placeholder, original, start) pairs) or an unmappable verdict carrying its
+ * reason — a discriminated pair.
+ */
+export type RedactMapView = {
+    text: string;
+    pairs: {
+        placeholder: string;
+        original: string;
+        start: number;
+    }[];
+} | {
+    unmappable: string;
+};
+/**
+ * Injected I/O. `readFile` returns the file's bytes (throwing on a missing or
+ * unreadable path). `redactMap` returns the redacted view of (Layer-1-cleaned)
+ * file text plus the ordered (placeholder, original, start) pairs, or an
+ * `{unmappable}` verdict. `redact` returns the plain redacted text, or null
+ * when nothing was redacted. `redactMap`/`redact` are the only secret-engine
+ * seam; they may be async and are awaited.
+ */
+export type RehydrateIo = {
+    readFile: (path: string) => string;
+    redactMap: (text: string) => Promise<RedactMapView> | RedactMapView;
+    redact: (text: string) => Promise<string | null> | (string | null);
+};

package/types/standardized-variants.d.mts

@@ -0,0 +1,22 @@
+/**
+ * True when `base` followed by `selector` (a U+FE00–U+FE0D code point) is a
+ * registered standardized variation sequence.
+ * @param {number} base
+ * @param {number} selector
+ * @returns {boolean}
+ */
+export function isStandardizedVariant(base: number, selector: number): boolean;
+/**
+ * GENERATED by scripts/gen-standardized-variants.mjs from UCD
+ * StandardizedVariants.txt (Unicode 17.0.0) — DO NOT EDIT.
+ *
+ * Registered standardized variation sequences: a base code point followed by a
+ * variation selector in U+FE00–U+FE0D. invisible.mjs preserves such a selector
+ * only when the immediately preceding base appears here; every other FE00–FE0D
+ * selector is stripped as a hidden-payload byte. Regenerate with
+ * `node scripts/gen-standardized-variants.mjs`; test/invisible-charset.test.mjs
+ * fails if this drifts from the pinned UCD slice.
+ */
+export const UNICODE_VERSION: "17.0.0";
+/** @type {Array<[number, number]>} [base, selector], sorted by base then selector. */
+export const STANDARDIZED_VARIANTS: Array<[number, number]>;