@superpanel-sdk/runtime 0.5.0 → 0.7.0

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

@@ -1,6 +1,6 @@
 /**
  * The page module's types bound to one sequence (15 §10.15): what `__gen/index.ts` exports as
- * `definePage`, `field`, `schemaField`, `createRow`, `deleteRow` and `defineAction`. Behaviour is
+ * `definePage`, `field`, `createRow` and `deleteRow`. Behaviour is
  * `define.ts`'s; this file only types it.
  *
  * Everything starts from `PageTables`, generated per sequence into `__gen/slots.type.ts`: for each
@@ -15,15 +15,34 @@
  *    18-record-search-index §4.6), `include` of lookups and ways back only, `some` / `every` / `none` on
  *    a way back (13-data-model-v1 §23.4);
  *  - an action's arguments come from its `parameters`; `db.<table>`'s writes take only that table's fields;
- *  - the page is the conversation's: code (functions, event handlers, the Orchestrator) gets the case
- *    (`CaseInput`) and reads with `ctx.api.db`.
+ *  - the page is the conversation's: code (functions, event handlers, the Orchestrator) is called
+ *    `(ctx, args)` and reads with `ctx.api.db`.
  */
-import type { PageTime, ChooseParam, CreateRowAction, CustomAction, DeleteRowAction, FieldCell, FieldOptions, RefFieldCell, RefOption, MessageAction, MessageOptions, PageBaseContext, PageChannel, PageChannelCaps, PageConversation, PageFaq, PageFaqEntry, PageHistory, PagePersona, PageRuns, PageScheduledAction, Placeable, SchemaFieldOptions, SlotState } from './define.js';
+import type { Action, AllPrefilled, DoNode, FieldNode, FullPrefill, FunctionHandle, KeyedOf, LeftForAi, PageActionHandle, PageContent, PageNode, PageSettings, RequiredKeys, RunAction, AnyRunHandle, RunArgs, SameArgs, SayOf } from './fns.js';
+import type { PageTime, ChooseParam, RefOption, PageBaseContext, PageChannel, PageChannelCaps, PageConversation, PageFaq, PageFaqEntry, PageHistory, PagePersona, PageRuns, PageScheduledAction, SlotState } from './define.js';
 declare const ID_BRAND: unique symbol;
 /** A row id of table `T`: an `Id<'injuries'>` is not an `Id<'providers'>`, and no string is an id. */
 export type Id<T extends string = string> = string & {
     readonly [ID_BRAND]: T;
 };
+declare const FORMAT_BRAND: unique symbol;
+/**
+ * A string in a format the AI is told (38 §2.4): any string is one, and the builder reads the mark to
+ * show the parameter as `date`, `phone`…; one format is not another.
+ */
+type Formatted<F extends string> = string & {
+    readonly [FORMAT_BRAND]?: F;
+};
+/** A calendar date, `YYYY-MM-DD`: the AI sees `date`. */
+export type IsoDate = Formatted<'date'>;
+/** An instant, ISO 8601 with an offset or Z: the AI sees `datetime`. */
+export type IsoDateTime = Formatted<'datetime'>;
+/** A time of day, `HH:mm`: the AI sees `time`. */
+export type TimeOfDay = Formatted<'time'>;
+/** A phone number: the AI sees `phone`. */
+export type Phone = Formatted<'phone'>;
+/** An email address: the AI sees `email`. */
+export type Email = Formatted<'email'>;
 /** One field, as `__gen/slots.type.ts` describes it. */
 export type PageFieldDesc = {
     value: unknown;
@@ -210,9 +229,10 @@ type ScalarFilterOf<V> = V | null | {
     lte?: V;
     gt?: V;
     gte?: V;
-    contains?: string;
+    /** A text's beginning; there is no `contains` / `endsWith`: find by a beginning or an exact field (34 §10). */
     startsWith?: string;
-    endsWith?: string;
+    /** `insensitive`: text compared in any case (`equals`, `in`, `startsWith`, ranges). */
+    mode?: 'default' | 'insensitive';
     /** By the slot's state (`asked_unknown`, `declined`, …): the one extension to Prisma's `where`. */
     state?: SlotState;
 };
@@ -320,14 +340,23 @@ type SelectKey<D, T extends keyof D, S> = {
 } | {
     select: S & ExactSelect<D, T, S>;
 };
+/**
+ * `after`: a row of the table as read, whatever its `include` / `select` (normally the last of the page
+ * before); the rows strictly after it in the read's order come (define.ts `FindArgs.after`).
+ */
+type AfterRow<T> = Readonly<{
+    id: Id<T & string>;
+    createdAt?: string;
+    updatedAt?: string;
+}> & {
+    readonly [field: string]: unknown;
+};
 export type FindManyArgs<D, T extends keyof D, I = IncludeArg<D, T>, S = SelectArg<D, T>> = IncludeKey<D, T, I> & SelectKey<D, T, S> & {
     where: Where<D, T>;
     orderBy?: OrderByArg<D, T>;
     take?: number;
     skip?: number;
-    cursor?: {
-        id: Id<T & string>;
-    };
+    after?: AfterRow<T>;
 };
 /** `findUnique`: by `id`; null when there is no such row. */
 export type FindUniqueArgs<D, T extends keyof D, I = IncludeArg<D, T>, S = SelectArg<D, T>> = IncludeKey<D, T, I> & SelectKey<D, T, S> & {
@@ -428,10 +457,12 @@ type TypedPageBaseContext<D, S extends string> = {
     scheduledAction: PageScheduledAction | null;
     /** The sequence's office hours now; null when it has none. */
     officeHours: PageBaseContext['officeHours'];
-    /** The contact's agreed follow-ups still to come (09). */
-    followUps: PageBaseContext['followUps'];
+    /** The case's next step (40 §2.2): its pending contacts, soonest first; the platform shows it before the page. */
+    nextSteps: PageBaseContext['nextSteps'];
     /** The business root's id. */
     subject: Id<S>;
+    /** 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: RowIfTable<D, 'contact'> | null;
     /** This conversation's session row (the session fields, cells); null outside one. */
@@ -442,21 +473,10 @@ type TypedPageBaseContext<D, S extends string> = {
     history: PageHistory;
     /** ISO timestamp of this render. */
     now: string;
-    /** A text or an email to send now (25 §8): `ctx.messages.text('link', { body })`. */
-    messages: TypedPageMessages<D>;
     /** The contact's time zone, today there, and `format` for a time as people read it (25 §11). */
     time: PageTime;
-};
-type TypedMessageOptions<D> = Omit<MessageOptions, 'to'> & {
-    /** The contact it goes to (a contact row the page read); absent: the contact of this conversation. */
-    to?: RowIfTable<D, 'contact'> | Id<'contact'>;
-};
-/** `ctx.messages`, its `to` a contact of this company. */
-export type TypedPageMessages<D> = {
-    text(key: string, options?: TypedMessageOptions<D>): MessageAction;
-    email(key: string, options?: TypedMessageOptions<D> & {
-        subject?: string;
-    }): MessageAction;
+    /** The environment's configuration, read only (76 §2.19): `ctx.env.get('callback_number')`. */
+    env: PageBaseContext['env'];
 };
 export type TypedActionContext<D, S extends string> = {
     db: TypedDb<D>;
@@ -466,106 +486,41 @@ export type TypedActionContext<D, S extends string> = {
     session: RowIfTable<D, 'session'> | null;
     now: string;
 };
-/** `table.field` (or `table.id`, a row) of this sequence: what `schemaField` takes. */
-export type SchemaFieldPath<D> = {
-    [T in TableOf<D>]: `${T}.id` | `${T}.${FieldOf<D, T>}`;
-}[TableOf<D>];
-export type TypedSchemaFieldParam<P extends string> = {
-    readonly $schemaField: P;
-    readonly extraction?: string;
-};
-/** One parameter: a schema field, or plain JSON Schema (an LLM function call's `parameters`). */
-export type TypedActionParam<D> = TypedSchemaFieldParam<SchemaFieldPath<D>> | {
-    readonly type: 'string';
-    readonly description?: string;
-    readonly enum?: readonly string[];
-} | {
-    readonly type: 'number' | 'integer';
-    readonly description?: string;
-    readonly enum?: readonly number[];
-} | {
-    readonly type: 'boolean';
-    readonly description?: string;
-} | {
-    readonly type: 'array';
-    readonly items: TypedActionParam<D>;
-    readonly description?: string;
-} | {
-    readonly type: 'object';
-    readonly properties: {
-        readonly [key: string]: TypedActionParam<D>;
-    };
-    readonly required?: readonly string[];
-    readonly description?: string;
-};
-export type TypedActionParameters<D> = {
-    readonly type: 'object';
-    readonly properties: {
-        readonly [key: string]: TypedActionParam<D>;
-    };
-    readonly required?: readonly string[];
-};
-/** What `run` gets for one parameter. */
-type ParamValue<D, P> = P extends {
-    $schemaField: `${infer T}.${infer F}`;
-} ? T extends keyof D ? F extends 'id' ? Id<T> : ValueOf<D, T, F> : never : P extends {
-    type: 'string';
-    enum: readonly (infer E)[];
-} ? E : P extends {
-    type: 'string';
-} ? string : P extends {
-    type: 'number' | 'integer';
-    enum: readonly (infer E)[];
-} ? E : P extends {
-    type: 'number' | 'integer';
-} ? number : P extends {
-    type: 'boolean';
-} ? boolean : P extends {
-    type: 'array';
-    items: infer I;
-} ? Array<ParamValue<D, I>> : P extends {
-    type: 'object';
-    properties: infer Props;
-} ? ArgsOf<D, {
-    properties: Props;
-    required: P extends {
-        required: infer R;
-    } ? R : [];
-}> : never;
-type RequiredOf<P> = P extends {
-    required: readonly (infer R)[];
-} ? R : never;
-/** What `run` gets: every parameter, required ones present, others optional. */
-export type ArgsOf<D, P> = P extends {
-    properties: infer Props;
-} ? Simplify<{
-    -readonly [K in Extract<keyof Props, RequiredOf<P>>]: ParamValue<D, Props[K]>;
-} & {
-    -readonly [K in Exclude<keyof Props, RequiredOf<P>>]?: ParamValue<D, Props[K]>;
-}> : Record<never, never>;
 declare const CHOOSE_BRAND: unique symbol;
 /** `choose(rows, label)` over rows of `T` (25 §10): the rows a row parameter of `T` is chosen among. */
 export type TypedChoose<T extends string> = ChooseParam & {
     readonly [CHOOSE_BRAND]?: T;
 };
-/** What a placed action is called with: a value, or for a row parameter its row's id or `choose(...)` (25 §10). */
+/**
+ * What the page fixed of an action's parameters (35 §2): values, a row parameter by its row's id; an
+ * optional one also `null`, none (the AI is not asked).
+ */
 export type PrefillOf<A> = {
-    [K in keyof A]?: A[K] | (NonNullable<A[K]> extends {
-        readonly [ID_BRAND]: infer T extends string;
-    } ? TypedChoose<T> : never);
-};
+    [K in keyof A]?: A[K] | (undefined extends A[K] ? null : never);
+};
+/** The parameters of `A` that are rows. */
+type RowKeys<A> = {
+    [K in keyof A]-?: NonNullable<A[K]> extends {
+        readonly [ID_BRAND]: string;
+    } ? K : never;
+}[keyof A];
 /**
- * A custom action: called to prefill arguments (`markError({ injury: i.id })`, one button per row) or to
- * offer the rows a row argument is chosen among (`cancel({ appointment: choose(rows, label) })`, 25 §10).
- * Placing it as it is leaves a row argument to the rows the page happens to show: not recommended.
+ * The rows the AI chooses a row parameter among, each with its label (35 §2): `choose(rows, label)`.
+ * With no row parameter there is nothing to choose: `options` takes nothing (`{}` would take anything).
  */
-export type TypedDefinedAction<A> = Placeable<CustomAction, PrefillOf<A>> & {
-    readonly actionName: string;
+export type OptionsOf<A> = [RowKeys<A>] extends [never] ? never : {
+    [K in RowKeys<A>]?: NonNullable<A[K]> extends {
+        readonly [ID_BRAND]: infer T extends string;
+    } ? TypedChoose<T> : never;
 };
+/** A page action's function (76 §2.11): `(ctx, args)`; what it is called with is the button's `prefill` and what the AI fills. */
+export type PageActionFn<A> = (ctx: never, args: A) => unknown;
+/** What a page function returns: `page(…)`, or `doNow(…)` to do something first (76). */
+export type PageResult = PageNode | DoNode;
 /** The page module of one sequence: `D` its tables (`PageTables`), `S` its business root table. */
 export type TypedPageModule<D, S extends string> = {
     /** Each channel's page is its own (17b §9.1): what a call shows and what a text shows may differ. */
-    definePage<Call = never, Sms = never, Email = never>(definition: {
+    definePage<Call extends PageResult = never, Sms extends PageResult = never, Email extends PageResult = never>(definition: {
         /** Called once when the conversation starts (24 §4): the persona for `ctx.channel`. */
         persona: (ctx: TypedPageContext<D, S>) => string | Promise<string>;
         /** Called once when the conversation starts (24 §4): the FAQ, at most 100 entries. */
@@ -583,60 +538,111 @@ export type TypedPageModule<D, S extends string> = {
             email?: (ctx: TypedPageContext<D, S, 'email'>) => Email | Promise<Email>;
         };
     };
-    field<Sl extends TypedSlot<unknown, string, string>>(slot: Sl, options?: FieldOptions): FieldCell<Sl>;
-    /** A ref field (26 §16.2 #7): the rows it may point at, `{ id, label }` each, or `choose(rows, label)`. */
-    refField<Sl extends TypedSlot<unknown, string, string>>(slot: Sl, options?: {
-        options?: ReadonlyArray<RefOption & {
-            id: Sl['value'] & string;
-        }> | ChooseParam;
-        readOnly?: boolean;
-    }): RefFieldCell<Sl>;
-    schemaField<const P extends SchemaFieldPath<D>>(path: P, options?: SchemaFieldOptions): TypedSchemaFieldParam<P>;
-    createRow<T extends TableOf<D>, const F extends readonly Exclude<FieldOf<D, T>, ParentOf<D, T>>[]>(table: T | {
-        readonly $table: T;
-    }, options: {
-        fields: F;
-        required?: ReadonlyArray<F[number]>;
-        label?: string;
-        description?: string;
-    }): Placeable<CreateRowAction, Partial<CreateData<D, T>>>;
-    deleteRow(row: Id<TableOf<D>> | {
-        readonly id: Id<TableOf<D>>;
-    }, options?: {
-        reason?: string;
-        label?: string;
-        description?: string;
-    }): DeleteRowAction;
     /** The rows a row parameter is chosen among, each with what the AI sees of it (25 §10). */
     choose<R extends {
         readonly id: Id<TableOf<D>>;
     }>(rows: readonly R[], label: (row: R) => string): TypedChoose<R['id'] extends {
         readonly [ID_BRAND]: infer T extends string;
     } ? T : never>;
-    defineAction<const P extends TypedActionParameters<D> = {
-        type: 'object';
-        properties: {};
-    }>(definition: {
-        name: string;
-        description: string;
-        parameters?: P;
-        run: (args: ArgsOf<D, P>, ctx: TypedActionContext<D, S>) => unknown;
-    }): TypedDefinedAction<ArgsOf<D, P>>;
-};
-/** What a page function may return instead of the page (17b §9.8): an action to run first. */
-type ReturnedAction = {
-    $action: string;
-} | {
-    $perform: true;
-} | ((...args: never[]) => unknown);
+};
+type AnySlot = TypedSlot<unknown, string, string>;
+/** What a function takes: its `args`, the second parameter of `(ctx, args)` (38 §2.1). */
+export type FunctionParamsOf<Fn> = Fn extends (...args: infer A) => unknown ? A extends [unknown, infer P, ...unknown[]] ? P extends object ? P : Record<never, never> : Record<never, never> : Record<never, never>;
+/** `table.field` of this sequence: how the page says to fill it (`page({ extraction })`). */
+type FieldPathOf<D> = {
+    [T in TableOf<D>]: `${T}.${FieldOf<D, T>}`;
+}[TableOf<D>];
+/** `fn` of `__gen` (76 §2.15): a handle per company function, its `args` type the function's. */
+export type FunctionHandles<F> = {
+    readonly [N in keyof F & string]: FunctionHandle<N, FunctionParamsOf<F[N]>>;
+};
+/**
+ * `act` of `__gen` (76 §2.11): a handle per page action of `actions.ts`, its `args` type the action's. An
+ * action takes the page action's `ctx` (`ActionCtx`): one written for another (a company function's `Ctx`)
+ * has no handle, and `run()` says so.
+ */
+export type ActionHandles<A, D, S extends string> = {
+    readonly [N in keyof A & string]: A[N] extends (ctx: TypedActionContext<D, S>, ...rest: never[]) => unknown ? PageActionHandle<N, FunctionParamsOf<A[N]>> : `actions.${N} takes (ctx: ActionCtx, args): the page action's ctx`;
+};
+/** Add a row of `T` (15 §10.6): `fields` the AI fills, `prefill` what the page fixed, `options` a ref field's rows. */
+type CreateRowOptions<D, T extends TableOf<D>> = {
+    /** What the AI fills; a ref field is chosen in `options` instead (35 §2). */
+    fields: ReadonlyArray<Exclude<FieldOf<D, T>, ParentOf<D, T> | RowKeys<CreateData<D, T>>>>;
+    required?: ReadonlyArray<Exclude<FieldOf<D, T>, ParentOf<D, T>>>;
+    prefill?: Partial<CreateData<D, T>>;
+    /** The rows the AI chooses a ref field's row among (35 §2). */
+    options?: OptionsOf<Omit<CreateData<D, T>, ParentOf<D, T>>>;
+};
 /**
- * The document a page script returns: `PageDocumentOf<typeof page>` of `context.page.ts`'s default
- * export. An action the page function returns instead (a lookup, a keypad) is not part of it.
+ * The fields a prefill surely fills: there, and never null, undefined or a written-out '' (76 §2.14), as
+ * the write counts them; a `string` from code counts as filled (the render refuses it when it is ''). `{ body_part: null }`, `''` or a value that may be missing fills nothing: a required field prefilled so is still nobody's.
  */
-export type PageDocumentOf<P> = P extends {
-    channels: infer C;
-} ? {
-    [K in keyof C]: C[K] extends ((...args: never[]) => infer R) | undefined ? Exclude<Awaited<R>, ReturnedAction> : never;
-}[keyof C] : never;
+type FilledKeys<P> = {
+    [X in keyof P]-?: undefined extends P[X] ? never : null extends P[X] ? never : string extends P[X] ? X : '' extends P[X] ? never : X;
+}[keyof P];
+/** The page's functions bound to one sequence (76 §2.17): what `__gen/index.ts` exports. */
+export type TypedPageFns<D, S extends string, F> = {
+    /** The page (76 §2.7): settings, then content by name. */
+    page(settings: PageSettings<{
+        readonly [K in FieldPathOf<D>]?: string;
+    }>, content: PageContent): PageNode;
+    /** A field the AI may write, or read only. A ref field is `refField()`. */
+    field(slot: AnySlot, options?: {
+        readOnly?: boolean;
+        expand?: boolean;
+    }): FieldNode;
+    /** A ref field: writable, the rows it may be set to (`options`); read-only, who its value is (`label`). */
+    refField(slot: AnySlot, options: {
+        options: ReadonlyArray<RefOption> | ChooseParam;
+        readOnly?: false;
+    } | {
+        readOnly: true;
+        label?: string;
+    }): FieldNode;
+    /** Add a row (15 §10.6). */
+    createRow<T extends TableOf<D>, const R extends ReadonlyArray<Exclude<FieldOf<D, T>, ParentOf<D, T>>> = [], P extends Partial<CreateData<D, T>> = {}, K extends string | undefined = undefined>(table: T, options: Omit<CreateRowOptions<D, T>, 'options' | 'required' | 'prefill'> & {
+        required?: R;
+        prefill?: P & {
+            readonly [X in Exclude<keyof P, keyof CreateData<D, T>>]: `${X & string} is not a field of ${T}`;
+        };
+        options?: undefined;
+        runKey?: K;
+    }): Action<'createRow', KeyedOf<K>, [Exclude<R[number], FilledKeys<P>>] extends [never] ? AllPrefilled : LeftForAi>;
+    /** With `options`, the AI chooses a ref field's row: a button's, never `doNow()`'s. */
+    createRow<T extends TableOf<D>, K extends string | undefined = undefined>(table: T, options: CreateRowOptions<D, T> & {
+        options: NonNullable<CreateRowOptions<D, T>['options']>;
+        runKey?: K;
+    }): Action<'createRow', KeyedOf<K>, LeftForAi>;
+    /**
+     * Run a company function (`fn.x`) or a page action (76 §2.15): every required parameter prefilled
+     * (what `doNow()` takes), or some left for the AI. `options` are rows of each row parameter's own table.
+     */
+    run<H extends AnyRunHandle, K extends string | undefined = undefined>(handle: H & SameArgs<H>, options: ([RequiredKeys<RunArgs<H>>] extends [never] ? {
+        prefill?: PrefillOf<RunArgs<H>>;
+    } : {
+        prefill: FullPrefill<RunArgs<H>>;
+    }) & {
+        options?: undefined;
+        args?: undefined;
+        say?: SayOf<H>;
+        runKey?: K;
+    }): RunAction<KeyedOf<K>, AllPrefilled>;
+    run<H extends AnyRunHandle, K extends string | undefined = undefined>(handle: H & SameArgs<H>, options?: {
+        prefill?: PrefillOf<RunArgs<H>>;
+        options?: OptionsOf<RunArgs<H>>;
+        args?: {
+            [P in keyof RunArgs<H>]?: string;
+        };
+        say?: SayOf<H>;
+        runKey?: K;
+    }): RunAction<KeyedOf<K>, LeftForAi>;
+    /** Delete a row and everything under it (15 §10.6.1). */
+    deleteRow<K extends string | undefined = undefined>(row: Id<TableOf<D>> | {
+        readonly id: Id<TableOf<D>>;
+    }, options?: {
+        reason?: string;
+        runKey?: K;
+    }): Action<'deleteRow', KeyedOf<K>, AllPrefilled>;
+};
 export {};
 //# sourceMappingURL=typed.d.ts.map

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

@@ -5,7 +5,10 @@
  * always a `value` attribute; flush left.
  *
  *   <notes><note id about value/></notes>   the model's own reminders (17b §8), first, all of them
- *   <guide value/>                          the page's `$guide`: what to do now and how
+ *   <next-step channel id name to at reason customer-quote booked-in/>   the platform's, before the page
+ *                                           (40 §2.2, 51 §2): the case's pending contacts, whatever the page
+ *                                           shows; `value` "none" when nothing is booked
+ *   <guide value/>                         the page's `$guide`: what to do now and how
  *   <page title description fallback>       the page:
  *     <definitions>                         once for the page, a definition per `table.field` some field
  *       <definition for label type …/>      on it shows expanded (`field(slot, { expand: true })`)
@@ -15,7 +18,10 @@
  *                                           definition is not shown (its type is); a ref's one-of: its rows
  *     <text key value/>                     read-only text
  *     <button id title does><arg …/></button>
+ *   Now: 2026-11-11T20:05Z                 the platform's, the last line (76 §2.19): the time now, in UTC,
+ *                                           to the minute; the only time the AI is given as "now"
  */
+import type { PageNextStep } from './define.js';
 import type { BlockNode, RenderedPage } from './render.js';
 export type WorkspaceNote = {
     id: string;
@@ -24,8 +30,26 @@ export type WorkspaceNote = {
 };
 export type WorkspaceTextOptions = {
     notes?: readonly WorkspaceNote[];
+    /**
+     * The case's next step (40 §2.2), shown before the page whatever the page shows: the AI knows what is
+     * booked before it reads the page. Times in `timeZone` (the contact's). Left out: no conversation (nothing is shown).
+     */
+    nextSteps?: {
+        steps: readonly PageNextStep[];
+        timeZone: string;
+    };
+    /**
+     * The time now (76 §2.19): the page's last line, `Now: 2026-11-11T20:05Z`, in UTC, never the contact's
+     * zone. Every engine that shows the AI a page gives it; left out: no such line.
+     */
+    now?: Date;
 };
 export declare function workspaceText(page: RenderedPage, options?: WorkspaceTextOptions): string;
+/** The last line of every page the AI reads (76 §2.19): the time now in UTC, to the minute (`Now: 2026-11-11T20:05Z`). */
+export declare function nowLine(now: Date): string;
+/** Stable, short appointment handle; the service resolves it within the authorized case, rejecting ambiguity. */
+export declare function nextStepReference(id: string): string;
+export declare function nextStepLines(steps: readonly PageNextStep[], timeZone: string): string[];
 /** The block at `path` (`''`: the root). */
 export declare function blockAt(page: RenderedPage, path: string): BlockNode | null;
 /** What `view` shows of one thing on the page (24 §3.2): a field with its definition, a button with its arguments. */

package/dist/core/page/workspace.js

@@ -1,3 +1,4 @@
+import { formatTime } from './time-format.js';
 export function workspaceText(page, options = {}) {
     const out = [];
     const notes = options.notes ?? [];
@@ -7,6 +8,8 @@ export function workspaceText(page, options = {}) {
             out.push(element('note', { id: n.id, about: n.about, value: n.text }));
         out.push('</notes>');
     }
+    if (options.nextSteps)
+        out.push(...nextStepLines(options.nextSteps.steps, options.nextSteps.timeZone));
     const root = page.root;
     if (root.guide)
         out.push(element('guide', { value: root.guide }));
@@ -29,8 +32,40 @@ export function workspaceText(page, options = {}) {
     for (const child of root.children)
         walk(page, child, defined, false, out);
     out.push('</page>');
+    if (options.now)
+        out.push(nowLine(options.now));
     return out.join('\n');
 }
+/** The last line of every page the AI reads (76 §2.19): the time now in UTC, to the minute (`Now: 2026-11-11T20:05Z`). */
+export function nowLine(now) {
+    return `Now: ${now.toISOString().slice(0, 16)}Z`;
+}
+/** Stable, short appointment handle; the service resolves it within the authorized case, rejecting ambiguity. */
+export function nextStepReference(id) {
+    return `step-${id.replaceAll('-', '').slice(0, 12)}`;
+}
+export function nextStepLines(steps, timeZone) {
+    if (!steps.length)
+        return [element('next-step', { value: 'none: nothing is booked to contact anyone on this case' })];
+    const when = (at) => {
+        try {
+            return formatTime(at, { timeZone });
+        }
+        catch {
+            return at;
+        }
+    };
+    return steps.map((step) => element('next-step', {
+        channel: step.channel,
+        id: nextStepReference(step.id),
+        name: step.name ?? undefined,
+        to: step.contact.name ?? step.contact.id,
+        at: when(step.at),
+        reason: step.reason ?? undefined,
+        'customer-quote': step.customerQuote ?? undefined,
+        'booked-in': step.bookedIn ? `the ${step.bookedIn.channel === 'call' ? 'call' : step.bookedIn.channel === 'sms' ? 'texts' : 'email'} of ${when(step.bookedIn.at)}` : 'by the case\'s follow-up rules',
+    }));
+}
 const kindOf = (cell) => `${cell.ref.table}.${cell.ref.field}`;
 /** Each `table.field` some field on the page shows expanded, in page order: the page gives its definition once. */
 function definedCells(page) {
@@ -51,7 +86,7 @@ function walk(page, node, defined, inList, out) {
     switch (node.kind) {
         case 'block': {
             const tag = node.list ? 'list' : 'block';
-            out.push(open(tag, { key: inList ? undefined : node.key, title: node.title, description: node.description }));
+            out.push(open(tag, { key: inList ? undefined : node.key || undefined, title: node.title, description: node.description }));
             for (const child of node.children)
                 walk(page, child, defined, node.list, out);
             out.push(`</${tag}>`);
@@ -66,13 +101,18 @@ function walk(page, node, defined, inList, out) {
         case 'text':
             // null: the page put nothing here now (a region that does not apply yet, a value it has not got).
             // In a list it has no key of its own, only its place, as a block there (26 §16.2 #10).
-            out.push(element('text', { key: inList ? undefined : node.key, value: node.value }));
+            out.push(element('text', { key: inList ? undefined : node.key || undefined, value: node.value }));
             return;
         case 'action':
             out.push(...buttonLines(page.actions[node.actionId]));
     }
 }
-const editable = (node, cell) => !node.readOnly && cell.writable;
+/**
+ * Whether the AI may change a field (30 §3): the field's final permission, the same wherever it is on the
+ * page. A place marked read-only cannot stop the AI writing a field writable elsewhere (it writes by id),
+ * so marking it there would only contradict the other place.
+ */
+const editable = (_node, cell) => cell.writable;
 /**
  * A field's value (26 §16.2): `key` always (#10; in a list, where it has only its place, none); `readonly`
  * only on one the AI cannot change (#6a); `more` when its definition is not shown, with its type (#6);
@@ -81,12 +121,12 @@ const editable = (node, cell) => !node.readOnly && cell.writable;
  * labelled it.
  */
 function fieldAttrs(page, node, cell, more, inList = false) {
-    const value = valueOf(cell, page);
+    const value = valueOf(cell);
     const open = editable(node, cell);
     const labels = cell.optionLabels ?? {};
     return {
         id: cell.slotId,
-        key: inList ? undefined : node.key,
+        key: inList ? undefined : node.key || undefined,
         readonly: !open,
         more,
         type: more ? cell.type : undefined,
@@ -97,16 +137,11 @@ function fieldAttrs(page, node, cell, more, inList = false) {
         reason: (cell.state === 'asked_unknown' || cell.state === 'declined') && cell.reason ? cell.reason : undefined,
     };
 }
-/** The value as JSON holds it; a value that is a row's id is the row's page name; null when not filled. */
-function valueOf(cell, page) {
+/** The value as JSON holds it; a ref's is its row's name (33); null when not filled. */
+function valueOf(cell) {
     if (cell.state !== 'filled')
         return null;
-    if (typeof cell.value === 'string') {
-        const name = Object.entries(page.rows).find(([, row]) => row.id === cell.value)?.[0];
-        if (name)
-            return name;
-    }
-    return cell.value ?? null;
+    return cell.valueRow ?? cell.value ?? null;
 }
 /**
  * What a field means and takes (26 §15.3): label, type, allowed values (`one-of`; a ref field's rows are