@theoremjs/agents 0.0.0-stage → 0.3.0

package/esm/src/surface/formats.js

@@ -0,0 +1,139 @@
+import { sensitiveSpans } from '../guardrails/sensitive.js';
+import { applySpans } from '../observability/spans.js';
+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;
+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 with its credential query parameters and `user:pass@` masked. */
+export function maskUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return raw.replace(/[?&;][^?&;#\s]*/g, (pair) => {
+            const at = pair.indexOf('=');
+            const name = pair.slice(1, at);
+            return at > 1 && at < pair.length - 1 && QUERY_CREDENTIAL.test(name)
+                ? `${pair.slice(0, at + 1)}${MASK}`
+                : pair;
+        });
+    }
+    const credentials = [...new Set(url.searchParams.keys())].filter((name) => CREDENTIAL_NAME.test(name));
+    if (!url.username && !url.password && credentials.length === 0)
+        return raw;
+    if (url.username)
+        url.username = MASK;
+    if (url.password)
+        url.password = MASK;
+    for (const name of credentials)
+        url.searchParams.set(name, MASK);
+    return url.href.replaceAll(encodeURIComponent(MASK), MASK);
+}
+/**
+ * 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,
+        CREDENTIAL_NAME.test(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 applySpans(out, sensitiveSpans(out));
+}
+/** 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,14 @@
+/**
+ * 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.
+ */
+import "../../_dnt.polyfills.js";
+export type { SecretCard } from './formats.js';
+export { knownSecrets, maskHeaders, maskUrl, scrubDeep, scrubText, secretCard } 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 { clientAnsweredHandler, 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,10 @@
+/**
+ * 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.
+ */
+import "../../_dnt.polyfills.js";
+export { knownSecrets, maskHeaders, maskUrl, scrubDeep, scrubText, secretCard } from './formats.js';
+export { createSurfaceRuntime, SURFACE_TOOL_NAMES } from './runtime.js';
+export { clientAnsweredHandler, SURFACE_PROMPT, surfaceTools } from './tools.js';
+export { defineAction } from './types.js';

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

@@ -0,0 +1,40 @@
+import type { Surface } from './types.js';
+/** One answered `act`, kept so a retried call replays instead of applying twice. */
+export interface SurfaceLedgerEntry {
+    callId: string;
+    at: string;
+    action: string;
+    intent?: string;
+    /** Whether it changed the surface, so a cancel or a lost answer after the fact can be told. */
+    applied: boolean;
+    result: unknown;
+    time: number;
+}
+export interface SurfaceRuntimeOptions {
+    now?: () => number;
+    /** Opens a declared surface that isn't mounted (goes to its page). */
+    open?: (surfaceId: string) => void;
+    mountWaitMs?: number;
+    /** A silent line for the agent: the person changed something, or a call's fate after the fact. */
+    onNote?: (line: string) => void;
+    /** Keeps the ledger across reloads; in memory when left out. */
+    ledger?: {
+        load(): readonly SurfaceLedgerEntry[];
+        save(entries: readonly SurfaceLedgerEntry[]): void;
+    };
+}
+export interface SurfaceRuntime {
+    /** Mounts a surface until the returned function is called. */
+    mount(surface: Surface): () => void;
+    /** A surface the agent may open though it isn't mounted: `open` takes it there. */
+    declare(id: string, title: string): void;
+    isSurfaceTool(name: string): boolean;
+    /** Answers a `look` or `act` call. Every answer is projected and scrubbed. */
+    answer(tool: string, args: unknown, callId: string): Promise<unknown>;
+    /** A call that changed the surface was cancelled, or its answer never got back: tells the agent once. */
+    settled(callId: string, how: 'cancelled' | 'undelivered'): void;
+    /** Where every mounted surface stands and what the agent last did; `null` when there is nothing. */
+    stateLine(): string | null;
+}
+export declare const SURFACE_TOOL_NAMES: readonly ["look", "act"];
+export declare function createSurfaceRuntime(options?: SurfaceRuntimeOptions): SurfaceRuntime;

package/esm/src/surface/runtime.js

@@ -0,0 +1,439 @@
+import { z } from 'zod';
+import { jsonSchemaFromZod } from '../kernel/tools/schema.js';
+import { knownSecrets, maskHeaders, maskUrl, scrubDeep, secretCard } from './formats.js';
+const LEDGER_SIZE = 100;
+const INTENT_WINDOW_MS = 60_000;
+const MOUNT_WAIT_MS = 5000;
+const NODE_LIST_CAP = 80;
+const RECENT_IN_STATE = 5;
+export const SURFACE_TOOL_NAMES = ['look', 'act'];
+const lookArgs = z.object({ at: z.string().optional() });
+const actArgs = z.object({
+    at: z.string().min(1),
+    action: z.string().min(1),
+    input: z.record(z.string(), z.unknown()).optional(),
+    basedOn: z.number().int().optional(),
+    intent: z.string().optional(),
+});
+const setInput = z.object({
+    changes: z
+        .record(z.string(), z.unknown())
+        .describe('Field name (or a dotted path in one, "include.usage") to its new value'),
+});
+const pointInput = z.object({
+    field: z.string().optional().describe('A field to focus; leave out to show the whole node'),
+});
+const BUILT_IN = {
+    set: {
+        description: 'Change fields. Each one refused comes back with why; the rest apply.',
+        effect: 'write',
+        input: setInput,
+    },
+    point: {
+        description: 'Show this node, or one of its fields, to the person: it is selected and focused. Use it to have them enter a secret.',
+        effect: 'read',
+        input: pointInput,
+    },
+};
+function issueCount(count) {
+    return `${String(count)} ${count === 1 ? 'issue' : 'issues'}`;
+}
+function rejectionsFrom(error) {
+    return error.issues.map((issue) => ({
+        field: issue.path.join('.') || 'input',
+        why: issue.message,
+    }));
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export function createSurfaceRuntime(options = {}) {
+    const now = options.now ?? Date.now;
+    const mounted = new Map();
+    const declared = new Map();
+    const mountWaiters = new Set();
+    let ledger = [...(options.ledger?.load() ?? [])];
+    const note = (line) => options.onNote?.(line);
+    const remember = (entry) => {
+        ledger = [...ledger.filter((old) => old.callId !== entry.callId), entry].slice(-LEDGER_SIZE);
+        options.ledger?.save(ledger);
+    };
+    const address = (surface, nodeId) => nodeId ? `${surface.id}/${nodeId}` : surface.id;
+    const nodeIssues = (surface, nodeId) => (surface.issues?.() ?? []).filter((issue) => issue.node === nodeId);
+    /** Every secret value showing on the page, by name: what the surface says, and every secret field. */
+    const secretsOf = (surface) => {
+        const found = { ...surface.secrets?.() };
+        for (const node of surface.nodes()) {
+            for (const [name, field] of Object.entries(node.fields?.() ?? {})) {
+                if (field.format === 'secret' && typeof field.value === 'string') {
+                    found[`${address(surface, node.id)}.${name}`] = field.value;
+                }
+            }
+        }
+        return found;
+    };
+    const known = () => knownSecrets(Object.assign({}, ...[...mounted.values()].map((surface) => secretsOf(surface))));
+    const project = (surface, node, name, field) => {
+        if (field.format === 'secret') {
+            const value = typeof field.value === 'string' ? field.value.trim() : '';
+            const self = `${address(surface, node.id)}.${name}`;
+            const sameAs = value
+                ? Object.entries(secretsOf(surface))
+                    .filter(([other, otherValue]) => other !== self && otherValue.trim() === value)
+                    .map(([other]) => other)
+                : [];
+            return secretCard(field.value, { sameAs, usedBy: field.usedBy });
+        }
+        if (field.format === 'url' && typeof field.value === 'string')
+            return maskUrl(field.value);
+        if (field.format === 'headers')
+            return maskHeaders(field.value);
+        return field.value;
+    };
+    const actionsOf = (node) => {
+        const own = Object.entries(node.actions ?? {});
+        const builtIn = [];
+        if (node.set && node.fields)
+            builtIn.push(['set', BUILT_IN.set]);
+        if (node.point)
+            builtIn.push(['point', BUILT_IN.point]);
+        return [...builtIn, ...own];
+    };
+    const children = (surface, nodeId) => surface
+        .nodes()
+        .filter((child) => child.id && (child.parent ?? '') === nodeId)
+        .map((child) => {
+        const count = nodeIssues(surface, child.id).length;
+        return {
+            at: address(surface, child.id),
+            title: child.title,
+            ...(count ? { issues: count } : {}),
+        };
+    });
+    const nodeView = ({ surface, node, at }) => {
+        const fields = node.fields?.() ?? {};
+        const about = Object.fromEntries(Object.entries(fields).flatMap(([name, field]) => {
+            const info = {
+                ...(field.type ? { type: field.type } : {}),
+                ...(field.doc ? { doc: field.doc } : {}),
+                ...(field.options?.length ? { options: field.options } : {}),
+                ...(field.format && field.format !== 'text' ? { format: field.format } : {}),
+                ...(field.readOnly ? { readOnly: field.readOnly } : {}),
+            };
+            return Object.keys(info).length ? [[name, info]] : [];
+        }));
+        const issues = nodeIssues(surface, node.id).map(({ field, message }) => ({
+            ...(field ? { field } : {}),
+            message,
+        }));
+        const kids = children(surface, node.id);
+        return {
+            at,
+            title: node.title,
+            revision: surface.revision(),
+            ...(node.summary ? { summary: node.summary } : {}),
+            ...(Object.keys(fields).length
+                ? {
+                    fields: Object.fromEntries(Object.entries(fields).map(([name, field]) => [
+                        name,
+                        project(surface, node, name, field),
+                    ])),
+                }
+                : {}),
+            ...(Object.keys(about).length ? { about } : {}),
+            ...(issues.length ? { issues } : {}),
+            actions: actionsOf(node).map(([name, action]) => ({
+                name,
+                effect: action.effect,
+                description: action.description,
+                ...(action.input ? { input: jsonSchemaFromZod(action.input, 'input') } : {}),
+            })),
+            ...(kids.length ? { children: kids } : {}),
+        };
+    };
+    const overview = () => ({
+        surfaces: [...mounted.values()].map((surface) => {
+            const issues = surface.issues?.() ?? [];
+            return {
+                at: surface.id,
+                title: surface.title,
+                revision: surface.revision(),
+                summary: surface.summary(),
+                ...(issues.length ? { issues: issues.length } : {}),
+                nodes: surface
+                    .nodes()
+                    .filter((node) => node.id)
+                    .slice(0, NODE_LIST_CAP)
+                    .map((node) => {
+                    const count = issues.filter((issue) => issue.node === node.id).length;
+                    return {
+                        at: address(surface, node.id),
+                        title: node.title,
+                        ...(node.parent ? { parent: address(surface, node.parent) } : {}),
+                        ...(count ? { issues: count } : {}),
+                    };
+                }),
+            };
+        }),
+        ...([...declared.keys()].some((id) => !mounted.has(id))
+            ? {
+                closed: [...declared]
+                    .filter(([id]) => !mounted.has(id))
+                    .map(([id, title]) => ({ at: id, title, note: 'Look or act on it to open it.' })),
+            }
+            : {}),
+    });
+    const waitForMount = (id, ms) => new Promise((resolve) => {
+        if (mounted.has(id)) {
+            resolve(true);
+            return;
+        }
+        const check = () => {
+            if (!mounted.has(id))
+                return;
+            clearTimeout(timer);
+            mountWaiters.delete(check);
+            resolve(true);
+        };
+        const timer = setTimeout(() => {
+            mountWaiters.delete(check);
+            resolve(false);
+        }, ms);
+        mountWaiters.add(check);
+    });
+    /** The node `at` names, opening its surface first when it is declared but not mounted. */
+    const resolve = async (at) => {
+        const slash = at.indexOf('/');
+        const surfaceId = slash < 0 ? at : at.slice(0, slash);
+        const nodeId = slash < 0 ? '' : at.slice(slash + 1);
+        if (!mounted.has(surfaceId)) {
+            if (!declared.has(surfaceId) || !options.open) {
+                return { refused: `Nothing called ${surfaceId} is open. Look to see what is.` };
+            }
+            options.open(surfaceId);
+            if (!(await waitForMount(surfaceId, options.mountWaitMs ?? MOUNT_WAIT_MS))) {
+                return { refused: `${surfaceId} did not open. Look to see where the person is.` };
+            }
+        }
+        const surface = mounted.get(surfaceId);
+        const node = surface?.nodes().find((candidate) => candidate.id === nodeId);
+        if (!surface || !node) {
+            return { refused: `No ${at} here. Look at ${surfaceId} for what is.` };
+        }
+        return { surface, node, at: address(surface, node.id) };
+    };
+    const changedSince = (surface, revision) => [
+        ...new Set((surface.changesSince?.(revision) ?? []).flatMap((change) => change.nodes.map((id) => address(surface, id)))),
+    ];
+    const look = async (args) => {
+        const parsed = lookArgs.safeParse(args ?? {});
+        if (!parsed.success)
+            return { status: 'refused', why: 'at must be text' };
+        if (!parsed.data.at)
+            return overview();
+        const target = await resolve(parsed.data.at);
+        if ('refused' in target)
+            return { status: 'refused', why: target.refused };
+        return nodeView(target);
+    };
+    const runBuiltIn = (target, name, input, ctx) => {
+        const { node } = target;
+        if (name === 'point') {
+            const field = typeof input.field === 'string' ? input.field : undefined;
+            node.point?.(field);
+            return { result: { shown: field ? `${target.at}.${field}` : target.at } };
+        }
+        const fields = node.fields?.() ?? {};
+        const rejected = [];
+        const allowed = {};
+        for (const [path, value] of Object.entries(input.changes)) {
+            const field = fields[path.split('.', 1)[0] ?? path];
+            if (!field)
+                rejected.push({ field: path, why: 'no such field; look at the node for its fields' });
+            else if (field.format === 'secret') {
+                rejected.push({
+                    field: path,
+                    why: 'only the person enters this: act point on it, then ask them to type it in',
+                });
+            }
+            else if (field.readOnly)
+                rejected.push({ field: path, why: field.readOnly });
+            else
+                allowed[path] = value;
+        }
+        if (Object.keys(allowed).length && node.set) {
+            rejected.push(...node.set(allowed, ctx).rejected);
+        }
+        return { rejected, node: node.id };
+    };
+    /** What an `act` call resolved to, or the answer that ends it before anything runs. */
+    const prepareAct = async (args) => {
+        const parsed = actArgs.safeParse(args ?? {});
+        if (!parsed.success) {
+            return {
+                done: { status: 'refused', why: 'Bad call.', rejected: rejectionsFrom(parsed.error) },
+            };
+        }
+        const { at, action: name, basedOn, intent } = parsed.data;
+        const target = await resolve(at);
+        if ('refused' in target)
+            return { done: { status: 'refused', why: target.refused } };
+        const { surface, node } = target;
+        const action = actionsOf(node).find(([candidate]) => candidate === name)?.[1];
+        if (!action) {
+            return {
+                done: {
+                    status: 'refused',
+                    why: `${target.at} has no ${name}. It has: ${actionsOf(node)
+                        .map(([candidate]) => candidate)
+                        .join(', ')}.`,
+                },
+            };
+        }
+        const checked = action.input
+            ? action.input.safeParse(parsed.data.input ?? {})
+            : { success: true, data: parsed.data.input ?? {} };
+        if (!checked.success) {
+            return {
+                done: { status: 'refused', why: 'Bad input.', rejected: rejectionsFrom(checked.error) },
+            };
+        }
+        const write = action.effect === 'write';
+        if (write && basedOn === undefined) {
+            return {
+                done: {
+                    status: 'refused',
+                    why: 'Pass basedOn: the revision from your last look.',
+                    revision: surface.revision(),
+                },
+            };
+        }
+        if (write && action.intent && intent) {
+            const repeat = ledger.find((entry) => entry.intent === intent &&
+                entry.at === target.at &&
+                now() - entry.time < INTENT_WINDOW_MS);
+            if (repeat)
+                return { done: repeat.result };
+        }
+        return { ready: { target, name, basedOn, intent, data: checked.data, write } };
+    };
+    const act = async (args, callId) => {
+        const seen = ledger.find((entry) => entry.callId === callId);
+        if (seen)
+            return seen.result;
+        const prepared = await prepareAct(args);
+        if (!prepared.ready)
+            return prepared.done;
+        const { target, name, basedOn, intent, data, write } = prepared.ready;
+        const { surface, node } = target;
+        let result;
+        let applied = false;
+        if (write && basedOn !== surface.revision()) {
+            result = {
+                status: 'stale',
+                why: 'The page changed since your look; nothing applied. Look again.',
+                revision: surface.revision(),
+                changed: changedSince(surface, basedOn ?? 0),
+            };
+        }
+        else {
+            const before = surface.revision();
+            const ctx = { callId, by: 'agent' };
+            try {
+                const own = node.actions?.[name];
+                const outcome = name in BUILT_IN && !own
+                    ? runBuiltIn(target, name, data, ctx)
+                    : await own.run(data, ctx);
+                const after = surface.revision();
+                applied = after !== before;
+                const landed = outcome.node === undefined ? undefined : await resolve(address(surface, outcome.node));
+                const issues = surface.issues?.() ?? [];
+                result = {
+                    status: write ? (applied ? 'applied' : 'unchanged') : 'done',
+                    revision: after,
+                    ...(applied ? { changed: changedSince(surface, before) } : {}),
+                    ...(outcome.rejected?.length ? { rejected: outcome.rejected } : {}),
+                    ...(outcome.result === undefined ? {} : { result: outcome.result }),
+                    ...(landed && !('refused' in landed) ? { node: nodeView(landed) } : {}),
+                    ...(write ? { issues: issues.length } : {}),
+                };
+            }
+            catch (err) {
+                result = { status: 'failed', why: errorText(err), revision: surface.revision() };
+            }
+        }
+        const scrubbed = scrubDeep(result, known());
+        remember({
+            callId,
+            at: target.at,
+            action: name,
+            ...(intent ? { intent } : {}),
+            applied,
+            result: scrubbed,
+            time: now(),
+        });
+        return scrubbed;
+    };
+    return {
+        mount(surface) {
+            mounted.set(surface.id, surface);
+            for (const waiter of [...mountWaiters])
+                waiter();
+            let seen = surface.revision();
+            const titles = () => new Map(surface.nodes().map((node) => [node.id, node.title]));
+            const stop = surface.subscribe?.(() => {
+                const changes = surface.changesSince?.(seen) ?? [];
+                seen = surface.revision();
+                const nodes = [
+                    ...new Set(changes.filter((change) => change.by === 'person').flatMap((c) => c.nodes)),
+                ];
+                if (nodes.length === 0)
+                    return;
+                const named = titles();
+                const what = nodes.map((id) => named.get(id) ?? (id || surface.title)).join(', ');
+                const count = surface.issues?.().length ?? 0;
+                note(`${surface.id} r${String(seen)}: the person changed ${what}; ${issueCount(count)}`);
+            });
+            return () => {
+                stop?.();
+                if (mounted.get(surface.id) === surface)
+                    mounted.delete(surface.id);
+            };
+        },
+        declare(id, title) {
+            declared.set(id, title);
+        },
+        isSurfaceTool(name) {
+            return SURFACE_TOOL_NAMES.includes(name);
+        },
+        async answer(tool, args, callId) {
+            try {
+                if (tool === 'look')
+                    return scrubDeep(await look(args), known());
+                if (tool === 'act')
+                    return await act(args, callId);
+                return { status: 'refused', why: `${tool} is not a surface tool.` };
+            }
+            catch (err) {
+                return scrubDeep({ status: 'failed', why: errorText(err) }, known());
+            }
+        },
+        settled(callId, how) {
+            const entry = ledger.find((candidate) => candidate.callId === callId);
+            if (!entry?.applied)
+                return;
+            note(`${entry.at} ${entry.action} applied, but ${how === 'cancelled' ? 'the call was cancelled after' : 'its answer never reached you'}`);
+        },
+        stateLine() {
+            const surfaces = [...mounted.values()].map((surface) => `${surface.id} r${String(surface.revision())}: ${surface.summary()}`);
+            const recent = ledger
+                .slice(-RECENT_IN_STATE)
+                .map((entry) => `${entry.at} ${entry.action}`)
+                .join(', ');
+            if (!surfaces.length && !recent)
+                return null;
+            const line = [surfaces.join('; '), recent ? `last calls: ${recent}` : ''].filter(Boolean);
+            return scrubDeep(`(state) ${line.join('; ')}`, known());
+        },
+    };
+}

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

@@ -0,0 +1,15 @@
+import type { ToolContext, ToolDefinitionInput } from '../kernel/tools/types.js';
+/**
+ * The handler for a function tool the client answers: it returns what the client sent back for
+ * the call, which the relay bridge hands over as `ctx.host.clientOutput`. With no output the call
+ * fails to the model, naming the tool; so does a call the bridge settled because the client never
+ * answered (`host.clientTimedOut`).
+ */
+export declare function clientAnsweredHandler(name: string): (input: unknown, ctx: ToolContext) => unknown;
+export interface SurfaceToolsOptions {
+    category?: string;
+}
+/** `look` and `act`: the two tools an agent uses to see and work in every surface a client mounts. */
+export declare function surfaceTools(options?: SurfaceToolsOptions): ToolDefinitionInput[];
+/** How to use `look` and `act`, for an agent's instructions. */
+export declare const SURFACE_PROMPT = "You see and work in the person's screen through surfaces, with two tools.\n- look: no `at` lists every surface. Look at a node before you act on it.\n- act: do one of the actions look lists. Pass basedOn (the revision from your last look) for writes.\n- Say a change is done only when act comes back applied. If it lists rejected fields, say which and why.\n- stale means the person changed something: look again, then go on. After refused or failed, look before retrying; never retry blind.\n- Secrets (keys, tokens, passwords) show only as cards: set or not, what they look like, their problems. You never see or type the value. To have the person enter one, act point on it and ask them to paste it. To find out whether it works, use the node's test action.\n- When something isn't working, look for issues, test what can be tested, and tell the person what you found in plain words.\n- A line starting \"(state)\" is a silent note about what changed on the page. It is background; never read it out. If it says something you did applied late or was cancelled, tell the person once, in a few words.";