@superpanel-sdk/runtime 0.2.2 → 0.5.0

package/dist/core/case-orchestrator/types.d.ts

@@ -0,0 +1,753 @@
+import type { SystemContext } from '../context/types.js';
+import type { Db, ReadDb } from '../page/define.js';
+import type { Id, PageTablesDesc, TypedDb, TypedReadDb } from '../page/typed.js';
+import type { ContactSchedule } from '../slot/schema.js';
+/** Reserved export of `sequences/<id>/orchestrator.ts` and its name in the build's `functions`. */
+export declare const ORCHESTRATOR_FUNCTION = "orchestrator";
+/** `orchestrator.ts`'s required `contacts` export: its name in the build's `functions`. */
+export declare const ORCHESTRATOR_CONTACTS_FUNCTION = "orchestratorContacts";
+/** `ctx.meta.entry` / RunScope entry of a Case Orchestrator call. */
+export declare const ORCHESTRATOR_ENTRY = "orchestrator";
+/** `SequenceBuild.orchestrator`: the entry point, and the function that says whom a Run may contact. */
+export type CaseOrchestratorManifest = {
+    fn: string;
+    contactsFn: string;
+};
+/** Platform tools a Run may open. Names, descriptions, schemas and executors belong to the platform. */
+export declare const CASE_ORCHESTRATOR_TOOL_NAMES: readonly ['readExchange', 'searchExchanges', 'updateSlots', 'scheduleCall', 'scheduleSms', 'scheduleEmail', 'scheduleUpdateSlots', 'rescheduleAction', 'cancelScheduledAction', 'scheduleNextSequence', 'closeInstance', 'scheduleWake', 'cancelWake'];
+export type CaseOrchestratorToolName = (typeof CASE_ORCHESTRATOR_TOOL_NAMES)[number];
+/** A reference to one platform tool, from `tools.*()`. */
+export type ToolRef<N extends CaseOrchestratorToolName = CaseOrchestratorToolName> = {
+    kind: 'tool';
+    name: N;
+};
+/** Channels the Agent can contact a contact on. */
+export type ContactChannel = 'call' | 'sms' | 'email';
+/**
+ * Kinds of actions the Agent can schedule: contacting a contact, slot writes at a later time,
+ * handing the instance over to the next sequence (14-sequence-instance §4.3), or waking the
+ * Orchestrator up (`wake`, 25 §6.3).
+ */
+export type ScheduledActionKind = ContactChannel | 'update_slots' | 'next_sequence' | 'wake';
+/** Fields every trigger has. `key` is a stable event id: triggers with the same key merge into one. */
+type TriggerBase = {
+    key: string;
+    occurredAt: string;
+};
+/**
+ * Why a Run started. Handed to `orchestrator` as is, so it is a public contract: grow it only
+ * (new `type`s, new optional fields); never rename or remove.
+ */
+export type RunTrigger = TriggerBase & ({
+    type: 'call.ended';
+    exchangeId: string;
+    direction: 'inbound' | 'outbound';
+    /** Null when the call never connected. Read it with `ctx.api.db.session.findUnique({ where: { id } })`. */
+    sessionId: Id<'session'> | null;
+    /** Set when the Agent scheduled this call. */
+    scheduledActionId: string | null;
+    /**
+     * `'connected'` when a session opened (corresponds to `result === 'answered'` on `ExchangeEvent`);
+     * `'voicemail'` when a message was left on it, `'screened'` when only a call-screening assistant
+     * answered (25 §13).
+     */
+    result: 'connected' | 'no-answer' | 'busy' | 'failed' | 'voicemail' | 'screened';
+}
+/** An outbound SMS was handed to the provider, or failed to send. */
+ | {
+    type: 'sms.sent';
+    exchangeId: string;
+    scheduledActionId: string | null;
+    result: 'sent' | 'failed';
+    /** Provider or platform error code when `result === 'failed'`; null otherwise. */
+    errorCode: string | null;
+}
+/** An outbound email was handed to the provider, or failed to send. */
+ | {
+    type: 'email.sent';
+    exchangeId: string;
+    scheduledActionId: string | null;
+    result: 'sent' | 'failed';
+    /** Provider or platform error code when `result === 'failed'`; null otherwise. */
+    errorCode: string | null;
+}
+/**
+ * One SMS run finished: its hooks ran and the reply was stored (21 §6.1). `exchangeId` holds the
+ * text line's exchange id (`sms:<our number id>:<their number>`, 21 §12.3).
+ */
+ | {
+    type: 'sms.turn-ended';
+    exchangeId: string;
+    runId: string;
+}
+/**
+ * One email run finished: its hooks ran and the reply was stored (21 §6.1). `exchangeId` holds the
+ * thread's exchange id (`email:<emailThreadId>`, 21 §12.3).
+ */
+ | {
+    type: 'email.turn-ended';
+    exchangeId: string;
+    runId: string;
+} | {
+    type: 'contact.communication-preferences.updated';
+    contactId: Id<'contact'>;
+    /** The contact's `Record.version` after the preference write committed. */
+    contactVersion: number;
+}
+/** The instance started (a first conversation, a script, a hand-over). */
+ | {
+    type: 'instance_started';
+}
+/** Requested after an edit in the frontend. */
+ | {
+    type: 'manual';
+    requestedBy: string;
+}
+/**
+ * A scheduled action failed its checks when it came due (the instance closed, the contact left
+ * the page, an opt-out, a deadline passed, a write no longer valid, …): nothing was done.
+ */
+ | {
+    type: 'scheduled_action.failed';
+    scheduledActionId: string;
+    kind: ScheduledActionKind;
+    errorCode: string;
+}
+/**
+ * Company code told the instance about something outside the platform (a payment posted, a CRM
+ * change): `ctx.api.instances.notify` from a webhook, a function or an event handler (25 §6.2).
+ * Only a label: the facts are in the records, read them with `ctx.api.db`.
+ */
+ | {
+    type: 'external';
+    reason: string;
+}
+/** A wake-up the Orchestrator booked with `scheduleWake` came due (25 §6.3). */
+ | {
+    type: 'timer';
+    name: string;
+    note: string | null;
+    scheduledActionId: string;
+}
+/**
+ * A call, texts or an email came in while the case was fully paused (29 §4.1): the AI did not take
+ * it; a call went to the fallback number, a message was kept unanswered. Told once the pause is lifted.
+ */
+ | {
+    type: 'inbound.paused';
+    channel: ContactChannel;
+    exchangeId: string;
+});
+export type RunTriggerType = RunTrigger['type'];
+/** A stored action's timing: `at`, the exact time (ISO 8601) it runs (25 §4). */
+export type ScheduledActionTiming = {
+    mode: 'at';
+    at: string;
+};
+/**
+ * What a contact (call / SMS / email) was asked for: its stored `input`. `timing` says when: it is
+ * what two requests are compared on and what a reschedule replaces; the other keys ride along.
+ */
+export type ContactActionInput = {
+    timing: ScheduledActionTiming;
+    /** Why it happens; the conversation it opens gets it too. */
+    note?: string;
+    /** The contact's address to use: its `phone` (a call, a text) or `email`, the default. */
+    to?: string;
+    /** Our number to use; default the contact's assigned number, else the sequence's outbound numbers. */
+    from?: string;
+    /**
+     * An agreed follow-up (the party asked for it or agreed to it): where, in which message (its
+     * time, ISO 8601) and in which words they said it. Absent for a regular follow-up.
+     * docs/design/09-agreed-follow-up.md
+     */
+    agreement?: {
+        exchangeId: string;
+        agreedAt: string;
+        customerQuote: string;
+    };
+};
+/** What scheduled slot writes (`update_slots`) were asked for: when, what is written, and why. */
+export type UpdateSlotsActionInput = {
+    timing: {
+        mode: 'at';
+        at: string;
+    };
+    writes: SlotWriteInput[];
+    reason: string;
+};
+/** What a hand-over (`next_sequence`) was asked for: when, to which sequence, on which row, its variables, and why. */
+export type NextSequenceActionInput = {
+    timing: {
+        mode: 'at';
+        at: string;
+    };
+    /** Name of the sequence the next instance runs. */
+    sequence: string;
+    /** The row the next instance starts on, when one was named; else this instance's own. */
+    subjectRecordId?: string;
+    variables?: Record<string, unknown>;
+    reason: string;
+};
+/** What a wake-up (`wake`) was booked for: when, its name (one pending per name), and why. */
+export type WakeActionInput = {
+    timing: {
+        mode: 'at';
+        at: string;
+    };
+    name: string;
+    note?: string;
+};
+/** Each kind's stored `input`. */
+export type ScheduledActionInputs = {
+    call: ContactActionInput;
+    sms: ContactActionInput;
+    email: ContactActionInput;
+    update_slots: UpdateSlotsActionInput;
+    next_sequence: NextSequenceActionInput;
+    wake: WakeActionInput;
+};
+export type ScheduledActionInput = ScheduledActionInputs[ScheduledActionKind];
+/** A pending contact: who and its `input`. */
+export type ContactActionView = {
+    id: string;
+    kind: ContactChannel;
+    /** The contact to reach. */
+    contactId: string;
+    /**
+     * When it runs (ISO 8601): `input.timing.at`, as given (25 §4).
+     */
+    scheduledFor: string;
+    input: ContactActionInput;
+};
+/** Pending scheduled slot writes: instance-level, no contact. */
+export type UpdateSlotsActionView = {
+    id: string;
+    kind: 'update_slots';
+    contactId: null;
+    /** Execution time (`input.timing.at`, ISO 8601). */
+    scheduledFor: string;
+    input: UpdateSlotsActionInput;
+};
+/** A pending hand-over to the next sequence: instance-level, no contact. */
+export type NextSequenceActionView = {
+    id: string;
+    kind: 'next_sequence';
+    contactId: null;
+    /** Execution time (`input.timing.at`, ISO 8601). */
+    scheduledFor: string;
+    input: NextSequenceActionInput;
+};
+/** A pending wake-up of the Orchestrator: instance-level, no contact. */
+export type WakeActionView = {
+    id: string;
+    kind: 'wake';
+    contactId: null;
+    /** When it wakes the Orchestrator (`input.timing.at`, ISO 8601). */
+    scheduledFor: string;
+    input: WakeActionInput;
+};
+/** A scheduled action still active when the Run input is built; `kind` tells which `input` it has. */
+export type ScheduledActionView = ContactActionView | UpdateSlotsActionView | NextSequenceActionView | WakeActionView;
+/** An agreed follow-up (`input.agreement` set) that already ran, failed or was cancelled. */
+export type FinishedAgreedActionView = ContactActionView & {
+    status: 'completed' | 'failed' | 'cancelled';
+    finishedAt: string;
+};
+/** One real contact (a call, or a sent / received SMS or email). */
+export type ExchangeEvent = {
+    exchangeId: string;
+    channel: 'call' | 'sms' | 'email';
+    direction: 'inbound' | 'outbound';
+    occurredAt: string;
+    /** Day of the interaction, counting the first interaction's day as 1. */
+    dayNumber: number;
+    /**
+     * Outcome of the contact:
+     * - `call`: `'answered'` | `'no-answer'` (includes busy) | `'failed'`
+     * - outbound `sms` / `email`: `'sent'` | `'failed'`
+     * - inbound `sms` / `email`: `'received'`
+     */
+    result: 'answered' | 'no-answer' | 'sent' | 'failed' | 'received';
+    /** A call's length in seconds; null for SMS and email, or a call whose length is not known yet. */
+    durationSec: number | null;
+    /** Set when the Agent scheduled it. */
+    scheduledActionId: string | null;
+};
+/** Exchange counts, last events by kind, and recent timeline for the Case (`all`) or one party. */
+export type ActivityStats = {
+    /** Timestamp of the very first interaction (day 1); null when none happened yet. */
+    firstAt: string | null;
+    /** Real contacts counted, of which `recent` holds the newest. */
+    total: number;
+    /** Today's day number; 1 when nothing happened yet. */
+    dayNumber: number;
+    /** Today's interaction counts: the party's contact timezone, or the primary party's for `all`. */
+    today: {
+        calls: number;
+        answeredCalls: number;
+        smsOut: number;
+        smsIn: number;
+        emailsOut: number;
+        emailsIn: number;
+    };
+    /** Most recent event of each kind (null when none happened yet). */
+    last: {
+        /** Most recent exchange across all channels and directions. */
+        exchange: ExchangeEvent | null;
+        /** Most recent inbound exchange (call, SMS, or email from the contact). */
+        inbound: ExchangeEvent | null;
+        /** Most recent outbound exchange (call, SMS, or email to the contact). */
+        outbound: ExchangeEvent | null;
+        /** Most recent call (inbound or outbound, answered or not). */
+        call: ExchangeEvent | null;
+        /** Most recent call that was answered (`result === 'answered'`). */
+        answeredCall: ExchangeEvent | null;
+        /** Most recent SMS (inbound or outbound). */
+        sms: ExchangeEvent | null;
+        /** Most recent email (inbound or outbound). */
+        email: ExchangeEvent | null;
+    };
+    /** Most recent events, oldest first (at most {@link ACTIVITY_RECENT_LIMIT}). */
+    recent: readonly ExchangeEvent[];
+};
+export declare const ACTIVITY_RECENT_LIMIT = 50;
+/** How far back `recentAgreedActions` reaches. */
+export declare const RECENT_AGREED_ACTIONS_DAYS = 14;
+/**
+ * Why a channel cannot be used: no phone / email on file, the contact opted out of it, or the address
+ * cannot take it (a number Twilio said is a landline or out of service, 21 §5.10).
+ */
+export type ChannelUnavailableReason = 'no_address' | 'opted_out' | 'unreachable';
+export type ChannelAvailability = {
+    /** The address exists and the channel is not opted out (globally or alone). */
+    channels: Record<ContactChannel, boolean>;
+    /** Why each unavailable channel is unavailable. */
+    unavailableChannels: Partial<Record<ContactChannel, ChannelUnavailableReason>>;
+};
+/** One party's activity, counted from its own first contact, in its own timezone. */
+export type PartyActivity = ActivityStats & ChannelAvailability & {
+    contactId: string;
+    timezone: string;
+    /** Local time of the party, ISO 8601 with offset. */
+    localNow: string;
+    localWeekday: string;
+    contactHours: PartyContactHours;
+};
+type ContactHoursWeekday = 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun';
+/**
+ * When a party may be contacted, in their timezone: their `contact_schedule` within the platform
+ * window, or default working hours when they have none. The platform places regular follow-ups (and
+ * agreed ones without an exact time) inside these hours.
+ */
+export type PartyContactHours = {
+    /**
+     * `contact_schedule`: the party's own schedule; `none`: none on file (every day all day). The
+     * company's rules for when to reach them are not here (25 §3): they are the company's own.
+     */
+    source: 'contact_schedule' | 'none';
+    /** Each weekday's windows; an empty list: never on that weekday. */
+    weekly: Readonly<Record<ContactHoursWeekday, readonly {
+        start: string;
+        end: string;
+    }[]>>;
+    /** Dates from today on whose hours replace the weekly ones, soonest first; an empty list: not that day. */
+    dateOverrides: readonly {
+        date: string;
+        windows: readonly {
+            start: string;
+            end: string;
+        }[];
+    }[];
+};
+/** Exchange aggregates the platform computes when a Run starts. */
+export type CaseActivity = {
+    /** Timezone of the instance-level day numbers: the first contact's of the Run's `contacts`. */
+    timezone: string;
+    all: ActivityStats;
+    /** Every contact the Run may reach (orchestrator.ts's `contacts`), keyed by contactId, in that order. */
+    byContact: Readonly<Record<string, PartyActivity>>;
+};
+export declare const EMPTY_CASE_ACTIVITY: CaseActivity;
+/** Frozen inputs of one orchestration Run. */
+export type CaseOrchestratorParams = {
+    /** This Run's triggers, frozen when it started, oldest first. */
+    triggers: readonly RunTrigger[];
+    /**
+     * Scheduled actions still waiting to run when the Run started. Writes through `ctx.api.tools`
+     * do not update it.
+     */
+    scheduledActions: readonly ScheduledActionView[];
+    /** Agreed follow-ups that finished in the last {@link RECENT_AGREED_ACTIONS_DAYS} days, newest first: a promise already kept is not booked again. */
+    recentAgreedActions: readonly FinishedAgreedActionView[];
+    activity: CaseActivity;
+};
+/**
+ * The Orchestrator's API: everything a function's `ctx.api` has (25 §7: the platform surfaces, every
+ * integration, `log`, the company's records), so a function of the sequence can be called from the
+ * Orchestrator with its `ctx` and works the same, plus the awaitable platform `tools`. Like a
+ * function's, `call` / `sms` / `email` read the history of the whole company and environment: pass
+ * `instanceId: ctx.meta.instanceId` to `list` for this instance's. `db` reads the records the way a page script does
+ * (Prisma-shaped, every `where` anchored) and changes them the way a page action does (`create` /
+ * `update` / `delete`), any row of the company and environment. Each call is one request: a write is
+ * its own transaction, and the same write sent again within the Run is not made twice; a Run run again
+ * (after it failed) writes again, so read first, then create.
+ * `D` is the sequence's `PageTables` (`__gen` binds it): tables, fields and ids typed.
+ */
+export type CaseOrchestratorApi<D extends PageTablesDesc | undefined = undefined> = Omit<SystemContext['api'], 'db'> & {
+    /**
+     * The platform's tools, the Agent's too: scheduling goes through them, where opt-outs and the
+     * instance's state are checked. A text or email sent with an integration directly is not.
+     */
+    tools: CaseOrchestratorTools;
+    db: D extends PageTablesDesc ? TypedDb<D> : Db;
+};
+/**
+ * `ctx` of `orchestrator`: a function's `ctx`, so a function can be
+ * called with it, plus `params` and `api.tools`. `D` types `ctx.api.db`.
+ */
+export type CaseOrchestratorContext<D extends PageTablesDesc | undefined = undefined> = Omit<SystemContext, 'api'> & {
+    api: CaseOrchestratorApi<D>;
+    params: CaseOrchestratorParams;
+};
+/**
+ * When a scheduled action runs (25 §4): `at`, an exact instant (ISO 8601 with an offset or Z; its
+ * offset need not be the contact's); pass the current time for now. It runs then: the platform does
+ * not check contact hours (25 §3). The company's rules decide `at`: `nextContactTime` for the first
+ * allowed time, `randomTimeBetween` to spread contacts.
+ */
+export type ScheduleTiming = {
+    at: string;
+};
+/**
+ * What makes a contact an agreed follow-up: the party asked for it or agreed to it in
+ * `agreedInExchangeId`, in their message at `agreedAt`, in the words `customerQuote` (all three
+ * together; the platform does not check them, and `agreedAt` tells agreements apart). Like any
+ * action it runs at its `at`; an opt-out still stops it.
+ * docs/design/09-agreed-follow-up.md
+ */
+export type AgreementFields = {
+    agreedInExchangeId?: string;
+    /** The time of the party's message, as the conversation shows it, ISO 8601 with an offset or Z. */
+    agreedAt?: string;
+    customerQuote?: string;
+    /** Why this contact happens; the conversation it opens gets it. Any action may have one. */
+    note?: string;
+};
+/**
+ * Whom to contact (one of the Run's `contacts`) and, optionally, the addresses: `to` one of the
+ * contact's phone / email fields' values (default: its `phone` / `email`), `from` one of our numbers
+ * (default: the contact's assigned number, else this sequence's outbound numbers, 14 §10).
+ */
+export type ScheduleActionInput = {
+    contactId: string;
+    to?: string;
+    from?: string;
+} & ScheduleTiming & AgreementFields;
+/** One field on an existing row, as `updateSlots` takes it. */
+export type SlotFieldWriteInput = {
+    /** `table.field`. */
+    path: string;
+    value?: string | number | boolean | string[] | null;
+    state?: 'filled' | 'empty' | 'asked_unknown' | 'declined';
+    reason?: string;
+    /** A multi-row table (`contact` included): the existing row's id. */
+    rowId?: string;
+};
+/**
+ * A new row of a multi-row table other than contact. Any field, conversation ones included; its
+ * parent when the parent is not the business root (which the platform fills).
+ */
+export type SlotInsertInput = {
+    insert: string;
+    values: Record<string, string | number | boolean | string[] | null | ContactSchedule>;
+};
+/** One slot write, as `updateSlots` and `scheduleUpdateSlots` take it. */
+export type SlotWriteInput = SlotFieldWriteInput | SlotInsertInput;
+/**
+ * Slot writes to make at a set time, and why. Validated now, written as given when due (checked
+ * again then); nothing is re-decided, so cancel or reschedule it when it no longer fits. Not a
+ * contact: no window or opt-out applies.
+ */
+export type ScheduleUpdateSlotsInput = {
+    at: string;
+    writes: SlotWriteInput[];
+    reason: string;
+};
+/**
+ * Hand the instance over to the next sequence at `at` (now when left out): when due, this instance
+ * closes (`superseded`) and an instance of `sequence` starts, in one transaction. It starts on
+ * `subjectRecordId`, a row of the table `sequence` declares as `subject`; left out, on this
+ * instance's own row, which then must be of that table (`subject_required`). A row with an active
+ * instance is refused (`subject_busy`).
+ */
+export type ScheduleNextSequenceInput = {
+    sequence: string;
+    subjectRecordId?: string;
+    at?: string;
+    variables?: Record<string, unknown>;
+    reason: string;
+};
+/** One utterance of a call, or one SMS / email, inside an exchange. */
+export type ExchangeEntry = {
+    at: string;
+    /** `party`: the person on the other side; `ai`: what the platform said or sent. */
+    speaker: 'party' | 'ai';
+    text: string;
+    /** Set when `text` was cut to fit the result. */
+    truncated?: true;
+};
+/** One exchange's content, a window of its entries at a time, newest window first. */
+export type ReadExchangeResult = {
+    exchangeId: string;
+    contactId: string | null;
+    direction: 'inbound' | 'outbound';
+    occurredAt: string;
+    totalEntries: number;
+    /** These are entries [from, to) of all of them; `from > 0`: pass `before: from` for earlier ones. */
+    range: {
+        from: number;
+        to: number;
+    };
+    entries: ExchangeEntry[];
+} & ({
+    channel: 'call';
+    /** Null while the call has not happened yet (still dialing or ringing). */
+    result: ExchangeEvent['result'] | null;
+    durationSec: number | null;
+} | {
+    channel: 'sms';
+} | {
+    channel: 'email';
+    subject: string | null;
+});
+/** A {@link ExchangeEvent} as `searchExchanges` returns it. */
+export type ExchangeSearchHit = Omit<ExchangeEvent, 'dayNumber' | 'durationSec'> & {
+    contactId: string | null;
+    /** The case it was on (with scope `contact`, possibly not this one); null when none. */
+    instanceId: string | null;
+    /** Calls only. */
+    durationSec?: number | null;
+    /** Emails only. */
+    subject?: string | null;
+    /** SMS / email: the start of the message body. */
+    preview?: string | null;
+};
+export type SearchExchangesResult = {
+    /** Every event matching the filters, not only this page. */
+    total: number;
+    /** Newest first. */
+    events: ExchangeSearchHit[];
+    /** Pass as `before` for the next (older) page; null on the last page. */
+    nextBefore: string | null;
+};
+/** Each tool's arguments: the same parameters the model sends. The tool validates them when it runs. */
+export type ToolCallArgs = {
+    /** `before`: exclusive upper entry index for paging back (pass `range.from` from the previous read). */
+    readExchange: {
+        exchangeId: string;
+        before?: number;
+    };
+    searchExchanges: {
+        /** `occurredAt >= from`, ISO 8601 with an offset or Z. */
+        from?: string;
+        /** `occurredAt < to`, ISO 8601 with an offset or Z. */
+        to?: string;
+        contactId?: string;
+        channel?: ExchangeEvent['channel'];
+        direction?: ExchangeEvent['direction'];
+        result?: ExchangeEvent['result'][];
+        scheduledActionId?: string;
+        /** `case` (default): this case only; `contact`: every case of this case's contacts (27 §5.4). */
+        scope?: 'case' | 'contact';
+        limit?: number;
+        /** Pagination cursor from a previous result's `nextBefore`. */
+        before?: string;
+    };
+    updateSlots: {
+        writes: SlotWriteInput[];
+    };
+    scheduleCall: ScheduleActionInput;
+    scheduleSms: ScheduleActionInput;
+    scheduleEmail: ScheduleActionInput;
+    scheduleUpdateSlots: ScheduleUpdateSlotsInput;
+    rescheduleAction: {
+        scheduledActionId: string;
+    } & ScheduleTiming & {
+        /** Required to move an agreed follow-up. */
+        reason?: string;
+        /** The party changed an agreed follow-up: where, in which message and in which words (all three). */
+        agreedInExchangeId?: string;
+        agreedAt?: string;
+        customerQuote?: string;
+    };
+    cancelScheduledAction: {
+        scheduledActionId: string;
+        reason: string;
+    };
+    scheduleNextSequence: ScheduleNextSequenceInput;
+    /** End this instance (completed / cancelled / a short text): pending actions are cancelled. */
+    /** `reason`: why, 1–64 characters (`'signed up'`, `'asked us to stop'`). */
+    closeInstance: {
+        reason: string;
+    };
+    scheduleWake: ScheduleWakeInput;
+    /** Cancel the pending wake-up of this name, if there is one. */
+    cancelWake: {
+        name: string;
+        reason?: string;
+    };
+};
+/**
+ * `scheduleWake`: wake this instance's Orchestrator at `at` with a `timer` trigger (25 §6.3). It
+ * contacts no one, so it runs exactly then, at any hour. One pending per `name`: booking the same
+ * name again moves it. Cancelled with the instance.
+ */
+export type ScheduleWakeInput = {
+    /** Its name in this instance (e.g. `payment-check`); the trigger carries it. */
+    name: string;
+    /** ISO 8601 with an offset or Z; at most 90 days ahead. */
+    at: string;
+    /** Why, for the Run it starts. */
+    note?: string;
+};
+export type WakeResult = {
+    /** `rescheduled`: a wake-up of this name was pending and moved; `existing`: it already had this time and note. */
+    outcome: 'created' | 'rescheduled' | 'existing';
+    scheduledActionId: string;
+    scheduledFor: string;
+};
+export type ScheduledResult = {
+    /**
+     * `existing`: this contact and channel already have an active action with the same timing, or
+     * these agreed words were already booked.
+     */
+    outcome: 'created' | 'existing';
+    scheduledActionId: string;
+    scheduledFor: string;
+    /**
+     * The contact's `Record.version` at the time the action was scheduled (`0` without a contact);
+     * for `existing`, the version recorded when it was first scheduled. Recorded only, not checked
+     * when the action fires.
+     */
+    contactVersion: number;
+    /** An agreed follow-up replaced this pending regular follow-up on the same channel (it is cancelled). */
+    supersededScheduledActionId?: string;
+};
+export type RescheduledResult = {
+    /** `unchanged`: the action already had this timing. */
+    outcome: 'rescheduled' | 'unchanged';
+    scheduledActionId: string;
+    scheduledFor: string;
+    /** The `scheduledFor` timestamp before rescheduling (equals `scheduledFor` when `unchanged`). */
+    previousScheduledFor: string;
+    /** The contact's `Record.version` at the time of rescheduling (`0` without a contact). */
+    contactVersion: number;
+};
+export type ToolCallResult = {
+    readExchange: ReadExchangeResult;
+    searchExchanges: SearchExchangesResult;
+    updateSlots: {
+        outcome: 'written';
+        paths: string[];
+        inserts: string[];
+    };
+    scheduleCall: ScheduledResult;
+    scheduleSms: ScheduledResult;
+    scheduleEmail: ScheduledResult;
+    scheduleUpdateSlots: ScheduledResult;
+    rescheduleAction: RescheduledResult;
+    /** `too_late`: it already started; otherwise the action's final status. */
+    cancelScheduledAction: {
+        outcome: 'cancelled' | 'too_late' | 'completed' | 'failed';
+        scheduledActionId: string;
+    };
+    scheduleNextSequence: ScheduledResult;
+    closeInstance: {
+        outcome: 'closed' | 'already_closed';
+        cancelledScheduledActionIds: string[];
+    };
+    scheduleWake: WakeResult;
+    /** `not_pending`: no wake-up of that name was waiting (it never was, already ran, or was cancelled). */
+    cancelWake: {
+        outcome: 'cancelled' | 'not_pending';
+        scheduledActionId: string | null;
+    };
+};
+export type ToolResult<T> = {
+    ok: true;
+    value: T;
+    toolCallId: string;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+    };
+    toolCallId: string;
+};
+export type ToolCallOptions = {
+    /**
+     * Stable idempotency key within the Run: calling the same tool again with the same `callKey`
+     * and arguments replays the recorded result instead of executing twice; reusing it for another
+     * tool or other arguments fails with `idempotency_conflict`.
+     */
+    callKey: string;
+};
+export type CaseOrchestratorTools = {
+    [N in CaseOrchestratorToolName]: (input: ToolCallArgs[N], options: ToolCallOptions) => Promise<ToolResult<ToolCallResult[N]>>;
+};
+/** An Agent Run request: the LLM decides which of `tools` to call. */
+export type AgentRequest = {
+    kind: 'agent';
+    /** The whole user message the Agent reads, written by company code (docs/design/08-case-orchestrator.md §5.3). */
+    prompt: string;
+    /** The tools the Agent may call, from `tools.*()`. Left out: every platform tool; `[]`: none. */
+    tools?: readonly ToolRef[];
+};
+/** An AgentRequest as the platform runs it: `tools` resolved to the Agent's whitelist. */
+export type ResolvedAgentRequest = AgentRequest & {
+    tools: readonly ToolRef[];
+};
+export type FinalOrchestrationResult = {
+    kind: 'final';
+    finalSummary: string;
+};
+export type CaseOrchestratorResult = AgentRequest | FinalOrchestrationResult;
+/**
+ * What code working on a case receives as `c` — the Orchestrator and event handlers: the instance, and
+ * its business root's id, the anchor of its reads (`ctx.api.db.<root table>.findUnique({ where: { id:
+ * c.subject } })`). Fixed for the instance, so the platform fills it; what changes (run variables, the
+ * instance's status) is read with `ctx.api.instances.get`.
+ */
+export type CaseInput<S extends string = string> = {
+    subject: Id<S>;
+    instanceId: string;
+};
+/** What `orchestrator` and `contacts` receive as `c` ({@link CaseInput}). */
+export type CaseOrchestratorInput<S extends string = string> = CaseInput<S>;
+/**
+ * `ctx` of `contacts`: the Orchestrator's API, before the Run's params are gathered; it only reads
+ * (`db` has the read methods only). The platform runs it more than once per Run, so a write or a
+ * tool call there would be made again each time.
+ */
+export type CaseOrchestratorContactsContext<D extends PageTablesDesc | undefined = undefined> = Omit<CaseOrchestratorContext<D>, 'params' | 'api'> & {
+    api: Pick<CaseOrchestratorApi<D>, 'call' | 'sms' | 'email' | 'log'> & {
+        db: D extends PageTablesDesc ? TypedReadDb<D> : ReadDb;
+    };
+};
+/**
+ * `orchestrator.ts`'s `contacts`: whom this Run may contact (schedule calls, SMS and email to), read
+ * with `ctx.api.db`; the ids of contact rows of the company. The platform runs it when the Run
+ * starts (a pending contact of a person no longer listed is cancelled, and
+ * `ctx.params.activity.byContact` is keyed by these), and again when the Run is handed to the Agent
+ * (the orchestrator may have changed the data).
+ */
+export type CaseOrchestratorContacts<C = CaseOrchestratorInput, D extends PageTablesDesc | undefined = undefined> = (caseContext: C, ctx: CaseOrchestratorContactsContext<D>) => Promise<readonly string[]>;
+/**
+ * `orchestrator.ts`: `export const orchestrator: CaseOrchestrator = async (c, ctx) => …`.
+ * `C` is the sequence's `CaseOrchestratorInput`; `D` its `PageTables` (`__gen` binds both).
+ */
+export type CaseOrchestrator<C = CaseOrchestratorInput, D extends PageTablesDesc | undefined = undefined> = (caseContext: C, ctx: CaseOrchestratorContext<D>) => Promise<CaseOrchestratorResult>;
+export {};
+//# sourceMappingURL=types.d.ts.map