@superpanel-sdk/runtime 0.2.2 → 0.5.0

package/dist/core/page/ops.js

@@ -0,0 +1,220 @@
+/**
+ * What the AI may do to a page (15 §10.6.2, 17b §4): change a slot (a value, `asked_unknown` /
+ * `declined`, or `empty` to clear it; a `multi_select` also by adding or removing options, 27 §3.3) and
+ * press an action. The check that turns its operations into ones
+ * the platform can run — every operation resolved against the page the AI saw, invalid ones dropped one
+ * by one with the reason.
+ */
+import { contactScheduleValueSchema } from '../slot/schema.js';
+import { TIME_VALUE_PATTERN } from '../slot/value.js';
+export function resolvePageOps(page, names, answer, allowed) {
+    const ops = [];
+    const dropped = [];
+    const list = Array.isArray(answer)
+        ? answer
+        : answer && typeof answer === 'object' && Array.isArray(answer.ops)
+            ? answer.ops
+            : null;
+    if (!list)
+        return { ops, dropped: answer == null ? [] : [{ op: answer, why: 'not { ops: [...] }' }] };
+    const slots = new Set(allowed.slots);
+    const actions = new Set(allowed.actions);
+    const opens = new Set(allowed.open);
+    for (const op of list) {
+        if (!op || typeof op !== 'object') {
+            dropped.push({ op, why: 'not an object' });
+            continue;
+        }
+        const o = op;
+        try {
+            if (typeof o.slot === 'string') {
+                if (!slots.has(o.slot))
+                    throw new OpError(`slot ${o.slot} is not editable here`);
+                ops.push(resolveSlot(page, names, page.cells[o.slot], o));
+            }
+            else if (typeof o.action === 'string') {
+                if (!actions.has(o.action))
+                    throw new OpError(`action ${o.action} is not on the page here`);
+                const action = page.actions[o.action];
+                ops.push({ kind: 'action', action, args: resolveArguments(names, action, o.arguments) });
+            }
+            else if (typeof o.open === 'string') {
+                if (!opens.has(o.open))
+                    throw new OpError(`cannot open ${o.open}`);
+                ops.push({ kind: 'open', path: o.open, why: typeof o.why === 'string' ? o.why : '' });
+            }
+            else {
+                throw new OpError('neither slot, action nor open');
+            }
+        }
+        catch (error) {
+            if (!(error instanceof OpError))
+                throw error;
+            dropped.push({ op, why: error.message });
+        }
+    }
+    return { ops, dropped };
+}
+class OpError extends Error {
+}
+const TIME_RE = new RegExp(TIME_VALUE_PATTERN);
+const STATES = new Set(['filled', 'asked_unknown', 'declined', 'empty']);
+function resolveSlot(page, names, cell, o) {
+    const state = (o.state ?? 'filled');
+    if (!STATES.has(state))
+        throw new OpError(`${cell.slotId}: state ${state} is not filled / asked_unknown / declined / empty`);
+    const reason = typeof o.reason === 'string' && o.reason ? o.reason : null;
+    const edits = ['add', 'remove'].filter((key) => key in o);
+    if (edits.length && cell.type !== 'multi_select')
+        throw new OpError(`${cell.slotId}: ${edits.join(' / ')} is for a multi_select field; write value`);
+    if (state !== 'filled') {
+        if (edits.length)
+            throw new OpError(`${cell.slotId}: ${edits.join(' / ')} goes with state filled`);
+        return { kind: 'slot', cell, value: null, state: state, reason };
+    }
+    if (cell.type === 'multi_select')
+        return { kind: 'slot', cell, value: multiSelectValue(cell, o, edits), state: 'filled', reason };
+    if (!('value' in o) || o.value === null || o.value === undefined || o.value === '') {
+        throw new OpError(`${cell.slotId}: filled needs a value`);
+    }
+    let value = o.value;
+    if (cell.options) {
+        // A lookup: the AI names one of the rows on the page.
+        if (typeof value !== 'string' || !cell.options.includes(value)) {
+            throw new OpError(`${cell.slotId}: ${JSON.stringify(value)} is not one of ${cell.options.join(', ') || '(no rows on the page)'}`);
+        }
+        const row = names.resolve(value);
+        if (!row)
+            throw new OpError(`${cell.slotId}: ${value} is not a row on the page`);
+        value = row.id;
+    }
+    else {
+        value = coerce(cell.slotId, cell.type, cell.choices, value);
+    }
+    return { kind: 'slot', cell, value, state: 'filled', reason };
+}
+/**
+ * A `multi_select`'s new value (27 §3.3): `value` replaces the list, `add` / `remove` change the one
+ * the AI saw on the page and keep the rest. In the options' order, each once.
+ */
+function multiSelectValue(cell, o, edits) {
+    const choices = cell.choices ?? [];
+    const given = edits.length ? edits : ['value'];
+    if (given.length + (edits.length && 'value' in o ? 1 : 0) > 1)
+        throw new OpError(`${cell.slotId}: one of value, add or remove at a time`);
+    const key = given[0];
+    const raw = o[key];
+    if (raw === null || raw === undefined)
+        throw new OpError(`${cell.slotId}: filled needs ${key}`);
+    // One option alone is taken as a list of one.
+    const list = Array.isArray(raw) ? raw : [raw];
+    const outside = list.filter((item) => typeof item !== 'string' || !choices.includes(item));
+    if (outside.length) {
+        throw new OpError(`${cell.slotId}: ${outside.map((v) => JSON.stringify(v)).join(', ')} not one of ${choices.map((v) => JSON.stringify(v)).join(', ')}`);
+    }
+    const now = cell.state === 'filled' && Array.isArray(cell.value) ? cell.value : [];
+    const next = new Set(key === 'value' ? list : now);
+    if (key === 'add')
+        for (const item of list)
+            next.add(item);
+    if (key === 'remove')
+        for (const item of list)
+            next.delete(item);
+    return choices.filter((choice) => next.has(choice));
+}
+function resolveArguments(names, action, raw) {
+    if (!action.input) {
+        if (raw && typeof raw === 'object' && Object.keys(raw).length)
+            throw new OpError(`${action.id}: takes no arguments`);
+        return {};
+    }
+    return resolveObject(names, action.id, action.input.properties, action.input.required, raw ?? {});
+}
+function resolveObject(names, where, properties, required, raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        throw new OpError(`${where}: arguments must be an object`);
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        const prop = properties[key];
+        if (!prop)
+            throw new OpError(`${where}: ${key} is not an argument here`);
+        if (value === null || value === undefined || value === '')
+            continue;
+        out[key] = resolveValue(names, `${where}.${key}`, prop, value);
+    }
+    for (const key of required ?? []) {
+        if (!(key in out))
+            throw new OpError(`${where}: ${key} is required`);
+    }
+    return out;
+}
+function resolveValue(names, where, prop, value) {
+    if (prop.type === 'array') {
+        if (!Array.isArray(value))
+            throw new OpError(`${where}: must be a list`);
+        return value.map((item, i) => resolveValue(names, `${where}[${i}]`, prop.items, item));
+    }
+    if (prop.type === 'object' && prop['x-type'] === 'contact_schedule') {
+        // Checked as the field checks it; `run` gets the schedule as it is.
+        const parsed = contactScheduleValueSchema.safeParse(value);
+        if (parsed.success)
+            return value;
+        const issue = parsed.error.issues[0];
+        throw new OpError(`${where}: not a contact schedule (${issue.path.join('.') || 'value'}: ${issue.message})`);
+    }
+    if (prop.type === 'object')
+        return resolveObject(names, where, prop.properties, prop.required, value);
+    if (prop.type === 'ref') {
+        // A row choice: one of the rows on the page, by page name; `run` gets its id.
+        const row = typeof value === 'string' && prop.enum.includes(value) ? names.resolve(value) : undefined;
+        if (!row)
+            throw new OpError(`${where}: must be one of ${prop.enum.join(', ') || '(no rows on the page)'}`);
+        return row.id;
+    }
+    if (prop.type === 'multi_select') {
+        // As a fill writes it: one option alone is a list of one; each once, in the options' order.
+        const list = Array.isArray(value) ? value : [value];
+        const outside = list.filter((item) => !prop.enum.includes(item));
+        if (outside.length)
+            throw new OpError(`${where}: ${outside.map((v) => JSON.stringify(v)).join(', ')} not one of ${prop.enum.map((v) => JSON.stringify(v)).join(', ')}`);
+        return prop.enum.filter((option) => list.includes(option));
+    }
+    // A schema field's argument is checked as a fill of the field is.
+    return coerce(where, prop.type === 'integer' ? 'number' : prop.type, prop.enum ?? null, value);
+}
+function coerce(where, type, enumValues, value) {
+    let out = value;
+    if (type === 'number') {
+        out = typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value)) ? Number(value) : value;
+        if (typeof out !== 'number' || !Number.isFinite(out))
+            throw new OpError(`${where}: ${JSON.stringify(value)} is not a number`);
+    }
+    else if (type === 'boolean') {
+        out = value === 'true' ? true : value === 'false' ? false : value;
+        if (typeof out !== 'boolean')
+            throw new OpError(`${where}: ${JSON.stringify(value)} is not true / false`);
+    }
+    else if (type === 'date') {
+        if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+            throw new OpError(`${where}: ${JSON.stringify(value)} is not YYYY-MM-DD`);
+    }
+    else if (type === 'datetime') {
+        if (typeof value !== 'string' || Number.isNaN(Date.parse(value)))
+            throw new OpError(`${where}: ${JSON.stringify(value)} is not a date-time`);
+    }
+    else if (type === 'time') {
+        if (typeof value !== 'string' || !TIME_RE.test(value))
+            throw new OpError(`${where}: ${JSON.stringify(value)} is not a time of day HH:mm, 24-hour (15:30)`);
+    }
+    else if (type === 'string' || type === 'select' || type === 'text' || type === 'phone' || type === 'email') {
+        if (typeof value === 'number' || typeof value === 'boolean')
+            out = String(value);
+        if (typeof out !== 'string')
+            throw new OpError(`${where}: ${JSON.stringify(value)} is not text`);
+    }
+    if (enumValues && !enumValues.includes(out)) {
+        throw new OpError(`${where}: ${JSON.stringify(value)} is not one of ${enumValues.map((v) => JSON.stringify(v)).join(', ')}`);
+    }
+    return out;
+}
+//# sourceMappingURL=ops.js.map

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

@@ -0,0 +1,253 @@
+import type { CompiledSlotSchema, RuntimeFieldDef } from '../slot/types.js';
+import type { ChannelAction, PageAction, PageChannel, SlotRef, SlotState } from './define.js';
+/**
+ * `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.
+ */
+export declare class RowNames {
+    private readonly byId;
+    private readonly byName;
+    private readonly counters;
+    name(table: string, id: string): string;
+    resolve(name: string): {
+        table: string;
+        id: string;
+    } | undefined;
+    nameOf(id: string): string | undefined;
+    toJSON(): Array<[string, string, string]>;
+    static fromJSON(entries: Array<[string, string, string]>): RowNames;
+}
+export type ReadSlot = {
+    value: unknown;
+    state: SlotState;
+    reason: string | null;
+    updatedAt: string | null;
+};
+export type PageReads = {
+    /** A row this run read, with its true slots; undefined when it was not read. */
+    row(id: string): {
+        table: string;
+        slots: Record<string, ReadSlot>;
+    } | undefined;
+    /** The ids new rows of `table` would hang under, from the parent conditions of this run's reads. */
+    parentsOf(table: string): readonly string[];
+};
+/** A block. Only the root has `guide` (24 §2.1): what to do now and how, the page's words. */
+export type BlockNode = {
+    kind: 'block';
+    key: string;
+    path: string;
+    title?: string;
+    description?: string;
+    list: boolean;
+    children: PageNode[];
+    guide?: string;
+};
+export type PageNode = BlockNode
+/** `expand`: shown with its definition (24 §2.2). */
+ | {
+    kind: 'cell';
+    key: string;
+    path: string;
+    slotId: string;
+    readOnly: boolean;
+    expand?: boolean;
+} | {
+    kind: 'text';
+    key: string;
+    path: string;
+    value: string | number | boolean | null;
+} | {
+    kind: 'action';
+    key: string;
+    path: string;
+    actionId: string;
+};
+export type RenderedCell = {
+    slotId: string;
+    ref: SlotRef;
+    /** The row's page name, `table#n`. */
+    row: string;
+    label: string;
+    description?: string;
+    /** The schema's; the page's `$extraction` for its `table.field` replaces it (`RenderedPage.extractions`). */
+    extraction?: string;
+    /** The field's type; `ref` for a lookup (26 §16.2 #7), as a row argument's. */
+    type: RuntimeFieldDef['dataType'] | 'ref';
+    /** A `select` / `multi_select` field's options; null on every other type. */
+    choices: string[] | null;
+    /** For a lookup (`refField`): the rows the page offers, by page name, in its order. */
+    options?: string[];
+    /** For a lookup: what the AI sees of each row the page offered, by page name (26 §16.2 #7). */
+    optionLabels?: Record<string, string>;
+    value: unknown;
+    state: SlotState;
+    reason: string | null;
+    updatedAt: string | null;
+    /** Writable in at least one place on the page (schema allows, page did not tighten everywhere). */
+    writable: boolean;
+    paths: string[];
+};
+/**
+ * A field type a `schemaField` argument keeps, named as the field's definition names it and checked as a
+ * fill of the field is (`string`, `number` and `boolean` are the plain ones below).
+ */
+export type FieldArgType = 'text' | 'phone' | 'email' | 'date' | 'datetime' | 'time' | 'select';
+/**
+ * One argument as the AI fills it. Never sent to a model as a schema: the page shows it as `<arg>` and
+ * the platform checks what the AI passed against it. A `schemaField` argument has its field's type
+ * (26 §15.8: the same names as a field's definition); a row choice is `ref`, its `enum` the rows' page
+ * names, and the platform hands `run` the row's id. The rest is plain JSON Schema, as the action wrote it.
+ */
+export type InputProperty = {
+    type: 'string';
+    description?: string;
+    enum?: Array<string | number>;
+} | {
+    type: 'number' | 'integer' | 'boolean';
+    description?: string;
+    enum?: Array<string | number>;
+} | {
+    type: FieldArgType;
+    description?: string;
+    enum?: string[];
+} | {
+    type: 'multi_select';
+    enum: string[];
+    description?: string;
+} | {
+    type: 'ref';
+    table: string;
+    enum: string[];
+    description?: string; /** What the AI sees of each row (`choose`), by page name. */
+    labels?: Record<string, string>;
+} | {
+    type: 'array';
+    items: InputProperty;
+    description?: string;
+} | {
+    type: 'object';
+    properties: Record<string, InputProperty>;
+    required?: string[];
+    description?: string;
+    /** May also be null. */
+    nullable?: true;
+    /** A field value with its own checks: the argument is validated as one (`contact_schedule`). */
+    'x-type'?: 'contact_schedule';
+};
+export type InputSchema = {
+    type: 'object';
+    properties: Record<string, InputProperty>;
+    required: string[];
+};
+export type RenderedAction = {
+    id: string;
+    kind: PageAction['$action'];
+    name: string;
+    description: string;
+    /** JSON Schema of the arguments the AI fills (prefilled ones left out); null: nothing to fill. */
+    input: InputSchema | null;
+    /** Server-only: what running it needs. Never shown to the AI. */
+    server: {
+        kind: 'createRow';
+        table: string;
+        parentId: string | null;
+        set: Record<string, unknown>;
+        fields: string[];
+        required: string[];
+    } | {
+        kind: 'deleteRow';
+        table: string;
+        rowId: string;
+        reason?: string;
+    } | {
+        kind: 'custom';
+        name: string;
+        prefill: Record<string, unknown>;
+    } | {
+        kind: 'channel';
+        spec: ChannelAction;
+    }
+    /** A text or an email sent now (25 §8); `to` the contact (null: the conversation's). */
+     | {
+        kind: 'message';
+        channel: 'sms' | 'email';
+        key: string;
+        to: string | null;
+        body?: string;
+        subject?: string;
+        say?: string;
+    }
+    /** Book what the customer asked for, as an agreed follow-up (25 §5), on one of `channels`. */
+     | {
+        kind: 'followUp';
+        key: string;
+        channels: Array<'call' | 'sms' | 'email'>;
+    }
+    /** A company function (20 §6.2): run on the Worker by the platform, waited for, with the page's prefilled arguments. */
+     | {
+        kind: 'function';
+        name: string;
+        say?: string;
+        prefill?: Record<string, unknown>;
+    };
+};
+/**
+ * The page function returned an action to run now instead of a page (17b §9.8): `action` is rendered
+ * as a button would be (its rows checked), `key` names its runs.
+ */
+export type AutoAction = {
+    action: RenderedAction;
+    key: string;
+    wait: boolean;
+};
+export type RenderedPage = {
+    root: BlockNode;
+    /** Set when the page function returned an action to run now: the page then has nothing else. */
+    auto?: AutoAction;
+    cells: Record<string, RenderedCell>;
+    actions: Record<string, RenderedAction>;
+    /**
+     * Set on a stand-in page when the page script failed (15 §10.9): the last good page marked stale and
+     * read-only, or an empty page. Nothing on it can be written, and it has no actions.
+     */
+    fallback?: {
+        reason: string;
+        stale: boolean;
+    };
+    /** Every row on the page, by page name; `parentId` is its parent. */
+    rows: Record<string, {
+        table: string;
+        id: string;
+        parentId: string | null;
+    }>;
+    /** The page's `$extraction` (26 §15.3): how to fill a field on this page, by `table.field`; replaces the schema's. */
+    extractions?: Record<string, string>;
+    warnings: string[];
+};
+export declare class PageDocumentError extends Error {
+    constructor(message: string);
+}
+export type RenderDocumentInput = {
+    document: unknown;
+    schema: CompiledSlotSchema;
+    reads: PageReads;
+    names: RowNames;
+    /** The conversation's channel: a button the channel cannot do (a transfer by text) is an error (20 §5.2). */
+    channel?: PageChannel;
+};
+export declare function renderDocument(input: RenderDocumentInput): RenderedPage;
+/**
+ * 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.
+ */
+export declare function runKeyOf(action: RenderedAction): string;
+/** The run key of an action the page function returned, when it names none. */
+export declare function actionKey(action: PageAction): string;
+/**
+ * The page to show when the page script failed (15 §10.9): the last good page, every cell read-only
+ * and no actions, marked stale; without one, an empty page.
+ */
+export declare function fallbackPage(last: RenderedPage | null, reason: string): RenderedPage;
+//# sourceMappingURL=render.d.ts.map