@retinue/agentkit 0.1.0 → 0.2.0

package/dist/guardrails/index.js

@@ -0,0 +1,108 @@
+/**
+ * Guardrails — REQ-046 (#205), task #211.
+ *
+ * A seam for checks a deployment needs and this runtime does not ship: PII redaction, moderation, a topic
+ * restriction, an output schema. Without it, a deployment that needs any of those has to edit the engine.
+ *
+ * The injection half of "guardrails" is already built and lives elsewhere (`security/prompt-safety.ts`), and it
+ * is deliberately *not* a guardrail in this sense: containment is structural — untrusted content is wrapped in a
+ * nonce-delimited envelope whether or not anything recognises an attack — whereas everything here is
+ * *inspection*, which can only act on what it detects. Conflating the two would invite someone to switch off
+ * containment because a detector is present.
+ *
+ * ## Three decisions that make this worth having
+ *
+ * **Tool calls are outputs.** A guardrail that inspects only the final message can be walked straight past by
+ * putting the data in a tool argument. Checking prose and not arguments is checking the boring half, so
+ * `GuardrailOutput` is a discriminated union of a message *and* a tool call, and the tool-call case is enforced
+ * at the one choke point every call goes through.
+ *
+ * **Fail closed.** A guardrail that throws refuses the turn, attributed to the guardrail that threw. The
+ * opposite default is how a guardrail silently stops guarding the day its dependency times out — and the run
+ * looks entirely normal afterwards, which is the property that makes it dangerous.
+ *
+ * **Every verdict is recorded, and never the value.** A redaction that leaves no trace is indistinguishable from
+ * the model never having been told, which makes an incident unreconstructable. So a record names *what* was
+ * redacted — the field, the entity type — and never what it contained, or the audit trail becomes the leak.
+ */
+/** What a guardrail may conclude. */
+export const GUARDRAIL_OUTCOMES = ["pass", "redacted", "refused"];
+const REFUSED_BY_THROW = "guardrail_failed";
+const subjectOf = (value) => {
+    if (typeof value === "object" && value !== null && "kind" in value) {
+        const kind = value.kind;
+        return kind === "tool-call" || kind === "tool-result" ? kind : "message";
+    }
+    return "input";
+};
+/**
+ * Run a list in declared order, threading the value through.
+ *
+ * Threading is what makes two redacting guardrails compose: the second inspects what the first produced, so one
+ * cannot undo the other by inspecting the original and returning its own edit of it. Order is the caller's
+ * declaration and is never sorted here — a guardrail set whose order depends on object key iteration is a set
+ * whose behaviour changes when someone reformats the config.
+ *
+ * A refusal short-circuits: the remaining guardrails are not consulted, because the turn is over and running
+ * them would spend money to annotate a decision already taken.
+ *
+ * Two exported entry points over one core rather than a `hook: "inspectInput" | "inspectOutput"` parameter. The
+ * parameterised version does not typecheck — indexing a union of two method signatures gives a function callable
+ * with neither argument type — and the `never` cast that silences it would have erased exactly the distinction
+ * the two subjects exist to keep.
+ */
+const applyEach = async (guardrails, select, value, context) => {
+    const records = [];
+    let current = value;
+    for (const guardrail of guardrails) {
+        const inspect = select(guardrail);
+        if (inspect === undefined)
+            continue;
+        let verdict;
+        try {
+            verdict = await inspect(current, context);
+        }
+        catch (error) {
+            // Fail closed, and say which one. A guardrail whose dependency timed out must not become a guardrail that
+            // passed everything: the whole point is that its absence is visible.
+            records.push({
+                guardrail: guardrail.name,
+                subject: subjectOf(current),
+                outcome: "refused",
+                code: REFUSED_BY_THROW,
+                threw: true,
+            });
+            return {
+                outcome: "refused",
+                by: guardrail.name,
+                code: REFUSED_BY_THROW,
+                message: `guardrail ${guardrail.name} could not complete: ${error instanceof Error ? error.message : String(error)}`,
+                records,
+            };
+        }
+        if (verdict.kind === "pass") {
+            records.push({ guardrail: guardrail.name, subject: subjectOf(current), outcome: "pass" });
+            continue;
+        }
+        if (verdict.kind === "redacted") {
+            records.push({ guardrail: guardrail.name, subject: subjectOf(current), outcome: "redacted", what: verdict.what });
+            current = verdict.value;
+            continue;
+        }
+        records.push({ guardrail: guardrail.name, subject: subjectOf(current), outcome: "refused", code: verdict.code });
+        return { outcome: "refused", by: guardrail.name, code: verdict.code, message: verdict.message, records };
+    }
+    return { outcome: "allowed", value: current, records };
+};
+/** Before the model sees the turn. */
+export const applyInputGuardrails = (guardrails, input, context) => applyEach(guardrails, (g) => (g.inspectInput ? (v, c) => g.inspectInput(v, c) : undefined), input, context);
+/** Before anything leaves the model — a message *or* a tool call. */
+export const applyOutputGuardrails = (guardrails, output, context) => applyEach(guardrails, (g) => (g.inspectOutput ? (v, c) => g.inspectOutput(v, c) : undefined), output, context);
+/**
+ * Whether a record could carry an inspected value — used by the test that asserts it never does.
+ *
+ * Here rather than in the test file because it states the invariant next to the type it constrains: a record has
+ * a fixed shape, and adding a field that holds content is the change this is meant to make somebody notice.
+ */
+export const recordCarriesOnlyMetadata = (record) => Object.keys(record).every((key) => ["guardrail", "subject", "outcome", "what", "code", "threw"].includes(key));
+//# sourceMappingURL=index.js.map

package/dist/guardrails/moderation.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Moderation, as an adapter — REQ-046 (#205), task #212, AC-4.
+ *
+ * **Off unless declared, and it takes the classifier rather than choosing one.** That is the whole design
+ * decision, and it is a cost decision rather than a technical one: a model call on every turn doubles the
+ * latency floor and adds a per-turn charge, and whether that is worth it depends on what a deployment is for.
+ * A runtime that imposed it would be spending somebody else's money on a policy they did not choose.
+ *
+ * So `classify` is supplied by the host. OpenAI's moderation endpoint is one implementation; a local classifier,
+ * a keyword list, or a shared service are others. None of them is a dependency of this package.
+ *
+ * ## The cost, stated
+ *
+ * One classifier call per inspected subject. With `subjects: ["input", "message"]` — the default — that is two
+ * calls per turn, in series with the model rather than parallel to it, because a turn that has already been
+ * answered cannot be un-answered. Add roughly the classifier's own latency twice to every turn.
+ *
+ * Reducing that is a real option and is why `subjects` is configurable: inspecting only `input` halves the cost
+ * and leaves generated content unchecked, which is the right trade for an internal tool and the wrong one for
+ * anything public.
+ *
+ * ## Failure is handled by the port, not here
+ *
+ * A classifier that times out throws, and `applyInputGuardrails` turns a throw into a refusal attributed to this
+ * guardrail. That is deliberate and it is the expensive-looking choice: a moderation outage stops turns. The
+ * alternative is a moderation outage that silently stops moderating, which is the one nobody notices.
+ */
+import type { Guardrail } from "./index.js";
+export type ModerationResult = {
+    readonly flagged: boolean;
+    /** Category names from the classifier. Used in the refusal message and the record; never the content. */
+    readonly categories?: readonly string[];
+};
+/** What the host supplies. Throwing is a refusal — see the module comment. */
+export type ModerationClassifier = (text: string) => Promise<ModerationResult> | ModerationResult;
+/** Which subjects to spend a classifier call on. */
+export declare const MODERATION_SUBJECTS: readonly ["input", "message", "tool-result"];
+export type ModerationSubject = (typeof MODERATION_SUBJECTS)[number];
+export type ModerationOptions = {
+    readonly classify: ModerationClassifier;
+    /**
+     * Defaults to `["input", "message"]` — two calls per turn.
+     *
+     * `tool-result` is off by default because a tool result is usually structured data rather than prose, and
+     * classifying JSON produces confident nonsense. Turn it on when tools return free text somebody will read.
+     */
+    readonly subjects?: readonly ModerationSubject[];
+    /** Minimum text length worth a call. Defaults to 1: a classifier call on an empty string is pure cost. */
+    readonly minLength?: number;
+    readonly name?: string;
+};
+export declare const createModerationGuardrail: (options: ModerationOptions) => Guardrail;
+//# sourceMappingURL=moderation.d.ts.map

package/dist/guardrails/moderation.js

@@ -0,0 +1,75 @@
+/**
+ * Moderation, as an adapter — REQ-046 (#205), task #212, AC-4.
+ *
+ * **Off unless declared, and it takes the classifier rather than choosing one.** That is the whole design
+ * decision, and it is a cost decision rather than a technical one: a model call on every turn doubles the
+ * latency floor and adds a per-turn charge, and whether that is worth it depends on what a deployment is for.
+ * A runtime that imposed it would be spending somebody else's money on a policy they did not choose.
+ *
+ * So `classify` is supplied by the host. OpenAI's moderation endpoint is one implementation; a local classifier,
+ * a keyword list, or a shared service are others. None of them is a dependency of this package.
+ *
+ * ## The cost, stated
+ *
+ * One classifier call per inspected subject. With `subjects: ["input", "message"]` — the default — that is two
+ * calls per turn, in series with the model rather than parallel to it, because a turn that has already been
+ * answered cannot be un-answered. Add roughly the classifier's own latency twice to every turn.
+ *
+ * Reducing that is a real option and is why `subjects` is configurable: inspecting only `input` halves the cost
+ * and leaves generated content unchecked, which is the right trade for an internal tool and the wrong one for
+ * anything public.
+ *
+ * ## Failure is handled by the port, not here
+ *
+ * A classifier that times out throws, and `applyInputGuardrails` turns a throw into a refusal attributed to this
+ * guardrail. That is deliberate and it is the expensive-looking choice: a moderation outage stops turns. The
+ * alternative is a moderation outage that silently stops moderating, which is the one nobody notices.
+ */
+/** Which subjects to spend a classifier call on. */
+export const MODERATION_SUBJECTS = ["input", "message", "tool-result"];
+const textOf = (output) => {
+    if (output.kind === "message")
+        return output.text;
+    if (output.kind === "tool-result")
+        return typeof output.output === "string" ? output.output : null;
+    // A tool call's arguments are not prose. Classifying a JSON object is a call spent on a question the
+    // classifier was not trained for — the PII guardrail is the one that reads arguments.
+    return null;
+};
+export const createModerationGuardrail = (options) => {
+    const subjects = options.subjects ?? ["input", "message"];
+    const minLength = options.minLength ?? 1;
+    const judge = async (text) => {
+        if (text.trim().length < minLength)
+            return { kind: "pass" };
+        const result = await options.classify(text);
+        if (!result.flagged)
+            return { kind: "pass" };
+        const categories = result.categories ?? [];
+        return {
+            kind: "refused",
+            code: "moderation",
+            // Categories, never the content. The message is shown to a person and stored in an event.
+            message: categories.length > 0
+                ? `That content was flagged as ${categories.join(", ")}.`
+                : "That content was flagged by moderation.",
+        };
+    };
+    return {
+        name: options.name ?? "moderation",
+        ...(subjects.includes("input")
+            ? { inspectInput: (input) => judge(input.text) }
+            : {}),
+        ...(subjects.some((s) => s === "message" || s === "tool-result")
+            ? {
+                inspectOutput: async (output) => {
+                    if (!subjects.includes(output.kind))
+                        return { kind: "pass" };
+                    const text = textOf(output);
+                    return text === null ? { kind: "pass" } : judge(text);
+                },
+            }
+            : {}),
+    };
+};
+//# sourceMappingURL=moderation.js.map

package/dist/guardrails/pii.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Personal data, detected and redacted — REQ-046 (#205), task #212.
+ *
+ * Deterministic and **offline**. No network call, no model call: a guardrail that costs a round trip per turn is
+ * one a deployment switches off under load, and the moment it is off is the moment it was needed. Everything
+ * here is a pattern plus, where one exists, a checksum.
+ *
+ * ## Why a checksum matters more than a pattern
+ *
+ * A sixteen-digit order number matches every "card number" regex ever written. Flagging it teaches people that
+ * this guardrail cries wolf, and a guardrail people have learned to ignore is worse than none — they route
+ * around it. So card numbers are Luhn-checked and IBANs mod-97-checked, and a candidate that fails its checksum
+ * is *not* personal data, it is a number.
+ *
+ * ## Referential consistency, without state
+ *
+ * A placeholder is derived from a hash of the value, so the same value always yields the same placeholder —
+ * `[email:7a3f19]`. That is not a cosmetic choice. A model asked to compare two records, handed two *different*
+ * placeholders for one email, concludes the records differ and reasons wrongly about data it was never allowed
+ * to see. Deriving from the value keeps equality and nothing else.
+ *
+ * The alternative — a counter per turn — would need state keyed by run and would break the moment a run
+ * resumed in a different process, which is the normal case for a durable runtime.
+ *
+ * A hash placeholder does permit equality testing, and that is the intended trade: equality is exactly the
+ * property being preserved. It leaks no plaintext and is not reversible.
+ */
+import type { Guardrail } from "./index.js";
+/** What to look for. Named so a record can say `email` without saying which email. */
+export declare const PII_ENTITIES: readonly ["email", "phone", "card_number", "iban", "ssn", "ip_address"];
+export type PiiEntity = (typeof PII_ENTITIES)[number];
+/**
+ * What to do when something is found.
+ *
+ * `redact` by default, and the reasoning is worth stating because the other choice is defensible: refusing is
+ * safer and ruder. A support agent pasting a customer's email into a chat has done something ordinary, and a
+ * runtime that refuses the turn teaches them to paste it somewhere with no guardrail at all. Redaction keeps the
+ * conversation working while the value never reaches the model.
+ *
+ * `refuse` is right where the data must not have been sent at all — a card number, under most policies — so the
+ * default is per-entity rather than global.
+ */
+export type PiiAction = "redact" | "refuse";
+export type PiiOptions = {
+    /** Which entities to look for. Defaults to all of them. */
+    readonly entities?: readonly PiiEntity[];
+    /** Per-entity action. Anything unlisted uses `defaultAction`. */
+    readonly actions?: Partial<Record<PiiEntity, PiiAction>>;
+    /** Defaults to `redact` — see `PiiAction`. */
+    readonly defaultAction?: PiiAction;
+};
+/** Six hex characters of a salted-by-entity hash: enough to distinguish values, short enough to read. */
+export declare const placeholderFor: (entity: PiiEntity, value: string) => string;
+export type PiiFinding = {
+    readonly entity: PiiEntity;
+    readonly value: string;
+};
+/**
+ * Every entity in a string, longest match first so a redaction cannot corrupt an overlapping one.
+ *
+ * Exported because it is the whole detector and it deserves to be tested directly rather than through a
+ * guardrail's verdict.
+ */
+export declare const findPii: (text: string, entities: readonly PiiEntity[]) => readonly PiiFinding[];
+/** Replace every finding with its derived placeholder. Same value ⇒ same placeholder, always. */
+export declare const redactText: (text: string, findings: readonly PiiFinding[]) => string;
+/**
+ * A guardrail that finds personal data in the turn, in tool arguments and in tool results.
+ *
+ * All three, because each is a real path: the person types it, the model puts it in an argument, or a tool reads
+ * a document that contains it. A guardrail covering one of the three is a guardrail whose coverage nobody can
+ * state.
+ */
+export declare const createPiiGuardrail: (options?: PiiOptions) => Guardrail;
+//# sourceMappingURL=pii.d.ts.map

package/dist/guardrails/pii.js

@@ -0,0 +1,193 @@
+/**
+ * Personal data, detected and redacted — REQ-046 (#205), task #212.
+ *
+ * Deterministic and **offline**. No network call, no model call: a guardrail that costs a round trip per turn is
+ * one a deployment switches off under load, and the moment it is off is the moment it was needed. Everything
+ * here is a pattern plus, where one exists, a checksum.
+ *
+ * ## Why a checksum matters more than a pattern
+ *
+ * A sixteen-digit order number matches every "card number" regex ever written. Flagging it teaches people that
+ * this guardrail cries wolf, and a guardrail people have learned to ignore is worse than none — they route
+ * around it. So card numbers are Luhn-checked and IBANs mod-97-checked, and a candidate that fails its checksum
+ * is *not* personal data, it is a number.
+ *
+ * ## Referential consistency, without state
+ *
+ * A placeholder is derived from a hash of the value, so the same value always yields the same placeholder —
+ * `[email:7a3f19]`. That is not a cosmetic choice. A model asked to compare two records, handed two *different*
+ * placeholders for one email, concludes the records differ and reasons wrongly about data it was never allowed
+ * to see. Deriving from the value keeps equality and nothing else.
+ *
+ * The alternative — a counter per turn — would need state keyed by run and would break the moment a run
+ * resumed in a different process, which is the normal case for a durable runtime.
+ *
+ * A hash placeholder does permit equality testing, and that is the intended trade: equality is exactly the
+ * property being preserved. It leaks no plaintext and is not reversible.
+ */
+import { createHash } from "node:crypto";
+/** What to look for. Named so a record can say `email` without saying which email. */
+export const PII_ENTITIES = ["email", "phone", "card_number", "iban", "ssn", "ip_address"];
+const LUHN_OK = (digits) => {
+    let sum = 0;
+    let double = false;
+    for (let i = digits.length - 1; i >= 0; i -= 1) {
+        let d = Number(digits[i]);
+        if (Number.isNaN(d))
+            return false;
+        if (double)
+            d = d * 2 > 9 ? d * 2 - 9 : d * 2;
+        sum += d;
+        double = !double;
+    }
+    return digits.length >= 13 && sum % 10 === 0;
+};
+/** ISO 7064 mod-97: move the first four characters to the end, letters to digits, remainder must be 1. */
+const IBAN_OK = (value) => {
+    const normalized = value.replace(/[\s-]/g, "").toUpperCase();
+    if (!/^[A-Z]{2}\d{2}[A-Z0-9]{10,30}$/.test(normalized))
+        return false;
+    const rearranged = normalized.slice(4) + normalized.slice(0, 4);
+    const expanded = [...rearranged].map((c) => (/[A-Z]/.test(c) ? String(c.charCodeAt(0) - 55) : c)).join("");
+    let remainder = 0;
+    for (const digit of expanded)
+        remainder = (remainder * 10 + Number(digit)) % 97;
+    return remainder === 1;
+};
+/**
+ * A phone number, as distinct from any other run of digits.
+ *
+ * The corpus caught this: the first pattern matched an order number, an epoch timestamp and an invoice
+ * reference, giving 78.6% precision. A guardrail that fires on invoice numbers is one somebody switches off, and
+ * for this kind of check **precision matters more than recall** — a false positive is visible on every turn,
+ * a false negative is invisible until it matters, and only one of the two gets the guardrail disabled.
+ *
+ * Two conditions, both needed:
+ *
+ * - **9 to 15 digits.** Below nine and it is a date, an error code or a quantity; above fifteen and it is longer
+ *   than E.164 permits, which usually means a card the Luhn check already rejected.
+ * - **A leading `+`, or at least two separators.** Humans group phone numbers — `020 7946 0958` — and machines
+ *   do not group serial numbers. Two separators rather than one, because one is `INV-2026-0043`.
+ *
+ * A date like `2026-08-27` has two separators and is excluded by the digit count; a bare `1756300000` has the
+ * digits and is excluded by the grouping.
+ */
+const PHONE_OK = (candidate) => {
+    const digits = (candidate.match(/\d/g) ?? []).length;
+    if (digits < 9 || digits > 15)
+        return false;
+    const separators = (candidate.match(/[\s\-()]/g) ?? []).length;
+    return candidate.trimStart().startsWith("+") || separators >= 2;
+};
+/**
+ * Detectors, each a pattern and an optional validator.
+ *
+ * Order matters: `card_number` runs before `phone`, because a long digit run matches both and a card number is
+ * the more consequential reading. Getting that backwards would redact a card as a phone number and apply the
+ * phone policy to it.
+ */
+const DETECTORS = [
+    { entity: "email", pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/g },
+    { entity: "iban", pattern: /\b[A-Z]{2}\d{2}[A-Z0-9 ]{10,34}\b/g, valid: IBAN_OK },
+    { entity: "card_number", pattern: /\b(?:\d[ -]?){13,19}\b/g, valid: (m) => LUHN_OK(m.replace(/[ -]/g, "")) },
+    { entity: "ssn", pattern: /\b\d{3}-\d{2}-\d{4}\b/g },
+    { entity: "ip_address", pattern: /\b(?:(?:25[0-5]|2[0-4]\d|1?\d?\d)\.){3}(?:25[0-5]|2[0-4]\d|1?\d?\d)\b/g },
+    // Last: the loosest pattern, so a card or an IBAN has already claimed its digits. And validated, because
+    // "a run of digits" is not a phone number — see PHONE_OK.
+    { entity: "phone", pattern: /\+?\d[\d\s\-()]{7,20}\d/g, valid: PHONE_OK },
+];
+/** Six hex characters of a salted-by-entity hash: enough to distinguish values, short enough to read. */
+export const placeholderFor = (entity, value) => `[${entity}:${createHash("sha256").update(`${entity}:${value}`).digest("hex").slice(0, 6)}]`;
+/**
+ * Every entity in a string, longest match first so a redaction cannot corrupt an overlapping one.
+ *
+ * Exported because it is the whole detector and it deserves to be tested directly rather than through a
+ * guardrail's verdict.
+ */
+export const findPii = (text, entities) => {
+    const found = [];
+    const claimed = [];
+    for (const detector of DETECTORS) {
+        if (!entities.includes(detector.entity))
+            continue;
+        for (const match of text.matchAll(detector.pattern)) {
+            const start = match.index ?? 0;
+            const end = start + match[0].length;
+            // A span already claimed by an earlier (more specific) detector is not re-read as something looser.
+            if (claimed.some((c) => start < c.end && end > c.start))
+                continue;
+            const value = match[0].trim();
+            if (detector.valid && !detector.valid(value))
+                continue;
+            claimed.push({ start, end });
+            found.push({ entity: detector.entity, value });
+        }
+    }
+    return found;
+};
+/** Replace every finding with its derived placeholder. Same value ⇒ same placeholder, always. */
+export const redactText = (text, findings) => {
+    let out = text;
+    // Longest first: replacing a short value that is a substring of a longer one would leave a fragment behind.
+    for (const finding of [...findings].sort((a, b) => b.value.length - a.value.length)) {
+        out = out.split(finding.value).join(placeholderFor(finding.entity, finding.value));
+    }
+    return out;
+};
+/** Walk any JSON-ish value, redacting strings. Tool arguments and results are objects, not prose. */
+const redactDeep = (value, entities, found) => {
+    if (typeof value === "string") {
+        const hits = findPii(value, entities);
+        found.push(...hits);
+        return hits.length === 0 ? value : redactText(value, hits);
+    }
+    if (Array.isArray(value))
+        return value.map((v) => redactDeep(v, entities, found));
+    if (value !== null && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, redactDeep(v, entities, found)]));
+    }
+    return value;
+};
+/**
+ * A guardrail that finds personal data in the turn, in tool arguments and in tool results.
+ *
+ * All three, because each is a real path: the person types it, the model puts it in an argument, or a tool reads
+ * a document that contains it. A guardrail covering one of the three is a guardrail whose coverage nobody can
+ * state.
+ */
+export const createPiiGuardrail = (options = {}) => {
+    const entities = options.entities ?? [...PII_ENTITIES];
+    const defaultAction = options.defaultAction ?? "redact";
+    const actionFor = (entity) => options.actions?.[entity] ?? defaultAction;
+    const decide = (findings, redacted) => {
+        if (findings.length === 0)
+            return { kind: "pass" };
+        const refusing = [...new Set(findings.filter((f) => actionFor(f.entity) === "refuse").map((f) => f.entity))];
+        if (refusing.length > 0) {
+            return {
+                kind: "refused",
+                code: "pii_present",
+                // Names the entity type, never the value — the message is shown to a person and stored in an event.
+                message: `That content contains ${refusing.join(", ")}. Please remove it and try again.`,
+            };
+        }
+        return { kind: "redacted", value: redacted(), what: [...new Set(findings.map((f) => f.entity))] };
+    };
+    return {
+        name: "pii",
+        inspectInput(input) {
+            const findings = findPii(input.text, entities);
+            return decide(findings, () => ({ ...input, text: redactText(input.text, findings) }));
+        },
+        inspectOutput(output, _context) {
+            if (output.kind === "message") {
+                const findings = findPii(output.text, entities);
+                return decide(findings, () => ({ ...output, text: redactText(output.text, findings) }));
+            }
+            const found = [];
+            const payload = redactDeep(output.kind === "tool-call" ? output.input : output.output, entities, found);
+            return decide(found, () => output.kind === "tool-call" ? { ...output, input: payload } : { ...output, output: payload });
+        },
+    };
+};
+//# sourceMappingURL=pii.js.map

package/dist/knowledge/index.d.ts

@@ -116,4 +116,5 @@ export declare const createEmbeddingPipeline: (deps: EmbeddingPipelineDeps) => {
 export type EmbeddingPipeline = ReturnType<typeof createEmbeddingPipeline>;
 export * from "./chunking.js";
 export * from "./retrieval.js";
+export * from "./navigate.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/knowledge/index.js

@@ -163,4 +163,5 @@ export const createEmbeddingPipeline = (deps) => {
 };
 export * from "./chunking.js";
 export * from "./retrieval.js";
+export * from "./navigate.js";
 //# sourceMappingURL=index.js.map

package/dist/knowledge/navigate.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Retrieval without vectors — REQ-050 (#209), task #219, AC-4.
+ *
+ * A **spike**, and the deliverable is a decision with numbers rather than a subsystem. See
+ * `docs/26-retrieval-quality.md` for what it scored.
+ *
+ * ## The idea being tested
+ *
+ * Embedding-based retrieval matches a query against fragments of text and hopes the fragments it surfaces are the
+ * ones that answer it. A person looking something up in a manual does something else entirely: they read the
+ * table of contents, decide which chapter is relevant, and then read it. That needs no index, no embedding cost
+ * and no re-indexing when a document changes — and its citations name a *document* somebody chose rather than a
+ * fragment a cosine distance surfaced.
+ *
+ * The cost is a model call per query, and latency measured in seconds rather than milliseconds.
+ *
+ * ## Two things this prototype found immediately
+ *
+ * **`KnowledgeStore` cannot enumerate its sources.** There is `listBySource`, `get`, `deleteSource` and
+ * `staleSources`, and no way to ask "what documents are in here". That is correct for a vector-based design —
+ * nothing needed it — and it is exactly what a navigating retriever needs first. So the outline arrives through
+ * a port the *host* supplies (`OutlineCatalogue`), which is honest but means this mode is not a drop-in for a
+ * deployment that already has hybrid retrieval working.
+ *
+ * **It does fit behind `RetrievalMode`**, which the issue asked to test. `createRetriever` gains one optional
+ * dependency and a fourth mode; every caller — `search_knowledge` included — is unchanged, and a deployment that
+ * has not wired a navigator gets a named refusal rather than a silent fall back to semantic search. If it had
+ * *not* fit, that would have been the finding; it fits.
+ */
+import type { ExecutionContext } from "../core/context.js";
+import type { KnowledgeChunk, KnowledgeStore } from "../persistence/index.js";
+import type { RetrievalOutcome } from "./retrieval.js";
+/** What a chooser sees of one document: enough to decide, and not the document itself. */
+export type SourceOutline = {
+    readonly sourceType: KnowledgeChunk["sourceType"];
+    readonly sourceId: string;
+    readonly title: string;
+    /** The heading trail, in document order. This is the table of contents a person would read. */
+    readonly headings: readonly string[];
+};
+/**
+ * Where the outline comes from.
+ *
+ * A port because the store cannot answer it (see the note above). A host that keeps documents in its own tables —
+ * which most do, since `KnowledgeStore` holds *chunks* — already has this list.
+ */
+export interface OutlineCatalogue {
+    list(context: {
+        readonly tenantId: ExecutionContext["tenantId"];
+        readonly authSubjects: readonly string[];
+    }): Promise<readonly SourceOutline[]>;
+}
+/**
+ * Whatever decides which documents to read. A model, in practice.
+ *
+ * A port rather than a model call, for the reason every model call in this package is a port: the platform must
+ * not acquire a provider, and a test must be able to pin the choice.
+ */
+export interface DocumentChooser {
+    readonly id: string;
+    choose(input: {
+        readonly query: string;
+        readonly catalogue: readonly SourceOutline[];
+        readonly limit: number;
+    }): Promise<readonly string[]>;
+}
+export type NavigatorDeps = {
+    readonly store: KnowledgeStore;
+    readonly catalogue: OutlineCatalogue;
+    readonly chooser: DocumentChooser;
+    /** Documents the chooser may pick. More than a handful and the model is guessing rather than choosing. */
+    readonly maxSources?: number;
+    /** Chunks read per chosen document. A whole 200-page document would not fit the caller's context. */
+    readonly maxChunksPerSource?: number;
+};
+export declare const DEFAULT_MAX_SOURCES = 3;
+export declare const DEFAULT_MAX_CHUNKS_PER_SOURCE = 40;
+export interface Navigator {
+    readonly id: string;
+    navigate(context: {
+        readonly tenantId: ExecutionContext["tenantId"];
+    }, input: {
+        readonly query: string;
+        readonly authSubjects: readonly string[];
+        readonly limit: number;
+    }): Promise<RetrievalOutcome>;
+}
+export declare const createNavigator: (deps: NavigatorDeps) => Navigator;
+//# sourceMappingURL=navigate.d.ts.map