@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,44 @@
+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;
+}
+/** Options for a surface runtime: the clock, how to open a declared surface, where notes go and where the ledger is kept. */
+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;
+    };
+}
+/** What the host holds to mount surfaces and answer the agent's `look` and `act` calls. */
+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;
+}
+/** The tools the runtime answers: `look` and `act`. */
+export declare const SURFACE_TOOL_NAMES: readonly ["look", "act"];
+/** Creates a runtime that mounts surfaces and answers the agent's `look` and `act` calls. */
+export declare function createSurfaceRuntime(options?: SurfaceRuntimeOptions): SurfaceRuntime;

package/esm/src/surface/runtime.js

@@ -0,0 +1,441 @@
+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;
+/** The tools the runtime answers: `look` and `act`. */
+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);
+}
+/** Creates a runtime that mounts surfaces and answers the agent's `look` and `act` calls. */
+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,9 @@
+import type { ToolDefinitionInput } from '../kernel/tools/types.js';
+/** Options for `surfaceTools`: the category the tools are registered under, `surface` by default. */
+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.";

package/esm/src/surface/tools.js

@@ -0,0 +1,62 @@
+import { z } from 'zod';
+const answer = z.record(z.string(), z.unknown());
+const lookInput = z.object({
+    at: z
+        .string()
+        .optional()
+        .describe('A surface ("studio") or a node in one ("studio/identity"); leave out to see every surface'),
+});
+const actInput = z.object({
+    at: z.string().describe('The node to act on, as look names it'),
+    action: z.string().describe('One of the actions look lists for that node'),
+    input: z
+        .record(z.string(), z.unknown())
+        .optional()
+        .describe("The action's input, per its schema"),
+    basedOn: z
+        .number()
+        .int()
+        .optional()
+        .describe('For a write: the revision from your last look. If the page changed since, nothing applies.'),
+    intent: z
+        .string()
+        .optional()
+        .describe('A short key for what the person asked ("image-agent"), so a repeat of a starting-over action applies once'),
+});
+/** `look` and `act`: the two tools an agent uses to see and work in every surface a client mounts. */
+export function surfaceTools(options = {}) {
+    const base = {
+        type: 'function',
+        category: options.category ?? 'surface',
+        paths: ['*'],
+        loadTier: 'T0',
+        permission: 'auto',
+        output: answer,
+        answeredBy: 'page',
+    };
+    return [
+        {
+            ...base,
+            name: 'look',
+            description: "See what is on the person's screen. With no `at`: every surface, its revision, summary, nodes, and issue counts. With `at`: that node's fields (secrets only as cards: set, what it looks like, problems), what each means, its issues, its actions with their input schemas, and its children.",
+            access: 'read-only',
+            input: lookInput,
+        },
+        {
+            ...base,
+            name: 'act',
+            description: "Do one of a node's actions: `set` fields, `point` the person at something, or the node's own (test, send, launch…). Comes back applied, unchanged, done, stale (the page changed: look again), refused, or failed, with what was rejected and why.",
+            access: 'read-write',
+            input: actInput,
+        },
+    ];
+}
+/** How to use `look` and `act`, for an agent's instructions. */
+export const SURFACE_PROMPT = `You see and work in the person's screen through surfaces, with two tools.
+- look: no \`at\` lists every surface. Look at a node before you act on it.
+- act: do one of the actions look lists. Pass basedOn (the revision from your last look) for writes.
+- Say a change is done only when act comes back applied. If it lists rejected fields, say which and why.
+- stale means the person changed something: look again, then go on. After refused or failed, look before retrying; never retry blind.
+- 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.
+- When something isn't working, look for issues, test what can be tested, and tell the person what you found in plain words.
+- 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.`;

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

@@ -0,0 +1,110 @@
+import type { z } from 'zod';
+/**
+ * How a field's value leaves the page. The runtime projects every value through
+ * its format before an agent sees it, so a page cannot forget to.
+ * - `secret`: only a card (set, what it looks like, what is wrong with it), never the value.
+ * - `url`: credential query parameters and `user:pass@` masked.
+ * - `headers`: a JSON object of headers, credential-named values masked.
+ * - `text` (the default): as is, then scrubbed with every other answer.
+ */
+export type SurfaceFieldFormat = 'secret' | 'url' | 'headers' | 'text';
+/** One value on a surface: what it holds and how the agent should read it. */
+export interface SurfaceField {
+    value: unknown;
+    /** The kind of value, as the agent should read it ("boolean", "one of …"). */
+    type?: string;
+    /** What the setting means. */
+    doc?: string;
+    options?: readonly unknown[];
+    format?: SurfaceFieldFormat;
+    /** Why the agent may not `set` it; the person still can. */
+    readOnly?: string;
+    /** For a secret: what uses it, so its card can say. */
+    usedBy?: readonly string[];
+}
+/** Something wrong on a node, or on one of its fields. */
+export interface SurfaceIssue {
+    node: string;
+    field?: string;
+    message: string;
+}
+/** A change that was not made, and why. */
+export interface SurfaceRejection {
+    field: string;
+    why: string;
+}
+/**
+ * - `read`: changes nothing.
+ * - `run`: does something outside the surface (tests a key, sends a message, exports).
+ * - `write`: changes the surface; it needs the revision the agent last saw.
+ */
+export type SurfaceEffect = 'read' | 'run' | 'write';
+/** Who a change is by, for the surface to record: notes are told only about the person's. */
+export type SurfaceAuthor = 'person' | 'agent';
+/** What an action run is told: its call id and who started it. */
+export interface SurfaceActionContext {
+    callId: string;
+    by: SurfaceAuthor;
+}
+/** What an action run returns: any rejections and its result. */
+export interface SurfaceActionOutcome {
+    rejected?: SurfaceRejection[];
+    /** What the action found or made; scrubbed like everything else. */
+    result?: unknown;
+    /** The node the change landed on (local id), shown back to the agent. */
+    node?: string;
+}
+/** Something the agent can do on a node: its description, effect, input schema, and `run`. */
+export interface SurfaceAction<Input = Record<string, unknown>> {
+    description: string;
+    effect: SurfaceEffect;
+    /** Checked before `run`; each issue comes back as a rejection. */
+    input?: z.ZodType<Input>;
+    /** A write that starts something over: the same `intent` again within a minute replays. */
+    intent?: boolean;
+    run(input: Input, ctx: SurfaceActionContext): SurfaceActionOutcome | Promise<SurfaceActionOutcome>;
+}
+/** One part of a surface, with its fields and actions. */
+export interface SurfaceNode {
+    /** Unique in its surface. The root's is `''`, addressed by the surface id alone. */
+    id: string;
+    title: string;
+    /** The parent's id; the root has none. */
+    parent?: string;
+    summary?: string;
+    fields?(): Record<string, SurfaceField>;
+    /**
+     * Applies field changes the runtime has checked: each names a field (or a dotted path in one),
+     * and none is a secret or read-only.
+     */
+    set?(changes: Record<string, unknown>, ctx: SurfaceActionContext): {
+        rejected: SurfaceRejection[];
+    };
+    /** Shows the node, or one of its fields, to the person: selects it, scrolls to it, focuses it. */
+    point?(field?: string): void;
+    actions?: Record<string, SurfaceAction<never>>;
+}
+/** A recorded change to a surface: its revision, author, and the nodes it touched. */
+export interface SurfaceChange {
+    revision: number;
+    by: SurfaceAuthor;
+    /** Local ids of the nodes it touched. */
+    nodes: readonly string[];
+}
+/** What a page mounts so an agent can see it and work in it. */
+export interface Surface {
+    id: string;
+    title: string;
+    revision(): number;
+    /** One line: what is here and where it stands. */
+    summary(): string;
+    /** Read fresh on every call. The first is the root. */
+    nodes(): readonly SurfaceNode[];
+    issues?(): readonly SurfaceIssue[];
+    changesSince?(revision: number): readonly SurfaceChange[];
+    subscribe?(listener: () => void): () => void;
+    /** Secret values by name, so any answer that carries one is scrubbed. Read per answer, never kept. */
+    secrets?(): Record<string, string>;
+}
+/** Defines an action with its input type inferred, then erased for `SurfaceNode.actions`. */
+export declare function defineAction<Input>(action: SurfaceAction<Input>): SurfaceAction<never>;

package/esm/src/surface/types.js

@@ -0,0 +1,4 @@
+/** Defines an action with its input type inferred, then erased for `SurfaceNode.actions`. */
+export function defineAction(action) {
+    return action;
+}