@theoremjs/agents 0.0.0-stage → 0.3.1

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';
+/*invariant:
+ * 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/system-one/protocol.d.ts

@@ -0,0 +1,8 @@
+import { type Protocol } from '../../kernel/protocols/mod.js';
+/** What a System One binding may set. Both are TypeSafe's opt-in "danger zone" headers. */
+export interface SystemOneOptions {
+    images?: boolean;
+    longContext?: boolean;
+}
+/** TypeSafe's decision API: questions about a state, answered in one call. */
+export declare const systemOne: Protocol<SystemOneOptions>;

package/esm/src/providers/system-one/protocol.js

@@ -0,0 +1,93 @@
+import { z } from 'zod';
+import { TheoremError } from '../../guardrails/error.js';
+import { labelText } from '../../guardrails/labels.js';
+import { jsonObjectSchema } from '../../kernel/json.js';
+import { defineProtocol } from '../../kernel/protocols/mod.js';
+const count = z.number().int().nonnegative();
+const reply = z.object({
+    model: z.string().min(1),
+    answers: z.record(z.string(), z.unknown()),
+    usage: z
+        .object({
+        input_tokens: count,
+        output_tokens: count,
+        cost: z.number().nonnegative().optional(),
+    })
+        .optional()
+        .catch(undefined),
+});
+const options = z.strictObject({
+    images: z.boolean().optional().describe(
+    // labels-exempt: builder field description, read by the studio and docs
+    'Let a decision hold images and box questions. TypeSafe calls this experimental, and a request that uses either is refused without it.'),
+    longContext: z.boolean().optional().describe(
+    // labels-exempt: builder field description, read by the studio and docs
+    'Raise the context window from 64k tokens to 262k. TypeSafe calls this slower and less accurate.'),
+});
+const IMAGES_HEADER = 'TypeSafe-Danger-Zone-Images';
+const LONG_CONTEXT_HEADER = 'TypeSafe-Danger-Zone-Long-Context';
+/** TypeSafe's decision API: questions about a state, answered in one call. */
+export const systemOne = defineProtocol({
+    id: 'systemOne',
+    name: 'System One',
+    description: "TypeSafe's decision API: questions about a state, answered in one call.", // labels-exempt: builder field description, read by the studio and docs
+    endpoints: { decision: '/systemone' },
+    options,
+    create(context) {
+        return {
+            async decide(request) {
+                const asksBox = Object.values(request.questions).some(({ type }) => type === 'box');
+                const holdsImages = asksBox || (request.assets && Object.keys(request.assets).length > 0);
+                if (holdsImages && !context.options.images)
+                    throw new TheoremError('unsupported', labelText('provider.decision_images_off'));
+                // why: Only a pinned 1.13 is known to refuse a box; aliases such as `jev-latest` move, so they pass.
+                if (asksBox && /^jev-1\.13(\.|$)/.test(context.apiId))
+                    throw new TheoremError('unsupported', labelText('provider.decision_box_model', { apiId: context.apiId }));
+                const headers = {};
+                if (holdsImages)
+                    headers[IMAGES_HEADER] = 'true';
+                if (context.options.longContext)
+                    headers[LONG_CONTEXT_HEADER] = 'true';
+                const body = jsonObjectSchema.parse({
+                    model: context.apiId,
+                    state: request.state,
+                    questions: request.questions,
+                    ...(request.assets && Object.keys(request.assets).length
+                        ? { assets: assetsOnWire(request.assets) }
+                        : {}),
+                });
+                for await (const row of context.send(body, { stream: false, headers })) {
+                    const parsed = reply.safeParse(row);
+                    if (!parsed.success)
+                        throw new TheoremError('bad_response', labelText('protocol.reply_shape', {
+                            protocol: 'systemOne',
+                            issues: z.prettifyError(parsed.error),
+                        }));
+                    const { model, answers, usage } = parsed.data;
+                    // invariant: The kernel validates every answer against its question before exposing it.
+                    return {
+                        model,
+                        answers: answers,
+                        ...(usage
+                            ? {
+                                usage: {
+                                    inputTokens: usage.input_tokens,
+                                    outputTokens: usage.output_tokens,
+                                    ...(usage.cost === undefined ? {} : { costUsd: usage.cost }),
+                                },
+                            }
+                            : {}),
+                    };
+                }
+                throw new TheoremError('bad_response', labelText('provider.decision_failed'));
+            },
+        };
+    },
+});
+const FORMATS = { 'image/png': 'png', 'image/jpeg': 'jpeg' };
+function assetsOnWire(assets) {
+    return Object.fromEntries(Object.entries(assets).map(([reference, { mimeType, data }]) => [
+        reference,
+        { type: 'image', format: FORMATS[mimeType], data_base64: data },
+    ]));
+}

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

@@ -0,0 +1,51 @@
+import type { TheoremError } from '../guardrails/error.js';
+import type { InteractionPart, ModelEvent } from '../kernel/types.js';
+/** Where a live model is in its reply when a frame arrives. */
+export type LiveTurnPhase = 'streaming' | 'complete' | 'abort';
+/** Tape row: the first key was refused for quota, so the call starts again on the fallback slot. */
+export declare const KEY_FALLBACK_ROW = "key_fallback";
+/** The provider's warning before it closed a live socket. */
+export interface LiveGoAway {
+    timeLeftMs?: number;
+    /** Milliseconds from the last warning to the close. */
+    closedAfterMs: number;
+}
+/** One thing a live socket received. `row` is the parsed frame, so the kernel records it beside the events it produced. */
+export type LiveQueueItem = {
+    type: 'batch';
+    events: ModelEvent[];
+    turnPhase: LiveTurnPhase;
+    row: Record<string, unknown>;
+} | {
+    type: 'row';
+    row: Record<string, unknown>;
+} | {
+    type: 'error';
+    error: Error;
+    row?: Record<string, unknown>;
+}
+/** `error` is set when the close was not normal; `goAway` when the provider warned first. */
+ | {
+    type: 'closed';
+    code: number;
+    reason: string;
+    error?: TheoremError;
+    goAway?: LiveGoAway;
+};
+/**
+ * An open live socket, in the kernel's terms: the setup the session was opened with, what the
+ * session sends the model, `batches` for what it receives, and `close`. A send on a socket that is
+ * no longer open is dropped.
+ */
+export interface LiveConnection {
+    readonly setup: Record<string, unknown>;
+    flush?(): Promise<void>;
+    /** Text the model reads without it ending the user's turn. */
+    sendContext(text: string): void;
+    /** Text, audio, or video from the user, as it arrives. */
+    sendInput(input: InteractionPart): void;
+    /** The result of a tool call the model made. */
+    sendToolResponse(callId: string, name: string, output: unknown, parts?: InteractionPart[]): void;
+    batches(): AsyncGenerator<LiveQueueItem>;
+    close(code?: number, reason?: string): void;
+}

package/esm/src/providers/types.js

@@ -0,0 +1,2 @@
+/** Tape row: the first key was refused for quota, so the call starts again on the fallback slot. */
+export const KEY_FALLBACK_ROW = 'key_fallback';

package/esm/src/providers/typesafe/provider.d.ts

@@ -0,0 +1,7 @@
+import { type Provider } from '../../kernel/protocols/provider.js';
+/** What registering `typesafeProvider` takes as `connection`. */
+export interface TypesafeConnection {
+    baseUrl?: string;
+}
+/** TypeSafe: System One decisions, at TypeSafe's own API. */
+export declare const typesafeProvider: Provider<TypesafeConnection, string>;

package/esm/src/providers/typesafe/provider.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { bearer, defineProvider, endpointUrlSchema, } from '../../kernel/protocols/provider.js';
+import { systemOne } from '../system-one/protocol.js';
+/** TypeSafe: System One decisions, at TypeSafe's own API. */
+export const typesafeProvider = defineProvider({
+    id: 'typesafe',
+    name: 'TypeSafe',
+    description: "System One decisions, at TypeSafe's own API.", // labels-exempt: builder field description, read by the studio and docs
+    connection: z
+        .strictObject({
+        baseUrl: endpointUrlSchema
+            .optional()
+            .describe('The API, by default https://api.typesafe.ai/v1.'), // labels-exempt: builder field description, read by the studio and docs
+    })
+        .default({}),
+    key: z.string().trim().min(1),
+    authorize: bearer(),
+    // why: docs.typesafe.ai/models, read 2026-10-19, prices Jev 1.13 and 1.14 alike at $0.042 per million input tokens, output free. The API reports no cost.
+    prices: {
+        checked: '2026-10-19',
+        models: { 'jev-*': { input: 0.042, output: 0 } },
+    },
+    serves: (at) => [{ protocol: systemOne, baseUrl: at.baseUrl ?? 'https://api.typesafe.ai/v1' }],
+});

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

@@ -0,0 +1,46 @@
+/** What stands in for a credential's value wherever one is shown. */
+export declare const MASK = "\u2022\u2022\u2022\u2022";
+/** 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[];
+}
+/** What an agent sees of a secret instead of its value: whether it is set, what kind it looks like, the mistakes it shows, and the other secrets with the same value and the places that use it. */
+export declare function secretCard(value: unknown, extra?: {
+    sameAs?: readonly string[];
+    usedBy?: readonly string[];
+}): SecretCard;
+/** Whether a header or query parameter's name says it carries a credential: what `maskHeaders` masks. */
+export declare function isCredentialName(name: string): boolean;
+/**
+ * A URL with its credential query parameters and `user:pass@` masked. The rest stays as written:
+ * a `{param}` in a tool's path is not encoded.
+ */
+export declare function maskUrl(raw: string): string;
+/**
+ * A masked URL with each masked credential filled in from `held`, the URL it was masked from.
+ * A mask `held` has no value for stays a mask.
+ */
+export declare function unmaskUrl(shown: string, held: string): string;
+/**
+ * Masked headers with each masked value filled in from `held`, the headers they were masked from.
+ * A mask `held` has no header for stays a mask.
+ */
+export declare function unmaskHeaders(shown: Record<string, string>, held: Record<string, string> | undefined): Record<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;

package/esm/src/surface/formats.js

@@ -0,0 +1,178 @@
+import { redactDetectors } from '../guardrails/detect-at.js';
+import { SENSITIVE_GROUPS } from '../guardrails/sensitive-groups.js';
+/** What stands in for a credential's value wherever one is shown. */
+export const MASK = '••••';
+/** Names that carry a credential, in a URL's query or a header. */
+const CREDENTIAL_NAME = /auth|key|token|secret|passw|pwd|cookie|session|signature|^sig$|credential|^code$|appid/i;
+/** Names a query parameter carries a credential under, in a URL too malformed to parse. */
+const QUERY_CREDENTIAL = /auth|key|token|secret|passw|pwd|signature|credential|appid/i;
+/** What a secret's prefix says it is. Nothing else about the value is told. */
+const SECRET_KINDS = [
+    [/^AIza/, 'Google API key'],
+    [/^sk-or-/, 'OpenRouter key'],
+    [/^sk-ant-/, 'Anthropic key'],
+    [/^sk-/, 'OpenAI key'],
+    [/^(?:ghp_|github_pat_)/, 'GitHub token'],
+    [/^xox[baprs]-/, 'Slack token'],
+    [/^AKIA/, 'AWS access key id'],
+    [/^eyJ[\w-]+\.[\w-]+\./, 'JWT'],
+    [/^Bearer\s/i, 'a whole Bearer header, not a bare token'],
+    [/^https?:\/\//i, 'a URL, not a key'],
+];
+/** Below this, a value is told as "short" and is too short to scrub safely. */
+const SHORT = 16;
+const SCRUB_MIN = 6;
+const TEXT_CAP = 2000;
+const BYTES_CAP = 200;
+/** What an agent sees of a secret instead of its value: whether it is set, what kind it looks like, the mistakes it shows, and the other secrets with the same value and the places that use it. */
+export function secretCard(value, extra = {}) {
+    const text = typeof value === 'string' ? value : '';
+    const core = text.trim();
+    const problems = [];
+    if (/^(?:<.*>|x{3,}|\.{3}|your[-_ ]?(?:api[-_ ]?)?key|changeme|todo)$/i.test(core)) {
+        problems.push('a placeholder, not a real value');
+    }
+    else {
+        if (core && core !== text)
+            problems.push('spaces or a line break around it');
+        if (/[\r\n]/.test(core))
+            problems.push('a line break inside');
+        else if (/\s/.test(core))
+            problems.push('a space inside');
+        if (/^(['"`]).*\1$/.test(core))
+            problems.push('wrapped in quotes');
+        if (core && core.length < SHORT)
+            problems.push('shorter than keys usually are');
+    }
+    const looksLike = SECRET_KINDS.find(([pattern]) => pattern.test(core))?.[1];
+    return {
+        secret: true,
+        set: core.length > 0,
+        ...(looksLike ? { looksLike } : {}),
+        problems,
+        sameAs: [...(extra.sameAs ?? [])],
+        usedBy: [...(extra.usedBy ?? [])],
+    };
+}
+/** A URL's `user:pass@`, after its scheme. */
+const USERINFO = /^([a-z][a-z0-9+.-]*:\/\/)([^/?#@]*)@/i;
+/** One `name=value` of a URL, with the separator before it. */
+const PAIR = /([?&;])([^=?&;#\s]*)=([^&;#\s]*)/g;
+/** A `user:pass`, as its two parts. A password keeps its own colons. */
+function userinfo(text) {
+    const at = text.indexOf(':');
+    return at < 0 ? [text, undefined] : [text.slice(0, at), text.slice(at + 1)];
+}
+function decoded(name) {
+    try {
+        return decodeURIComponent(name);
+    }
+    catch {
+        return name;
+    }
+}
+/** Whether a header or query parameter's name says it carries a credential: what `maskHeaders` masks. */
+export function isCredentialName(name) {
+    return CREDENTIAL_NAME.test(name);
+}
+/**
+ * A URL with its credential query parameters and `user:pass@` masked. The rest stays as written:
+ * a `{param}` in a tool's path is not encoded.
+ */
+export function maskUrl(raw) {
+    const names = URL.canParse(raw) ? CREDENTIAL_NAME : QUERY_CREDENTIAL;
+    return raw
+        .replace(USERINFO, (_whole, scheme, info) => {
+        const [user, password] = userinfo(info);
+        return `${scheme}${user && MASK}${password === undefined ? '' : `:${password && MASK}`}@`;
+    })
+        .replace(PAIR, (pair, separator, name, value) => value && names.test(decoded(name)) ? `${separator}${name}=${MASK}` : pair);
+}
+/**
+ * A masked URL with each masked credential filled in from `held`, the URL it was masked from.
+ * A mask `held` has no value for stays a mask.
+ */
+export function unmaskUrl(shown, held) {
+    const [user, password] = userinfo(USERINFO.exec(held)?.[2] ?? '');
+    const values = new Map();
+    for (const [, , name = '', value = ''] of held.matchAll(PAIR)) {
+        values.set(name, [...(values.get(name) ?? []), value]);
+    }
+    return shown
+        .replace(USERINFO, (_whole, scheme, info) => {
+        const [shownUser, shownPassword] = userinfo(info);
+        const name = shownUser === MASK && user ? user : shownUser;
+        const pass = shownPassword === MASK && password ? password : shownPassword;
+        return `${scheme}${name}${pass === undefined ? '' : `:${pass}`}@`;
+    })
+        .replace(PAIR, (pair, separator, name, value) => {
+        const real = value === MASK ? values.get(name)?.shift() : undefined;
+        return real ? `${separator}${name}=${real}` : pair;
+    });
+}
+/**
+ * Masked headers with each masked value filled in from `held`, the headers they were masked from.
+ * A mask `held` has no header for stays a mask.
+ */
+export function unmaskHeaders(shown, held) {
+    return Object.fromEntries(Object.entries(shown).map(([name, value]) => [
+        name,
+        value === MASK ? (held?.[name] ?? value) : value,
+    ]));
+}
+/**
+ * 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 function maskHeaders(raw) {
+    if (raw === undefined || raw === null || raw === '')
+        return raw;
+    let headers = raw;
+    if (typeof raw === 'string') {
+        try {
+            headers = JSON.parse(raw);
+        }
+        catch {
+            return `(not a JSON object, ${String(raw.length)} characters)`;
+        }
+    }
+    if (typeof headers !== 'object' || headers === null || Array.isArray(headers)) {
+        return '(not a JSON object)';
+    }
+    const masked = Object.fromEntries(Object.entries(headers).map(([name, value]) => [name, isCredentialName(name) ? MASK : value]));
+    return typeof raw === 'string' ? JSON.stringify(masked) : masked;
+}
+/** Scrubs text: each known secret value by name, then the kernel's sensitive patterns. */
+export function scrubText(text, known) {
+    let out = text;
+    for (const [name, value] of known) {
+        if (value.length >= SCRUB_MIN)
+            out = out.replaceAll(value, `[secret ${name}]`);
+    }
+    return redactDetectors(out, SENSITIVE_GROUPS);
+}
+/** Known secret values worth scrubbing: trimmed, long enough, longest first. */
+export function knownSecrets(secrets) {
+    return Object.entries(secrets)
+        .map(([name, value]) => [name, value.trim()])
+        .filter(([, value]) => value.length >= SCRUB_MIN)
+        .sort((a, b) => b[1].length - a[1].length);
+}
+/** Every string in `value` scrubbed and capped; long base64 under `data` told as bytes. */
+export function scrubDeep(value, known) {
+    if (typeof value === 'string') {
+        const text = scrubText(value, known);
+        return text.length > TEXT_CAP ? `${text.slice(0, TEXT_CAP)}…(cut)` : text;
+    }
+    if (Array.isArray(value))
+        return value.map((item) => scrubDeep(item, known));
+    if (typeof value === 'object' && value !== null) {
+        return Object.fromEntries(Object.entries(value).map(([key, inner]) => [
+            key,
+            key === 'data' && typeof inner === 'string' && inner.length > BYTES_CAP
+                ? '(bytes)'
+                : scrubDeep(inner, known),
+        ]));
+    }
+    return value;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * Surfaces: one protocol for an agent to see and work in a client's screen. A page mounts a
+ * surface (nodes with fields and actions); the agent uses two tools, `look` and `act`, and the
+ * runtime projects every answer so secrets reach it only as cards.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export type { SecretCard } from './formats.js';
+export { isCredentialName, knownSecrets, MASK, maskHeaders, maskUrl, scrubDeep, scrubText, secretCard, unmaskHeaders, unmaskUrl, } from './formats.js';
+export type { SurfaceLedgerEntry, SurfaceRuntime, SurfaceRuntimeOptions, } from './runtime.js';
+export { createSurfaceRuntime, SURFACE_TOOL_NAMES } from './runtime.js';
+export type { SurfaceToolsOptions } from './tools.js';
+export { SURFACE_PROMPT, surfaceTools } from './tools.js';
+export type { Surface, SurfaceAction, SurfaceActionContext, SurfaceActionOutcome, SurfaceAuthor, SurfaceChange, SurfaceEffect, SurfaceField, SurfaceFieldFormat, SurfaceIssue, SurfaceNode, SurfaceRejection, } from './types.js';
+export { defineAction } from './types.js';

package/esm/src/surface/mod.js

@@ -0,0 +1,12 @@
+/**
+ * Surfaces: one protocol for an agent to see and work in a client's screen. A page mounts a
+ * surface (nodes with fields and actions); the agent uses two tools, `look` and `act`, and the
+ * runtime projects every answer so secrets reach it only as cards.
+ *
+ * @module
+ */
+import "../../_dnt.polyfills.js";
+export { isCredentialName, knownSecrets, MASK, maskHeaders, maskUrl, scrubDeep, scrubText, secretCard, unmaskHeaders, unmaskUrl, } from './formats.js';
+export { createSurfaceRuntime, SURFACE_TOOL_NAMES } from './runtime.js';
+export { SURFACE_PROMPT, surfaceTools } from './tools.js';
+export { defineAction } from './types.js';