@superpanel-sdk/runtime 0.5.0 → 0.7.0

package/dist/core/page/render.js

@@ -1,6 +1,6 @@
 /**
- * Page document → `RenderedPage` (15 §10.9 output). Runs on the platform, after the page script
- * returned its document from the sandbox.
+ * A page's envelope → `RenderedPage` (15 §10.9 output). Runs on the platform, after the page script
+ * returned its page from the sandbox: the envelope the page module made of its JSX (31 §8).
  *
  * The document is walked once. Every slot becomes a cell joined with its schema definition; its value
  * is taken from what the platform itself read (`PageReads`), never from the document, and a slot
@@ -12,57 +12,67 @@
  * choose among the rows of their table there (15 §10.15 point 9). So lookups and actions are rendered
  * after the walk, once every row on the page is known.
  *
- * Cells are addressed by slot id `table#n.field` (`RowNames`: stable for a conversation, layout-free);
+ * Cells are addressed by slot id `table:<uuid tail>.field` (`RowNames`: the row's own, layout-free);
  * actions and blocks by their page path (`injuries.rows.0.markError`), resolved against the very page
  * the AI saw.
  */
 import { parentOf } from '../slot/company-metadata.js';
 import { ROW_ID_FIELD } from '../slot/schema.js';
 import { getCompiledTable, getTableField } from '../slot/compile-schema.js';
-import { isChoose } from './define.js';
+import { isChoose, PAGE_TOOLS } from './define.js';
+import { isEnvelope } from './envelope.js';
+import { CONTACT_TABLE } from '../slot/company-metadata.js';
+import { fallbackSpoken } from '../conversation/index.js';
 // ---------------------------------------------------------------------------------------------
 // Row names (15 §10.6.2)
 /**
- * `table#n` for each row a conversation has seen: the same row keeps its name on every page of the
- * conversation; names only grow and are never reused, so a late output naming a deleted row's name
- * cannot reach another row. Serialisable (`toJSON` / `fromJSON`) so a session can keep it.
+ * `table:` and the last 12 hex digits of the row's uuid (33): what the row is called in logs, the
+ * timeline and the database too, so the same in every conversation and every process; nothing to keep.
+ * A name comes from the id alone, never from which row came first: two rows of a table alike in those
+ * digits (one page of n rows: about n² / 2⁴⁹) are both named by their whole id from then on, and the
+ * short name they share resolves to neither. So a name from an earlier conversation, or another
+ * process, means the row it meant or no row (the AI is told), never another row. A name resolves only
+ * to a row named here, and the AI's names are checked against the page's own (`one-of`, `enum`) first.
  */
 export class RowNames {
-    byId = new Map();
-    byName = new Map();
-    counters = new Map();
+    /** The rows named here: id → table. */
+    tables = new Map();
+    /** A short name → the ids of its table ending in its digits. */
+    byShort = new Map();
     name(table, id) {
-        const known = this.byId.get(id);
-        if (known)
-            return known;
-        const n = (this.counters.get(table) ?? 0) + 1;
-        this.counters.set(table, n);
-        const name = `${table}#${n}`;
-        this.byId.set(id, name);
-        this.byName.set(name, { table, id });
-        return name;
+        this.tables.set(id, table);
+        const short = shortRowName(table, id);
+        let ids = this.byShort.get(short);
+        if (!ids)
+            this.byShort.set(short, (ids = new Set()));
+        ids.add(id);
+        return ids.size > 1 ? `${table}:${id}` : short;
     }
     resolve(name) {
-        return this.byName.get(name);
+        const at = name.indexOf(':');
+        if (at < 0)
+            return undefined;
+        const table = name.slice(0, at);
+        const rest = name.slice(at + 1);
+        if (this.tables.get(rest) === table)
+            return { table, id: rest };
+        const ids = this.byShort.get(name);
+        if (ids?.size !== 1)
+            return undefined;
+        const [id] = ids;
+        return { table, id: id };
     }
     nameOf(id) {
-        return this.byId.get(id);
-    }
-    toJSON() {
-        return [...this.byName.entries()].map(([name, { table, id }]) => [name, table, id]);
-    }
-    static fromJSON(entries) {
-        const names = new RowNames();
-        for (const [name, table, id] of entries) {
-            names.byId.set(id, name);
-            names.byName.set(name, { table, id });
-            const n = Number(name.slice(name.lastIndexOf('#') + 1));
-            if (n > (names.counters.get(table) ?? 0))
-                names.counters.set(table, n);
-        }
-        return names;
+        const table = this.tables.get(id);
+        if (table === undefined)
+            return undefined;
+        const short = shortRowName(table, id);
+        return this.byShort.get(short).size > 1 ? `${table}:${id}` : short;
     }
 }
+function shortRowName(table, id) {
+    return `${table}:${id.slice(-12)}`;
+}
 export class PageDocumentError extends Error {
     constructor(message) {
         super(message);
@@ -72,30 +82,23 @@ export class PageDocumentError extends Error {
 const MAX_DEPTH = 32;
 /** Channel actions only a call can do; by text only `end` (17b §9.8). */
 const CALL_ONLY = new Set(['transfer', 'keypad', 'announce', 'voicemail']);
+/** Tools only a call can use (76 §2.18). */
+const CALL_ONLY_TOOLS = new Set(['pressKeypad']);
 export function renderDocument(input) {
-    const perform = performOf(input.document);
-    if (perform?.action.$action === 'channel' && input.channel !== undefined && input.channel !== 'call' && CALL_ONLY.has(perform.action.channel)) {
-        throw new PageDocumentError(`the page function returned ${perform.action.channel}, which only a call can do (this is ${input.channel})`);
-    }
-    if (perform) {
-        // An action to run now: rendered as a button on a page of its own, so its rows are checked the same way.
-        const inner = renderDocument({ ...input, document: { action: perform.action } });
-        const action = inner.actions['action'];
-        if (!action)
-            throw new PageDocumentError(`the action the page function returned cannot run: ${inner.warnings.join('; ') || 'no row to run it on'}`);
-        return { ...inner, auto: { action, key: perform.key ?? actionKey(perform.action), wait: perform.wait ?? true } };
-    }
+    // Only what the page module marked (31 §8): an object shaped like a button is not one.
+    if (!isEnvelope(input.document))
+        throw new PageDocumentError('the page function returns page(…) or doNow(…) (76 §2.1)');
+    const envelope = input.document;
+    if ('do' in envelope)
+        return renderDo(input, envelope.do);
     const { schema, reads, names } = input;
-    if (!isPlainObject(input.document))
-        throw new PageDocumentError('the page script must return an object');
+    const envelopePage = envelope.page;
     const cells = {};
     const actions = {};
     const rows = {};
     const warnings = [];
-    /** Rows with a cell on the page, by table (page names). */
-    const cellRows = new Map();
     const pendingActions = [];
-    const extractions = pageExtractions(input.document, schema, warnings);
+    const extractions = pageExtractions(envelopePage.extraction, schema, warnings);
     const rowName = (table, id) => {
         const name = names.name(table, id);
         if (!rows[name]) {
@@ -105,7 +108,6 @@ export function renderDocument(input) {
         }
         return name;
     };
-    const rowsOnPage = (table) => [...(cellRows.get(table) ?? [])];
     const cellOf = (key, path, value) => {
         const refCell = isRefFieldCell(value) ? value : null;
         const fieldCell = isFieldCell(value) ? value : refCell ? { $field: true, slot: refCell.slot, ...(refCell.readOnly ? { readOnly: true } : {}) } : null;
@@ -116,33 +118,30 @@ export function renderDocument(input) {
         const read = reads.row(ref.id);
         const table = getCompiledTable(schema, ref.table);
         const def = table?.fields[ref.field];
+        // The row id and the parent never change and never are empty: nothing a field could show or open.
+        // Who the row belongs to is said in words, `text(…)` (31 §4).
+        const isParent = table ? parentOf(table)?.field === ref.field : false;
+        if (isParent || ref.field === ROW_ID_FIELD) {
+            throw new PageDocumentError(`${path}: ${ref.table}.${ref.field} is ${isParent ? 'the parent' : 'the row id'}: it never changes, so it is not a field on the page; say who the row belongs to with text(…), e.g. case: text("Zhang San's car accident case")`);
+        }
         if (!read || read.table !== ref.table || !def || !(ref.field in read.slots)) {
             warnings.push(`${path}: a slot this run did not read (${ref.table}.${ref.field}); shown as read-only text`);
             return { kind: 'text', key, path, value: displayable(slot.value) };
         }
         const truth = read.slots[ref.field];
         const name = rowName(ref.table, ref.id);
-        const onPage = cellRows.get(ref.table) ?? new Set();
-        onPage.add(name);
-        cellRows.set(ref.table, onPage);
         const slotId = `${name}.${ref.field}`;
-        const isParent = parentOf(table)?.field === ref.field;
-        const isLookup = Boolean(def.ref) && !isParent;
-        // A ref field is placed with refField: its candidates and their labels are the page's (26 §16.2 #7).
-        if (isLookup && fieldCell && !refCell)
-            throw new PageDocumentError(`${path}: ${ref.table}.${ref.field} is a ref field: place it with refField(slot, { options })`);
+        const isLookup = Boolean(def.ref);
+        // A ref field is placed with refField, read-only too: its candidates and their labels, or who its value
+        // is, are the page's (26 §16.2 #7); a bare row name says nothing (31 §4).
+        if (isLookup && !refCell)
+            throw new PageDocumentError(`${path}: ${ref.table}.${ref.field} is a ref field: place it with refField(slot, { options }) (read-only, refField(slot, { readOnly: true, label: '…' }))`);
         if (refCell && !isLookup)
-            throw new PageDocumentError(`${path}: refField(...) is for a ref field; ${ref.table}.${ref.field} is ${isParent ? 'the parent' : 'not a ref'}`);
+            throw new PageDocumentError(`${path}: refField(...) is for a ref field; ${ref.table}.${ref.field} is not a ref`);
         const offered = refCell ? refOptions(path, refCell, def.ref.table) : null;
-        // The page decides (19-page-writable-cells): a slot placed as is is read-only, `field(...)` opens
-        // it. Never the row id or the parent. A lookup opens where its table's rows are on the page
-        // (settled below): the AI cannot make up a row id.
-        const fixed = isParent || ref.field === ROW_ID_FIELD;
-        if (fieldCell && !fieldCell.readOnly && fixed) {
-            warnings.push(`${path}: field(...) cannot open ${ref.table}.${ref.field} (${isParent ? 'the parent' : 'the row id'}); it stays read-only`);
-        }
+        // The page decides (19-page-writable-cells): `field(slot, { readOnly: true })` is read-only, `field(slot)` opens it.
         // A ref field with no row to offer is shown, not opened: nothing to choose (data, not a page mistake).
-        const placeWritable = fieldCell !== null && !fieldCell.readOnly && !fixed && (!offered || offered.length > 0);
+        const placeWritable = fieldCell !== null && !fieldCell.readOnly && (!offered || offered.length > 0);
         const existing = cells[slotId];
         if (existing) {
             existing.writable ||= placeWritable;
@@ -170,6 +169,11 @@ export function renderDocument(input) {
             if (isLookup)
                 cell.type = 'ref';
             cells[slotId] = cell;
+            // The row a ref holds is named even when nothing else of it is on the page (33): the AI reads
+            // `case_contact:3f9a2c1d7e04`, never a bare id. Named only: it does not join `rows`, which is
+            // what the page's actions may write.
+            if (def.ref && truth.state === 'filled' && typeof truth.value === 'string')
+                cell.valueRow = names.name(def.ref.table, truth.value);
         }
         if (offered) {
             const target = cells[slotId];
@@ -191,59 +195,104 @@ export function renderDocument(input) {
             throw new PageDocumentError(`${path}: refField offers ${option.id}, not a ${target} row this run read`);
         return { name: rowName(target, option.id), label: option.label };
     });
-    const walk = (key, path, value, depth) => {
+    /**
+     * Data (31 §4): shown as it is, blocks, lists and text, whatever keys it has (`$action` too). Nothing in
+     * it is a field or a button: the page module marked those, and data cannot carry the mark.
+     */
+    const walkData = (key, path, value, depth) => {
         if (depth > MAX_DEPTH)
             throw new PageDocumentError(`${path || 'page'}: nested deeper than ${MAX_DEPTH}`);
-        if (value === undefined || typeof value === 'function')
-            return null;
-        if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        if (value === null || typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
             return { kind: 'text', key, path, value };
-        }
-        if (isAction(value)) {
-            pendingActions.push({ path, value });
-            return { kind: 'action', key, path, actionId: path };
-        }
-        const cell = cellOf(key, path, value);
-        if (cell)
-            return cell;
-        if (Array.isArray(value)) {
-            const children = value
-                .map((item, i) => walk(String(i), join(path, String(i)), item, depth + 1))
-                .filter((n) => n !== null);
-            return { kind: 'block', key, path, list: true, children };
-        }
+        if (Array.isArray(value))
+            return { kind: 'block', key, path, list: true, children: value.map((item, i) => walkData(String(i), join(path, String(i)), item, depth + 1)) };
         if (isPlainObject(value)) {
-            if (isRowLike(value)) {
-                warnings.push(`${path}: a whole row is not a cell; put its slots on the page`);
+            return { kind: 'block', key, path, list: false, children: Object.entries(value).map(([k, item]) => walkData(k, join(path, k), item, depth + 1)) };
+        }
+        return { kind: 'text', key, path, value: String(value) };
+    };
+    /** One node of the envelope (31 §8): what the page module marked as a block, a field, a button, or data. */
+    const walkEnvelope = (node, parent, place, depth) => {
+        if (depth > MAX_DEPTH)
+            throw new PageDocumentError(`${parent || 'page'}: nested deeper than ${MAX_DEPTH}`);
+        // Where it is, for messages: its name, or its place when it has none (46 §2.2).
+        const path = join(parent, node.key || `#${place}`);
+        switch (node.k) {
+            case 'block': {
+                const block = { kind: 'block', key: node.key, path, list: node.list, children: [] };
+                if (node.title !== undefined)
+                    block.title = node.title;
+                if (node.description !== undefined)
+                    block.description = node.description;
+                node.children.forEach((child, i) => {
+                    const out = walkEnvelope(child, path, i, depth + 1);
+                    if (out)
+                        block.children.push(out);
+                });
+                return block;
             }
-            const block = { kind: 'block', key, path, list: false, children: [] };
-            if (typeof value.$title === 'string')
-                block.title = value.$title;
-            if (typeof value.$description === 'string')
-                block.description = value.$description;
-            pageMarks(block, value, path, depth === 0, warnings);
-            for (const [childKey, child] of Object.entries(value)) {
-                if (childKey.startsWith('$'))
-                    continue;
-                // A button's id is the keys joined with '.': a key with a '.' in it would collide with a nested one (26 §16.2 #3).
-                if (childKey.includes('.'))
-                    throw new PageDocumentError(`${join(path, childKey) || 'page'}: a key on the page cannot contain '.' (${JSON.stringify(childKey)})`);
-                const node = walk(childKey, join(path, childKey), child, depth + 1);
-                if (node)
-                    block.children.push(node);
+            case 'field': {
+                const cell = cellOf(node.key, path, node.cell);
+                if (!cell)
+                    throw new PageDocumentError(`${path}: not a field`);
+                return cell;
+            }
+            case 'button': {
+                // Its id comes once every button is known (46 §2.1).
+                const action = { kind: 'action', key: '', path, actionId: '' };
+                pendingActions.push({ path, value: node.action, node: action });
+                return action;
+            }
+            case 'data':
+                return walkData(node.key, path, node.value, depth);
+            case 'toolbox': {
+                // The tools as buttons in their own block (76 §2.18): the AI presses one like any button.
+                const block = { kind: 'block', key: node.key, path, list: false, title: 'Tools', children: [] };
+                node.tools.forEach((tool, i) => {
+                    if (!PAGE_TOOLS.includes(tool))
+                        throw new PageDocumentError(`${path}: ${tool} is not a platform tool (${PAGE_TOOLS.join(', ')})`);
+                    const at = join(path, String(i));
+                    // A call tool on a text or an email page (76 §2.12): left off, said in the log.
+                    if (input.channel !== undefined && input.channel !== 'call' && CALL_ONLY_TOOLS.has(tool)) {
+                        warnings.push(`${at}: ${tool}() is a call tool, and this is ${input.channel}: left off the page (place it only on a call)`);
+                        return;
+                    }
+                    const action = { kind: 'action', key: '', path: at, actionId: '' };
+                    pendingActions.push({ path: action.path, value: { $action: 'tool', tool: tool }, node: action });
+                    block.children.push(action);
+                });
+                // Every tool left off (or none given): no toolbox on the page (76 §2.12).
+                return block.children.length ? block : null;
             }
-            return block;
         }
-        return { kind: 'text', key, path, value: String(value) };
     };
-    const root = walk('', '', input.document, 0);
+    const root = { kind: 'block', key: '', path: '', list: false, children: [] };
+    if (envelopePage.title !== undefined)
+        root.title = envelopePage.title;
+    if (envelopePage.description !== undefined)
+        root.description = envelopePage.description;
+    if (envelopePage.guide?.trim())
+        root.guide = envelopePage.guide;
+    envelopePage.children.forEach((child, i) => {
+        const out = walkEnvelope(child, '', i, 1);
+        if (out)
+            root.children.push(out);
+    });
+    const voice = envelopePage.voice;
     // Every row on the page is known now: what lookups and row parameters may choose.
-    const env = { schema, reads, rowName, rowsOnPage, warnings, ...(input.channel ? { channel: input.channel } : {}) };
-    for (const { path, value } of pendingActions) {
+    const env = { schema, reads, rowName, warnings, ...(input.channel ? { channel: input.channel } : {}), ...(input.functions ? { functions: input.functions } : {}), ...(input.actions ? { actions: input.actions } : {}) };
+    const placed = [];
+    for (const { path, value, node } of pendingActions) {
         const rendered = renderAction(path, value, env);
         if (rendered)
-            actions[path] = rendered;
+            placed.push({ action: rendered, node });
     }
+    const ids = buttonIds(placed.map((p) => p.action), rows);
+    placed.forEach(({ action, node }, i) => {
+        const id = ids[i];
+        node.actionId = id;
+        actions[id] = { ...action, id };
+    });
     // An action that cannot be pressed is not on the page.
     const prune = (block) => {
         block.children = block.children.filter((child) => child.kind !== 'action' || child.actionId in actions);
@@ -255,8 +304,27 @@ export function renderDocument(input) {
     const page = { root, cells, actions, rows, warnings };
     if (extractions.size)
         page.extractions = Object.fromEntries(extractions);
+    if (voice !== undefined)
+        page.voice = voice;
     return page;
 }
+/**
+ * `doNow()` (76): what the page does now, rendered as a button would be so its rows are checked the same
+ * way. Nobody fills what the page left out: a required parameter it did not prefill is an error (30 §7.2).
+ */
+function renderDo(input, run) {
+    if (run.action.$action === 'channel' && input.channel !== undefined && input.channel !== 'call' && CALL_ONLY.has(run.action.channel)) {
+        throw new PageDocumentError(`the page function returned ${run.action.channel}, which only a call can do (this is ${input.channel})`);
+    }
+    const inner = renderDocument({ ...input, document: { $envelope: 1, page: { children: [{ k: 'button', key: '', action: run.action }] } } });
+    const action = Object.values(inner.actions)[0];
+    if (!action)
+        throw new PageDocumentError(`the action the page function returned cannot run: ${inner.warnings.join('; ') || 'no row to run it on'}`);
+    const missing = action.input?.required ?? [];
+    if (missing.length)
+        throw new PageDocumentError(`doNow(): ${action.name} runs with nobody to fill ${missing.join(', ')}: prefill ${missing.length > 1 ? 'them' : 'it'}`);
+    return { ...inner, auto: { action, key: run.key ?? actionKey(run.action), wait: run.wait ?? true } };
+}
 /**
  * The action as the AI presses it, or null when it cannot be pressed on this page: with a warning when
  * the page placed it wrong; silently when a required row choice has no row on the page (no injury yet
@@ -290,30 +358,65 @@ function unfillable(properties, required, prefix = '') {
 function renderActionOf(path, action, env) {
     const { schema, reads, rowName, warnings } = env;
     if (action.$action === 'channel') {
-        // Not on this channel (a transfer by text): the types keep it to `ctx.call`, so reaching here is a bug.
+        // Not on this channel (a transfer by text, 76 §2.12): left off the page, said in the log; the page
+        // should check the channel itself.
         if (env.channel !== undefined && env.channel !== 'call' && CALL_ONLY.has(action.channel)) {
-            throw new PageDocumentError(`${path}: ${action.channel} is a call action, and this is ${env.channel} (use ctx.call only on the call page)`);
+            env.warnings.push(`${path}: ${action.channel} is a call action, and this is ${env.channel}: left off the page (place it only on a call)`);
+            return null;
         }
         return channelButton(path, action);
     }
+    if (action.$action === 'tool') {
+        if (env.channel !== undefined && env.channel !== 'call' && CALL_ONLY_TOOLS.has(action.tool)) {
+            env.warnings.push(`${path}: ${action.tool}() is a call tool, and this is ${env.channel}: left off the page (place it only on a call)`);
+            return null;
+        }
+        return toolButton(path, action.tool);
+    }
     if (action.$action === 'createRow') {
         const table = getCompiledTable(schema, action.table);
         if (!table)
             throw new PageDocumentError(`${path}: createRow on ${action.table}, not a table of this sequence`);
         const parent = parentOf(table);
-        for (const key of Object.keys(action.prefill)) {
+        const fieldParam = (field) => ({ $schemaField: `${action.table}.${field}` });
+        const properties = {};
+        // A ref field is chosen among the rows the page gives (`options`, 35 §2), or fixed (`prefill`).
+        const chosen = [];
+        for (const [key, value] of Object.entries(action.prefill)) {
             if (!getTableField(table, key))
                 throw new PageDocumentError(`${path}: createRow(${action.table}) prefills ${key}, not a field of it`);
+            if (isChoose(value)) {
+                if (parent?.field === key)
+                    throw new PageDocumentError(`${path}: the parent ${key} is where the row goes, not the AI's choice: prefill it`);
+                const offered = chooseParam(`${path}: options.${key}`, fieldParam(key), value, env);
+                if (emptyOptional(offered, key, action.required))
+                    continue;
+                properties[key] = offered;
+                chosen.push(key);
+            }
+            else if (parent?.field !== key) {
+                checkPrefill(`${path}: prefill.${key}`, fieldParam(key), value, env);
+            }
+        }
+        // A required field the page prefilled empty (null or '', as the write counts it): nobody fills it,
+        // and the write would fail (76 §2.14).
+        for (const key of action.required) {
+            const value = Object.hasOwn(action.prefill, key) ? action.prefill[key] : undefined;
+            if (value === null || value === '') {
+                throw new PageDocumentError(`${path}: createRow(${action.table}) ${key} is required: prefill a value, not ${value === null ? 'null' : "''"}, or leave it to the AI (fields)`);
+            }
         }
-        const properties = {};
         for (const fieldName of action.fields) {
-            if (!getTableField(table, fieldName))
+            const def = getTableField(table, fieldName);
+            if (!def)
                 throw new PageDocumentError(`${path}: createRow field ${action.table}.${fieldName} is not in this sequence`);
             if (parent?.field === fieldName)
                 throw new PageDocumentError(`${path}: the parent ${fieldName} is prefilled, not a field to fill`);
             if (fieldName in action.prefill)
                 continue;
-            properties[fieldName] = expandParam(path, { $schemaField: `${action.table}.${fieldName}` }, env);
+            if (def.ref)
+                throw new PageDocumentError(`${path}: ${action.table}.${fieldName} is a ref field: give the rows the AI chooses among, options: { ${fieldName}: choose(rows, label) }, or prefill it`);
+            properties[fieldName] = expandParam(path, fieldParam(fieldName), env);
         }
         // Where the new row hangs: prefilled, else the one parent this run's reads of the table were anchored on.
         let parentId = null;
@@ -334,9 +437,7 @@ function renderActionOf(path, action, env) {
             }
             rowName(parentRow.table, parentId);
         }
-        const set = { ...action.prefill };
-        if (parent)
-            delete set[parent.field];
+        const set = Object.fromEntries(Object.entries(action.prefill).filter(([key, value]) => !isChoose(value) && key !== parent?.field));
         const under = parent && parentId ? ` under ${rowName(parent.table, parentId)}` : '';
         return {
             id: path,
@@ -344,7 +445,7 @@ function renderActionOf(path, action, env) {
             name: action.label ?? `Add ${table.label}`,
             description: action.description ?? `Adds a new ${table.label} (${action.table})${under}.`,
             input: { type: 'object', properties, required: action.required.filter((r) => r in properties) },
-            server: { kind: 'createRow', table: action.table, parentId, set, fields: action.fields, required: action.required },
+            server: { kind: 'createRow', table: action.table, parentId, set, fields: [...action.fields, ...chosen], required: action.required, ...(action.key ? { key: action.key } : {}) },
         };
     }
     if (action.$action === 'deleteRow') {
@@ -360,40 +461,50 @@ function renderActionOf(path, action, env) {
             name: action.label ?? `Delete ${name}`,
             description: action.description ?? `Delete ${name} and everything under it.`,
             input: null,
-            server: { kind: 'deleteRow', table: read.table, rowId: action.rowId, ...(action.reason ? { reason: action.reason } : {}) },
+            server: { kind: 'deleteRow', table: read.table, rowId: action.rowId, ...(action.reason ? { reason: action.reason } : {}), ...(action.key ? { key: action.key } : {}) },
         };
     }
-    if (action.$action === 'message')
-        return messageButton(path, action, env);
     if (action.$action === 'followUp')
-        return followUpButton(path, action);
+        return followUpButton(path, action, env);
+    if (action.$action === 'cancelFollowUp')
+        return cancelFollowUpButton(path, action);
     if (action.$action === 'function') {
-        const { input, prefill } = actionInput(path, action.name, action.parameters, action.prefill ?? {}, env);
+        // The function's parameters are its definition's (31 §7); a page may still declare them on the button.
+        const parameters = action.parameters ?? env.functions?.[action.name]?.parameters;
+        const { input, prefill } = actionInput(path, action.name, parameters, action.prefill ?? {}, env, action.args);
         return {
             id: path,
             kind: 'function',
             name: action.label ?? action.name,
             description: action.description ?? `Runs ${action.name}.`,
             input,
-            server: { kind: 'function', name: action.name, ...(action.say ? { say: action.say } : {}), ...(Object.keys(prefill).length ? { prefill } : {}) },
+            server: { kind: 'function', name: action.name, ...(action.say ? { say: action.say } : {}), ...(Object.keys(prefill).length ? { prefill } : {}), ...(action.key ? { key: action.key } : {}) },
         };
     }
-    const { input, prefill } = actionInput(path, action.name, action.parameters, action.prefill, env);
+    // A page action's parameters are its `args` type's, as the build read it (38 §2.9).
+    const parameters = action.parameters ?? env.actions?.[action.name]?.parameters;
+    const { input, prefill } = actionInput(path, action.name, parameters, action.prefill, env, action.args);
     return {
         id: path,
         kind: 'custom',
-        name: action.name,
-        description: action.description,
+        name: action.label ?? action.name,
+        description: action.description ?? `Runs ${action.name}.`,
         input,
-        server: { kind: 'custom', name: action.name, prefill },
+        server: { kind: 'custom', name: action.name, prefill, ...(action.key ? { key: action.key } : {}) },
     };
 }
+/** An optional row with no row to choose: not asked (a required one leaves its button off, `renderAction`). */
+function emptyOptional(offered, key, required) {
+    return offered.type === 'ref' && offered.enum.length === 0 && !required.includes(key);
+}
 /**
- * What the AI fills of an action's parameters, and what the page fixed. A prefilled row is checked and
- * put on the page; a `choose(...)` (25 §10) becomes the AI's choice among exactly those rows, each shown
- * with its label.
+ * What the AI fills of an action's parameters, and what the page fixed (35 §2). A prefilled row is
+ * checked and put on the page; a row in `options` (`choose(...)`) becomes the AI's choice among exactly
+ * those rows, each shown with its label. A row parameter with neither is the page's mistake: the AI is
+ * never left to guess among unlabelled rows. A required row with no row to choose stays, and
+ * `renderAction` leaves the button off; an optional one is not asked.
  */
-function actionInput(path, name, parameters, given, env) {
+function actionInput(path, name, parameters, given, env, args = {}) {
     const declared = parameters?.properties ?? {};
     const properties = {};
     const prefill = {};
@@ -401,29 +512,55 @@ function actionInput(path, name, parameters, given, env) {
         if (!(key in declared))
             throw new PageDocumentError(`${path}: ${name} prefills ${key}, not one of its parameters`);
     }
+    // How to fill each one on this page is the page's (31 §7): the AI fills only what is not prefilled.
+    for (const [key, text] of Object.entries(args)) {
+        if (!(key in declared))
+            throw new PageDocumentError(`${path}: ${name} has no parameter ${key} to describe`);
+        if (key in given && !isChoose(given[key]))
+            throw new PageDocumentError(`${path}: ${name}'s ${key} is prefilled: the AI does not fill it, so it needs no description`);
+        if (typeof text !== 'string')
+            throw new PageDocumentError(`${path}: the description of ${key} must be text`);
+    }
+    const required = parameters?.required ?? [];
     for (const [key, param] of Object.entries(declared)) {
         const value = given[key];
         if (isChoose(value)) {
-            properties[key] = chooseParam(`${path}: ${name}({ ${key} })`, param, value, env);
+            const chosen = chooseParam(`${path}: ${name} options.${key}`, param, value, env);
+            if (!emptyOptional(chosen, key, required))
+                properties[key] = chosen;
             continue;
         }
         if (key in given) {
+            // Prefilled, nobody fills it: a required one must have a value (30 §7.2).
+            if ((value === null || value === undefined) && (parameters?.required ?? []).includes(key)) {
+                throw new PageDocumentError(`${path}: ${name} prefills its required ${key} with ${value === null ? 'null' : 'nothing'}: nobody fills it after the page`);
+            }
+            // An optional one fixed as none: not asked, and not passed (its parameter is `T | undefined`).
+            if (value === null || value === undefined)
+                continue;
             checkPrefill(`${path}: ${name}({ ${key} })`, param, value, env);
             prefill[key] = value;
             continue;
         }
+        if (isRefParam(param) || (isSchemaFieldParam(param) && rowTableOf(`${path}.${key}`, param, env.schema))) {
+            throw new PageDocumentError(`${path}: ${name}'s ${key} is a row: give the rows the AI chooses among, options: { ${key}: choose(rows, label) }, or prefill it`);
+        }
         properties[key] = expandParam(`${path}.${key}`, param, env);
     }
+    for (const [key, text] of Object.entries(args)) {
+        if (properties[key] && text.trim())
+            properties[key] = { ...properties[key], description: text };
+    }
     const input = Object.keys(properties).length
-        ? { type: 'object', properties, required: (parameters?.required ?? []).filter((r) => r in properties) }
+        ? { type: 'object', properties, required: required.filter((r) => r in properties) }
         : null;
     return { input, prefill };
 }
 /** A row parameter's candidates, as `choose(...)` gave them: rows this run read, of the parameter's table. */
 function chooseParam(where, param, chosen, env) {
-    const table = isSchemaFieldParam(param) ? rowTableOf(where, param, env.schema) : null;
+    const table = isRefParam(param) ? param.table : isSchemaFieldParam(param) ? rowTableOf(where, param, env.schema) : null;
     if (!table)
-        throw new PageDocumentError(`${where}: choose(...) is for a row parameter (schemaField('table.id') or a lookup)`);
+        throw new PageDocumentError(`${where}: choose(...) is for a row parameter (Id<'table'>)`);
     if (chosen.table !== null && chosen.table !== table)
         throw new PageDocumentError(`${where}: choose(...) gives ${chosen.table} rows, the parameter takes ${table}`);
     const names = [];
@@ -445,12 +582,12 @@ function schemaFieldOf(where, param, schema) {
     const [table, field, ...rest] = param.$schemaField.split('.');
     const def = table ? getCompiledTable(schema, table) : undefined;
     if (!table || !field || rest.length || !def)
-        throw new PageDocumentError(`${where}: schemaField('${param.$schemaField}') is not a table.field of this sequence`);
+        throw new PageDocumentError(`${where}: '${param.$schemaField}' is not a table.field of this sequence`);
     if (field === 'id')
         return { table, field, def: null };
     const fieldDef = getTableField(def, field);
     if (!fieldDef)
-        throw new PageDocumentError(`${where}: schemaField('${param.$schemaField}') is not a field of this sequence`);
+        throw new PageDocumentError(`${where}: '${param.$schemaField}' is not a field of this sequence`);
     return { table, field, def: fieldDef };
 }
 /** The table a parameter chooses a row of (`table.id`, a lookup), or null. */
@@ -462,17 +599,17 @@ function rowTableOf(where, param, schema) {
 }
 /** A parameter as JSON Schema for the AI: schema fields filled in from the schema, row choices as enums. */
 function expandParam(where, param, env) {
+    if (isRefParam(param))
+        throw new PageDocumentError(`${where}: a row inside a list or an object cannot be chosen: make it a parameter of its own, chosen with options`);
     if (isSchemaFieldParam(param)) {
         const rowTable = rowTableOf(where, param, env.schema);
         const { table, def } = schemaFieldOf(where, param, env.schema);
-        if (rowTable) {
-            const names = env.rowsOnPage(rowTable);
-            const help = param.extraction ?? def?.extraction;
-            return { type: 'ref', table: rowTable, enum: names, ...(help ? { description: help } : {}) };
-        }
+        // A row inside a list or an object: `options` cannot reach it (35 §2).
+        if (rowTable)
+            throw new PageDocumentError(`${where}: a row inside a list or an object cannot be chosen: make it a parameter of its own, chosen with options`);
         // The page's extraction replaces the schema's; type and allowed values stay the schema's.
         const fieldDef = param.extraction !== undefined ? { ...def, extraction: param.extraction } : def;
-        return fieldDef.dataType === 'contact_schedule' ? scheduleProperty(fieldDef) : scalarProperty(fieldDef);
+        return fieldDef.dataType === 'contact_schedule' ? scheduleProperty(fieldDef.extraction || undefined) : scalarProperty(fieldDef);
     }
     if (param.type === 'array') {
         const out = { type: 'array', items: expandParam(`${where}[]`, param.items, env) };
@@ -491,6 +628,8 @@ function expandParam(where, param, env) {
             out.description = param.description;
         return out;
     }
+    if (param.type === 'contact_schedule')
+        return scheduleProperty(param.description);
     return { ...param };
 }
 /**
@@ -500,6 +639,13 @@ function expandParam(where, param, env) {
 function checkPrefill(where, param, value, env) {
     if (value === null || value === undefined)
         return;
+    if (isRefParam(param)) {
+        const read = typeof value === 'string' ? env.reads.row(value) : undefined;
+        if (!read || read.table !== param.table)
+            throw new PageDocumentError(`${where} is not a ${param.table} row this run read`);
+        env.rowName(read.table, value);
+        return;
+    }
     if (isSchemaFieldParam(param)) {
         const rowTable = rowTableOf(where, param, env.schema);
         if (!rowTable)
@@ -519,6 +665,10 @@ function checkPrefill(where, param, value, env) {
     if (param.type === 'object') {
         if (!isPlainObject(value))
             throw new PageDocumentError(`${where} must be an object`);
+        // A prefilled object is the page's whole: the AI cannot fill a part of it (30 §7.2).
+        const missing = (param.required ?? []).filter((key) => value[key] === undefined || value[key] === null);
+        if (missing.length)
+            throw new PageDocumentError(`${where} is prefilled without ${missing.join(', ')}: a prefilled object needs every required part, nobody fills the rest`);
         for (const [key, child] of Object.entries(param.properties))
             checkPrefill(`${where}.${key}`, child, value[key], env);
     }
@@ -532,8 +682,8 @@ function scalarProperty(def) {
         return { type: 'select', enum: def.options ?? [], ...help };
     return { type: def.dataType, ...help };
 }
-/** A `contact_schedule` field: its own structure (`ContactSchedule`), not text. */
-function scheduleProperty(def) {
+/** A contact's hours (a `contact_schedule` field, a `ContactSchedule` argument): its own structure, not text. */
+function scheduleProperty(help) {
     const window = {
         type: 'object',
         properties: {
@@ -547,7 +697,7 @@ function scheduleProperty(def) {
     return {
         type: 'object',
         'x-type': 'contact_schedule',
-        ...describeField(def),
+        ...(help ? { description: help } : {}),
         properties: {
             weekly: {
                 type: 'object',
@@ -570,7 +720,7 @@ function scheduleProperty(def) {
     };
 }
 /**
- * An argument's help (26 §16.2 #5a): how to fill it, the page's (`schemaField(…, { extraction })`) or else
+ * An argument's help (26 §16.2 #5a): how to fill it, the page's (`page({ extraction })`) or else
  * the field's; none when neither says. The label is not repeated in it; how its type is written is the
  * system message's (26 §15.8).
  */
@@ -578,6 +728,94 @@ function describeField(def) {
     return def.extraction ? { description: def.extraction } : {};
 }
 // ---------------------------------------------------------------------------------------------
+/**
+ * The buttons' ids (46 §2.1), in page order: what each does (its run key's words: a function's name,
+ * `add:injury`, `remove`, `transfer`, …); where several on the page do the same, the rows that tell them
+ * apart, by page name (`voidInjury@injury:3f9a2c1d7e04`); where that still leaves two alike, `#2`, `#3`
+ * after the first. Unique on the page, and the same from one render to the next while the button does
+ * the same thing to the same rows.
+ */
+export function buttonIds(buttons, rows) {
+    const nameOf = new Map(Object.entries(rows).map(([name, row]) => [row.id, name]));
+    const bases = buttons.map(buttonBase);
+    const rowsOf = buttons.map((button) => boundRows(button, nameOf));
+    const ids = buttons.map((_, i) => {
+        const alike = bases.flatMap((base, j) => (base === bases[i] ? [j] : []));
+        if (alike.length === 1)
+            return bases[i];
+        // Only the rows that differ among them: the case or contact they all share says nothing.
+        const shared = rowsOf[alike[0]].filter((name) => alike.every((j) => rowsOf[j].includes(name)));
+        const own = rowsOf[i].filter((name) => !shared.includes(name));
+        return own.length ? `${bases[i]}@${own.join(',')}` : bases[i];
+    });
+    const seen = new Map();
+    return ids.map((id) => {
+        const n = (seen.get(id) ?? 0) + 1;
+        seen.set(id, n);
+        return n === 1 ? id : `${id}#${n}`;
+    });
+}
+/**
+ * The button the AI means by `id` on this page (46 §2.1), or null. Its own id first; else an id it read
+ * on an earlier page, where alike buttons needed their rows (`bookSlot@slot_option:d12f648904ec`) and now
+ * one is left (`bookSlot`): the one button doing that to those rows. Never a guess among several.
+ */
+export function pressedButton(page, id) {
+    if (id in page.actions)
+        return id;
+    const plain = id.replace(/#\d+$/, '');
+    const at = plain.lastIndexOf('@');
+    if (at < 0)
+        return null;
+    const base = plain.slice(0, at);
+    const rows = plain.slice(at + 1).split(',').filter(Boolean);
+    const nameOf = new Map(Object.entries(page.rows).map(([name, row]) => [row.id, name]));
+    const found = Object.values(page.actions).filter((button) => {
+        if (buttonBase(button) !== base)
+            return false;
+        const bound = boundRows(button, nameOf);
+        return rows.every((row) => bound.includes(row));
+    });
+    return found.length === 1 ? found[0].id : null;
+}
+/** What a button does, as its id says it (46 §2.1): its run key, in words the AI reads. */
+function buttonBase(button) {
+    const server = button.server;
+    if (server.kind === 'createRow')
+        return server.key ?? `add:${server.table}`;
+    if (server.kind === 'deleteRow')
+        return server.key ?? 'remove';
+    if (server.kind === 'channel' && server.spec.channel === 'keypad')
+        return `keypad:${server.spec.key}`;
+    return runKeyOf(button);
+}
+/** The page names of the rows a button works on: the row it removes, where it adds, the rows it is prefilled with. */
+function boundRows(button, nameOf) {
+    const server = button.server;
+    const values = [];
+    if (server.kind === 'deleteRow')
+        values.push(server.rowId);
+    if (server.kind === 'createRow')
+        values.push(server.parentId, ...Object.values(server.set));
+    if (server.kind === 'custom' || server.kind === 'function')
+        values.push(...Object.values(server.prefill ?? {}));
+    if (server.kind === 'followUp')
+        values.push(server.prefill.contactId);
+    const names = [];
+    const visit = (value) => {
+        if (typeof value === 'string') {
+            const name = nameOf.get(value);
+            if (name && !names.includes(name))
+                names.push(name);
+        }
+        else if (Array.isArray(value))
+            value.forEach(visit);
+        else if (isPlainObject(value))
+            Object.values(value).forEach(visit);
+    };
+    values.forEach(visit);
+    return names;
+}
 function join(path, key) {
     return path ? `${path}.${key}` : key;
 }
@@ -596,24 +834,6 @@ function isFieldCell(value) {
 function isRefFieldCell(value) {
     return isPlainObject(value) && value.$refField === true && Array.isArray(value.options);
 }
-function isAction(value) {
-    return (isPlainObject(value) &&
-        (value.$action === 'createRow' ||
-            value.$action === 'deleteRow' ||
-            value.$action === 'custom' ||
-            (value.$action === 'function' && typeof value.name === 'string') ||
-            (value.$action === 'message' && typeof value.key === 'string') ||
-            (value.$action === 'followUp' && Array.isArray(value.channels)) ||
-            (value.$action === 'channel' && typeof value.channel === 'string')));
-}
-/** The page function returned an action to run now (`perform(…)`, or the action itself). */
-function performOf(document) {
-    if (isPlainObject(document) && document.$perform === true && isAction(document.action))
-        return document;
-    if (isAction(document))
-        return { $perform: true, action: document };
-    return null;
-}
 /**
  * The run key of a button on the page (17b §7): the action's own key, whoever runs it — the model
  * pressing it, or the page function returning it — not its place on the page, which moves with rows.
@@ -621,90 +841,62 @@ function performOf(document) {
 export function runKeyOf(action) {
     const server = action.server;
     if (server.kind === 'custom')
-        return server.name;
+        return server.key ?? server.name;
     if (server.kind === 'createRow')
-        return `createRow:${server.table}`;
+        return server.key ?? `createRow:${server.table}`;
     if (server.kind === 'deleteRow')
-        return `deleteRow:${server.rowId}`;
+        return server.key ?? `deleteRow:${server.rowId}`;
     if (server.kind === 'function')
-        return server.name;
-    if (server.kind === 'message' || server.kind === 'followUp')
+        return server.key ?? server.name;
+    if (server.kind === 'followUp' || server.kind === 'cancelFollowUp')
         return server.key;
+    // A tool's run key is its name, fixed (76 §2.18): a page has one toolbox, each tool once.
+    if (server.kind === 'tool')
+        return server.tool;
     return actionKey(server.spec);
 }
 /** The run key of an action the page function returned, when it names none. */
 export function actionKey(action) {
     if (action.$action === 'custom')
-        return action.name;
+        return action.key ?? action.name;
     if (action.$action === 'function')
-        return action.name;
-    if (action.$action === 'message' || action.$action === 'followUp')
+        return action.key ?? action.name;
+    if (action.$action === 'followUp' || action.$action === 'cancelFollowUp')
         return action.key;
     if (action.$action === 'createRow')
-        return `createRow:${action.table}`;
+        return action.key ?? `createRow:${action.table}`;
     if (action.$action === 'deleteRow')
-        return `deleteRow:${action.rowId}`;
+        return action.key ?? `deleteRow:${action.rowId}`;
+    if (action.$action === 'tool')
+        return action.tool;
     if (action.channel === 'keypad' || action.channel === 'announce')
         return action.key;
-    return action.channel;
-}
-/** Marks removed with the todos (24 §2.3): a page still writing one is told what replaced it. */
-/** The marks a page object may carry: `$title`, `$description` on any block; `$guide`, `$extraction` on the root. */
-const KNOWN_MARKS = new Set(['$title', '$description', '$guide', '$extraction']);
-const REMOVED_MARKS = {
-    $say: 'write $guide on the page\'s root',
-    $done: 'show what is done as a result, or stop guiding to it',
-    $locked: 'leave out what the AI must not touch; say why in plain text',
-    $summary: 'nothing is folded any more',
-    $recommend: 'write $guide on the page\'s root',
-};
+    return action.key ?? action.channel;
+}
 /**
  * The page's `$extraction` (26 §15.3): how to fill a field on this page, by `table.field`, replacing the
  * schema's for every place it is on the page. One per field for the whole page, so a field means the
  * same everywhere on it. A `table.field` the schema does not have is warned and left out.
  */
-function pageExtractions(document, schema, warnings) {
+/** `page({ extraction })` (26 §15.3): how to fill a field on this page, by `table.field`. */
+function pageExtractions(value, schema, warnings) {
     const out = new Map();
-    const value = isPlainObject(document) ? document.$extraction : undefined;
     if (value === undefined || value === null)
         return out;
     if (!isPlainObject(value))
-        throw new PageDocumentError('page: $extraction must be an object of table.field → text');
+        throw new PageDocumentError('page({ extraction }): an object of table.field → text');
     for (const [key, text] of Object.entries(value)) {
         if (typeof text !== 'string')
-            throw new PageDocumentError(`page: $extraction['${key}'] must be text`);
+            throw new PageDocumentError(`page({ extraction }): '${key}' must be text`);
         const [table, field, ...rest] = key.split('.');
         if (!table || !field || rest.length || !getCompiledTable(schema, table)?.fields[field]) {
-            warnings.push(`page: $extraction['${key}'] is not a table.field of the schema; left out`);
+            warnings.push(`page({ extraction }): '${key}' is not a table.field of the schema; left out`);
             continue;
         }
         out.set(key, text);
     }
     return out;
 }
-/** `$guide` and `$extraction` on the root (24 §2.1, 26 §15.3); on any other block they are refused, as the removed marks are. */
-function pageMarks(block, value, path, isRoot, warnings) {
-    const where = path || 'page';
-    for (const [mark, instead] of Object.entries(REMOVED_MARKS)) {
-        if (value[mark] !== undefined)
-            throw new PageDocumentError(`${where}: ${mark} was removed (24 §2.3): ${instead}`);
-    }
-    // A misspelt mark (`$titel`) would otherwise do nothing, silently (26 §16.2 #4).
-    for (const mark of Object.keys(value)) {
-        if (mark.startsWith('$') && !KNOWN_MARKS.has(mark))
-            warnings.push(`${where}: ${mark} is not a page mark (${[...KNOWN_MARKS].join(', ')}); ignored`);
-    }
-    if (!isRoot && value.$extraction !== undefined)
-        throw new PageDocumentError(`${where}: $extraction is the page's: write it on the page's root, one per page (26 §15.3)`);
-    if (value.$guide === undefined || value.$guide === null)
-        return;
-    if (typeof value.$guide !== 'string')
-        throw new PageDocumentError(`${where}: $guide must be text`);
-    if (!isRoot)
-        throw new PageDocumentError(`${where}: $guide is the page's: write it on the page's root, one per page (24 §2.1)`);
-    if (value.$guide.trim())
-        block.guide = value.$guide;
-}
 const CHANNEL_NAMES = {
     transfer: ['Transfer to a person', 'Hand the call to a person. Press it only when the customer wants a person or the page says so.'],
     keypad: ['Collect a keypress', 'The customer answers by pressing a key on their phone.'],
@@ -716,6 +908,32 @@ const BACKGROUND_TRANSFER = [
     'Call a person in the background',
     'Calls a person while you keep helping the customer; the customer is put through once the person takes the call. Press it only when the customer wants a person or the page says so.',
 ];
+/** What the AI sees of each tool (76 §2.18). */
+const TOOL_BUTTONS = {
+    pressKeypad: {
+        name: 'Press keys on their phone menu',
+        description: "Press keys on the other side's automated phone menu, e.g. 'Press 1 for prescriptions'. Give the keys as one string: digits 0–9, * and #; w waits half a second (\"1w2\"). Only for an automated menu, never to talk to a person.",
+        input: { type: 'object', properties: { keys: { type: 'string', description: 'The keys to press, in order: 0–9, *, #, w (wait half a second)' } }, required: ['keys'] },
+    },
+    convertTime: {
+        name: 'Convert a time',
+        description: 'Convert between a local time in a time zone and an instant in UTC. Give local and time_zone to get the instant in UTC; give at and time_zone to get the weekday, date and time there.',
+        input: {
+            type: 'object',
+            properties: {
+                time_zone: { type: 'string', description: 'IANA time zone, e.g. America/Chicago' },
+                local: { type: 'string', description: 'A local date and time there, YYYY-MM-DDTHH:mm' },
+                at: { type: 'datetime', description: 'An instant, UTC (…Z)' },
+            },
+            required: ['time_zone'],
+        },
+    },
+};
+/** A platform tool as a button (76 §2.18): the platform runs it with what the AI gave. */
+function toolButton(path, tool) {
+    const { name, description, input } = TOOL_BUTTONS[tool];
+    return { id: path, kind: 'tool', name, description, input: structuredClone(input), server: { kind: 'tool', tool } };
+}
 /** A channel action as a button: nothing for the AI to fill; what it does stays on the server. */
 function channelButton(path, action) {
     const [name, description] = action.channel === 'transfer' && action.mode === 'background' ? BACKGROUND_TRANSFER : CHANNEL_NAMES[action.channel];
@@ -725,79 +943,81 @@ function channelButton(path, action) {
         id: path,
         kind: 'channel',
         name: label ?? name,
-        description: text ?? (action.channel === 'keypad' ? `${description} It says: "${action.say}"` : description),
+        description: text ?? (action.channel === 'keypad' ? `${description} It says: "${fallbackSpoken(action.say).text}"` : description),
         input: null,
         server: { kind: 'channel', spec: action },
     };
 }
+const CHANNEL_WORDS = { call: 'a call', sms: 'a text', email: 'an email' };
 /**
- * A text or an email as a button (25 §8): the contact it goes to must be a contact row this run read (it
- * goes on the page); what the page left out (`body`, an email's `subject`) the AI fills.
+ * The next-step button (40 §2.2): the AI gives when, the channel, why, and the customer's own words when
+ * they asked for it (an agreed follow-up, 09). Whom: the conversation's contact, unless the page fixed one
+ * (`prefill.contactId`) or gave the contacts the AI chooses among (`choose(...)`). Independent
+ * appointments coexist; an optional explicit target edits one (51).
  */
-function messageButton(path, action, env) {
-    if (action.to !== undefined) {
-        const read = env.reads.row(action.to);
-        if (!read || read.table !== 'contact') {
-            env.warnings.push(`${path}: ${action.key} goes to ${action.to}, not a contact this run read; left off the page`);
-            return null;
-        }
-        env.rowName('contact', action.to);
-    }
-    const what = action.channel === 'sms' ? 'text' : 'email';
+function followUpButton(path, action, env) {
+    const given = action.prefill ?? {};
+    // One channel offered, or the page fixed it: nothing for the AI to choose.
+    const channel = given.channel ?? (action.channels.length === 1 ? action.channels[0] : undefined);
+    const ways = (channel ? [channel] : action.channels).map((c) => CHANNEL_WORDS[c]).join(' or ');
     const properties = {};
-    if (action.channel === 'email' && action.subject === undefined)
-        properties.subject = { type: 'string', description: 'The email\'s subject line' };
-    if (action.body === undefined)
-        properties.body = { type: 'string', description: `The ${what} to send, in full, in the customer's language` };
-    const to = action.to !== undefined ? env.rowName('contact', action.to) : 'the customer';
-    const server = { kind: 'message', channel: action.channel, key: action.key, to: action.to ?? null };
-    if (action.body !== undefined)
-        server.body = action.body;
-    if (action.subject !== undefined)
-        server.subject = action.subject;
-    if (action.say !== undefined)
-        server.say = action.say;
+    if (!channel)
+        properties.channel = { type: 'select', enum: [...action.channels], description: 'How to reach them' };
+    properties.scheduled_action = { type: 'string', description: 'To edit one existing appointment, its step-… ID shown below; leave out to ADD an independent appointment' };
+    properties.name = { type: 'string', description: 'Optional business label, only when the page gives a naming convention; do not invent one for deduplication' };
+    // Every time the AI writes is UTC (76 §2.19): it asks the customer's time and time zone and converts.
+    properties.at = {
+        type: 'datetime',
+        description: 'When, in UTC (ending in Z): ask them the time and their time zone (unless the page says it), then convert; for a time the customer said vaguely ("tomorrow afternoon") a time inside it',
+    };
+    properties.reason = { type: 'string', description: 'Why, in a few words: what the contact is for' };
+    properties.customer_quote = { type: 'string', description: 'When the customer asked for it or agreed to it: their own words, as said; leave out otherwise' };
+    const prefill = channel ? { channel } : {};
+    const contact = given.contactId;
+    if (typeof contact === 'string') {
+        checkPrefill(`${path}: prefill.contactId`, { type: 'ref', table: CONTACT_TABLE }, contact, env);
+        prefill.contactId = contact;
+    }
+    else if (contact) {
+        const offered = chooseParam(`${path}: options.contactId`, { type: 'ref', table: CONTACT_TABLE }, contact, env);
+        // The choice adds people besides the conversation's contact (always the default): none to add, and
+        // the button books for that contact, as when the AI leaves the choice out.
+        if (offered.type === 'ref' && offered.enum.length)
+            properties.contact = { ...offered, description: 'Whom to contact; leave out for the person in this conversation' };
+    }
     return {
         id: path,
-        kind: 'message',
-        name: action.label ?? (action.channel === 'sms' ? 'Send a text' : 'Send an email'),
+        kind: 'followUp',
+        name: action.label ?? 'Book the next step',
         description: action.description ??
-            (action.body !== undefined
-                ? `Sends the fixed ${what} "${action.label ?? action.key}" to ${to} now.`
-                : `Sends a ${what} you write to ${to} now.`),
-        input: Object.keys(properties).length ? { type: 'object', properties, required: Object.keys(properties) } : null,
-        server,
+            [
+                `Books the case's next step: ${ways} at a set time, and why.`,
+                "Press it when the customer asks to be contacted at a time or agrees to one you offered (give their words), or when the case needs a contact at a set time; tell them it is booked only once it is.",
+                "Independent appointments can coexist, even for the same person and channel. Adding does not replace any appointment.",
+                "To change one appointment, give its scheduled_action ID from the list below. Only that appointment changes; leave contact out to keep its contact.",
+            ].join(' '),
+        input: { type: 'object', properties, required: [...(channel ? [] : ['channel']), 'at', 'reason'] },
+        server: { kind: 'followUp', key: action.key, channels: [...action.channels], prefill },
     };
 }
-const CHANNEL_WORDS = { call: 'a call', sms: 'a text', email: 'an email' };
-/** The follow-up button (25 §5): the AI gives the channel, the time and the customer's own words. */
-function followUpButton(path, action) {
-    const ways = action.channels.map((c) => CHANNEL_WORDS[c]).join(' or ');
+/** The cancel-next-step button (40 §2.2): the AI says why. */
+function cancelFollowUpButton(path, action) {
     return {
         id: path,
-        kind: 'followUp',
-        name: action.label ?? 'Book the follow-up they asked for',
+        kind: 'cancelFollowUp',
+        name: action.label ?? 'Cancel the next step',
         description: action.description ??
-            `The customer asked for ${ways} later, or agreed to one, at a time they said: press it then, and tell them it is booked. Not for a follow-up they did not ask for.`,
-        input: {
-            type: 'object',
-            properties: {
-                channel: { type: 'select', enum: [...action.channels], description: 'How they want to be reached' },
-                at: { type: 'datetime', description: 'When, as they said it, with the offset of their time zone; for a vague time ("tomorrow afternoon") a time inside it' },
-                customer_quote: { type: 'string', description: 'Their own words asking for it or agreeing to it, as said' },
-                note: { type: 'string', description: 'What it is for, in a few words' },
-            },
-            required: ['channel', 'at', 'customer_quote'],
-        },
-        server: { kind: 'followUp', key: action.key, channels: [...action.channels] },
+            "Cancels ONE appointment by its scheduled_action ID from the list below, with a reason. Other appointments stay. Talking to someone does not automatically complete their appointments; cancel only what is no longer needed.",
+        input: { type: 'object', properties: { scheduled_action: { type: 'string', description: 'The step-… ID of the appointment to cancel' }, reason: { type: 'string', description: 'Why it is no longer needed' } }, required: ['scheduled_action', 'reason'] },
+        server: { kind: 'cancelFollowUp', key: action.key },
     };
 }
+function isRefParam(param) {
+    return !isSchemaFieldParam(param) && param.type === 'ref';
+}
 function isSchemaFieldParam(value) {
     return isPlainObject(value) && typeof value.$schemaField === 'string';
 }
-function isRowLike(value) {
-    return typeof value.id === 'string' && Object.values(value).some(isSlotLike);
-}
 function displayable(value) {
     if (value === null || value === undefined)
         return null;