@superpanel-sdk/runtime 0.5.0 → 0.7.0

package/dist/core/page/define.js

@@ -3,11 +3,13 @@
  * inside the QuickJS sandbox, bundled into the page script, so it imports nothing at runtime and only
  * uses `globalThis.__host` (the sandbox's async host call, services `page/sandbox.ts`).
  *
- * A page script reads with `db` and returns a free-form document: objects are blocks, arrays are
- * lists, a slot is a cell, `field(slot, …)` a cell with page settings, other plain values read-only
- * content, and actions (`createRow`, `deleteRow`, `defineAction`) buttons. The platform turns the
- * document into a `RenderedPage` (`render.ts`).
+ * A page script reads with `db` and returns a page written with functions (76): `page(…)`, or
+ * `doNow(…)` to do something first. The page functions (`fns.ts`) are built from what is here (a
+ * field's cell, a button's action) and cross the sandbox as an envelope; the platform turns it into a
+ * `RenderedPage` (`render.ts`).
  */
+import { checkSpoken } from '../conversation/index.js';
+import { toFnPageResult } from './fns.js';
 function runsOf(runs, key, scope) {
     return (scope === 'case' ? runs?.caseActions : runs?.actions)?.[key];
 }
@@ -19,21 +21,44 @@ export function tried(runs, key, scope = 'run') {
 export function lastActionRun(runs, key, scope = 'run') {
     return runsOf(runs, key, scope)?.at(-1) ?? null;
 }
-function agree(options) {
+/** The next-step button (`scheduleFollowUp({ channels })`, 76). */
+export function followUpAction(options) {
     const channels = [...new Set(options?.channels ?? [])];
     if (!channels.length || channels.some((c) => c !== 'call' && c !== 'sms' && c !== 'email')) {
-        throw new Error("followUps.agree({ channels }): name at least one of 'call', 'sms', 'email'");
+        throw new Error("scheduleFollowUp(): name at least one of 'call', 'sms', 'email'");
     }
     const action = { $action: 'followUp', key: options.key ?? 'followUp', channels };
+    const prefill = options.prefill ?? {};
+    const unknown = Object.keys(prefill).filter((key) => key !== 'channel' && key !== 'contactId' && prefill[key] !== undefined);
+    if (unknown.length)
+        throw new Error(`scheduleFollowUp(): the page fixes only channel and contactId, not ${unknown.join(', ')}`);
+    const fixed = {};
+    if (prefill.channel !== undefined) {
+        if (!channels.includes(prefill.channel))
+            throw new Error(`scheduleFollowUp(): prefill.channel ${JSON.stringify(prefill.channel)} is not one of ${channels.join(', ')}`);
+        fixed.channel = prefill.channel;
+    }
+    if (prefill.contactId !== undefined) {
+        if (typeof prefill.contactId !== 'string' && !isChoose(prefill.contactId))
+            throw new Error('scheduleFollowUp(): contactId is a contact row\'s id, or choose(contacts, label) in options');
+        fixed.contactId = prefill.contactId;
+    }
+    if (Object.keys(fixed).length)
+        action.prefill = fixed;
     if (options.label !== undefined)
         action.label = options.label;
     if (options.description !== undefined)
         action.description = options.description;
     return action;
 }
-/** The agreed follow-ups with the button that books one. */
-export function pageFollowUps(list) {
-    return Object.assign([...list], { agree });
+/** The cancel-next-step button (`cancelFollowUp()`, 76). */
+export function cancelFollowUpAction(options = {}) {
+    const action = { $action: 'cancelFollowUp', key: options.key ?? 'cancelFollowUp' };
+    if (options.label !== undefined)
+        action.label = options.label;
+    if (options.description !== undefined)
+        action.description = options.description;
+    return action;
 }
 /** At most this many FAQ entries in a conversation (24 §7.2): the catalog is in every prompt. */
 export const MAX_FAQ_ENTRIES = 100;
@@ -57,29 +82,11 @@ export function choose(rows, label) {
 export function isChoose(value) {
     return typeof value === 'object' && value !== null && value.$choose === true && Array.isArray(value.options);
 }
-function message(channel, key, options) {
-    if (!key || typeof key !== 'string')
-        throw new Error(`messages.${channel === 'sms' ? 'text' : 'email'}(): name it with a key`);
-    const action = { $action: 'message', channel, key };
-    if (options.to !== undefined) {
-        const to = typeof options.to === 'string' ? options.to : isRow(options.to) ? options.to.id : null;
-        if (!to)
-            throw new Error(`messages: ${key}: \`to\` must be a contact row read from db, or its id`);
-        action.to = to;
-    }
-    for (const name of ['body', 'subject', 'say', 'label', 'description']) {
-        const value = options[name];
-        if (value !== undefined)
-            action[name] = value;
-    }
-    return action;
-}
-export const messages = {
-    text: (key, options = {}) => message('sms', key, options),
-    email: (key, options = {}) => message('email', key, options),
-};
+export const PAGE_TOOLS = ['pressKeypad', 'convertTime'];
 export function transferTo(options) {
     const mode = options.mode ?? 'cold';
+    if (options.whisper !== undefined && mode === 'cold')
+        throw new Error('transferTo: whisper is for a transfer the person confirms (warm or background); a cold one has no confirmation');
     if (options.bridge !== undefined && mode !== 'background')
         throw new Error(`transferTo: bridge is for a background transfer (mode '${mode}')`);
     const action = { $action: 'channel', channel: 'transfer', to: options.to, mode };
@@ -91,8 +98,16 @@ export function transferTo(options) {
         action.callerId = options.callerId;
     if (options.briefing !== undefined)
         action.briefing = options.briefing;
-    if (options.bridge !== undefined)
+    if (options.whisper !== undefined)
+        action.whisper = options.whisper;
+    if (options.bridge !== undefined) {
         action.bridge = { ...options.bridge };
+        if (options.bridge.customer !== undefined)
+            action.bridge.customer = checkSpoken(options.bridge.customer, 'transferTo: bridge.customer');
+    }
+    // Checked and made canonical where the transfer runs (the page sandbox has no Intl).
+    if (options.language !== undefined)
+        action.language = options.language.trim();
     if (options.label !== undefined)
         action.label = options.label;
     if (options.description !== undefined)
@@ -103,10 +118,10 @@ export function transferTo(options) {
 export function isSipUri(to) {
     return /^sips?:/i.test(to.trim());
 }
-export function keypad(key, options) {
+export function keypadAction(key, options) {
     if (!options.digits.length)
         throw new Error(`keypad('${key}'): digits must name at least one key`);
-    const action = { $action: 'channel', channel: 'keypad', key, say: options.say, digits: [...options.digits], timeoutMs: options.timeoutMs ?? 8000 };
+    const action = { $action: 'channel', channel: 'keypad', key, say: checkSpoken(options.say, `keypad('${key}'): say`), digits: [...options.digits], timeoutMs: options.timeoutMs ?? 8000 };
     if (options.write !== undefined)
         action.write = isSlot(options.write) ? { ...options.write.ref } : { ...options.write };
     if (options.map !== undefined)
@@ -127,7 +142,7 @@ export function runFunction(name, options = {}) {
     if (options.description !== undefined)
         action.description = options.description;
     if (options.say !== undefined)
-        action.say = options.say;
+        action.say = checkSpoken(options.say, `runFunction('${name}'): say`);
     if (options.parameters !== undefined)
         action.parameters = options.parameters;
     if (options.prefill !== undefined) {
@@ -139,20 +154,18 @@ export function runFunction(name, options = {}) {
     }
     return action;
 }
-export function announce(key, text) {
-    return { $action: 'channel', channel: 'announce', key, text };
+export function announceAction(key, text, options = {}) {
+    return { $action: 'channel', channel: 'announce', key, text: checkSpoken(text, `announce('${key}'): text`), ...(options.answers ? { answers: true } : {}) };
 }
-export function voicemail(text, options = {}) {
-    if (typeof text !== 'string' || !text.trim())
-        throw new Error('voicemail(text): the message to leave');
-    const action = { $action: 'channel', channel: 'voicemail', text };
+export function voicemailAction(text, options = {}) {
+    const action = { $action: 'channel', channel: 'voicemail', text: checkSpoken(text, 'voicemail(text): the message to leave') };
     if (options.label !== undefined)
         action.label = options.label;
     if (options.description !== undefined)
         action.description = options.description;
     return action;
 }
-export function end(options = {}) {
+export function endAction(options = {}) {
     const action = { $action: 'channel', channel: 'end' };
     if (options.label !== undefined)
         action.label = options.label;
@@ -160,17 +173,6 @@ export function end(options = {}) {
         action.description = options.description;
     return action;
 }
-export function perform(action, options = {}) {
-    const plain = typeof action.toJSON === 'function' && !('$action' in action) ? action.toJSON() : action;
-    if (plain.$action === 'channel' && options.wait === false)
-        throw new Error('perform(): a channel action cannot run in the background');
-    const out = { $perform: true, action: plain };
-    if (options.key !== undefined)
-        out.key = options.key;
-    if (options.wait !== undefined)
-        out.wait = options.wait;
-    return out;
-}
 // ---------------------------------------------------------------------------------------------
 function isSlot(value) {
     return (typeof value === 'object' &&
@@ -250,7 +252,7 @@ export function checkPageStart(raw) {
  * (`options: [{ id, label }]`, or `choose(rows, label)`); read-only, `options` only labels the current
  * value. Its definition is always on the page. `field()` refuses a ref field.
  */
-export function refField(slot, options = {}) {
+export function refFieldCell(slot, options = {}) {
     if (!isSlot(slot))
         throw new Error('refField(): the first argument must be a slot read from db');
     const given = options.options ?? [];
@@ -270,7 +272,7 @@ export function refField(slot, options = {}) {
         cell.readOnly = options.readOnly;
     return cell;
 }
-export function field(slot, options = {}) {
+export function fieldCell(slot, options = {}) {
     if (!isSlot(slot))
         throw new Error('field(): the first argument must be a slot read from db');
     if (options.hint !== undefined || options.extraction !== undefined) {
@@ -285,23 +287,12 @@ export function field(slot, options = {}) {
         cell.expand = options.expand;
     return cell;
 }
-/** A parameter taken from the schema: `schemaField('providers.name')`, `schemaField('injuries.id')` (a row). */
-export function schemaField(path, options = {}) {
-    if (options.description !== undefined)
-        throw new Error(`schemaField('${path}'): \`description\` was renamed \`extraction\``);
-    const param = { $schemaField: path };
-    if (options.extraction !== undefined)
-        param.extraction = options.extraction;
-    return param;
-}
 function placeable(make) {
-    const place = ((prefill) => make(toPrefill((prefill ?? {}))));
-    place.toJSON = () => make({});
-    return place;
+    return (prefill) => make(toPrefill((prefill ?? {})));
 }
 const CREATE_ROW_OPTIONS = new Set(['fields', 'required', 'label', 'description']);
 /** Add a row (15 §10.6): `fields` are what the AI fills; call it to preset the rest (`({ status: 'active' })`). */
-export function createRow(table, options) {
+export function createRowAction(table, options) {
     const tableName = typeof table === 'string' ? table : table.$table;
     // An option it does not know (a `prefill` here, say) would otherwise be dropped: preset values are
     // given by calling it, `createRow(…)({ parent: row.id })` (26 §16.2 #5d).
@@ -325,7 +316,7 @@ export function createRow(table, options) {
     });
 }
 /** Delete a row (cascading, 15 §10.6.1): a built-in action with the row prefilled and nothing to fill. */
-export function deleteRow(row, options = {}) {
+export function deleteRowAction(row, options = {}) {
     const rowId = typeof row === 'string' ? row : isRow(row) ? row.id : null;
     if (!rowId)
         throw new Error('deleteRow(): the first argument must be a row read from db, or its id');
@@ -338,25 +329,6 @@ export function deleteRow(row, options = {}) {
         action.description = options.description;
     return action;
 }
-const ACTIONS = new Map();
-/**
- * A custom action, declared like an LLM function call: `parameters` are everything `run` takes. Where
- * the page places it, some parameters may be prefilled; the AI fills the rest.
- */
-export function defineAction(definition) {
-    if (ACTIONS.has(definition.name))
-        throw new Error(`defineAction(): two actions are named ${definition.name}`);
-    ACTIONS.set(definition.name, { run: definition.run });
-    const parameters = definition.parameters ?? { type: 'object', properties: {} };
-    const place = placeable((prefill) => {
-        for (const key of Object.keys(prefill)) {
-            if (!(key in parameters.properties))
-                throw new Error(`${definition.name}: ${key} is not one of its parameters`);
-        }
-        return { $action: 'custom', name: definition.name, description: definition.description, parameters, prefill };
-    });
-    return Object.assign(place, { actionName: definition.name, run: definition.run });
-}
 /** Prefilled values as given (ids and plain JSON, as `parameters` types them), without the unset ones. */
 function toPrefill(prefill) {
     const out = {};
@@ -401,6 +373,14 @@ function timeOf(at) {
         today: at.today,
         format: (when, options = {}) => call('time', [when, { timeZone: options.timeZone ?? at.zone, ...(options.style ? { style: options.style } : {}) }]),
         day: (when, timeZone) => call('day', [when, timeZone ?? at.zone]),
+        at: (date, time, timeZone) => call('at', [date, time, timeZone ?? at.zone]),
+        parts: (when, timeZone) => call('parts', [when, timeZone ?? at.zone]),
+    };
+}
+/** `ctx.env` (76 §2.19): read only, the environment's configuration as the platform loaded it for this run. */
+function envOf(values) {
+    return {
+        get: (key) => (Object.hasOwn(values, key) && values[key] !== undefined ? values[key] : null),
     };
 }
 /** `history` inside the sandbox: each count is a `history` host call. */
@@ -416,14 +396,71 @@ function historyProxy() {
 export function emptyRuns() {
     return { actions: {}, caseActions: {} };
 }
-/** What the compiled page script evaluates to: renders the page, or runs one of its actions. */
-export function pageEntry(mod) {
+const ACTION_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * The page actions of `actions.ts` (76 §2.11), by name: its `actions` export, a plain object of
+ * `(ctx, args)` functions. No module, no actions. Read as its own keys only: `toString` is no action.
+ */
+function pageActionsOf(actionsModule) {
+    const out = new Map();
+    if (!actionsModule)
+        return out;
+    const actions = Object.hasOwn(actionsModule, 'actions') ? actionsModule.actions : undefined;
+    if (typeof actions !== 'object' || actions === null || Array.isArray(actions)) {
+        throw new Error('actions.ts must export const actions = { name: async (ctx: ActionCtx, args) => … } (76 §2.11)');
+    }
+    for (const name of Object.keys(actions)) {
+        const fn = actions[name];
+        if (name === '__proto__')
+            throw new Error("actions.ts: actions.__proto__: pick another name (JavaScript keeps it for an object's prototype)");
+        if (!ACTION_NAME.test(name))
+            throw new Error(`actions.ts: actions['${name}']: an action's name is an identifier (letters, digits, _): it is the run key`);
+        if (typeof fn !== 'function')
+            throw new Error(`actions.ts: actions.${name} is not a function: an action is async (ctx: ActionCtx, args) => …`);
+        out.set(name, fn);
+    }
+    return out;
+}
+/**
+ * The page actions a rendered page runs that `actions.ts` does not have (a stale or misspelled `act.x`):
+ * read where actions are, its buttons and its `doNow()`, never inside `data()` (data stays data, 31 §8).
+ */
+function unknownActions(envelope, actions) {
+    const missing = new Set();
+    const check = (action) => {
+        if (action.$action === 'custom' && !actions.has(action.name))
+            missing.add(action.name);
+    };
+    const visit = (nodes) => {
+        for (const node of nodes) {
+            if (node.k === 'button')
+                check(node.action);
+            else if (node.k === 'block')
+                visit(node.children);
+        }
+    };
+    if ('do' in envelope)
+        check(envelope.do.action);
+    else
+        visit(envelope.page.children);
+    return [...missing];
+}
+/**
+ * What the compiled page script evaluates to: renders the page, or runs one of its actions. `actionsModule`
+ * is the sequence's `actions.ts` (76 §2.11), null without one.
+ */
+export function pageEntry(mod, actionsModule = null) {
     const exported = (mod.default ?? mod.page);
+    if (Object.hasOwn(mod, 'actions')) {
+        throw new Error('context.page.ts exports actions: page actions go in actions.ts (export const actions = { … }), run with run(act.name, …) (76 §2.11)');
+    }
+    const actions = pageActionsOf(actionsModule);
     return (arg) => {
         if (arg.mode === 'channels') {
             if (exported?.kind !== 'page')
                 throw new Error('context.page.ts must default-export definePage({ persona, faq, call, sms, email })');
-            return { channels: Object.keys(exported.channels ?? {}) };
+            // The page actions: the build checks it read each one's parameters.
+            return { channels: Object.keys(exported.channels ?? {}), actions: [...actions.keys()] };
         }
         if (arg.mode === 'render' || arg.mode === 'start') {
             const channels = exported?.kind === 'page' ? (exported.channels ?? {}) : null;
@@ -434,7 +471,7 @@ export function pageEntry(mod) {
             if (!channel || typeof main !== 'function')
                 throw new Error(`context.page.ts has no page function for ${arg.channel ?? 'any channel'}`);
             const caps = channel === 'call'
-                ? { call: { transferTo, keypad, announce, voicemail, previous: arg.call?.previous ?? null, farEnd: arg.call?.farEnd ?? null } }
+                ? { call: { previous: arg.call?.previous ?? null, farEnd: arg.call?.farEnd ?? null, heard: arg.call?.heard ?? null, phase: arg.call?.phase ?? 'live' } }
                 : channel === 'sms'
                     ? { sms: { inbound: arg.sms?.inbound ?? [] } }
                     : { email: { inbound: arg.email?.inbound ?? [], mailbox: arg.email?.mailbox ?? '' } };
@@ -443,35 +480,39 @@ export function pageEntry(mod) {
                 runs: arg.runs ?? emptyRuns(),
                 scheduledAction: arg.scheduledAction ?? null,
                 officeHours: arg.officeHours ?? null,
-                followUps: pageFollowUps(arg.followUps ?? []),
+                nextSteps: [...(arg.nextSteps ?? [])],
                 subject: arg.subject,
+                instanceId: arg.instanceId,
                 caller: arg.caller,
                 session: arg.session,
                 conversation: arg.conversation,
                 history: historyProxy(),
                 now: arg.now,
-                messages,
                 time: timeOf(arg.time ?? { zone: 'America/New_York', today: arg.now.slice(0, 10) }),
+                env: envOf(arg.env ?? {}),
             };
             const ctx = { ...base, ...caps, channel };
             if (arg.mode === 'start') {
                 const page = exported;
                 return Promise.all([page.persona(ctx), page.faq ? page.faq(ctx) : []]).then(([persona, faq]) => ({ persona, faq }));
             }
-            return main(ctx);
+            // A page returns nodes (76): the platform reads their envelope (31 §8).
+            return Promise.resolve(main(ctx))
+                .then(toFnPageResult)
+                .then((envelope) => {
+                const missing = unknownActions(envelope, actions);
+                if (missing.length)
+                    throw new Error(`the page runs ${missing.map((name) => `act.${name}`).join(', ')}, not in actions.ts (76 §2.11)`);
+                return envelope;
+            });
         }
         if (arg.mode !== 'action')
             throw new Error(`unknown page mode ${String(arg.mode)}`);
-        const action = ACTIONS.get(arg.name);
-        if (!action)
-            throw new Error(`no action named ${arg.name}`);
-        return action.run(arg.args, {
-            db: dbProxy('readWrite'),
-            subject: arg.subject,
-            caller: arg.caller,
-            session: arg.session ?? null,
-            now: arg.now,
-        });
+        const run = actions.get(arg.name);
+        if (!run)
+            throw new Error(`actions.ts has no action named ${arg.name}`);
+        // A page action is a function like any other (38 §2.9): `(ctx, args)`.
+        return run({ db: dbProxy('readWrite'), subject: arg.subject, caller: arg.caller, session: arg.session ?? null, now: arg.now }, arg.args);
     };
 }
 //# sourceMappingURL=define.js.map

package/dist/core/page/envelope.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The envelope (31 §8): what crosses out of the page's sandbox. The page module turns the node tree a
+ * page function returned (`fns.ts`, 76) into it; nodes carry a mark no JSON can carry, so only what the
+ * page module marked is a block, a field, a button or a toolbox here, and the platform reads only this
+ * (`render.ts`).
+ */
+import type { FieldCell, PageAction, RefFieldCell } from './define.js';
+/** `key`: the node's name, a label for the AI (46 §2.2); `''` when it has none (a button never has one). */
+export type EnvelopeNode = {
+    k: 'block';
+    key: string;
+    title?: string;
+    description?: string;
+    list: boolean;
+    children: EnvelopeNode[];
+} | {
+    k: 'field';
+    key: string;
+    cell: FieldCell | RefFieldCell;
+} | {
+    k: 'button';
+    key: string;
+    action: PageAction;
+} | {
+    k: 'data';
+    key: string;
+    value: unknown;
+}
+/** The platform's tools the page lets the AI use (76 §2.18), by name. */
+ | {
+    k: 'toolbox';
+    key: string;
+    tools: string[];
+};
+export type EnvelopePage = {
+    title?: string;
+    description?: string;
+    guide?: string;
+    extraction?: Record<string, string>;
+    voice?: unknown;
+    children: EnvelopeNode[];
+};
+export type Envelope = {
+    $envelope: 1;
+    page: EnvelopePage;
+} | {
+    $envelope: 1;
+    do: {
+        action: PageAction;
+        key?: string;
+        wait?: boolean;
+    };
+};
+export declare function isEnvelope(value: unknown): value is Envelope;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/core/page/envelope.js

@@ -0,0 +1,4 @@
+export function isEnvelope(value) {
+    return typeof value === 'object' && value !== null && value.$envelope === 1;
+}
+//# sourceMappingURL=envelope.js.map