@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/providers/shared/pcm.d.ts

@@ -0,0 +1,14 @@
+export interface PcmFormat {
+    sampleRate: number;
+    channels: number;
+}
+export declare function writeAscii(view: DataView, offset: number, str: string): void;
+export declare function pcmFormatFromMime(mime: string): PcmFormat | undefined;
+export declare function wrapPcmAsWav(pcm: Uint8Array, format: PcmFormat): Uint8Array;
+export declare function pcmMediaAsWav(media: {
+    mimeType: string;
+    data: string;
+}): {
+    mimeType: string;
+    data: string;
+};

package/esm/src/providers/shared/pcm.js

@@ -0,0 +1,78 @@
+/*
+ * Each transport states the PCM format on the wire (probes 23/09/2026):
+ * - Gemini Live: `audio/pcm;rate=24000`
+ * - Interactions: `audio/l16; rate=24000; channels=1` (buffered), or
+ *   `audio/l16` with `sample_rate` / `channels` fields (stream deltas)
+ * - OpenRouter speech: `content-type: audio/pcm;rate=24000;channels=1`
+ *
+ * Samples are 16-bit little-endian on all three (measured), although RFC 2586
+ * defines `audio/L16` as big-endian. A mime without `rate=` has no known
+ * format, so its bytes pass through unchanged rather than being wrapped at a
+ * guessed rate. `channels=` absent means one channel (the RFC 2586 default;
+ * Live documents mono output).
+ */
+import { base64ToBytes, bytesToBase64 } from '../../kernel/util/base64.js';
+const BITS_PER_SAMPLE = 16;
+const RAW_PCM_ESSENCES = new Set(['audio/pcm', 'audio/l16']);
+export function writeAscii(view, offset, str) {
+    for (let i = 0; i < str.length; i++)
+        view.setUint8(offset + i, str.charCodeAt(i));
+}
+function positiveInt(value) {
+    if (value === undefined || !/^\d+$/.test(value))
+        return undefined;
+    const n = Number(value);
+    return n > 0 ? n : undefined;
+}
+function parseMime(mime) {
+    const [essence = '', ...rest] = mime.split(';');
+    const params = new Map();
+    for (const param of rest) {
+        const eq = param.indexOf('=');
+        if (eq > 0)
+            params.set(param.slice(0, eq).trim().toLowerCase(), param.slice(eq + 1).trim());
+    }
+    return { essence: essence.trim().toLowerCase(), params };
+}
+export function pcmFormatFromMime(mime) {
+    const { essence, params } = parseMime(mime);
+    if (!RAW_PCM_ESSENCES.has(essence))
+        return undefined;
+    const sampleRate = positiveInt(params.get('rate'));
+    if (sampleRate === undefined)
+        return undefined;
+    const channels = params.has('channels') ? positiveInt(params.get('channels')) : 1;
+    if (channels === undefined)
+        return undefined;
+    return { sampleRate, channels };
+}
+export function wrapPcmAsWav(pcm, format) {
+    const { sampleRate, channels } = format;
+    const blockAlign = (channels * BITS_PER_SAMPLE) / 8;
+    const byteRate = sampleRate * blockAlign;
+    const dataSize = pcm.length;
+    const buf = new ArrayBuffer(44 + dataSize);
+    const view = new DataView(buf);
+    writeAscii(view, 0, 'RIFF');
+    view.setUint32(4, 36 + dataSize, true);
+    writeAscii(view, 8, 'WAVE');
+    writeAscii(view, 12, 'fmt ');
+    view.setUint32(16, 16, true);
+    view.setUint16(20, 1, true); // PCM
+    view.setUint16(22, channels, true);
+    view.setUint32(24, sampleRate, true);
+    view.setUint32(28, byteRate, true);
+    view.setUint16(32, blockAlign, true);
+    view.setUint16(34, BITS_PER_SAMPLE, true);
+    writeAscii(view, 36, 'data');
+    view.setUint32(40, dataSize, true);
+    new Uint8Array(buf, 44).set(pcm);
+    return new Uint8Array(buf);
+}
+export function pcmMediaAsWav(media) {
+    const format = pcmFormatFromMime(media.mimeType);
+    if (!format)
+        return media;
+    const wav = wrapPcmAsWav(base64ToBytes(media.data), format);
+    return { mimeType: 'audio/wav', data: bytesToBase64(wav) };
+}

package/esm/src/providers/shared/response-identity.d.ts

@@ -0,0 +1,11 @@
+import type { ProviderEvent, TurnResponse } from '../../kernel/types.js';
+/**
+ * Emits as soon as the wire names the response and again whenever that changes, so a
+ * call that fails or is cut by a guardrail still records which model served it.
+ */
+export declare function foldResponse(known: TurnResponse | undefined, seen: TurnResponse | undefined): {
+    known: TurnResponse | undefined;
+    event?: Extract<ProviderEvent, {
+        type: 'response';
+    }>;
+};

package/esm/src/providers/shared/response-identity.js

@@ -0,0 +1,12 @@
+/**
+ * Emits as soon as the wire names the response and again whenever that changes, so a
+ * call that fails or is cut by a guardrail still records which model served it.
+ */
+export function foldResponse(known, seen) {
+    if (!seen)
+        return { known };
+    const next = { ...known, ...seen };
+    if (next.id === known?.id && next.model === known?.model)
+        return { known };
+    return { known: next, event: { type: 'response', response: next } };
+}

package/esm/src/providers/shared/sse.d.ts

@@ -0,0 +1,10 @@
+export declare function asObject(parsed: unknown): Record<string, unknown> | undefined;
+export declare function dataRecord(raw: string, sseEvent: string): Record<string, unknown>;
+export declare function takeSsePayloads(buffer: string, pendingEvent?: string): {
+    rest: string;
+    payloads: Record<string, unknown>[];
+    pendingEvent: string;
+};
+export declare function readSseChunks(body: ReadableStream<Uint8Array>): AsyncGenerator<Record<string, unknown>>;
+/** Silently skips malformed payloads, unlike `readSseChunks`. */
+export declare function parseSseStream(body: ReadableStream<Uint8Array>): AsyncGenerator<Record<string, unknown>>;

package/esm/src/providers/shared/sse.js

@@ -0,0 +1,79 @@
+const DATA_PREFIX = 'data: ';
+const EVENT_PREFIX = 'event: ';
+const DONE = '[DONE]';
+export function asObject(parsed) {
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        return parsed;
+    }
+    return undefined;
+}
+export function dataRecord(raw, sseEvent) {
+    const data = raw.slice(DATA_PREFIX.length).trim();
+    const row = {};
+    if (sseEvent) {
+        row.sseEvent = sseEvent;
+    }
+    if (!data || data === DONE) {
+        row.eventType = 'sse_done';
+        return row;
+    }
+    try {
+        const parsed = JSON.parse(data);
+        const obj = asObject(parsed);
+        if (obj) {
+            return { ...obj, ...row };
+        }
+        row.eventType = 'sse_unparsed';
+        row.data = parsed;
+        return row;
+    }
+    catch {
+        row.eventType = 'sse_unparsed';
+        row.data = data;
+        return row;
+    }
+}
+export function takeSsePayloads(buffer, pendingEvent = '') {
+    const payloads = [];
+    const chunks = buffer.split('\n');
+    const rest = chunks.pop() ?? '';
+    let sseEvent = pendingEvent;
+    for (const line of chunks) {
+        if (line.startsWith(EVENT_PREFIX)) {
+            sseEvent = line.slice(EVENT_PREFIX.length).trim();
+        }
+        else if (line.startsWith(DATA_PREFIX)) {
+            payloads.push(dataRecord(line, sseEvent));
+            sseEvent = '';
+        }
+    }
+    return { rest, payloads, pendingEvent: sseEvent };
+}
+export async function* readSseChunks(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let pendingEvent = '';
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const result = takeSsePayloads(buffer, pendingEvent);
+        buffer = result.rest;
+        pendingEvent = result.pendingEvent;
+        for (const payload of result.payloads) {
+            yield payload;
+        }
+    }
+}
+/** Silently skips malformed payloads, unlike `readSseChunks`. */
+export async function* parseSseStream(body) {
+    for await (const payload of readSseChunks(body)) {
+        if (payload.eventType === 'sse_done')
+            return;
+        if (payload.eventType === 'sse_unparsed')
+            continue;
+        yield payload;
+    }
+}

package/esm/src/providers/shared/structured-output.d.ts

@@ -0,0 +1,4 @@
+import type { TurnEvent } from '../../kernel/types.js';
+/** Invalid JSON is a `bad_response` error, never a silent skip. */
+declare function structuredEvent(text: string): TurnEvent;
+export { structuredEvent };

package/esm/src/providers/shared/structured-output.js

@@ -0,0 +1,11 @@
+import { TheoremError, toErrorEvent } from '../../guardrails/error.js';
+/** Invalid JSON is a `bad_response` error, never a silent skip. */
+function structuredEvent(text) {
+    try {
+        return { type: 'structured', structured: JSON.parse(text) };
+    }
+    catch (cause) {
+        return toErrorEvent(new TheoremError('bad_response', 'structured output was not valid JSON', { cause }));
+    }
+}
+export { structuredEvent };

package/esm/src/providers/shared/tool-args.d.ts

@@ -0,0 +1,25 @@
+import { type ToolCallBase } from '../../kernel/tools/events.js';
+import type { ProviderEvent } from '../../kernel/types.js';
+/**
+ * Adapters never invent a history call id or name: a provider that needs a
+ * missing one rejects the request, and that error is the answer.
+ */
+export declare function historyToolIdentity(fields: Record<string, string | undefined>): Record<string, string>;
+export type ParsedToolArguments = {
+    ok: true;
+    value: Record<string, unknown>;
+} | {
+    ok: false;
+    error: string;
+    raw: string;
+};
+export declare function parseToolArgumentsObject(raw: unknown): ParsedToolArguments;
+export declare function historyToolArguments(raw: unknown): Record<string, unknown>;
+/** A call sent without an id gets one, so its request and failure events join. */
+export declare function toolCallEvents(call: {
+    id?: string;
+    name: string;
+    thoughtSignature?: string;
+}, rawArguments: unknown): ProviderEvent[];
+/** Keeps the thought signature: the model still reads the failed call's result back. */
+export declare function malformedToolCall(base: ToolCallBase, message: string, raw: unknown, thoughtSignature?: string): ProviderEvent[];

package/esm/src/providers/shared/tool-args.js

@@ -0,0 +1,84 @@
+import { TheoremError } from '../../guardrails/error.js';
+import { failureEvent, newCallId, toolCallRequestEvent, } from '../../kernel/tools/events.js';
+import { isRecord } from '../../kernel/util/record.js';
+/**
+ * Adapters never invent a history call id or name: a provider that needs a
+ * missing one rejects the request, and that error is the answer.
+ */
+export function historyToolIdentity(fields) {
+    const present = {};
+    for (const [key, value] of Object.entries(fields)) {
+        if (value !== undefined)
+            present[key] = value;
+    }
+    return present;
+}
+export function parseToolArgumentsObject(raw) {
+    if (typeof raw === 'string') {
+        const trimmed = raw.trim();
+        if (trimmed.length === 0) {
+            return { ok: true, value: {} };
+        }
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (isRecord(parsed)) {
+                return { ok: true, value: parsed };
+            }
+            return {
+                ok: false,
+                error: 'tool arguments JSON must be an object',
+                raw,
+            };
+        }
+        catch {
+            return {
+                ok: false,
+                error: 'malformed tool arguments JSON',
+                raw,
+            };
+        }
+    }
+    if (isRecord(raw)) {
+        return { ok: true, value: raw };
+    }
+    if (raw === undefined || raw === null) {
+        return { ok: true, value: {} };
+    }
+    return {
+        ok: false,
+        error: 'tool arguments must be a JSON object',
+        raw: String(raw),
+    };
+}
+export function historyToolArguments(raw) {
+    const parsed = parseToolArgumentsObject(raw);
+    if (!parsed.ok) {
+        throw new TheoremError('bad_response', parsed.error);
+    }
+    return parsed.value;
+}
+/** A call sent without an id gets one, so its request and failure events join. */
+export function toolCallEvents(call, rawArguments) {
+    const name = call.name.trim();
+    const base = { name, callId: call.id ?? newCallId(name) };
+    if (!name) {
+        return malformedToolCall(base, 'function call is missing a name', rawArguments, call.thoughtSignature);
+    }
+    const parsed = parseToolArgumentsObject(rawArguments);
+    if (!parsed.ok) {
+        return malformedToolCall(base, parsed.error, parsed.raw, call.thoughtSignature);
+    }
+    return [toolCallRequestEvent(base, parsed.value, { thoughtSignature: call.thoughtSignature })];
+}
+/** Keeps the thought signature: the model still reads the failed call's result back. */
+export function malformedToolCall(base, message, raw, thoughtSignature) {
+    return [
+        toolCallRequestEvent(base, {}, { thoughtSignature }),
+        failureEvent(base, {
+            code: 'malformed_arguments',
+            kind: 'bad_response',
+            message,
+            details: { raw },
+        }),
+    ];
+}

package/esm/src/providers/shared/upstream-tap.d.ts

@@ -0,0 +1,8 @@
+import type { KeySlot, ProviderCompleteRequest } from '../../kernel/types.js';
+export declare function tapeHeaderValue(key: string, value: string): string;
+export declare function tapeHeaders(headers?: HeadersInit): Record<string, string>;
+export declare function throwRow(err: unknown): Record<string, unknown>;
+export declare function tapFetch(tap: ProviderCompleteRequest['tapUpstream'], send?: typeof fetch, keySlot?: KeySlot): typeof fetch;
+/** fetch rejects only when no response came back, so any non-abort, non-timeout rejection is `network`. */
+export declare function networkError(err: unknown): unknown;
+export declare function networkFetch(send?: typeof fetch): typeof fetch;

package/esm/src/providers/shared/upstream-tap.js

@@ -0,0 +1,85 @@
+import { describeError, isAbortError, isTimeoutError, TheoremError, } from '../../guardrails/error.js';
+const SECRET_HEADER = /key|auth|cookie|secret|token/i;
+export function tapeHeaderValue(key, value) {
+    if (SECRET_HEADER.test(key)) {
+        return '[redacted]';
+    }
+    return value;
+}
+export function tapeHeaders(headers) {
+    const out = {};
+    for (const [key, value] of new Headers(headers).entries()) {
+        out[key] = tapeHeaderValue(key, value);
+    }
+    return out;
+}
+export function throwRow(err) {
+    if (err instanceof Error) {
+        return { eventType: 'http_throw', name: err.name, message: err.message };
+    }
+    return { eventType: 'http_throw', name: 'Error', message: String(err) };
+}
+/** A non-string body is named rather than read, since reading it would consume the stream. */
+function tapeBody(body) {
+    if (body === undefined || body === null) {
+        return {};
+    }
+    if (typeof body !== 'string') {
+        return { bodyKind: body.constructor.name };
+    }
+    try {
+        return { body: JSON.parse(body) };
+    }
+    catch {
+        return { body };
+    }
+}
+export function tapFetch(tap, send = fetch, keySlot) {
+    if (!tap) {
+        return send;
+    }
+    return async (url, init) => {
+        const method = init?.method ?? 'GET';
+        tap({
+            eventType: 'http_request',
+            method,
+            url: String(url),
+            headers: tapeHeaders(init?.headers),
+            ...(keySlot ? { keySlot } : {}),
+            ...tapeBody(init?.body),
+        });
+        try {
+            const res = await send(url, init);
+            tap({
+                eventType: 'http_response',
+                status: res.status,
+                headers: tapeHeaders(res.headers),
+            });
+            if (!res.ok) {
+                tap({ eventType: 'http_error_body', body: await res.clone().text() });
+            }
+            return res;
+        }
+        catch (err) {
+            tap(throwRow(err));
+            throw err;
+        }
+    };
+}
+/** fetch rejects only when no response came back, so any non-abort, non-timeout rejection is `network`. */
+export function networkError(err) {
+    if (err instanceof TheoremError || isAbortError(err) || isTimeoutError(err)) {
+        return err;
+    }
+    return new TheoremError('network', describeError(err), { cause: err });
+}
+export function networkFetch(send = fetch) {
+    return async (url, init) => {
+        try {
+            return await send(url, init);
+        }
+        catch (err) {
+            throw networkError(err);
+        }
+    };
+}

package/esm/src/providers/shared/upstream-tape.d.ts

@@ -0,0 +1,6 @@
+export declare function inlineBytesKey(rec: Record<string, unknown>): string | undefined;
+export declare function scrubRecord(rec: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function scrubUpstream(value: unknown): Promise<unknown>;
+export declare function removeCanaries(text: string, canaries: readonly string[]): string;
+export declare function redactCanaryInTree(value: unknown, canaries: readonly string[]): unknown;
+export declare function tapeUpstream(value: unknown, canaries: readonly string[]): Promise<unknown>;

package/esm/src/providers/shared/upstream-tape.js

@@ -0,0 +1,88 @@
+import { redactCanaryText } from '../../guardrails/canary.js';
+import { sha256, sha256Base64 } from '../../kernel/engine/hash.js';
+import { mapStrings } from '../../kernel/engine/tree.js';
+/*
+ * Inline bytes on a taped row are stored as their sha256, never as bytes.
+ * The shapes are the ones every taped transport sends (probes 23/09/2026):
+ *
+ * - `{ mime_type, data }`: Interactions request parts, stream deltas and
+ *   buffered steps (image, audio, document); the OpenRouter speech body row.
+ * - `{ mimeType, data }`: Theorem's own media parts (a tool's raw output) and
+ *   Gemini Live `inlineData`.
+ * - `{ b64_json, media_type }`: OpenRouter `/images` `data[]` entries.
+ * - a `data:<mime>;base64,<bytes>` string: OpenRouter chat
+ *   `message.images[].image_url.url`.
+ *
+ * The hash covers the raw bytes, the same hash a trace blob part carries. A
+ * record whose bytes were hashed carries `dataKind: 'sha256'`; a hashed data
+ * url becomes `data:<mime>;sha256,<hex>`. Inline data that is not base64 is
+ * hashed as text and says so: `dataKind: 'text_sha256'`, `data:<mime>;text_sha256,<hex>`.
+ */
+const DATA_URL = /^data:([^;,]+);base64,/;
+export function inlineBytesKey(rec) {
+    const mime = rec.mime_type ?? rec.mimeType;
+    if (typeof mime === 'string' && typeof rec.data === 'string') {
+        return 'data';
+    }
+    if (typeof rec.media_type === 'string' && typeof rec.b64_json === 'string') {
+        return 'b64_json';
+    }
+    return undefined;
+}
+const BYTES_SHA256 = 'sha256';
+const TEXT_SHA256 = 'text_sha256';
+async function inlineHash(base64) {
+    const digest = await sha256Base64(base64);
+    return digest
+        ? { kind: BYTES_SHA256, hash: digest.hash }
+        : { kind: TEXT_SHA256, hash: await sha256(base64) };
+}
+async function scrubString(text) {
+    const match = DATA_URL.exec(text);
+    if (!match) {
+        return text;
+    }
+    const { kind, hash } = await inlineHash(text.slice(match[0].length));
+    return `data:${match[1]};${kind},${hash}`;
+}
+export async function scrubRecord(rec) {
+    const bytesKey = inlineBytesKey(rec);
+    let dataKind;
+    const pairs = await Promise.all(Object.entries(rec).map(async ([key, nested]) => {
+        if (key === bytesKey && typeof nested === 'string') {
+            const { kind, hash } = await inlineHash(nested);
+            dataKind = kind;
+            return [key, hash];
+        }
+        return [key, await scrubUpstream(nested)];
+    }));
+    const out = Object.fromEntries(pairs);
+    if (dataKind) {
+        out.dataKind = dataKind;
+    }
+    return out;
+}
+export function scrubUpstream(value) {
+    if (typeof value === 'string') {
+        return scrubString(value);
+    }
+    if (Array.isArray(value)) {
+        return Promise.all(value.map((item) => scrubUpstream(item)));
+    }
+    if (value && typeof value === 'object') {
+        return scrubRecord(value);
+    }
+    return Promise.resolve(value);
+}
+export function removeCanaries(text, canaries) {
+    return canaries.reduce((out, canary) => redactCanaryText(out, canary), text);
+}
+export function redactCanaryInTree(value, canaries) {
+    if (!canaries.some(Boolean)) {
+        return value;
+    }
+    return mapStrings(value, (text) => removeCanaries(text, canaries));
+}
+export async function tapeUpstream(value, canaries) {
+    return redactCanaryInTree(await scrubUpstream(value), canaries);
+}

package/esm/src/providers/shared/vault.d.ts

@@ -0,0 +1,13 @@
+import type { KeySlot, KeyVault, ProviderCompleteRequest } from '../../kernel/types.js';
+/** The key in `slot`. One vault serves every provider; a slot holds whatever secret the host put there. */
+export declare function requireKey(vault: KeyVault | undefined, slot: KeySlot): string;
+/** The profile's fallback slot and its key, when the vault holds a different key there. */
+export declare function fallbackKey(slot: KeySlot | undefined, vault: KeyVault | undefined, primary: string): {
+    slot: KeySlot;
+    key: string;
+} | undefined;
+/**
+ * A tapped fetch for a provider that takes a bearer token. A quota refusal retries once with the
+ * fallback slot's key, when the profile names one; each try's slot is on the tape.
+ */
+export declare function bearerFetch(req: Pick<ProviderCompleteRequest, 'tapUpstream' | 'keySlot' | 'fallbackKeySlot'>, send: typeof fetch, vault: KeyVault | undefined, primary: string): typeof fetch;

package/esm/src/providers/shared/vault.js

@@ -0,0 +1,41 @@
+import { TheoremError } from '../../guardrails/error.js';
+import { tapFetch } from './upstream-tap.js';
+const HTTP_QUOTA = 429;
+/** The key in `slot`. One vault serves every provider; a slot holds whatever secret the host put there. */
+export function requireKey(vault, slot) {
+    const key = vault?.[slot]?.trim();
+    if (!key) {
+        throw new TheoremError('auth', `the vault has no key in slot '${slot}'`);
+    }
+    return key;
+}
+/** The profile's fallback slot and its key, when the vault holds a different key there. */
+export function fallbackKey(slot, vault, primary) {
+    const key = slot ? vault?.[slot]?.trim() : undefined;
+    if (!slot || !key || key === primary) {
+        return undefined;
+    }
+    return { slot, key };
+}
+/**
+ * A tapped fetch for a provider that takes a bearer token. A quota refusal retries once with the
+ * fallback slot's key, when the profile names one; each try's slot is on the tape.
+ */
+export function bearerFetch(req, send, vault, primary) {
+    const first = tapFetch(req.tapUpstream, send, req.keySlot);
+    const fallback = req.keySlot ? fallbackKey(req.fallbackKeySlot, vault, primary) : undefined;
+    if (!fallback) {
+        return first;
+    }
+    const second = tapFetch(req.tapUpstream, send, fallback.slot);
+    return async (url, init) => {
+        const res = await first(url, init);
+        if (res.status !== HTTP_QUOTA) {
+            return res;
+        }
+        await res.body?.cancel();
+        const headers = new Headers(init?.headers);
+        headers.set('Authorization', `Bearer ${fallback.key}`);
+        return await second(url, { ...init, headers });
+    };
+}

package/esm/src/providers/types.d.ts

@@ -0,0 +1,19 @@
+import type { KeyVault } from '../kernel/types.js';
+export interface OpenAiGatewayConfig {
+    baseUrl?: string;
+    siteUrl?: string;
+    siteName?: string;
+    fetch?: typeof fetch;
+}
+export interface LocalProviderConfig {
+    /** e.g. `http://127.0.0.1:11434` for Ollama. */
+    baseUrl: string;
+    fetch?: typeof globalThis.fetch;
+}
+/** What `createProvider` hands an adapter: the host's settings for it plus the one vault. */
+export type OpenAiGatewayTransport = OpenAiGatewayConfig & {
+    vault?: KeyVault;
+};
+export type LocalTransport = LocalProviderConfig & {
+    vault?: KeyVault;
+};

package/esm/src/providers/types.js

@@ -0,0 +1 @@
+export {};

package/esm/src/surface/formats.d.ts

@@ -0,0 +1,28 @@
+/** What an agent sees of a secret. */
+export interface SecretCard {
+    secret: true;
+    set: boolean;
+    looksLike?: string;
+    /** Mistakes the value shows: whitespace, quotes, a line break, a placeholder. */
+    problems: string[];
+    /** Other secrets holding the same value. */
+    sameAs: string[];
+    usedBy: string[];
+}
+export declare function secretCard(value: unknown, extra?: {
+    sameAs?: readonly string[];
+    usedBy?: readonly string[];
+}): SecretCard;
+/** A URL with its credential query parameters and `user:pass@` masked. */
+export declare function maskUrl(raw: string): string;
+/**
+ * Headers as JSON, credential-named values masked. Text that is not a JSON object is
+ * told only by its length: a parse error would quote it.
+ */
+export declare function maskHeaders(raw: unknown): unknown;
+/** Scrubs text: each known secret value by name, then the kernel's sensitive patterns. */
+export declare function scrubText(text: string, known: readonly [string, string][]): string;
+/** Known secret values worth scrubbing: trimmed, long enough, longest first. */
+export declare function knownSecrets(secrets: Record<string, string>): [string, string][];
+/** Every string in `value` scrubbed and capped; long base64 under `data` told as bytes. */
+export declare function scrubDeep(value: unknown, known: readonly [string, string][]): unknown;