@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/core/page/define.js

@@ -0,0 +1,518 @@
+/**
+ * The page module (15 §10.2–§10.6): what a sequence's `context.page.ts` is written with. It runs
+ * 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 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];
+}
+/** Whether the action `key` ran at least once (whatever its result), in this run or (`'case'`) on the case. */
+export function tried(runs, key, scope = 'run') {
+    return (runsOf(runs, key, scope)?.length ?? 0) > 0;
+}
+/** The latest run of the action `key`, in this run or (`'case'`) on the case, if any. */
+export function lastActionRun(runs, key, scope = 'run') {
+    return runsOf(runs, key, scope)?.at(-1) ?? null;
+}
+/** 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("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 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;
+export function choose(rows, label) {
+    if (!Array.isArray(rows))
+        throw new Error('choose(rows, label): rows must be a list of rows read from db');
+    let table = null;
+    const options = rows.map((row) => {
+        if (!isRow(row))
+            throw new Error('choose(rows, label): each row must be a row read from db');
+        const ref = Object.values(row).find(isSlot)?.ref;
+        if (ref) {
+            if (table !== null && table !== ref.table)
+                throw new Error(`choose(): rows of ${table} and ${ref.table} together`);
+            table = ref.table;
+        }
+        return { id: row.id, label: String(label(row)) };
+    });
+    return { $choose: true, table, options };
+}
+export function isChoose(value) {
+    return typeof value === 'object' && value !== null && value.$choose === true && Array.isArray(value.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 };
+    if (options.sipAuth !== undefined && !isSipUri(options.to))
+        throw new Error(`transferTo: sipAuth is for a SIP URI, not ${options.to}`);
+    if (options.sipAuth !== undefined)
+        action.sipAuth = { ...options.sipAuth };
+    if (options.callerId !== undefined)
+        action.callerId = options.callerId;
+    if (options.briefing !== undefined)
+        action.briefing = options.briefing;
+    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)
+        action.description = options.description;
+    return action;
+}
+/** Whether a transfer's `to` is a SIP URI rather than a phone number. */
+export function isSipUri(to) {
+    return /^sips?:/i.test(to.trim());
+}
+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: 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)
+        action.map = { ...options.map };
+    if (options.label !== undefined)
+        action.label = options.label;
+    if (options.description !== undefined)
+        action.description = options.description;
+    return action;
+}
+/** A company function as a button (20 §6.2): `runFunction('importOrders', { label, say, parameters })`. */
+export function runFunction(name, options = {}) {
+    if (!name || typeof name !== 'string')
+        throw new Error('runFunction(): name the function (one of functions/)');
+    const action = { $action: 'function', name };
+    if (options.label !== undefined)
+        action.label = options.label;
+    if (options.description !== undefined)
+        action.description = options.description;
+    if (options.say !== undefined)
+        action.say = checkSpoken(options.say, `runFunction('${name}'): say`);
+    if (options.parameters !== undefined)
+        action.parameters = options.parameters;
+    if (options.prefill !== undefined) {
+        for (const key of Object.keys(options.prefill)) {
+            if (!(key in (options.parameters?.properties ?? {})))
+                throw new Error(`runFunction('${name}'): ${key} is not one of its parameters`);
+        }
+        action.prefill = toPrefill(options.prefill);
+    }
+    return action;
+}
+export function announceAction(key, text, options = {}) {
+    return { $action: 'channel', channel: 'announce', key, text: checkSpoken(text, `announce('${key}'): text`), ...(options.answers ? { answers: true } : {}) };
+}
+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 endAction(options = {}) {
+    const action = { $action: 'channel', channel: 'end' };
+    if (options.label !== undefined)
+        action.label = options.label;
+    if (options.description !== undefined)
+        action.description = options.description;
+    return action;
+}
+// ---------------------------------------------------------------------------------------------
+function isSlot(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'ref' in value &&
+        'state' in value &&
+        typeof value.ref === 'object' &&
+        value.ref !== null);
+}
+function isRow(value) {
+    return typeof value === 'object' && value !== null && typeof value.id === 'string';
+}
+/** Every channel a page may be written for, in order. */
+export const PAGE_CHANNELS = ['call', 'sms', 'email'];
+/**
+ * `context.page.ts` (17b §9.1, 24 §4): `definePage({ persona: (ctx) => '…', faq: (ctx) => [...], call:
+ * async (ctx) => page, sms: … })`. One page function per channel; what they share is the company code's
+ * own business.
+ */
+export function definePage(definition) {
+    if (!definition || typeof definition !== 'object' || typeof definition === 'function') {
+        throw new Error('definePage({ persona, faq, call, sms, email }): one page function per channel');
+    }
+    const channels = {};
+    for (const channel of PAGE_CHANNELS) {
+        const fn = definition[channel];
+        if (fn === undefined)
+            continue;
+        if (typeof fn !== 'function')
+            throw new Error(`definePage(): ${channel} must be a page function`);
+        channels[channel] = fn;
+    }
+    if (Object.keys(channels).length === 0)
+        throw new Error('definePage(): no page function (call, sms, email)');
+    if (typeof definition.persona !== 'function') {
+        throw new Error('definePage(): persona must be a function, called once when the conversation starts: persona: (ctx) => \'You are …\' (24 §4)');
+    }
+    if (definition.faq !== undefined && typeof definition.faq !== 'function') {
+        throw new Error('definePage(): faq must be a function, called once when the conversation starts: faq: (ctx) => [{ id, description, content }] (24 §4)');
+    }
+    return { kind: 'page', persona: definition.persona, faq: definition.faq ?? null, channels };
+}
+/**
+ * What `persona` and `faq` returned, checked (24 §4): a persona's text; at most `MAX_FAQ_ENTRIES` FAQ
+ * entries, each with an id of its own, a description and an answer. Throws what is wrong.
+ */
+export function checkPageStart(raw) {
+    const value = raw;
+    if (typeof value?.persona !== 'string' || !value.persona.trim())
+        throw new Error('persona(ctx) must return the persona\'s text');
+    const faq = value.faq ?? [];
+    if (!Array.isArray(faq))
+        throw new Error('faq(ctx) must return a list of { id, description, content }');
+    if (faq.length > MAX_FAQ_ENTRIES)
+        throw new Error(`faq(ctx) returned ${faq.length} entries; at most ${MAX_FAQ_ENTRIES} (24 §7.2)`);
+    const seen = new Set();
+    const entries = faq.map((entry, i) => {
+        const e = entry;
+        for (const key of ['id', 'description', 'content']) {
+            if (typeof e?.[key] !== 'string' || !e[key].trim())
+                throw new Error(`faq(ctx)[${i}]: ${key} must be text`);
+        }
+        if (seen.has(e.id))
+            throw new Error(`faq(ctx): the id ${e.id} is used twice`);
+        seen.add(e.id);
+        return { id: e.id, description: e.description, content: e.content };
+    });
+    return { persona: value.persona, faq: entries };
+}
+/**
+ * A cell the AI may write (19-page-writable-cells): a slot placed on a page as is is read-only;
+ * `field(slot)` opens it, unless `readOnly: true`. The row id and the parent never open; a lookup
+ * chooses among its table's rows on the page.
+ */
+/**
+ * A ref field (a lookup) on the page (26 §16.2 #7): the rows the AI may set it to, each with its label
+ * (`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 refFieldCell(slot, options = {}) {
+    if (!isSlot(slot))
+        throw new Error('refField(): the first argument must be a slot read from db');
+    const given = options.options ?? [];
+    const list = isChoose(given) ? given.options : given;
+    if (!Array.isArray(list))
+        throw new Error('refField(): options must be a list of { id, label } or choose(rows, label)');
+    const cell = {
+        $refField: true,
+        slot,
+        options: list.map((option) => {
+            if (!option || typeof option.id !== 'string')
+                throw new Error('refField(): each option is { id, label }, id a row id');
+            return { id: option.id, label: String(option.label) };
+        }),
+    };
+    if (options.readOnly !== undefined)
+        cell.readOnly = options.readOnly;
+    return cell;
+}
+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) {
+        throw new Error("field(): how to fill a field is the page's: write it in $extraction on the page's root, by table.field (26 §15.3)");
+    }
+    const cell = { $field: true, slot };
+    if (options.readOnly !== undefined)
+        cell.readOnly = options.readOnly;
+    if (options.required !== undefined)
+        throw new Error('field(): `required` was removed (24 §2.3): say what is still needed in $guide');
+    if (options.expand !== undefined)
+        cell.expand = options.expand;
+    return cell;
+}
+function placeable(make) {
+    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 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).
+    const unknown = Object.keys(options).filter((key) => !CREATE_ROW_OPTIONS.has(key));
+    if (unknown.length) {
+        throw new Error(`createRow('${tableName}'): unknown option ${unknown.join(', ')} (it takes ${[...CREATE_ROW_OPTIONS].join(', ')}); preset values by calling it: createRow('${tableName}', { … })({ field: value })`);
+    }
+    return placeable((prefill) => {
+        const action = {
+            $action: 'createRow',
+            table: tableName,
+            fields: [...options.fields],
+            required: [...(options.required ?? [])],
+            prefill,
+        };
+        if (options.label !== undefined)
+            action.label = options.label;
+        if (options.description !== undefined)
+            action.description = options.description;
+        return action;
+    });
+}
+/** Delete a row (cascading, 15 §10.6.1): a built-in action with the row prefilled and nothing to fill. */
+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');
+    const action = { $action: 'deleteRow', rowId };
+    if (options.reason !== undefined)
+        action.reason = options.reason;
+    if (options.label !== undefined)
+        action.label = options.label;
+    if (options.description !== undefined)
+        action.description = options.description;
+    return action;
+}
+/** Prefilled values as given (ids and plain JSON, as `parameters` types them), without the unset ones. */
+function toPrefill(prefill) {
+    const out = {};
+    for (const [key, value] of Object.entries(prefill)) {
+        if (value !== undefined)
+            out[key] = value;
+    }
+    return out;
+}
+function host() {
+    const call = globalThis.__host;
+    if (!call)
+        throw new Error('the page module runs inside the page sandbox only');
+    return call;
+}
+function dbProxy(mode) {
+    const call = host();
+    return new Proxy({}, {
+        get(_, table) {
+            if (typeof table !== 'string')
+                return undefined;
+            const read = (method) => (args) => call('records', [table, method, args ?? {}]);
+            const reads = {
+                $table: table,
+                findUnique: read('findUnique'),
+                findFirst: read('findFirst'),
+                findMany: read('findMany'),
+                count: read('count'),
+            };
+            if (mode === 'read')
+                return reads;
+            const write = (method) => (args) => call('write', [table, method, args ?? {}]);
+            return { ...reads, create: write('create'), update: write('update'), upsert: write('upsert'), delete: write('delete') };
+        },
+    });
+}
+/** `ctx.time` inside the sandbox: `format` and `day` are host calls (the sandbox has no `Intl`). */
+function timeOf(at) {
+    const call = host();
+    return {
+        zone: at.zone,
+        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. */
+function historyProxy() {
+    const call = host();
+    return {
+        sessionCount: (where) => call('history', ['sessionCount', where ?? {}]),
+        exchangeCount: (where) => call('history', ['exchangeCount', where ?? {}]),
+        timeline: (where) => call('history', ['timeline', where ?? {}]),
+    };
+}
+/** No runs yet. */
+export function emptyRuns() {
+    return { actions: {}, caseActions: {} };
+}
+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 })');
+            // 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;
+            if (!channels)
+                throw new Error('context.page.ts must default-export definePage({ persona, faq, call, sms, email })');
+            const channel = arg.channel ?? Object.keys(channels)[0] ?? null;
+            const main = channel ? channels[channel] : undefined;
+            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: { 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 ?? '' } };
+            const base = {
+                db: dbProxy('read'),
+                runs: arg.runs ?? emptyRuns(),
+                scheduledAction: arg.scheduledAction ?? null,
+                officeHours: arg.officeHours ?? null,
+                nextSteps: [...(arg.nextSteps ?? [])],
+                subject: arg.subject,
+                instanceId: arg.instanceId,
+                caller: arg.caller,
+                session: arg.session,
+                conversation: arg.conversation,
+                history: historyProxy(),
+                now: arg.now,
+                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 }));
+            }
+            // 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 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