@superpanel-sdk/runtime 0.5.0 → 0.7.0

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

@@ -1,30 +1,22 @@
 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 { Db } from '../page/define.js';
+import type { Id, PageTablesDesc, TypedDb } 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. */
+/** `SequenceBuild.orchestrator`: the entry point. */
 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 declare const CASE_ORCHESTRATOR_TOOL_NAMES: readonly ['readExchange', 'searchExchanges', 'scheduleCall', 'scheduleSms', 'scheduleEmail', 'scheduleUpdateSlots', 'rescheduleAction', 'cancelScheduledAction', 'scheduleNextSequence', '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. */
+/** Channels a contact is reached on. */
 export type ContactChannel = 'call' | 'sms' | 'email';
 /**
- * Kinds of actions the Agent can schedule: contacting a contact, slot writes at a later time,
+ * Kinds of actions that can be scheduled: 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).
  */
@@ -44,14 +36,13 @@ export type RunTrigger = TriggerBase & ({
     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. */
+    /** Set when the call was a scheduled action. */
     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).
+     * `'voicemail'` when a message was left on it (65 §3.3).
      */
-    result: 'connected' | 'no-answer' | 'busy' | 'failed' | 'voicemail' | 'screened';
+    result: 'connected' | 'no-answer' | 'busy' | 'failed' | 'voicemail';
 }
 /** An outbound SMS was handed to the provider, or failed to send. */
  | {
@@ -91,8 +82,8 @@ export type RunTrigger = TriggerBase & ({
 } | {
     type: 'contact.communication-preferences.updated';
     contactId: Id<'contact'>;
-    /** The contact's `Record.version` after the preference write committed. */
-    contactVersion: number;
+    /** The `SlotWriteLog` row of the preference field this write changed: what changed, by whom (41 §2). */
+    slotWriteLogId: string;
 }
 /** The instance started (a first conversation, a script, a hand-over). */
  | {
@@ -113,6 +104,19 @@ export type RunTrigger = TriggerBase & ({
     kind: ScheduledActionKind;
     errorCode: string;
 }
+/**
+ * A scheduled action ended with nothing else to say so (74 §4.7): every action that ends wakes the
+ * Orchestrator, to book the next step or close the case. `not_sent`: a text or email whose page decided to
+ * send nothing (`reason` says why); `written`: slot writes made.
+ */
+ | {
+    type: 'scheduled_action.ended';
+    scheduledActionId: string;
+    kind: ScheduledActionKind;
+    outcome: 'not_sent' | 'written';
+    /** Why it was not sent (`noReply: …`, `handoff: …`); null for `written`. */
+    reason: string | null;
+}
 /**
  * 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).
@@ -146,12 +150,11 @@ export type ScheduledActionTiming = {
 };
 /**
  * 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.
+ * what two requests are compared on and what a reschedule replaces; the other keys ride along. Why
+ * it happens is the action's `reason` (40 §2.6).
  */
 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. */
@@ -167,16 +170,15 @@ export type ContactActionInput = {
         customerQuote: string;
     };
 };
-/** What scheduled slot writes (`update_slots`) were asked for: when, what is written, and why. */
+/** What scheduled slot writes (`update_slots`) were asked for: when, and what is written (why: the action's `reason`). */
 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. */
+/** What a hand-over (`next_sequence`) was asked for: when, to which sequence, on which row, its variables (why: the action's `reason`). */
 export type NextSequenceActionInput = {
     timing: {
         mode: 'at';
@@ -187,16 +189,13 @@ export type NextSequenceActionInput = {
     /** 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. */
+/** When a wake-up fires. Its business name and explanation are the action's `name` and `reason` columns (51). */
 export type WakeActionInput = {
     timing: {
         mode: 'at';
         at: string;
     };
-    name: string;
-    note?: string;
 };
 /** Each kind's stored `input`. */
 export type ScheduledActionInputs = {
@@ -211,6 +210,8 @@ export type ScheduledActionInput = ScheduledActionInputs[ScheduledActionKind];
 /** A pending contact: who and its `input`. */
 export type ContactActionView = {
     id: string;
+    name?: string | null;
+    status?: 'scheduled' | 'running' | 'completed' | 'failed' | 'cancelled';
     kind: ContactChannel;
     /** The contact to reach. */
     contactId: string;
@@ -219,33 +220,47 @@ export type ContactActionView = {
      */
     scheduledFor: string;
     input: ContactActionInput;
+    /** Why it was booked (40 §2.6); null when nobody said. */
+    reason: string | null;
 };
 /** Pending scheduled slot writes: instance-level, no contact. */
 export type UpdateSlotsActionView = {
     id: string;
+    name?: string | null;
+    status?: 'scheduled' | 'running' | 'completed' | 'failed' | 'cancelled';
     kind: 'update_slots';
     contactId: null;
     /** Execution time (`input.timing.at`, ISO 8601). */
     scheduledFor: string;
     input: UpdateSlotsActionInput;
+    /** Why it was booked (40 §2.6); null when nobody said. */
+    reason: string | null;
 };
 /** A pending hand-over to the next sequence: instance-level, no contact. */
 export type NextSequenceActionView = {
     id: string;
+    name?: string | null;
+    status?: 'scheduled' | 'running' | 'completed' | 'failed' | 'cancelled';
     kind: 'next_sequence';
     contactId: null;
     /** Execution time (`input.timing.at`, ISO 8601). */
     scheduledFor: string;
     input: NextSequenceActionInput;
+    /** Why it was booked (40 §2.6); null when nobody said. */
+    reason: string | null;
 };
 /** A pending wake-up of the Orchestrator: instance-level, no contact. */
 export type WakeActionView = {
     id: string;
+    name?: string | null;
+    status?: 'scheduled' | 'running' | 'completed' | 'failed' | 'cancelled';
     kind: 'wake';
     contactId: null;
     /** When it wakes the Orchestrator (`input.timing.at`, ISO 8601). */
     scheduledFor: string;
     input: WakeActionInput;
+    /** Why it was booked (40 §2.6); null when nobody said. */
+    reason: string | null;
 };
 /** A scheduled action still active when the Run input is built; `kind` tells which `input` it has. */
 export type ScheduledActionView = ContactActionView | UpdateSlotsActionView | NextSequenceActionView | WakeActionView;
@@ -271,7 +286,7 @@ export type ExchangeEvent = {
     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. */
+    /** Set when it was a scheduled action. */
     scheduledActionId: string | null;
 };
 /** Exchange counts, last events by kind, and recent timeline for the Case (`all`) or one party. */
@@ -360,12 +375,12 @@ export type PartyContactHours = {
         }[];
     }[];
 };
-/** Exchange aggregates the platform computes when a Run starts. */
+/** Exchange aggregates of an instance with the contacts its code names (`ctx.api.exchanges.activity`, 38 §2.8). */
 export type CaseActivity = {
-    /** Timezone of the instance-level day numbers: the first contact's of the Run's `contacts`. */
+    /** Timezone of the instance-level day numbers: the first named contact's. */
     timezone: string;
     all: ActivityStats;
-    /** Every contact the Run may reach (orchestrator.ts's `contacts`), keyed by contactId, in that order. */
+    /** Every named contact, keyed by contactId, in the order named. */
     byContact: Readonly<Record<string, PartyActivity>>;
 };
 export declare const EMPTY_CASE_ACTIVITY: CaseActivity;
@@ -380,7 +395,6 @@ export type CaseOrchestratorParams = {
     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
@@ -396,19 +410,20 @@ export type CaseOrchestratorParams = {
  */
 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
+     * The platform's tools: 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`.
+ * `ctx` of `orchestrator`: a function's `ctx` (38 §2.3), so a function can be called with it, plus
+ * `api.tools`. `D` types `ctx.api.db`.
  */
-export type CaseOrchestratorContext<D extends PageTablesDesc | undefined = undefined> = Omit<SystemContext, 'api'> & {
+export type CaseOrchestratorContext<D extends PageTablesDesc | undefined = undefined> = Omit<SystemContext, 'api' | 'meta'> & {
+    /** What runs, where (38 §2.3): the instance is `args.instanceId`. */
+    meta: Omit<SystemContext['meta'], 'instanceId'>;
     api: CaseOrchestratorApi<D>;
-    params: CaseOrchestratorParams;
 };
 /**
  * When a scheduled action runs (25 §4): `at`, an exact instant (ISO 8601 with an offset or Z; its
@@ -422,7 +437,7 @@ export type ScheduleTiming = {
 /**
  * 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
+ * together; the platform does not check them, and they serve only as evidence, not deduplication). Like any
  * action it runs at its `at`; an opt-out still stops it.
  * docs/design/09-agreed-follow-up.md
  */
@@ -435,7 +450,7 @@ export type AgreementFields = {
     note?: string;
 };
 /**
- * Whom to contact (one of the Run's `contacts`) and, optionally, the addresses: `to` one of the
+ * Whom to contact 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).
  */
@@ -443,8 +458,9 @@ export type ScheduleActionInput = {
     contactId: string;
     to?: string;
     from?: string;
+    name?: string;
 } & ScheduleTiming & AgreementFields;
-/** One field on an existing row, as `updateSlots` takes it. */
+/** One field on an existing row, as `scheduleUpdateSlots` takes it. */
 export type SlotFieldWriteInput = {
     /** `table.field`. */
     path: string;
@@ -462,7 +478,7 @@ export type SlotInsertInput = {
     insert: string;
     values: Record<string, string | number | boolean | string[] | null | ContactSchedule>;
 };
-/** One slot write, as `updateSlots` and `scheduleUpdateSlots` take it. */
+/** One slot write, as `scheduleUpdateSlots` takes it. */
 export type SlotWriteInput = SlotFieldWriteInput | SlotInsertInput;
 /**
  * Slot writes to make at a set time, and why. Validated now, written as given when due (checked
@@ -558,15 +574,12 @@ export type ToolCallArgs = {
         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';
+        /** That case's exchanges. Company code names at least one of `instanceId`, `contactId`, `scheduledActionId`. */
+        instanceId?: string;
         limit?: number;
         /** Pagination cursor from a previous result's `nextBefore`. */
         before?: string;
     };
-    updateSlots: {
-        writes: SlotWriteInput[];
-    };
     scheduleCall: ScheduleActionInput;
     scheduleSms: ScheduleActionInput;
     scheduleEmail: ScheduleActionInput;
@@ -586,11 +599,6 @@ export type ToolCallArgs = {
         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: {
@@ -625,12 +633,6 @@ export type ScheduledResult = {
     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;
 };
@@ -641,17 +643,10 @@ export type RescheduledResult = {
     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;
@@ -663,10 +658,6 @@ export type ToolCallResult = {
         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: {
@@ -677,77 +668,41 @@ export type ToolCallResult = {
 export type ToolResult<T> = {
     ok: true;
     value: T;
-    toolCallId: string;
+    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;
+    toolCallId?: string;
 };
+/** The tools that only read: they work on no instance (38 §2.7). */
+export type ReadToolName = 'readExchange' | 'searchExchanges';
+/**
+ * `ctx.api.tools` (38 §2.7): a platform API of every function and entry, the same for every caller,
+ * held to the caller's company and environment. A command names the instance it works on and acts
+ * each time it is called (its record is `toolCallId`); a read names what it reads.
+ */
 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[];
+    [N in CaseOrchestratorToolName]: (input: N extends ReadToolName ? ToolCallArgs[N] : ToolCallArgs[N] & {
+        instanceId: string;
+    }) => Promise<ToolResult<ToolCallResult[N]>>;
 };
-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`.
+ * What `orchestrator` is called with (38 §2.2): the instance and its business root's id, the anchor of
+ * its reads (`ctx.api.db.<root table>.findUnique({ where: { id: args.subject } })`), and the Run's
+ * frozen inputs. What changes (run variables, the instance's status) is read with
+ * `ctx.api.instances.get`.
  */
-export type CaseInput<S extends string = string> = {
+export type CaseOrchestratorArgs<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[]>;
+} & CaseOrchestratorParams;
 /**
- * `orchestrator.ts`: `export const orchestrator: CaseOrchestrator = async (c, ctx) => …`.
- * `C` is the sequence's `CaseOrchestratorInput`; `D` its `PageTables` (`__gen` binds both).
+ * `orchestrator.ts`: `export const orchestrator: CaseOrchestrator = async (ctx, args) => …`.
+ * `D` is the company's `PageTables`, `S` the sequence's subject table (`__gen` binds both).
  */
-export type CaseOrchestrator<C = CaseOrchestratorInput, D extends PageTablesDesc | undefined = undefined> = (caseContext: C, ctx: CaseOrchestratorContext<D>) => Promise<CaseOrchestratorResult>;
+export type CaseOrchestrator<D extends PageTablesDesc | undefined = undefined, S extends string = string> = (ctx: CaseOrchestratorContext<D>, args: CaseOrchestratorArgs<S>) => Promise<void>;
 export {};
 //# sourceMappingURL=types.d.ts.map

package/dist/core/case-orchestrator/types.js

@@ -1,14 +1,11 @@
 /** Reserved export of `sequences/<id>/orchestrator.ts` and its name in the build's `functions`. */
 export const ORCHESTRATOR_FUNCTION = 'orchestrator';
-/** `orchestrator.ts`'s required `contacts` export: its name in the build's `functions`. */
-export const ORCHESTRATOR_CONTACTS_FUNCTION = 'orchestratorContacts';
 /** `ctx.meta.entry` / RunScope entry of a Case Orchestrator call. */
 export const ORCHESTRATOR_ENTRY = 'orchestrator';
 /** Platform tools a Run may open. Names, descriptions, schemas and executors belong to the platform. */
 export const CASE_ORCHESTRATOR_TOOL_NAMES = [
     'readExchange',
     'searchExchanges',
-    'updateSlots',
     'scheduleCall',
     'scheduleSms',
     'scheduleEmail',
@@ -16,7 +13,6 @@ export const CASE_ORCHESTRATOR_TOOL_NAMES = [
     'rescheduleAction',
     'cancelScheduledAction',
     'scheduleNextSequence',
-    'closeInstance',
     'scheduleWake',
     'cancelWake',
 ];

package/dist/core/context/email-message.d.ts

@@ -85,10 +85,35 @@ export declare const emailGetOutput: z.ZodNullable<z.ZodObject<{
     delivery: z.ZodNullable<z.ZodString>;
     occurredAt: z.ZodString;
 }, z.core.$strip>>;
-/** Platform email-history capability, reached from scripts as `ctx.api.email`. */
+/**
+ * An email sent now (64 §15), from any entry, as a text is (`ctx.api.sms.send`): one recipient, no cc or bcc.
+ * `to` is a contact's row id, or `{ address }` for someone who is not one (an on-call lawyer, opposing
+ * counsel). An address that is a contact's of this environment is sent as to that contact: their opt-outs
+ * are checked. `from` names the mailbox (its name in the environment); absent, a contact's own mailbox (one
+ * picked at random is remembered on them), else any active one. It goes back in the newest thread with
+ * them on that mailbox, else starts one; stored with the run, then sent. The case it is about, and who
+ * hears `email.sent`: as for a text. Pause and contact hours are not checked.
+ */
+export declare const emailSendInput: z.ZodObject<{
+    to: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        address: z.ZodString;
+    }, z.core.$strict>]>;
+    body: z.ZodString;
+    subject: z.ZodOptional<z.ZodString>;
+    instanceId: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type EmailSendParams = z.infer<typeof emailSendInput>;
+/** The thread the email went on (`email.sent` on the case's timeline). */
+export declare const emailSendOutput: z.ZodObject<{
+    exchangeId: z.ZodString;
+}, z.core.$strip>;
+export type EmailSendResult = z.infer<typeof emailSendOutput>;
+/** Platform email capability, reached from scripts as `ctx.api.email`: the history, and sending one now. */
 export type EmailHistoryApi = {
     list(input: EmailListParams): Promise<EmailListResult>;
     get(id: string): Promise<EmailRecord | null>;
+    send(input: EmailSendParams): Promise<EmailSendResult>;
 };
 export declare const emailHistoryMockService: EmailHistoryApi;
 export declare const emailHistorySurface: {
@@ -153,6 +178,20 @@ export declare const emailHistorySurface: {
                 occurredAt: z.ZodString;
             }, z.core.$strip>>;
         };
+        send: {
+            input: z.ZodObject<{
+                to: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+                    address: z.ZodString;
+                }, z.core.$strict>]>;
+                body: z.ZodString;
+                subject: z.ZodOptional<z.ZodString>;
+                instanceId: z.ZodOptional<z.ZodString>;
+                from: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>;
+            output: z.ZodObject<{
+                exchangeId: z.ZodString;
+            }, z.core.$strip>;
+        };
     };
     mock: EmailHistoryApi;
 };

package/dist/core/context/email-message.js

@@ -41,6 +41,29 @@ export const emailListOutput = z.object({
 });
 export const emailGetInput = z.string().min(1);
 export const emailGetOutput = emailRecord.nullable();
+/**
+ * An email sent now (64 §15), from any entry, as a text is (`ctx.api.sms.send`): one recipient, no cc or bcc.
+ * `to` is a contact's row id, or `{ address }` for someone who is not one (an on-call lawyer, opposing
+ * counsel). An address that is a contact's of this environment is sent as to that contact: their opt-outs
+ * are checked. `from` names the mailbox (its name in the environment); absent, a contact's own mailbox (one
+ * picked at random is remembered on them), else any active one. It goes back in the newest thread with
+ * them on that mailbox, else starts one; stored with the run, then sent. The case it is about, and who
+ * hears `email.sent`: as for a text. Pause and contact hours are not checked.
+ */
+export const emailSendInput = z
+    .object({
+    to: z.union([z.string().min(1), z.object({ address: z.string().min(1) }).strict()]),
+    body: z.string().min(1),
+    /** Absent: a reply to the thread's subject, or a plain one for a new thread. */
+    subject: z.string().optional(),
+    /** The case the email is about, any of this environment's; absent: the run's own case, if any. */
+    instanceId: z.string().min(1).optional(),
+    /** The mailbox to send from, by its name in the environment. */
+    from: z.string().min(1).optional(),
+})
+    .strict();
+/** The thread the email went on (`email.sent` on the case's timeline). */
+export const emailSendOutput = z.object({ exchangeId: z.string() });
 export const emailHistoryMockService = {
     async list(input) {
         return { emails: [], offset: input.offset, limit: input.limit };
@@ -48,11 +71,15 @@ export const emailHistoryMockService = {
     async get() {
         return null;
     },
+    async send() {
+        return { exchangeId: 'mock-email' };
+    },
 };
 export const emailHistorySurface = {
     methods: {
         list: { input: emailListInput, output: emailListOutput },
         get: { input: emailGetInput, output: emailGetOutput },
+        send: { input: emailSendInput, output: emailSendOutput },
     },
     mock: emailHistoryMockService,
 };

package/dist/core/context/email.d.ts

@@ -83,12 +83,24 @@ export declare const emailGetAttachmentOutput: z.ZodObject<{
     data: z.ZodString;
 }, z.core.$strip>;
 export type EmailGetAttachmentOutput = z.infer<typeof emailGetAttachmentOutput>;
+/**
+ * A mailbox as company code reaches it (`ctx.api.integration.emails[]`): reading its messages and their
+ * attachments. Sending is `ctx.api.email.send` (64 §15): opt-outs checked, stored, threaded, on the case.
+ */
 export type EmailService = {
-    sendEmail(input: EmailSendEmailInput): Promise<EmailSendEmailOutput>;
     getMessage(input: EmailGetMessageInput): Promise<EmailGetMessageOutput>;
     listMessages(input: EmailListMessagesInput): Promise<EmailListMessagesOutput>;
     getAttachment(input: EmailGetAttachmentInput): Promise<EmailGetAttachmentOutput>;
 };
+/**
+ * The mail provider as the platform drives it: the reads, and handing an email to Gmail / Outlook as is
+ * (no opt-out check, no record). The platform's own; company code never reaches `sendEmail`.
+ */
+export type EmailProviderService = EmailService & {
+    sendEmail(input: EmailSendEmailInput): Promise<EmailSendEmailOutput>;
+};
+/** The provider methods only the platform calls: left out of the company's script surface. */
+export declare const EMAIL_PLATFORM_ONLY_METHODS: readonly ["sendEmail"];
 export declare const emailMockService: EmailService;
 export type EmailApi = IntegrationAccountFields & EmailService & {
     readonly address: string;

package/dist/core/context/email.js

@@ -61,10 +61,9 @@ export const emailGetAttachmentOutput = z.object({
     contentType: z.string(),
     data: z.string(),
 });
+/** The provider methods only the platform calls: left out of the company's script surface. */
+export const EMAIL_PLATFORM_ONLY_METHODS = ['sendEmail'];
 export const emailMockService = {
-    async sendEmail() {
-        return { id: 'mock-email-id', threadId: 'mock-thread' };
-    },
     async getMessage() {
         return {
             id: 'mock-email-id',