@theoremjs/agents 0.3.0 → 0.3.2

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

@@ -61,19 +61,23 @@ export function historyToolArguments(raw) {
 export function toolCallEvents(call, rawArguments) {
     const name = call.name.trim();
     const base = { name, callId: call.id ?? newCallId(name) };
+    const request = {
+        stepId: call.stepId,
+        stepCallCount: call.stepCallCount,
+    };
     if (!name) {
-        return malformedToolCall(base, 'function call is missing a name', rawArguments, call.thoughtSignature);
+        return malformedToolCall(base, 'function call is missing a name', rawArguments, request);
     }
     const parsed = parseToolArgumentsObject(rawArguments);
     if (!parsed.ok) {
-        return malformedToolCall(base, parsed.error, parsed.raw, call.thoughtSignature);
+        return malformedToolCall(base, parsed.error, parsed.raw, request);
     }
-    return [toolCallRequestEvent(base, parsed.value, { thoughtSignature: call.thoughtSignature })];
+    return [toolCallRequestEvent(base, parsed.value, request)];
 }
-/** Keeps the thought signature: the model still reads the failed call's result back. */
-export function malformedToolCall(base, message, raw, thoughtSignature) {
+/** The model still reads the failed call's result back. */
+export function malformedToolCall(base, message, raw, request = {}) {
     return [
-        toolCallRequestEvent(base, {}, { thoughtSignature }),
+        toolCallRequestEvent(base, {}, request),
         failureEvent(base, {
             code: 'malformed_arguments',
             kind: 'bad_response',

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

@@ -0,0 +1,16 @@
+import type { ModelEvent } from '../../kernel/types.js';
+/** A tool call a provider is streaming: its id and name as far as they have come, and its arguments' text. */
+export interface StreamingToolCall {
+    id?: string;
+    name: string;
+    args: string;
+    /** How much of `args` has gone out as `tool_draft` events. */
+    drafted?: number;
+}
+/**
+ * The `tool_draft` event for what `call.args` has gained since it last drafted, and advances
+ * `call.drafted`. Nothing until the call has an id and a name: the call is emitted under that id,
+ * and its draft is joined to it by that id alone. Whatever came before then goes out in the first
+ * draft.
+ */
+export declare function toolDraftEvents(call: StreamingToolCall): ModelEvent[];

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

@@ -0,0 +1,14 @@
+/**
+ * The `tool_draft` event for what `call.args` has gained since it last drafted, and advances
+ * `call.drafted`. Nothing until the call has an id and a name: the call is emitted under that id,
+ * and its draft is joined to it by that id alone. Whatever came before then goes out in the first
+ * draft.
+ */
+export function toolDraftEvents(call) {
+    const name = call.name.trim();
+    const from = call.drafted ?? 0;
+    if (!(call.id && name) || call.args.length <= from)
+        return [];
+    call.drafted = call.args.length;
+    return [{ type: 'tool_draft', callId: call.id, name, text: call.args.slice(from) }];
+}

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

@@ -1,8 +1,8 @@
-import type { KeySlot, ProviderCompleteRequest } from '../../kernel/types.js';
+import type { KeySlot, ModelRequest } 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;
+export declare function tapFetch(tap: ModelRequest['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-tape.js

@@ -1,7 +1,7 @@
 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):
  *

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

@@ -1,19 +1,51 @@
-import type { KeyVault } from '../kernel/types.js';
-export interface OpenAiGatewayConfig {
-    baseUrl?: string;
-    siteUrl?: string;
-    siteName?: string;
-    fetch?: typeof fetch;
+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;
 }
-export interface LocalProviderConfig {
-    /** e.g. `http://127.0.0.1:11434` for Ollama. */
-    baseUrl: string;
-    fetch?: typeof globalThis.fetch;
+/** 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>;
 }
-/** 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;
+/** `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

@@ -1 +1,2 @@
-export {};
+/** 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

@@ -1,3 +1,5 @@
+/** 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;
@@ -9,12 +11,28 @@ export interface SecretCard {
     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;
-/** A URL with its credential query parameters and `user:pass@` masked. */
+/** 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.

package/esm/src/surface/formats.js

@@ -1,6 +1,7 @@
-import { sensitiveSpans } from '../guardrails/sensitive.js';
-import { applySpans } from '../observability/spans.js';
-const MASK = '••••';
+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. */
@@ -23,6 +24,7 @@ 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();
@@ -52,31 +54,71 @@ export function secretCard(value, extra = {}) {
         usedBy: [...(extra.usedBy ?? [])],
     };
 }
-/** A URL with its credential query parameters and `user:pass@` masked. */
-export function maskUrl(raw) {
-    let url;
+/** 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 {
-        url = new URL(raw);
+        return decodeURIComponent(name);
     }
     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;
-        });
+        return name;
     }
-    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);
+}
+/** 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
@@ -97,10 +139,7 @@ export function maskHeaders(raw) {
     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,
-    ]));
+    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. */
@@ -110,7 +149,7 @@ export function scrubText(text, known) {
         if (value.length >= SCRUB_MIN)
             out = out.replaceAll(value, `[secret ${name}]`);
     }
-    return applySpans(out, sensitiveSpans(out));
+    return redactDetectors(out, SENSITIVE_GROUPS);
 }
 /** Known secret values worth scrubbing: trimmed, long enough, longest first. */
 export function knownSecrets(secrets) {

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

@@ -2,13 +2,15 @@
  * 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 { knownSecrets, maskHeaders, maskUrl, scrubDeep, scrubText, 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 { clientAnsweredHandler, SURFACE_PROMPT, surfaceTools } 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

@@ -2,9 +2,11 @@
  * 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 { knownSecrets, maskHeaders, maskUrl, scrubDeep, scrubText, secretCard } from './formats.js';
+export { isCredentialName, knownSecrets, MASK, maskHeaders, maskUrl, scrubDeep, scrubText, secretCard, unmaskHeaders, unmaskUrl, } from './formats.js';
 export { createSurfaceRuntime, SURFACE_TOOL_NAMES } from './runtime.js';
-export { clientAnsweredHandler, SURFACE_PROMPT, surfaceTools } from './tools.js';
+export { SURFACE_PROMPT, surfaceTools } from './tools.js';
 export { defineAction } from './types.js';

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

@@ -10,6 +10,7 @@ export interface SurfaceLedgerEntry {
     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). */
@@ -23,6 +24,7 @@ export interface SurfaceRuntimeOptions {
         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;
@@ -36,5 +38,7 @@ export interface SurfaceRuntime {
     /** 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

@@ -6,6 +6,7 @@ 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({
@@ -47,6 +48,7 @@ function rejectionsFrom(error) {
 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();

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

@@ -1,11 +1,5 @@
-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;
+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;
 }

package/esm/src/surface/tools.js

@@ -1,27 +1,10 @@
 import { z } from 'zod';
-/**
- * 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 function clientAnsweredHandler(name) {
-    return (_input, ctx) => {
-        const host = ctx.host;
-        if (host && 'clientOutput' in host)
-            return host.clientOutput;
-        if (host?.clientTimedOut) {
-            throw new Error("The page didn't answer. Look before trying again.");
-        }
-        throw new Error(`${name} runs in the client, and the client sent no result.`);
-    };
-}
 const answer = z.record(z.string(), z.unknown());
 const lookInput = z.object({
     at: z
         .string()
         .optional()
-        .describe('A surface ("playground") or a node in one ("playground/identity"); leave out to see every surface'),
+        .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'),
@@ -49,23 +32,22 @@ export function surfaceTools(options = {}) {
         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.",
+            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,
-            handler: clientAnsweredHandler('look'),
         },
         {
             ...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.",
+            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,
-            handler: clientAnsweredHandler('act'),
         },
     ];
 }