@ouispec/agent-worker 0.1.1 → 0.2.2

package/dist/ui/ui-tools.js

@@ -1,6 +1,72 @@
-import { boundObservations } from './observations.js';
+/**
+ * UI tools: the page's actions as the worker runs them (ADR-0209, ADR-0245).
+ *
+ * The page sends an index of what it offers. Each action of the index is a
+ * tool here, run by sending an OUI action request to the client that sent the
+ * turn and waiting for its answer (ADR-0209 D2): the model gets what really
+ * happened — the action's result or error — and what the page offers and shows
+ * afterwards. An action's definition is fetched from the page when it is
+ * needed (`oui.describe`), and what did not fit an answer is read from it
+ * (`oui.read`).
+ *
+ * The model is not given one tool per action: it is given the index, and three
+ * tools to work it with (`ui_act`, `ui_describe`, `ui_read`). The per-action
+ * tools built here are what `ui_act` runs, so every check a tool call goes
+ * through — input, quota, policy, approval — sees the action itself.
+ */
+import { randomUUID } from 'node:crypto';
+import { AGENT_UI_TOOLS } from '@ouispec/agent-core';
+import { jsonBytes, OUI_DESCRIBE_ACTION, OUI_READ_ACTION, OUI_RUNTIME_SURFACE, } from 'oui-spec/spec';
+import { boundObservations, DEFAULT_PAGE_STATE_CHARS, observationSchemas } from './observations.js';
+import { describeSchema } from './outline.js';
+import { definitionKey, indexDiff, indexText, isFullSurface, isSurfaceIndex, pageActions, pageFromIndex, pageFromSurfaces, } from './page-index.js';
+import { liftAnswerImage } from './answer-image.js';
 import { createUISequence } from './ui-sequence.js';
-const DEFAULT_MAX_OBSERVATION_CHARS = 6_000;
+/** The tool that runs one action of the page. Built by the orchestrator, which unwraps it to the action's own tool. */
+export const UI_ACT_TOOL = AGENT_UI_TOOLS.act;
+/** The tool that says what actions take. */
+export const UI_DESCRIBE_TOOL = AGENT_UI_TOOLS.describe;
+/** The tool that reads part of the page's state. */
+export const UI_READ_TOOL = AGENT_UI_TOOLS.read;
+/** After this many changes refused in a row, the turn changes nothing more in the page. */
+export const BLIND_REFUSALS_BEFORE_STOP = 2;
+export function createPageSight() {
+    let why = null;
+    let inARow = 0;
+    let total = 0;
+    let stopped = false;
+    const STOPPED = 'Not run: the page still cannot be seen, so nothing more is changed in it this turn. ' +
+        'Tell the user plainly what you did, what you could not confirm, and what they can check on their screen.';
+    return {
+        blind: () => why,
+        lost: (reason) => {
+            why = reason;
+        },
+        seen: () => {
+            why = null;
+            inARow = 0;
+        },
+        refuseChange() {
+            if (stopped) {
+                total++;
+                return { error: STOPPED, stopped: true };
+            }
+            if (!why)
+                return null;
+            inARow++;
+            total++;
+            if (inARow >= BLIND_REFUSALS_BEFORE_STOP)
+                stopped = true;
+            return {
+                error: `Not run: you cannot see the page (${why}). Read it first, with ${AGENT_UI_TOOLS.read} or an action that only reads; ` +
+                    'then run this again if it is still needed. Never change the page to find out what it shows.',
+                stopped: false,
+            };
+        },
+        refusals: () => total,
+        stopped: () => stopped,
+    };
+}
 /**
  * When to send a request again while no tab has received it (dispatchUntilAnswered):
  * after 1 s, then 2, 4, and every 8 s.
@@ -15,60 +81,299 @@ export const MAX_RESEND_AFTER_MS = 8_000;
 export const RECEIVED_RESEND_AFTER_MS = 10_000;
 /** How long to wait for an async action's outcome when it declares no limit of its own. */
 export const DEFAULT_JOB_WAIT_MS = 5 * 60_000;
-/** Build the UI tools for a set of surfaces. The first surface to declare an action id keeps it. */
-export function buildUITools(surfaces, deps) {
-    const tools = [];
-    const owner = new Map();
-    const collisions = [];
-    const sequence = deps.sequence ?? createUISequence();
-    for (const surface of surfaces) {
-        for (const action of surface.actions) {
-            const kept = owner.get(action.id);
-            if (kept !== undefined) {
-                collisions.push({ actionId: action.id, keptSurface: kept, droppedSurface: surface.id });
-                continue;
-            }
-            owner.set(action.id, surface.id);
-            tools.push(uiTool(surface, action, deps, sequence));
-        }
-    }
-    return { tools, collisions };
-}
-function uiTool(surface, action, deps, sequence) {
+/** The most actions one `ui_describe` call describes. */
+export const MAX_DESCRIBED_ACTIONS = 8;
+/**
+ * Build the UI tools for a page: one per action, which `ui_act` runs, and the
+ * two the model calls itself to learn what actions take and to read the page.
+ * The first surface to offer an action id keeps it.
+ */
+export function buildUITools(page, deps) {
+    const shared = {
+        deps,
+        sequence: deps.sequence ?? createUISequence(),
+        held: deps.held ?? new Map(),
+        sight: deps.sight ?? createPageSight(),
+    };
+    const { actions, collisions } = pageActions(page);
     return {
-        name: action.id,
+        tools: actions.map((action) => actionTool(action, shared)),
+        collisions,
+        describe: describeTool(shared),
+        read: readTool(shared),
+    };
+}
+/** The tool for one action of the page: what `ui_act` runs. */
+function actionTool(action, shared) {
+    const { surface, entry } = action;
+    const tool = {
+        name: entry.id,
         kind: 'ui',
-        description: describe(surface, action),
-        inputSchema: (action.input ?? { type: 'object', properties: {} }),
+        description: `[UI · ${surface.name}] ${entry.description}`,
+        // Stands in until the definition is fetched: `resolveInputSchema` puts the
+        // real one here, with the action's whole description, so what reads the
+        // tool after (the approval card's labels and its words) reads the
+        // declaration itself and not its line in the index.
+        inputSchema: { type: 'object' },
+        resolveInputSchema: async (ctx) => {
+            const definition = await definitionOf(action, shared, ctx);
+            tool.inputSchema = (definition.input ?? { type: 'object', properties: {} });
+            tool.title = definition.title ?? definition.description;
+            tool.consequence = definition.description;
+            return tool.inputSchema;
+        },
         // The approval card's words and whether a call needs approval come from
         // the declaration (ADR-0228 §2.1–2.2). `confirm` marks a destructive
         // action, or one that changes what the person works in: either asks.
-        ...(action.title ? { title: action.title } : { title: action.description }),
-        consequence: action.description,
-        ...(action.effect !== undefined ? { effect: action.effect } : {}),
-        ...(action.confirm ? { destructive: true } : {}),
+        title: entry.title ?? entry.description,
+        consequence: entry.description,
+        ...(entry.effect !== undefined ? { effect: entry.effect } : {}),
+        ...(entry.confirm ? { destructive: true } : {}),
         execute(input, ctx) {
             // In the place the orchestrator took when the model's call arrived, or,
             // called directly, in a place taken now (ui-sequence.ts).
-            const slot = ctx.uiSlot ?? sequence.reserve();
-            return slot.run(() => runAction(surface, action, deps, sequence, input, ctx));
+            const slot = ctx.uiSlot ?? shared.sequence.reserve();
+            return slot.run(async () => {
+                // Checked here, in the action's place in the turn's order, and not when
+                // the model's call arrived: of two changes called in one response, the
+                // first's answer decides whether the second may run (ADR-0245 §2.5).
+                const refusal = entry.effect === 'view' ? null : shared.sight.refuseChange();
+                if (refusal) {
+                    shared.deps.log?.('warn', 'UI action refused: the page cannot be seen', { action: entry.id, stopped: refusal.stopped });
+                    return {
+                        success: false,
+                        error: refusal.error,
+                        data: { notRun: true, ...(refusal.stopped ? { uiStopped: true } : { blind: true }) },
+                    };
+                }
+                return runAction(action, shared, input, ctx);
+            });
+        },
+    };
+    return tool;
+}
+// ─── Definitions ─────────────────────────────────────────────────────────────
+/** Thrown when an action's definition cannot be had: the model is told why. */
+export class DefinitionUnavailable extends Error {
+}
+/**
+ * The definitions of `wanted`, from what the turn holds and, for the rest,
+ * from the page (`oui.describe`). An action the page no longer offers is left
+ * out of the result.
+ */
+async function definitionsOf(wanted, shared, ctx) {
+    const found = new Map();
+    let missing = wanted.filter((a) => {
+        const held = shared.held.get(definitionKey(a.surface.id, a.entry));
+        if (held)
+            found.set(a, held);
+        return !held;
+    });
+    // A frame carries so many definitions; the page defers the rest, which are asked for again.
+    for (let round = 0; missing.length > 0 && round < wanted.length; round++) {
+        const room = ctx.socketRoom;
+        if (!room)
+            throw new Error('[agent-sdk] Describing a UI action needs the turn’s room');
+        const request = {
+            requestId: `describe-${randomUUID()}`,
+            surfaceId: OUI_RUNTIME_SURFACE,
+            actionId: OUI_DESCRIBE_ACTION,
+            params: { actions: missing.map((a) => ({ surface: a.surface.id, action: a.entry.id })) },
+            timestamp: Date.now(),
+        };
+        const answered = await dispatchUntilAnswered(shared.deps, room, request, ctx);
+        if (!answered.result) {
+            // A page that does not answer cannot be seen either: nothing is changed in it until it is read.
+            shared.sight.lost('the page is not answering');
+            throw new DefinitionUnavailable('The page did not answer when asked what its actions take. It may be closed or offline: tell the user the page is not responding.');
+        }
+        if (!answered.result.success) {
+            throw new DefinitionUnavailable(`The page could not say what its actions take: ${answered.result.error?.message ?? 'it gave no reason'}`);
+        }
+        const data = (answered.result.data ?? {});
+        const before = missing.length;
+        for (const { surface, action: definition } of data.definitions ?? []) {
+            const asked = missing.find((a) => a.surface.id === surface && a.entry.id === definition.id);
+            if (!asked)
+                continue;
+            shared.held.set(definitionKey(surface, asked.entry), definition);
+            found.set(asked, definition);
+        }
+        const deferred = new Set((answered.result.data?.deferred ?? []).map((d) => `${d.surface}\u0000${d.action}`));
+        missing = missing.filter((a) => !found.has(a) && deferred.has(`${a.surface.id}\u0000${a.entry.id}`));
+        if (missing.length === before)
+            break;
+    }
+    return found;
+}
+async function definitionOf(action, shared, ctx) {
+    const definition = (await definitionsOf([action], shared, ctx)).get(action);
+    if (!definition) {
+        throw new DefinitionUnavailable(`"${action.entry.id}" is no longer on the page. Read the page's index for what it offers now.`);
+    }
+    return definition;
+}
+// ─── ui_describe ─────────────────────────────────────────────────────────────
+function describeTool(shared) {
+    return {
+        name: UI_DESCRIBE_TOOL,
+        kind: 'ui',
+        effect: 'view',
+        description: 'Says what actions of the page take: each action’s full description and its input, as a JSON Schema when it is small, ' +
+            'or in outline when it is large. An outline names how to open each part: call again with that one action and `path`. ' +
+            'A part opened by its path is given whole; a list too long for one answer says how many rows it has and where the next begin (`from`). ' +
+            `Describe an action before the first time you use it, unless its line in the index already says everything it takes. Up to ${MAX_DESCRIBED_ACTIONS} actions a call.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                actions: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    minItems: 1,
+                    maxItems: MAX_DESCRIBED_ACTIONS,
+                    description: 'The ids of the actions, as the page’s index gives them.',
+                },
+                path: {
+                    type: 'string',
+                    description: 'With one action: the part of its input to open, as an outline named it. A property ("style.fill"), ' +
+                        'a union member ("effect=glow"), a list’s items ("stops.[]").',
+                },
+                from: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'With one action: the row to start at, when an answer said its rows continue ("call again with from: 81").',
+                },
+            },
+            required: ['actions'],
+            additionalProperties: false,
+            sideEffects: false,
+        },
+        async execute(input, ctx) {
+            const ids = input.actions;
+            const path = typeof input.path === 'string' ? input.path : '';
+            const from = typeof input.from === 'number' ? input.from : undefined;
+            if ((path || from) && ids.length !== 1) {
+                return { success: false, error: 'A path or a row to start at reads part of one action’s input: name one action with it.' };
+            }
+            const offered = new Map(pageActions(shared.deps.currentPage()).actions.map((a) => [a.entry.id, a]));
+            const wanted = ids.flatMap((id) => offered.get(id) ?? []);
+            const unknown = ids.filter((id) => !offered.has(id));
+            let definitions;
+            try {
+                definitions = await definitionsOf(wanted, shared, ctx);
+            }
+            catch (err) {
+                if (err instanceof DefinitionUnavailable)
+                    return { success: false, error: err.message };
+                throw err;
+            }
+            const described = wanted.flatMap((action) => {
+                const definition = definitions.get(action);
+                if (!definition) {
+                    unknown.push(action.entry.id);
+                    return [];
+                }
+                const view = describeSchema(definition.input, { path, from });
+                return [
+                    {
+                        action: definition.id,
+                        ...(definition.title ? { title: definition.title } : {}),
+                        surface: action.surface.name,
+                        description: definition.description,
+                        ...(definition.usage ? { whenToUse: definition.usage } : {}),
+                        ...(definition.preconditions ? { preconditions: definition.preconditions } : {}),
+                        ...(definition.effect === 'transaction' || definition.confirm ? { needsApproval: true } : {}),
+                        ...(definition.async
+                            ? { waitsForItsWork: definition.estimatedDuration ? `yes, about ${definition.estimatedDuration}` : 'yes' }
+                            : {}),
+                        ...('error' in view
+                            ? { error: view.error }
+                            : view.whole
+                                ? { [path ? 'part' : 'input']: JSON.parse(view.text) }
+                                : { [path ? 'partOutline' : 'inputOutline']: view.text }),
+                    },
+                ];
+            });
+            const notOffered = unknown.length
+                ? { notOnThePage: unknown, note: 'These are not actions of the page as it is now: read the index for what it offers.' }
+                : {};
+            return described.length > 0 || unknown.length === 0
+                ? { success: true, data: { actions: described, ...notOffered } }
+                : { success: false, error: `None of these is an action of the page as it is now: ${unknown.join(', ')}. Read the index for what it offers.` };
         },
     };
 }
-async function runAction(surface, action, deps, sequence, input, ctx) {
+// ─── ui_read ─────────────────────────────────────────────────────────────────
+function readTool(shared) {
+    return {
+        name: UI_READ_TOOL,
+        kind: 'ui',
+        effect: 'view',
+        description: 'Reads part of the page’s state: an observation of a surface, or the part of it at `path`. For a list it returns ' +
+            'rows from `offset`, `limit` at a time, with the total and where the next page begins. Use it for what the page ' +
+            'state says was cut or left out, and to see the page again after an answer came without its state. ' +
+            'When a surface has its own tools to query or inspect its rows, prefer those: they find rows by what they are.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                surface: { type: 'string', description: 'The surface’s id, as the page state gives it.' },
+                observation: { type: 'string', description: 'The observation’s id.' },
+                path: { type: 'string', description: 'A JSON Pointer into the value ("/lists/rows"). Leave out for the whole value.' },
+                offset: { type: 'integer', minimum: 0, description: 'For a list: the first row to return. Default 0.' },
+                limit: { type: 'integer', minimum: 1, maximum: 200, description: 'For a list: how many rows. Default 50.' },
+            },
+            required: ['surface', 'observation'],
+            additionalProperties: false,
+            sideEffects: false,
+        },
+        execute(input, ctx) {
+            const slot = ctx.uiSlot ?? shared.sequence.reserve();
+            return slot.run(async () => {
+                const room = ctx.socketRoom;
+                if (!room)
+                    throw new Error('[agent-sdk] Reading the page needs the turn’s room');
+                const request = {
+                    requestId: ctx.toolCallId ?? `read-${randomUUID()}`,
+                    surfaceId: OUI_RUNTIME_SURFACE,
+                    actionId: OUI_READ_ACTION,
+                    params: input,
+                    timestamp: Date.now(),
+                };
+                const answered = await dispatchUntilAnswered(shared.deps, room, request, ctx);
+                if (!answered.result) {
+                    shared.sight.lost('the page did not answer a read');
+                    return {
+                        success: false,
+                        error: 'The page did not answer. It may be closed or offline: tell the user the page is not responding.',
+                    };
+                }
+                const result = answered.result;
+                if (!result.success)
+                    return { success: false, error: result.error?.message ?? 'The page could not read that.' };
+                // The page answered with what it holds: it can be seen again.
+                shared.sight.seen();
+                return { success: true, data: result.data };
+            });
+        },
+    };
+}
+// ─── Running an action ───────────────────────────────────────────────────────
+async function runAction(action, shared, input, ctx) {
+    const { deps, sequence, sight } = shared;
+    const { surface, entry } = action;
     const requestId = ctx.toolCallId;
     const room = ctx.socketRoom;
     if (!requestId || !room) {
-        throw new Error(`[agent-sdk] UI tool ${action.id} needs the tool call id and the turn's room`);
+        throw new Error(`[agent-sdk] UI tool ${entry.id} needs the tool call id and the turn's room`);
     }
     // The page as the actions before this one left it.
-    const before = sequence.latestSurfaces() ?? deps.currentSurfaces();
-    // The surfaces the worker holds, so the answer repeats them only if they changed (oui-spec §7.3.4).
+    const before = sequence.latestSurfaces() ?? deps.currentPage();
+    // What the worker holds of the page, so the answer repeats it only if it changed (oui-spec §7.3.4).
     const knownSurfaces = sequence.knownHash();
     const request = {
         requestId,
         surfaceId: surface.id,
-        actionId: action.id,
+        actionId: entry.id,
         params: input,
         timestamp: Date.now(),
         ...(ctx.approval ? { approval: ctx.approval } : {}),
@@ -78,34 +383,48 @@ async function runAction(surface, action, deps, sequence, input, ctx) {
     if (!answered.result) {
         const within = `within ${Math.round(deps.resultTimeoutMs / 1000)}s`;
         const sent = `${answered.sends} time${answered.sends === 1 ? '' : 's'}`;
+        // It may have run, and what the page shows now is unknown.
+        if (answered.received || !answered.receipts)
+            sight.lost(`the page did not answer "${entry.id}"`);
         return {
             success: false,
             error: (answered.received
-                ? `The page received "${action.id}" but its answer did not arrive ${within} (the request was sent ${sent}). ` +
-                    'It may have run: check what the page shows before trying again.'
+                ? `The page received "${entry.id}" but its answer did not arrive ${within} (the request was sent ${sent}). ` +
+                    'It may have run: read what the page shows before doing anything else.'
                 : answered.receipts
-                    ? `No open page received "${action.id}" ${within} (sent ${sent}): the person's page may be closed or offline. ` +
+                    ? `No open page received "${entry.id}" ${within} (sent ${sent}): the person's page may be closed or offline. ` +
                         'It did not run there. Tell the user the page is not responding.'
-                    : `The page did not answer "${action.id}" ${within}, though the request was sent to it ${sent}. ` +
-                        'It may or may not have run: check what the page shows before trying again, and tell the user if it is not responding.'),
+                    : `The page did not answer "${entry.id}" ${within}, though the request was sent to it ${sent}. ` +
+                        'It may or may not have run: read what the page shows before doing anything else, and tell the user if it is not responding.'),
         };
     }
-    const result = withSurfaces(answered.result, sequence);
-    deps.onResult(result);
+    const first = withPage(answered.result, shared);
+    deps.onResult(first.result, first.page);
     // Work that outlives the call (a GPU job, an export) was only started: wait
     // for its outcome, so the model tells the person it is done only once it is.
-    const final = result.success && result.interim ? await awaitOutcome(action, deps, requestId, ctx) : null;
-    const outcome = final && final !== 'running' ? withSurfaces(final, sequence) : final;
-    if (outcome && outcome !== 'running')
-        deps.onResult(outcome);
-    const answer = outcome && outcome !== 'running' ? outcome : result;
+    const final = first.result.success && first.result.interim ? await awaitOutcome(entry, deps, requestId, ctx) : null;
+    const outcome = final && final !== 'running' ? withPage(final, shared) : null;
+    if (outcome)
+        deps.onResult(outcome.result, outcome.page);
+    const answer = outcome ?? first;
+    measure(deps, entry.id, answer.result);
+    if (answer.result.delivery?.omitted.includes('observations')) {
+        sight.lost(`the answer to "${entry.id}" came without the page's state (${answer.result.delivery.reason})`);
+    }
+    else {
+        sight.seen();
+    }
+    // A picture in the answer goes to the model as a picture, not as base64 text.
+    const lifted = liftAnswerImage(answer.result.data);
+    const shown = lifted.data === answer.result.data ? answer.result : { ...answer.result, data: lifted.data };
     const data = {
-        ...forModel(answer, before, deps.maxObservationChars ?? DEFAULT_MAX_OBSERVATION_CHARS, surface.id),
-        ...(outcome === 'running' ? { status: 'running', note: stillRunningNote(action) } : {}),
+        ...forModel(shown, before, answer.page, deps.maxObservationChars ?? DEFAULT_PAGE_STATE_CHARS, surface.id),
+        ...(final === 'running' ? { status: 'running', note: stillRunningNote(entry) } : {}),
     };
-    return answer.success
-        ? { success: true, data }
-        : { success: false, data, error: answer.error?.message ?? `"${action.id}" failed` };
+    const image = lifted.image ? { image: lifted.image } : {};
+    return answer.result.success
+        ? { success: true, data, ...image }
+        : { success: false, data, error: answer.result.error?.message ?? `"${entry.id}" failed`, ...image };
 }
 /**
  * Send the request to the turn's room, and send it again only while it may not
@@ -153,22 +472,28 @@ async function dispatchUntilAnswered(deps, room, request, ctx) {
     }
 }
 /**
- * An answer with the surfaces it stands for: those it carries, or those the
- * worker holds under the hash it reports (an answer repeats surfaces only when
- * they changed). Recorded as the page's surfaces from now on.
+ * An answer with the page it stands for: the index it carries, the one derived
+ * from the definitions it carries, or the one the worker holds under the hash
+ * it reports (an answer repeats what the page offers only when that changed).
+ * Recorded as the page from now on.
  */
-function withSurfaces(result, sequence) {
-    const surfaces = sequence.resolve(result);
-    sequence.record(surfaces, result.surfacesHash);
-    return surfaces && !result.surfaces ? { ...result, surfaces } : result;
+function withPage(result, shared) {
+    const carried = Array.isArray(result.index) && result.index.every(isSurfaceIndex)
+        ? pageFromIndex(result.index)
+        : Array.isArray(result.surfaces) && result.surfaces.every(isFullSurface)
+            ? pageFromSurfaces(result.surfaces, shared.held)
+            : undefined;
+    const page = shared.sequence.resolve({ ...(carried ? { page: carried } : {}), surfacesHash: result.surfacesHash });
+    shared.sequence.record(page, result.surfacesHash);
+    return { result, page };
 }
 /**
  * The final answer to a started action: its outcome once the work is done or
  * has failed, or `'running'` when it has not finished by its own limit (its
  * polling's `maxDurationMs`) or by when the turn must stop waiting.
  */
-async function awaitOutcome(action, deps, requestId, ctx) {
-    const until = Math.min(Date.now() + (action.polling?.maxDurationMs ?? DEFAULT_JOB_WAIT_MS), deps.waitDeadline?.() ?? Infinity);
+async function awaitOutcome(entry, deps, requestId, ctx) {
+    const until = Math.min(Date.now() + (entry.maxDurationMs ?? DEFAULT_JOB_WAIT_MS), deps.waitDeadline?.() ?? Infinity);
     const timeoutMs = until - Date.now();
     if (timeoutMs <= 0)
         return 'running';
@@ -183,36 +508,44 @@ async function awaitOutcome(action, deps, requestId, ctx) {
         return 'running';
     return final;
 }
-function stillRunningNote(action) {
-    return (`"${action.id}" started and has not finished yet, so it is not done: tell the person it is still running, ` +
+function stillRunningNote(entry) {
+    return (`"${entry.id}" started and has not finished yet, so it is not done: tell the person it is still running, ` +
         'never that it is done. Its status and result appear in the page state when it finishes.');
 }
-function describe(surface, action) {
-    let desc = `[UI · ${surface.name}] ${action.description}`;
-    if (action.usage)
-        desc += `\n\nWhen to use: ${action.usage}`;
-    if (action.preconditions)
-        desc += `\n\nPreconditions: ${action.preconditions}`;
-    if (action.async) {
-        desc +=
-            '\n\nAsync: waits for the work to finish and returns its outcome; if it is still running when the wait ends, ' +
-                'it says so (status "running"), and the outcome appears in the page state when it finishes.';
-        if (action.estimatedDuration)
-            desc += ` Estimated duration: ${action.estimatedDuration}.`;
-    }
-    return desc;
+/** Report an answer's size by part, and whether it had to be shortened (ADR-0245 §2.6). */
+function measure(deps, actionId, result) {
+    if (!deps.log)
+        return;
+    const offered = result.index ?? result.surfaces;
+    deps.log(result.delivery?.trimmed ? 'warn' : 'info', 'UI answer', {
+        requestId: result.requestId,
+        action: actionId,
+        bytes: {
+            total: jsonBytes(result),
+            offered: jsonBytes(offered),
+            observations: jsonBytes(result.observations),
+            data: jsonBytes(result.data),
+        },
+        form: result.index ? 'index' : result.surfaces ? 'full' : 'unchanged',
+        ...(offered ? { actions: (result.index ?? []).reduce((n, s) => n + s.index.length, 0) + (result.surfaces ?? []).reduce((n, s) => n + s.actions.length, 0) } : {}),
+        ...(result.fit ? { fitted: { lists: result.fit.observations?.length ?? 0, dataLeftOut: !!result.fit.data } } : {}),
+        ...(result.delivery?.trimmed ? { trimmed: result.delivery.omitted, refusedBecause: result.delivery.reason } : {}),
+    });
 }
 /**
- * What the model sees: the outcome, and what the page offers now. Tool changes
- * are named so the model knows the page it is on, not just that something
- * happened.
+ * What the model sees: the outcome, what the page offers now where that
+ * changed, and what it shows. A new surface comes with its index; an action
+ * added to or removed from a surface is named, so the model knows the page it
+ * is on, not just that something happened.
  */
-function forModel(result, before, maxObservationChars, actingSurfaceId) {
-    const after = result.surfaces ?? before;
-    const beforeActions = new Set(before.flatMap((s) => s.actions.map((a) => a.id)));
-    const afterActions = new Set(after.flatMap((s) => s.actions.map((a) => a.id)));
-    const added = [...afterActions].filter((id) => !beforeActions.has(id));
-    const removed = [...beforeActions].filter((id) => !afterActions.has(id));
+function forModel(result, before, page, maxObservationChars, actingSurfaceId) {
+    const after = page ?? before;
+    const was = new Set(before.map((s) => s.id));
+    const opened = after.filter((s) => !was.has(s.id));
+    // Within the surfaces that stayed, what was added and what went.
+    const stayed = (surfaces) => surfaces.filter((s) => was.has(s.id) && after.some((a) => a.id === s.id));
+    const { added, removed } = indexDiff(stayed(before), stayed(after));
+    const closed = before.filter((s) => !after.some((a) => a.id === s.id)).map((s) => s.name);
     return {
         ...(result.data !== undefined ? { result: result.data } : {}),
         ...(result.error ? { error: result.error } : {}),
@@ -221,24 +554,72 @@ function forModel(result, before, maxObservationChars, actingSurfaceId) {
             ? { note: 'The page was still loading when this was reported; what it offers may still change.' }
             : {}),
         ...(result.delivery?.trimmed ? { delivery: deliveryNote(result.delivery) } : {}),
+        ...(result.fit?.data ? { resultLeftOut: dataNote(result.fit.data) } : {}),
         page: {
             surfaces: after.map((s) => s.name),
-            ...(added.length ? { toolsAdded: added } : {}),
-            ...(removed.length ? { toolsRemoved: removed } : {}),
+            ...(opened.length ? { nowOffers: indexText(opened) } : {}),
+            ...(closed.length ? { noLongerOnScreen: closed } : {}),
+            ...(added.length ? { actionsAdded: added } : {}),
+            ...(removed.length ? { actionsRemoved: removed } : {}),
         },
         ...(result.observations && Object.keys(result.observations).length
-            ? { state: boundObservations(result.observations, maxObservationChars, actingSurfaceId) }
+            ? {
+                state: boundObservations(result.observations, maxObservationChars, actingSurfaceId, {
+                    schemas: observationSchemas(after),
+                    changed: changedRefs(result.data),
+                }),
+            }
             : {}),
+        ...(result.fit?.observations?.length ? { notShown: fitNotes(result.fit.observations) } : {}),
     };
 }
+/**
+ * The rows an action says it changed (a room result's `changed`, ADR-0244
+ * §2.5), by what addresses them: kept whole in the page state it comes with.
+ */
+function changedRefs(data) {
+    const changed = data?.changed;
+    if (!Array.isArray(changed))
+        return [];
+    return changed.flatMap((row) => {
+        const ref = row?.ref;
+        return typeof ref === 'string' ? [ref] : [];
+    });
+}
+/** What the model is told about a result too large to send: it ran, and its result must be read another way. */
+function dataNote(data) {
+    return (`The action ran, but what it returned was too large to send (${data.bytes} bytes; an answer carries ${data.limit}). ` +
+        'Its outcome above stands. Read what it produced from the page state, or with a tool that returns it in parts.');
+}
+/** What of the page's state the client left out to fit its answer, and how to read each part (oui-spec §7.3.9). */
+export function fitNotes(cuts) {
+    return cuts.map((cut) => {
+        const where = `${cut.surface}.${cut.observation}${cut.path}`;
+        const read = (extra) => `${UI_READ_TOOL}(${JSON.stringify({ surface: cut.surface, observation: cut.observation, ...(cut.path ? { path: cut.path } : {}), ...extra })})`;
+        if (cut.kind === 'list') {
+            return `${where} has ${cut.total} rows; the page sent the first ${cut.kept}. Read more with ${read({ offset: cut.kept })}, or with the surface's own query tool.`;
+        }
+        if (cut.kind === 'text') {
+            return `${where} is ${cut.total} characters; the page sent the first ${cut.kept}. Read it whole with ${read({})}.`;
+        }
+        return `${where} (${cut.total} bytes) was left out to fit the answer. Read it with ${read({})}.`;
+    });
+}
 /**
  * What the model is told about an answer the tab had to trim to deliver
  * (oui-spec §7.3.6): the outcome is what happened, and what it lacks.
  */
 function deliveryNote(delivery) {
-    const lacks = delivery.omitted.map((field) => (field === 'data' ? 'what the action returned' : `the page's ${field}`));
+    const lacks = delivery.omitted.map((field) => field === 'data'
+        ? 'what the action returned'
+        : field === 'observations'
+            ? 'the page’s state'
+            : 'what the page now offers');
+    const blind = delivery.omitted.includes('observations');
     return (`The page ran this, and its outcome here is what happened, but its full answer was refused on the way ` +
         `(${delivery.reason}), so it came without ${lacks.join(', ')}. ` +
-        "Don't assume what the page shows: read its state from the next action's answer before relying on it.");
+        (blind
+            ? `You cannot see the page now: read it (${UI_READ_TOOL}, or a surface's own read tools) before anything else. Nothing that changes the page runs until you have.`
+            : 'The page state below is current.'));
 }
 //# sourceMappingURL=ui-tools.js.map