@superpanel-sdk/runtime 0.2.3 → 0.7.0

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

@@ -0,0 +1,904 @@
+/**
+ * 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 { type Channel, type Direction, type Spoken } from '../conversation/index.js';
+import type { TimelineEntry, TimelineWhere } from './timeline.js';
+import type { TimeParts } from './time-format.js';
+export type SlotState = 'filled' | 'empty' | 'asked_unknown' | 'declined';
+export type SlotRef = {
+    table: string;
+    id: string;
+    field: string;
+};
+/** One field as read: plain data, never mutated. */
+export type Slot<V = unknown> = Readonly<{
+    value: V | null;
+    state: SlotState;
+    reason: string | null;
+    updatedAt: string | null;
+    ref: SlotRef;
+    /** The target row, on a lookup that was `include`d. */
+    row?: PageRow | null;
+}>;
+/** A row as `db` returns it: `id`, one slot per field. */
+export type PageRow = {
+    readonly id: string;
+} & {
+    readonly [field: string]: unknown;
+};
+export type FindArgs = {
+    where?: Record<string, unknown>;
+    include?: Record<string, unknown>;
+    select?: Record<string, boolean>;
+    orderBy?: Record<string, 'asc' | 'desc'> | Array<Record<string, 'asc' | 'desc'>>;
+    take?: number;
+    skip?: number;
+    /**
+     * Where a page starts: a row as `db` returned it, normally the last of the page before. The rows
+     * strictly after it in this read's order come (`orderBy`, then creation, then id; rows without a
+     * value of the order field last), then `skip`. Read by value, never looked up: a row deleted or
+     * changed since still marks where it was. It needs the row's `id` and `createdAt`, its `updatedAt`
+     * when ordered by that, and the slot of each field ordered by (keep it in `select`). Only that place
+     * is sent (over `ctx.api.db`, not the rest of the row and what it included); an order value not of
+     * its field's type is refused.
+     */
+    after?: PageRow;
+};
+/** One table's read methods (Prisma Client's read-only subset). */
+export type TableReader<Row = PageRow> = {
+    readonly $table: string;
+    findUnique(args: {
+        where: Record<string, unknown>;
+        include?: FindArgs['include'];
+        select?: FindArgs['select'];
+    }): Promise<Row | null>;
+    findFirst(args: FindArgs): Promise<Row | null>;
+    findMany(args: FindArgs): Promise<Row[]>;
+    count(args: {
+        where: Record<string, unknown>;
+    }): Promise<number>;
+};
+/**
+ * Prisma-shaped writes of an action's `run` (15 §10.6.1): create / update / upsert / delete. `upsert`
+ * finds the row by one `unique` field (18-record-search-index §4.5): updated when there is one, else
+ * created with that value.
+ */
+export type TableWriter = {
+    create(args: {
+        data: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+    }>;
+    update(args: {
+        where: {
+            id: string;
+        };
+        data: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+    }>;
+    upsert(args: {
+        where: Record<string, unknown>;
+        create: Record<string, unknown>;
+        update: Record<string, unknown>;
+    }): Promise<{
+        id: string;
+    }>;
+    delete(args: {
+        where: {
+            id: string;
+        };
+        reason?: string;
+    }): Promise<{
+        id: string;
+    }>;
+};
+/** `db` where only reading is allowed (a page render): each table's read methods. */
+export type ReadDb = {
+    readonly [table: string]: TableReader;
+};
+/** `db`, Prisma-shaped: each table's read and write methods on one object. */
+export type Db = {
+    readonly [table: string]: TableReader & TableWriter;
+};
+/**
+ * What the platform knows about this conversation (11-remove-sequence-schema §3.3): written once when
+ * its session opened, read-only, never a cell.
+ */
+export type PageConversation = {
+    /** The session id. */
+    id: string;
+    channel: Channel;
+    /** Who started this conversation; a resumed one keeps it. */
+    direction: Direction;
+    /** The contact was created while this conversation opened. */
+    isNewContact: boolean;
+    /** ISO timestamp the session opened. */
+    startedAt: string;
+    /** The provider's id of the call (Twilio's CallSid, 62), as the resolve got it; null when unknown. */
+    externalId: string | null;
+};
+/**
+ * Counts over this instance, worked out when the page renders (11-remove-sequence-schema §3.3.1).
+ * The first call of the instance is `await history.sessionCount({ channel: 'call' }) === 1`.
+ */
+export type PageHistory = {
+    /** Conversations (sessions) of this instance, every contact, the current one included. */
+    sessionCount(where?: {
+        channel?: Channel;
+    }): Promise<number>;
+    /**
+     * Exchanges of this instance recorded so far (an unanswered dial included). The current
+     * conversation's own is recorded once its first step is decided, so the opening decision does not
+     * count it (a scheduled call's, written before dialing, it does); later turns do. "Is this the first
+     * call" is `sessionCount`'s question.
+     */
+    exchangeCount(where?: {
+        channel?: Channel;
+        direction?: Direction;
+    }): Promise<number>;
+    /**
+     * The case's timeline (20 §3): messages, calls, the AI's runs and actions, field changes, scheduled
+     * contacts, oldest first; the newest `limit` (50) unless `before` pages back. A text page can show the
+     * last call; a call page, the texts since.
+     */
+    timeline(where?: TimelineWhere): Promise<TimelineEntry[]>;
+};
+/** The channels a page function is written for (17b §9.1, 20 §5.1): one page function per channel. */
+export type PageChannel = 'call' | 'sms' | 'email';
+/**
+ * What the platform recorded (17b §9.8), read-only. `actions` by action key: every run of an action in
+ * this run on this case (one the page function returned, or a button the AI pressed), oldest first;
+ * `caseActions` the same for the whole case, every channel and run (21 §6.7).
+ */
+export type PageRuns = {
+    actions: Record<string, PageActionRun[]>;
+    caseActions: Record<string, PageActionRun[]>;
+};
+/** Where `tried()` and `lastActionRun()` look: this run on this case (the default), or the whole case. */
+export type ActionRunScope = 'run' | 'case';
+/** `started`: under way (a keypad or a transfer waiting for its result, a function running). */
+export type PageActionRun = {
+    result: 'ok' | 'failed' | 'started';
+    /** ISO time. */
+    at: string;
+    error?: string;
+    /** What a channel action brought back (the digits pressed), or what a function returned (25 §11, as text). */
+    value?: string;
+};
+/** Whether the action `key` ran at least once (whatever its result), in this run or (`'case'`) on the case. */
+export declare function tried(runs: PageRuns | null | undefined, key: string, scope?: ActionRunScope): boolean;
+/** The latest run of the action `key`, in this run or (`'case'`) on the case, if any. */
+export declare function lastActionRun(runs: PageRuns | null | undefined, key: string, scope?: ActionRunScope): PageActionRun | null;
+/**
+ * The case's next step (40 §2.2): its pending contact — when, on which channel, whom, why, and where it
+ * was booked. Independent appointments may coexist (51); the platform shows them after every conversation page.
+ */
+export type PageNextStep = {
+    id: string;
+    name?: string | null;
+    channel: 'call' | 'sms' | 'email';
+    /** When it runs, ISO 8601. */
+    at: string;
+    /** Whom it contacts: the contact's id, and what they are called (their name, else their phone or email; null when none is on file). */
+    contact: {
+        id: string;
+        name: string | null;
+    };
+    /** Why (40 §2.6); null when nobody said. */
+    reason: string | null;
+    /** The contact's own words asking for it or agreeing to it (an agreed follow-up, 09); null otherwise. */
+    customerQuote: string | null;
+    /** The conversation it was booked in, its channel and when it started; null: booked outside one (the Orchestrator, company code). */
+    bookedIn: {
+        channel: 'call' | 'sms' | 'email';
+        at: string;
+    } | null;
+};
+/**
+ * The button that books the case's next step (40 §2.2): what the customer asked for or agreed to, or
+ * what the AI decides the case needs. The AI gives when, the channel, why, and the customer's words
+ * when they said it (an agreed follow-up, 09); whom is the conversation's contact unless the page lets
+ * the AI choose (`options`) or fixes one (`prefill`). It adds an independent appointment, or edits one explicitly by ID (51).
+ */
+export type FollowUpAction = {
+    $action: 'followUp';
+    /** The run key (default `followUp`). */
+    key: string;
+    /** The channels it may book, of the ones this sequence has a page for. */
+    channels: Array<'call' | 'sms' | 'email'>;
+    /** What the page fixed: the channel (one of `channels`), whom (a contact row's id); `contactId: choose(...)`: the contacts the AI chooses among. */
+    prefill?: {
+        channel?: 'call' | 'sms' | 'email';
+        contactId?: string | ChooseParam;
+    };
+    label?: string;
+    description?: string;
+};
+/** The button that cancels the case's next step (40 §2.2), with why. */
+export type CancelFollowUpAction = {
+    $action: 'cancelFollowUp';
+    /** The run key (default `cancelFollowUp`). */
+    key: string;
+    label?: string;
+    description?: string;
+};
+/** The next-step button (`scheduleFollowUp({ channels })`, 76). */
+export declare function followUpAction(options: {
+    channels: Array<'call' | 'sms' | 'email'>;
+    key?: string;
+    label?: string;
+    description?: string;
+    prefill?: Record<string, unknown>;
+}): FollowUpAction;
+/** The cancel-next-step button (`cancelFollowUp()`, 76). */
+export declare function cancelFollowUpAction(options?: {
+    key?: string;
+    label?: string;
+    description?: string;
+}): CancelFollowUpAction;
+/**
+ * One FAQ entry (24 §7): its id, what it covers (the catalog in the prompt shows these two), and the
+ * answer (the AI fetches it with `get_faq`).
+ */
+export type PageFaqEntry = {
+    id: string;
+    description: string;
+    content: string;
+};
+/** At most this many FAQ entries in a conversation (24 §7.2): the catalog is in every prompt. */
+export declare const MAX_FAQ_ENTRIES = 100;
+/** What the page decides once, when the conversation starts (24 §4): who the AI is, and its FAQ. */
+export type PageStart = {
+    persona: string;
+    faq: PageFaqEntry[];
+};
+/** The scheduled contact this conversation carries out (an outbound call or message, 09 §3.5). */
+export type PageScheduledAction = {
+    id: string;
+    /** What the contact agreed to, in the exchange where they agreed; null for a routine follow-up. */
+    agreedInExchangeId: string | null;
+    /** The contact's own words agreeing to it; null for a routine follow-up. */
+    customerQuote: string | null;
+    note: string | null;
+    /** ISO time it was scheduled for. */
+    scheduledFor: string;
+};
+export type PageBaseContext = {
+    /** Read-only: a render never writes. */
+    db: ReadDb;
+    /** What the platform recorded in this conversation; empty outside one. */
+    runs: PageRuns;
+    /** Why this conversation happened when the platform started it (17b §9.2); null for an inbound one. */
+    scheduledAction: PageScheduledAction | null;
+    /** The sequence's office hours now; null when it has none. */
+    officeHours: {
+        open: boolean;
+        timezone: string;
+        today: Array<{
+            start: string;
+            end: string;
+        }>;
+    } | null;
+    /**
+     * The case's independent pending contact appointments (51), soonest first. The platform shows
+     * their stable IDs before the page. `scheduleFollowUp()` adds or edits one; `cancelFollowUp()`
+     * cancels an explicit target. Empty when nothing is booked.
+     */
+    nextSteps: PageNextStep[];
+    /** The business root's id. */
+    subject: string;
+    /** The instance this conversation is on: prefill it to a function that needs it (38 §2.2). */
+    instanceId: string;
+    /** The contact of the conversation; null outside one. */
+    caller: PageRow | null;
+    /** This conversation's session row (the session fields, cells); null outside one. */
+    session: PageRow | null;
+    /** This conversation's platform facts; null outside one. */
+    conversation: PageConversation | null;
+    /** Counts over this instance. */
+    history: PageHistory;
+    /** ISO timestamp of this render. */
+    now: string;
+    /** Times for people (25 §11): the sandbox has no `Intl`, so formatting goes through the platform. */
+    time: PageTime;
+    /**
+     * The environment's configuration, read only (76 §2.19): the values of its `env` integrations, the
+     * same functions read with `ctx.api.integration.envs`; null when no `env` integration has the key.
+     */
+    env: PageEnv;
+};
+/**
+ * `ctx.time` (25 §11): the contact's time zone and today there, `format` for a time as people read it,
+ * and `day` for the calendar day of a time. `zone` is the contact's `timezone`, else worked out from
+ * their postal code, state or phone.
+ */
+export type PageTime = {
+    /** The contact's time zone (America/New_York without a contact). */
+    zone: string;
+    /** Today, `YYYY-MM-DD`, in `zone`. */
+    today: string;
+    /** `at` as people read it, in `timeZone` (default `zone`): "Tue, Nov 3, 3:00 PM EST". */
+    format(at: string, options?: {
+        timeZone?: string;
+        style?: 'datetime' | 'date' | 'time';
+    }): Promise<string>;
+    /** The calendar day (`YYYY-MM-DD`) at `at` in `timeZone` (default `zone`), to compare days or key a rule by date. */
+    day(at: string | number, timeZone?: string): Promise<string>;
+    /** The exact moment (ISO, UTC) a clock in `timeZone` (default `zone`) shows `date` at `time` (`HH:mm`), 74 §4.7. */
+    at(date: string, time: string, timeZone?: string): Promise<string>;
+    /** `at` on a clock in `timeZone` (default `zone`): date, `HH:mm`, hour, minute, ISO weekday, offset (74 §4.7). */
+    parts(at: string | number, timeZone?: string): Promise<TimeParts>;
+};
+/**
+ * A text the customer sent since the last run (20 §5.2): what this run is for. `earlier`: sent before,
+ * in a run that failed, and not answered yet (20 §5.4).
+ */
+export type PageSmsMessage = {
+    id: string;
+    body: string;
+    at: string;
+    earlier?: boolean;
+};
+/** An email the customer sent since the last run (20 §5.2), quoted history and signature taken out. */
+export type PageEmailMessage = {
+    id: string;
+    from: string;
+    to: string[];
+    cc: string[];
+    subject: string | null;
+    body: string;
+    at: string;
+    /** Listed only (20 §7): their contents are not read yet. */
+    attachments: Array<{
+        name: string;
+        contentType?: string;
+    }>;
+    /** Sent before, in a run that failed, and not answered yet (20 §5.4). */
+    earlier?: boolean;
+};
+/**
+ * This person's previous call on this case (21 §5.2): the facts a page decides by whether to pick up where it
+ * left off (a line dropped a minute ago) or open as usual (a call a week ago, or one handed to a person). A
+ * new call never carries the previous one's conversation or session fields.
+ */
+export type PagePreviousCall = {
+    /** ISO time it ended. */
+    endedAt: string;
+    direction: Direction;
+    /** How the call went: connected, no_answer, busy, failed, fallback, apology. */
+    outcome: string | null;
+    /** How its conversation ended, when the AI took it: `hangup` (the line closed: the caller hung up, or it dropped), `end` (the AI ended it), `transfer`, `error`. */
+    endedBy: string | null;
+    /** Its last lines, oldest first. */
+    lastLines: Array<{
+        speaker: 'party' | 'ai';
+        text: string;
+    }>;
+};
+/**
+ * A voicemail greeting answered the outbound call, as the voice service tells it (65 §3.1); `said`: what
+ * it said. The page decides what to do: leave a message (`doNow(voicemail({ … }))`), or end (a full mailbox). A page
+ * that returns nothing for it has the voice service hang up. Anything else that answers (a person, a
+ * call-screening assistant, a phone menu) the page's model tells from the words; the page writes what to do.
+ */
+export type PageFarEnd = {
+    kind: 'voicemail';
+    said: string;
+};
+/**
+ * The words this render answers (65 §3.2): what the person just said; `first`, the far end's first words
+ * on an outbound call, before the AI said anything (a "Hello?" can get the opening line at once, a long
+ * first sentence is the model's to answer). Null when the render answers no words (the opening, an event).
+ */
+export type PageHeard = {
+    text: string;
+    first: boolean;
+};
+/** What only a call has (20 §5.2): on `ctx.call`. A call's own buttons (transfers, `keypad`) are left off a text's page (76 §2.12). */
+export type PageCallCaps = {
+    /** This person's previous call on this case; null when there is none. */
+    previous: PagePreviousCall | null;
+    /** A voicemail answered, once the voice service knows (65 §3.1); null otherwise, and on an inbound call. */
+    farEnd: PageFarEnd | null;
+    /** The words this render answers (65 §3.2); null when it answers none. */
+    heard: PageHeard | null;
+    /**
+     * `live` while the call is on the line; `wrapup` once it has hung up and the AI finishes what the call
+     * left (40 §2.5): fields, buttons that need no line, notes. Nothing said is heard then.
+     */
+    phase: PageCallPhase;
+};
+/** Where a call is (40 §2.5): on the line, or its wrap-up after the hang-up. */
+export type PageCallPhase = 'live' | 'wrapup';
+/** What each channel adds to the page function's context (20 §5.2). */
+export type PageChannelCaps = {
+    call: {
+        call: PageCallCaps;
+    };
+    sms: {
+        sms: {
+            inbound: PageSmsMessage[];
+        };
+    };
+    email: {
+        email: {
+            inbound: PageEmailMessage[];
+            mailbox: string;
+        };
+    };
+};
+/** The context of one channel's page function. */
+export type PageContextOf<C extends PageChannel> = PageBaseContext & {
+    channel: C;
+} & PageChannelCaps[C];
+/** Any channel's context: what a helper shared by several page functions takes (switch on `channel`). */
+export type PageContext = {
+    [C in PageChannel]: PageContextOf<C>;
+}[PageChannel];
+export type ActionContext = {
+    db: Db;
+    subject: string;
+    caller: PageRow | null;
+    /**
+     * On a call, this party's session for this case (25 §9), as `ctx.session` on the page; null by text and
+     * email. `db.session.update({ where: { id: session.id }, data })` writes it in the action's transaction.
+     */
+    session: PageRow | null;
+    now: string;
+};
+/**
+ * Page settings of a cell `field(...)` opens: `readOnly` to show it with these settings without opening
+ * it, and `expand` to show the AI its definition (type, allowed values, how to fill it; 24 §2.2), not
+ * shown when left out. How to fill a field on this page is the page's `$extraction`, one per field for
+ * the whole page (26 §15.3); `extraction` here is refused. `hint` was renamed and is refused;
+ * `required` was removed (24 §2.3).
+ */
+export type FieldOptions = {
+    readOnly?: boolean;
+    expand?: boolean;
+    extraction?: MovedOption<'$extraction'>;
+    hint?: MovedOption<'$extraction'>;
+    required?: RemovedOption;
+};
+/** A removed option: any value is a type error. */
+export type RemovedOption = never;
+/** A removed option: any value is a type error whose message names the new one. */
+export type RenamedOption<New extends string> = `renamed: use ${New}`;
+/** An option that moved to the page: any value is a type error whose message names where it went. */
+export type MovedOption<Where extends string> = `moved: use the page's ${Where}`;
+export type FieldCell<S = Slot> = {
+    $field: true;
+    slot: S;
+    readOnly?: boolean;
+    expand?: boolean;
+};
+/** A row a ref field may point at, and what the AI sees of it (26 §16.2 #7). */
+export type RefOption = {
+    id: string;
+    label: string;
+};
+export type RefFieldOptions = {
+    /**
+     * The rows it may point at, with their labels: `[{ id, label }]`, or `choose(rows, label)`. Read-only:
+     * only to label the current value (put the current row in it). None: only the row's name is shown.
+     */
+    options?: readonly RefOption[] | ChooseParam;
+    readOnly?: boolean;
+};
+/** A ref field on the page (26 §16.2 #7): its candidates given by the page, each with its label. */
+export type RefFieldCell<S = Slot> = {
+    $refField: true;
+    slot: S;
+    options: RefOption[];
+    readOnly?: boolean;
+};
+/**
+ * A parameter taken from the schema (an added row's fields, `createRow(table, { fields })`): the platform fills
+ * in its type, allowed values and `extraction`. `table.id`, or a lookup field, chooses a row on the page.
+ */
+export type SchemaFieldParam = {
+    $schemaField: string;
+    extraction?: string;
+};
+/** One parameter of an action: plain JSON Schema as the build reads it from a function's `args` type (38 §2.4), or a schema field. */
+export type ActionParam = SchemaFieldParam | {
+    type: 'string' | 'number' | 'integer' | 'boolean';
+    description?: string;
+    enum?: Array<string | number>;
+}
+/** A row of `table` (`Id<'table'>`, 38 §2.4): the page prefills it or gives the rows to choose among. */
+ | {
+    type: 'ref';
+    table: string;
+    description?: string;
+}
+/** A string in a format (`IsoDate`, `Phone`…, 38 §2.4). */
+ | {
+    type: 'date' | 'datetime' | 'time' | 'phone' | 'email';
+    description?: string;
+}
+/** When a contact may be reached (`ContactSchedule`, 25 §3): checked as a contact_schedule field's value is. */
+ | {
+    type: 'contact_schedule';
+    description?: string;
+} | {
+    type: 'array';
+    items: ActionParam;
+    description?: string;
+} | {
+    type: 'object';
+    properties: Record<string, ActionParam>;
+    required?: string[];
+    description?: string;
+};
+/** An action's `parameters`, as an LLM function call declares them. */
+export type ActionParameters = {
+    type: 'object';
+    properties: Record<string, ActionParam>;
+    required?: string[];
+};
+export type CreateRowAction = {
+    $action: 'createRow';
+    table: string;
+    /** The run key (`runKey`); without it, `createRow:<table>`. */
+    key?: string;
+    label?: string;
+    description?: string;
+    fields: string[];
+    required: string[];
+    /** Preset values (the parent, `status: 'active'`): kept on the server, never shown to the AI. */
+    prefill: Record<string, unknown>;
+};
+export type DeleteRowAction = {
+    $action: 'deleteRow';
+    rowId: string;
+    /** The run key (`runKey`); without it, `deleteRow:<row id>`. */
+    key?: string;
+    label?: string;
+    description?: string;
+    reason?: string;
+};
+export type CustomAction = {
+    $action: 'custom';
+    name: string;
+    /** How to fill each parameter on this page, by name (`run(…, { args })`, 31 §7): replaces the parameter's own. */
+    args?: Record<string, string>;
+    /** What the AI sees as its title (`button({ title })`); without it, `name`. */
+    label?: string;
+    /** The run key (`runKey`); without it, `name`. */
+    key?: string;
+    /** What the AI sees it does (`button({ does })`). */
+    description?: string;
+    /** What it takes; without them, its `args` type's, as the build read it (38 §2.9). */
+    parameters?: ActionParameters;
+    /** Parameters filled where the page placed the action: kept on the server, never shown to the AI. */
+    prefill: Record<string, unknown>;
+};
+/**
+ * A company function (`functions/`, 38 §2.1) as a button, or returned by the page function to
+ * run now (20 §6.2). It runs on the Worker, outside the page's transaction, and is waited for; on a call,
+ * `say` is said first and the customer cannot interrupt until it is done (20 §6.3).
+ */
+export type FunctionAction = {
+    $action: 'function';
+    name: string;
+    /** How to fill each parameter on this page, by name (`run(…, { args })`, 31 §7): replaces the parameter's own. */
+    args?: Record<string, string>;
+    /** The run key (`runKey`); without it, `name`. */
+    key?: string;
+    label?: string;
+    description?: string;
+    /** Said first, verbatim, on a call only (ignored elsewhere), in the call's language (66): the customer only listens meanwhile. */
+    say?: Spoken;
+    /** What the AI fills: plain JSON Schema or schema fields, as a custom action's. */
+    parameters?: ActionParameters;
+    /** Parameters the page fills (a row's id) or offers rows for (`choose(...)`, 25 §10); kept on the server. */
+    prefill?: Record<string, unknown>;
+};
+/**
+ * The rows a row parameter may be chosen among (25 §10), with what the AI sees of each:
+ * `cancel({ appointment: choose(appointments, (a) => `${a.date.value} with ${a.provider.value}`) })`. The
+ * candidates are these rows, wherever else the page shows them (or not); none: the button is left off.
+ */
+export type ChooseParam = {
+    $choose: true;
+    table: string | null;
+    options: Array<{
+        id: string;
+        label: string;
+    }>;
+};
+export declare function choose<R extends PageRow>(rows: readonly R[], label: (row: R) => string): ChooseParam;
+export declare function isChoose(value: unknown): value is ChooseParam;
+/** A platform tool on the page (76 §2.18): the AI presses it like a button and reads its result next turn. */
+export type ToolAction = {
+    $action: 'tool';
+    tool: PageToolName;
+};
+/** The platform's tools (76 §2.18). */
+export type PageToolName = 'pressKeypad' | 'convertTime';
+export declare const PAGE_TOOLS: readonly PageToolName[];
+export type PageAction = CreateRowAction | DeleteRowAction | CustomAction | ChannelAction | FunctionAction | FollowUpAction | CancelFollowUpAction | ToolAction;
+/** Hand the call to a person. */
+export type TransferAction = {
+    $action: 'channel';
+    channel: 'transfer';
+    /** E.164 number to dial, or a SIP URI (`sip:desk@pbx.example.com`, headers after `?`). */
+    to: string;
+    /** A SIP `to` that asks for credentials: kept on the server, never on the page the AI reads. */
+    sipAuth?: {
+        username: string;
+        password: string;
+    };
+    /**
+     * The caller ID the person sees: the customer's number or ours (default: the voice service's own rule).
+     * A call that came in by SIP shows ours to a phone number whatever is asked (the carrier refuses it).
+     */
+    callerId?: 'customer' | 'service';
+    /**
+     * cold: connect and leave; warm: brief the person first with `briefing`, the customer on hold meanwhile;
+     * background: warm, but the AI keeps talking with the customer while the person is called, and the
+     * customer is put through once the person takes it. Nobody takes it: the conversation simply goes on.
+     */
+    mode: 'cold' | 'warm' | 'background';
+    /**
+     * What the briefing should cover (74 §3.3): the very words, or an instruction ("say who is calling and
+     * why"). A model writes it as two or three sentences read aloud to the person, from this and the
+     * conversation so far (at the opening, from this alone), in their `language`; field names, underscores
+     * and codes are said the way a person would say them.
+     */
+    briefing?: string;
+    /**
+     * Warm and background (76 §2.9): what the person hears on a loop when they pick up, before they confirm:
+     * who it is and what about. The platform adds how to confirm; without it, "You have a call from {company}".
+     * English for now, whatever `language` says.
+     */
+    whisper?: string;
+    /**
+     * Background only: what is said as the two are put through. `person`: to the person, once they take
+     * the call (`{{briefing}}` is the briefing; without it, the briefing). `customer`: to the customer, in
+     * their language (66: per language; without it, a chime only).
+     */
+    bridge?: {
+        person?: string;
+        customer?: Spoken;
+    };
+    /**
+     * The language of the person taking the call (BCP-47; default `en`), not the customer's (48 §10.3): what
+     * is said to them (the briefing, the waiting line) is said and written in it, and they are heard in it.
+     */
+    language?: string;
+    /** The run key (`runKey`): two transfers on a page apart; without it, `transfer`. */
+    key?: string;
+    label?: string;
+    description?: string;
+};
+/** Collect keypresses on a call: what was pressed is written to `write` (through `map` when given). */
+export type KeypadAction = {
+    $action: 'channel';
+    channel: 'keypad';
+    /** The run key: `tried(ctx.runs, key)` after the first try. */
+    key: string;
+    /** Said once, verbatim, before waiting for a key, in the call's language (66). */
+    say: Spoken;
+    /** The keys that count. */
+    digits: string[];
+    timeoutMs: number;
+    /** Where the key goes: a slot read from db. */
+    write?: SlotRef;
+    /** Pressed key → value written (`{ '1': 'en', '2': 'es' }`); without it the key itself. */
+    map?: Record<string, string | number | boolean>;
+    label?: string;
+    description?: string;
+};
+/**
+ * Say a fixed text, verbatim and not interruptible (a compliance statement), in the call's language (66).
+ * After it, the model answers what the customer said; `answers`: the text is that answer (an opening line
+ * for a "Hello?", 65 §3.2), and nothing more is said after it.
+ */
+export type AnnounceAction = {
+    $action: 'channel';
+    channel: 'announce';
+    key: string;
+    text: Spoken;
+    answers?: true;
+};
+/** End the conversation (a call hangs up once the last line has played; an SMS conversation closes). */
+export type EndAction = {
+    $action: 'channel';
+    channel: 'end'; /** The run key; without it, `end`. */
+    key?: string;
+    label?: string;
+    description?: string;
+};
+/**
+ * Leave a message on the voicemail (25 §13): after its beep, word for word (what a regulated business may
+ * leave is fixed), then hang up. The call's outcome is `voicemail`.
+ */
+export type VoicemailAction = {
+    $action: 'channel';
+    channel: 'voicemail'; /** Per language (66). */
+    text: Spoken; /** The run key; without it, `voicemail`. */
+    key?: string;
+    label?: string;
+    description?: string;
+};
+export type ChannelAction = TransferAction | KeypadAction | AnnounceAction | EndAction | VoicemailAction;
+export declare function transferTo(options: {
+    to: string;
+    sipAuth?: TransferAction['sipAuth'];
+    callerId?: TransferAction['callerId'];
+    mode?: TransferAction['mode'];
+    briefing?: string;
+    whisper?: string;
+    bridge?: TransferAction['bridge'];
+    language?: string;
+    label?: string;
+    description?: string;
+}): TransferAction;
+/** Whether a transfer's `to` is a SIP URI rather than a phone number. */
+export declare function isSipUri(to: string): boolean;
+export declare function keypadAction(key: string, options: {
+    say: Spoken;
+    digits: string[];
+    timeoutMs?: number;
+    write?: Slot | SlotRef;
+    map?: Record<string, string | number | boolean>;
+    label?: string;
+    description?: string;
+}): KeypadAction;
+/** A company function as a button (20 §6.2): `runFunction('importOrders', { label, say, parameters })`. */
+export declare function runFunction(name: string, options?: {
+    label?: string;
+    description?: string;
+    say?: Spoken;
+    parameters?: ActionParameters;
+    prefill?: Record<string, unknown>;
+}): FunctionAction;
+export declare function announceAction(key: string, text: Spoken, options?: {
+    answers?: boolean;
+}): AnnounceAction;
+export declare function voicemailAction(text: Spoken, options?: {
+    label?: string;
+    description?: string;
+}): VoicemailAction;
+export declare function endAction(options?: {
+    label?: string;
+    description?: string;
+}): EndAction;
+/** Every channel a page may be written for, in order. */
+export declare const PAGE_CHANNELS: readonly PageChannel[];
+/** A page function: the page for one channel, or an action to run now (17b §9.1, §9.8). */
+export type PageFunction<D> = (ctx: PageContext) => D | Promise<D>;
+/**
+ * Who the employee is and how they talk on this conversation's channel (`ctx.channel`), and the FAQ the
+ * AI may look things up in (24 §4). Called once, when the conversation starts, with the page's context
+ * at that moment; what they return holds for the whole conversation (the head of every prompt).
+ */
+export type PagePersona = (ctx: PageContext) => string | Promise<string>;
+export type PageFaq = (ctx: PageContext) => PageFaqEntry[] | Promise<PageFaqEntry[]>;
+export type PageDefinition<D> = {
+    persona: PagePersona;
+    faq?: PageFaq;
+    call?: (ctx: PageContextOf<'call'>) => D | Promise<D>;
+    sms?: (ctx: PageContextOf<'sms'>) => D | Promise<D>;
+    email?: (ctx: PageContextOf<'email'>) => D | Promise<D>;
+};
+export type DefinedPage<D> = {
+    kind: 'page';
+    persona: PagePersona;
+    faq: PageFaq | null;
+    channels: Partial<Record<PageChannel, PageFunction<D>>>;
+};
+/**
+ * `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 declare function definePage<D>(definition: PageDefinition<D>): DefinedPage<D>;
+/**
+ * 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 declare function checkPageStart(raw: unknown): PageStart;
+/**
+ * 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 declare function refFieldCell<S extends Slot>(slot: S, options?: RefFieldOptions): RefFieldCell<S>;
+export declare function fieldCell<S extends Slot>(slot: S, options?: FieldOptions): FieldCell<S>;
+/**
+ * An action placed on a page: call it to prefill parameters (`addProvider({ injury: i.id })`), or place
+ * it as it is (nothing prefilled).
+ */
+export type Placeable<A extends PageAction, P> = (prefill?: P) => A;
+/** Add a row (15 §10.6): `fields` are what the AI fills; call it to preset the rest (`({ status: 'active' })`). */
+export declare function createRowAction(table: TableReader | string, options: {
+    fields: readonly string[];
+    required?: readonly string[];
+    label?: string;
+    description?: string;
+}): Placeable<CreateRowAction, Record<string, unknown>>;
+/** Delete a row (cascading, 15 §10.6.1): a built-in action with the row prefilled and nothing to fill. */
+export declare function deleteRowAction(row: PageRow | string, options?: {
+    reason?: string;
+    label?: string;
+    description?: string;
+}): DeleteRowAction;
+/** The environment's configuration on a page (76 §2.19), read only. */
+export type PageEnv = {
+    get<T = unknown>(key: string): T | null;
+};
+export type PageEntryArg = {
+    /** `start`: `persona` and `faq` once, when the conversation starts (24 §4), with the same context. */
+    mode: 'render' | 'start';
+    /** The page function to run; outside a conversation, the first one the page defines. */
+    channel: PageChannel | null;
+    subject: string;
+    /** The instance this conversation is on (38 §2.2: a function that needs it is prefilled it). */
+    instanceId: string;
+    caller: PageRow | null;
+    session: PageRow | null;
+    conversation: PageConversation | null;
+    runs: PageRuns;
+    scheduledAction: PageScheduledAction | null;
+    officeHours: PageContext['officeHours'];
+    nextSteps?: PageNextStep[];
+    now: string;
+    /** The contact's time zone and today there (25 §11). */
+    time?: {
+        zone: string;
+        today: string;
+    };
+    /** The environment's configuration (76 §2.19): its `env` integrations' values by key, as functions read them. */
+    env?: Record<string, unknown>;
+    /** What the customer sent since the last run (20 §5.2): a text run's texts, an email run's emails. */
+    sms?: {
+        inbound: PageSmsMessage[];
+    };
+    email?: {
+        inbound: PageEmailMessage[];
+        mailbox: string;
+    };
+    call?: {
+        previous: PagePreviousCall | null;
+        farEnd?: PageFarEnd | null;
+        heard?: PageHeard | null;
+        phase?: PageCallPhase;
+    };
+}
+/** The channels with a page function: read once, when the sequence is compiled. */
+ | {
+    mode: 'channels';
+} | {
+    mode: 'action';
+    name: string;
+    /** The prefilled parameters and the AI's, merged. */
+    args: Record<string, unknown>;
+    subject: string;
+    caller: PageRow | null;
+    session: PageRow | null;
+    now: string;
+};
+/** No runs yet. */
+export declare function emptyRuns(): PageRuns;
+/**
+ * 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 declare function pageEntry(mod: Record<string, unknown>, actionsModule?: Record<string, unknown> | null): (arg: PageEntryArg) => unknown;
+//# sourceMappingURL=define.d.ts.map