toolroll 0.9.36 → 0.9.38

package/dist/contracts/chat-actions.js

@@ -0,0 +1,133 @@
+/**
+ * Shared chat actions (chat-actions.ts): one schema for each action's data — what the lead proposes and what a saved
+ * proposal carries after `prepareSharedAction` has checked and rewritten it — and one for the saved proposal itself.
+ * The allowed fields (`CHAT_ACTION_FIELDS`) and the request types are derived from these; what JSON Schema can't say
+ * (credentials and control characters in text, each field's length, a zone or option that exists, who may act) runs
+ * in `prepareSharedAction` after parsing, with its own named refusal.
+ *
+ * A flow drawing, trigger or script inside a request is read by its own contract (flows.ts `validateFlowDefinition`,
+ * flow-triggers.ts `validateTriggerConfig`, flow-scripts.ts `validateScript`) when the action is prepared, in every
+ * vocabulary those accept; here it is only "a value".
+ */
+import { z } from "zod";
+import { parseContract, readVersioned, versioned } from "./contract.js";
+/** An id the store minted: a positive safe integer. */
+const id = z.int().min(1);
+const words = z.string();
+/** A drawing, trigger or script: read by its own contract when the action is prepared. */
+const nested = z.unknown();
+const skillFile = z.strictObject({ path: z.string(), base64: z.string() });
+/** An object whose keys its own reader knows (a script draft, an action's staleness fence). */
+const anyObject = z.object({}).catchall(z.unknown());
+/**
+ * Each action's data, field order as the lead reads it in `get_actions`. Fields a branch ignores or reads through
+ * its own validator stay unknown: 0.9.36 accepted null and other non-string values there. Preparation still checks
+ * the selected branch and saves the same request bytes. No schema defaults or coercion may change its stamp.
+ */
+export const chatActionRequestSchemas = {
+    skill_import: z.strictObject({ repo: words, content: words.optional(), files: z.array(skillFile).optional() }),
+    skill_enable: z.strictObject({ repo: words, version: words }),
+    skill_disable: z.strictObject({ repo: words, version: words }),
+    skill_restore: z.strictObject({ repo: words, restore: id }),
+    skill_test: z.strictObject({ repo: words, version: words, sample: words, nonce: words }),
+    knowledge_instructions: z.strictObject({ repo: words, instructions: words.optional() }),
+    knowledge_save: z.strictObject({ repo: words, title: words, content: words, id: words.optional() }),
+    knowledge_remove: z.strictObject({ repo: words, id: words }),
+    knowledge_restore: z.strictObject({ repo: words, restore: id }),
+    tool_add: z.strictObject({
+        repo: words, catalog: z.unknown().optional(), name: z.unknown().optional(), command: z.unknown().optional(), args: z.unknown().optional(),
+        url: z.unknown().optional(), secrets: z.unknown().optional(), about: z.unknown().optional(),
+    }),
+    tool_remove: z.strictObject({ repo: words, name: words }),
+    flow_create: z.strictObject({ repo: words, name: words, definition: nested, trigger: nested.optional() }),
+    flow_starter: z.strictObject({ repo: words, starter: words }),
+    flow_edit: z.strictObject({ flow: id, name: words.optional(), definition: nested.optional() }),
+    flow_card_add: z.strictObject({ flow: id, title: words, description: z.unknown().optional(), zone: words.optional() }),
+    flow_card_move: z.strictObject({ card: id, zone: words }),
+    flow_card_approve: z.strictObject({ card: id, note: words.optional() }),
+    flow_card_send_back: z.strictObject({ card: id, note: words.optional() }),
+    /** An option by its number (from 1), or a reply that becomes the note. */
+    flow_card_choose: z.strictObject({ card: id, choice: z.int().nullable().optional(), note: z.unknown().optional() }),
+    flow_card_cancel: z.strictObject({ card: id }),
+    flow_card_comment: z.strictObject({ card: id, note: words }),
+    flow_card_assign: z.strictObject({ card: id, owner: words.nullable().optional() }),
+    flow_card_watch: z.strictObject({ card: id, watching: z.unknown().optional() }),
+    flow_script_save: z.strictObject({ repo: words, script: anyObject }),
+    flow_trigger_add: z.strictObject({ flow: id, trigger: nested }),
+    flow_trigger_pause: z.strictObject({ trigger: id }),
+    flow_trigger_resume: z.strictObject({ trigger: id }),
+    flow_trigger_remove: z.strictObject({ trigger: id }),
+    teammate_create: z.strictObject({ repo: words, template: z.unknown().optional(), name: z.unknown().optional(), soul: z.unknown().optional() }),
+    teammate_soul: z.strictObject({ teammate: id, soul: words }),
+    teammate_state: z.strictObject({ teammate: id, state: z.enum(["active", "paused", "removed"]) }),
+    teammate_note: z.strictObject({ teammate: id, note: words }),
+    teammate_answer: z.strictObject({ question: id, choice: z.unknown().optional(), text: z.unknown().optional() }),
+    teammate_tools: z.strictObject({
+        teammate: id, tool: words, change: z.enum(["grant", "revoke", "rule"]), action: z.unknown().optional(), use: z.unknown().optional(),
+        limitField: z.unknown().optional(), limitOver: z.unknown().optional(), undoWith: z.unknown().optional(),
+    }),
+    teammate_memory: z.strictObject({ teammate: id, memory: id, change: z.enum(["edit", "forget"]), text: z.unknown().optional() }),
+    teammate_routine: z.strictObject({ teammate: id, change: z.enum(["add", "remove"]), routine: z.unknown().optional(), schedule: z.unknown().optional(), text: z.unknown().optional() }),
+    teammate_undo: z.strictObject({ teammate: id, call: id }),
+    kit_setup: z.strictObject({ repo: words, kit: words }),
+    decision_record: z.strictObject({ repo: words, claim: words, why: words, supersedes: id.optional(), source: words.optional() }),
+    decision_retire: z.strictObject({ repo: words, decision: id, reason: words }),
+    /** The line, and (from 1) the line it replaces; 0 or none adds it. */
+    lead_about_you: z.strictObject({ line: words, replaces: z.int().min(0).optional() }),
+    scope_approve: z.strictObject({ task: words }),
+    result_accept: z.strictObject({ task: words, run: id }),
+    task_cancel: z.strictObject({ task: words }),
+    task_resume: z.strictObject({ task: words, run: id }),
+};
+export const CHAT_ACTION_OPERATIONS = Object.keys(chatActionRequestSchemas);
+/** The fields each action takes, from its schema. */
+export const CHAT_ACTION_FIELDS = Object.fromEntries(CHAT_ACTION_OPERATIONS.map(operation => [operation, Object.keys(chatActionRequestSchemas[operation].shape)]));
+const isOperation = (value) => typeof value === "string" && Object.hasOwn(chatActionRequestSchemas, value);
+/** One action's data, refused by path (`card: required`, `payload: unknown key 'cards' (did you mean card?)`). */
+export function readChatActionRequest(operation, input) {
+    return parseContract(chatActionRequestSchemas[operation], input);
+}
+export const SHARED_ACTION_VERSION = 1;
+/**
+ * A prepared action as a proposal saves it: the action, its checked request, the project, the card's title and
+ * terms, the stamp that proves nothing changed before it is confirmed, and the state the stamp was taken over (each
+ * action's own staleness fence, read back only by that action).
+ */
+export const sharedActionSchema = versioned(SHARED_ACTION_VERSION, {
+    operation: z.enum(CHAT_ACTION_OPERATIONS),
+    request: anyObject,
+    repo: z.string(),
+    title: z.string(),
+    terms: z.array(z.string()),
+    stamp: z.string(),
+    state: anyObject,
+});
+const SHARED_ACTION_FIELDS = Object.keys(sharedActionSchema.shape).filter(field => field !== "version");
+/**
+ * A proposal saved before it carried `version` (every one through 0.9.36), as version 1. Its reader took the fields
+ * it knew and passed any others through unread, so this keeps exactly the known fields.
+ */
+export function upgradeUnversionedSharedAction(body) {
+    const out = { version: SHARED_ACTION_VERSION };
+    for (const field of SHARED_ACTION_FIELDS)
+        if (Object.hasOwn(body, field))
+            out[field] = body[field];
+    return out;
+}
+export const SHARED_ACTION_UPGRADES = { 0: upgradeUnversionedSharedAction };
+const under = (prefix, issues) => issues.map(issue => {
+    const path = issue.path === "payload" ? prefix : `${prefix}.${issue.path}`;
+    return { ...issue, path, line: `${path}${issue.line.slice(issue.path.length)}` };
+});
+/** Legacy readers checked only the envelope. Confirmation still prepares the request again before acting. */
+export function readSharedAction(input) {
+    const read = readVersioned(sharedActionSchema, input, SHARED_ACTION_UPGRADES);
+    if (!read.ok)
+        return read;
+    if (!isOperation(read.value.operation))
+        return { ok: false, issues: [{ path: "operation", kind: "bad-value", line: "operation: not an action" }] };
+    if (!Object.hasOwn(input, "version") || input["version"] === 0)
+        return read;
+    const request = readChatActionRequest(read.value.operation, read.value.request);
+    return request.ok ? read : { ok: false, issues: under("request", request.issues) };
+}

package/dist/contracts/chat-callback-rows.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The saved side of a chat button: the row its one-time token names. A proposal card's buttons in Slack, Discord and
+ * Teams (`chat_action`, read with the part and event it rides) and a result's, plan's, failure's or pull request's own
+ * buttons (`chat_decide_action`, chat-decide.ts). SQLite's own CHECKs bound them when written; these say what a
+ * reader may rely on, so a row that isn't that is refused by column, never read as a guess.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** A proposal card's button (chat-delivery.ts), with the part's message and the event's binding, channel and thread. */
+export declare const proposalActionRowSchema: z.ZodObject<{
+    token: z.ZodString;
+    part: z.ZodInt;
+    proposal: z.ZodInt;
+    phase: z.ZodEnum<{
+        cancel: "cancel";
+        confirm: "confirm";
+        dismiss: "dismiss";
+        yes: "yes";
+    }>;
+    expires: z.ZodString;
+    consumed: z.ZodNullable<z.ZodString>;
+    message: z.ZodNullable<z.ZodString>;
+    binding: z.ZodNullable<z.ZodInt>;
+    channel: z.ZodString;
+    thread: z.ZodString;
+}, z.core.$strict>;
+export type ProposalActionRow = z.infer<typeof proposalActionRowSchema>;
+export declare function readProposalActionRow(row: unknown): ContractResult<ProposalActionRow>;
+export declare const DECIDE_ACTS: readonly ["accept", "changes", "retry", "approve", "not-now", "merge"];
+export declare const DECIDE_PHASES: readonly ["offer", "yes", "cancel"];
+/** A decide button (chat-decide.ts): who and where it was sent, what it does to which task and run, and the stamp it holds. */
+export declare const decideActionRowSchema: z.ZodObject<{
+    token: z.ZodString;
+    channel: z.ZodString;
+    binding: z.ZodInt;
+    chat: z.ZodString;
+    message: z.ZodNullable<z.ZodString>;
+    act: z.ZodEnum<{
+        accept: "accept";
+        approve: "approve";
+        changes: "changes";
+        merge: "merge";
+        "not-now": "not-now";
+        retry: "retry";
+    }>;
+    phase: z.ZodEnum<{
+        cancel: "cancel";
+        offer: "offer";
+        yes: "yes";
+    }>;
+    task_id: z.ZodString;
+    run: z.ZodNullable<z.ZodInt>;
+    digest: z.ZodString;
+    created_at: z.ZodString;
+    expires_at: z.ZodString;
+    consumed_at: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type DecideActionRow = z.infer<typeof decideActionRowSchema>;
+export declare function readDecideActionRow(row: unknown): ContractResult<DecideActionRow>;

package/dist/contracts/chat-callback-rows.js

@@ -0,0 +1,46 @@
+/**
+ * The saved side of a chat button: the row its one-time token names. A proposal card's buttons in Slack, Discord and
+ * Teams (`chat_action`, read with the part and event it rides) and a result's, plan's, failure's or pull request's own
+ * buttons (`chat_decide_action`, chat-decide.ts). SQLite's own CHECKs bound them when written; these say what a
+ * reader may rely on, so a row that isn't that is refused by column, never read as a guess.
+ */
+import { z } from "zod";
+import { parseContract } from "./contract.js";
+const when = z.string();
+/** A proposal card's button (chat-delivery.ts), with the part's message and the event's binding, channel and thread. */
+export const proposalActionRowSchema = z.strictObject({
+    token: z.string(),
+    part: z.int(),
+    proposal: z.int(),
+    phase: z.enum(["confirm", "dismiss", "yes", "cancel"]),
+    expires: when,
+    consumed: when.nullable(),
+    message: z.string().nullable(),
+    binding: z.int().nullable(),
+    channel: z.string(),
+    thread: z.string(),
+});
+export function readProposalActionRow(row) {
+    return parseContract(proposalActionRowSchema, row);
+}
+export const DECIDE_ACTS = ["accept", "changes", "retry", "approve", "not-now", "merge"];
+export const DECIDE_PHASES = ["offer", "yes", "cancel"];
+/** A decide button (chat-decide.ts): who and where it was sent, what it does to which task and run, and the stamp it holds. */
+export const decideActionRowSchema = z.strictObject({
+    token: z.string().regex(/^d:[a-f0-9]{24}$/),
+    channel: z.string(),
+    binding: z.int(),
+    chat: z.string(),
+    message: z.string().nullable(),
+    act: z.enum(DECIDE_ACTS),
+    phase: z.enum(DECIDE_PHASES),
+    task_id: z.string(),
+    run: z.int().nullable(),
+    digest: z.string(),
+    created_at: when,
+    expires_at: when,
+    consumed_at: when.nullable(),
+});
+export function readDecideActionRow(row) {
+    return parseContract(decideActionRowSchema, row);
+}

package/dist/contracts/chat-content.d.ts

@@ -0,0 +1,276 @@
+/**
+ * What Slack, Discord and Teams keep between steps (chat-delivery-state.ts): one schema for a received event's body
+ * (`chat_event.payload`, by the event's kind) and one for a planned message part (`chat_part.payload`), the message a
+ * button rides and the content a delivery repaints. Both are saved with `version`; a body or part saved before they
+ * carried one reads as it did then (its known fields; a reader then passed any others by unread).
+ *
+ * An event body lives only until the event is handled (then it is `{}`); a part lives as long as its message.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** One planned message part, as delivery reads it. */
+export declare const chatContentShape: {
+    text: z.ZodString;
+    /** Where the part is sent when not the binding's own DM: a room's channel. */
+    channel: z.ZodOptional<z.ZodString>;
+    proposal: z.ZodOptional<z.ZodInt>;
+    image: z.ZodOptional<z.ZodObject<{
+        taskId: z.ZodString;
+        run: z.ZodInt;
+        artifact: z.ZodInt;
+        sha256: z.ZodString;
+    }, z.core.$strict>>;
+    /** A screenshot sent with a result (result-shots.ts): it follows that result's message part, in its thread when
+     * the app allows; a refused upload becomes one plain line, and one removed by retention goes quietly. */
+    shot: z.ZodOptional<z.ZodObject<{
+        follows: z.ZodNullable<z.ZodInt>;
+    }, z.core.$strict>>;
+    task: z.ZodOptional<z.ZodString>;
+    run: z.ZodOptional<z.ZodInt>;
+    edit: z.ZodOptional<z.ZodString>;
+    phase: z.ZodOptional<z.ZodLiteral<"armed">>;
+    link: z.ZodOptional<z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>>;
+    /** More link buttons after `link`: [Look first] beside [Merge] or [Accept and finish]. */
+    also: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>>>;
+    /** A flow decision's buttons ride this part (v88): minted when it is planned. */
+    flow: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        actions: z.ZodArray<z.ZodEnum<{
+            approve: "approve";
+            edit: "edit";
+            "send-back": "send-back";
+        }>>;
+    }, z.core.$strict>>;
+    /** A flow's "Person chooses" buttons ride this part: minted when it is planned. */
+    choose: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        options: z.ZodArray<z.ZodObject<{
+            choice: z.ZodInt;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    /** "Use this as your note?" Yes / No about the person's message `held` (an event id), for one choice's visit. */
+    note: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        held: z.ZodString;
+    }, z.core.$strict>>;
+    /** A teammate's question's buttons ride this part (v93): each option, then one to answer in words (choice null). */
+    question: z.ZodOptional<z.ZodObject<{
+        id: z.ZodInt;
+        choices: z.ZodArray<z.ZodObject<{
+            choice: z.ZodNullable<z.ZodString>;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    /** The lead's question to its owner rides this part: its options, then "Something else". */
+    ask: z.ZodOptional<z.ZodObject<{
+        turn: z.ZodInt;
+        options: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    /** The lead's own reply, already shaped (reply-shape.ts): the channel renders its bold anchors and labelled links in its own format. */
+    voice: z.ZodOptional<z.ZodLiteral<true>>;
+};
+export declare const chatContentSchema: z.ZodObject<{
+    text: z.ZodString;
+    channel: z.ZodOptional<z.ZodString>;
+    proposal: z.ZodOptional<z.ZodInt>;
+    image: z.ZodOptional<z.ZodObject<{
+        taskId: z.ZodString;
+        run: z.ZodInt;
+        artifact: z.ZodInt;
+        sha256: z.ZodString;
+    }, z.core.$strict>>;
+    shot: z.ZodOptional<z.ZodObject<{
+        follows: z.ZodNullable<z.ZodInt>;
+    }, z.core.$strict>>;
+    task: z.ZodOptional<z.ZodString>;
+    run: z.ZodOptional<z.ZodInt>;
+    edit: z.ZodOptional<z.ZodString>;
+    phase: z.ZodOptional<z.ZodLiteral<"armed">>;
+    link: z.ZodOptional<z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>>;
+    also: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>>>;
+    flow: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        actions: z.ZodArray<z.ZodEnum<{
+            approve: "approve";
+            edit: "edit";
+            "send-back": "send-back";
+        }>>;
+    }, z.core.$strict>>;
+    choose: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        options: z.ZodArray<z.ZodObject<{
+            choice: z.ZodInt;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    note: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        held: z.ZodString;
+    }, z.core.$strict>>;
+    question: z.ZodOptional<z.ZodObject<{
+        id: z.ZodInt;
+        choices: z.ZodArray<z.ZodObject<{
+            choice: z.ZodNullable<z.ZodString>;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    ask: z.ZodOptional<z.ZodObject<{
+        turn: z.ZodInt;
+        options: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    voice: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+export type ChatContent = z.infer<typeof chatContentSchema>;
+export declare const CHAT_PART_VERSION = 1;
+export declare const savedChatPartSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    text: z.ZodString;
+    channel: z.ZodOptional<z.ZodString>;
+    proposal: z.ZodOptional<z.ZodInt>;
+    image: z.ZodOptional<z.ZodObject<{
+        taskId: z.ZodString;
+        run: z.ZodInt;
+        artifact: z.ZodInt;
+        sha256: z.ZodString;
+    }, z.core.$strict>>;
+    shot: z.ZodOptional<z.ZodObject<{
+        follows: z.ZodNullable<z.ZodInt>;
+    }, z.core.$strict>>;
+    task: z.ZodOptional<z.ZodString>;
+    run: z.ZodOptional<z.ZodInt>;
+    edit: z.ZodOptional<z.ZodString>;
+    phase: z.ZodOptional<z.ZodLiteral<"armed">>;
+    link: z.ZodOptional<z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>>;
+    also: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        path: z.ZodString;
+    }, z.core.$strict>>>;
+    flow: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        actions: z.ZodArray<z.ZodEnum<{
+            approve: "approve";
+            edit: "edit";
+            "send-back": "send-back";
+        }>>;
+    }, z.core.$strict>>;
+    choose: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        options: z.ZodArray<z.ZodObject<{
+            choice: z.ZodInt;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    note: z.ZodOptional<z.ZodObject<{
+        card: z.ZodInt;
+        entry: z.ZodInt;
+        held: z.ZodString;
+    }, z.core.$strict>>;
+    question: z.ZodOptional<z.ZodObject<{
+        id: z.ZodInt;
+        choices: z.ZodArray<z.ZodObject<{
+            choice: z.ZodNullable<z.ZodString>;
+            label: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    ask: z.ZodOptional<z.ZodObject<{
+        turn: z.ZodInt;
+        options: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    voice: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+/** A saved part's content (`version` is the saved form's, not the content's). */
+export declare function readChatPart(raw: string): ContractResult<ChatContent>;
+/** A part as it is saved. */
+export declare function savedChatPart(content: ChatContent): string;
+export declare const CHAT_EVENT_VERSION = 1;
+/** `pair <code>`: only the code's hash is kept. */
+export declare const chatPairBodySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    hash: z.ZodString;
+}, z.core.$strict>;
+/**
+ * A message: its words (cut at the lead's limit, `originalLength` saying how long it was), or a plain line to answer
+ * with instead (`unsupported`: a file the app can't take). A room's or notice's carrier event has none. `about` is the
+ * task its turn is about, once chosen; `lead` is a held message passed to the lead as it was (chat-flow.ts).
+ */
+export declare const chatMessageBodySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    text: z.ZodOptional<z.ZodString>;
+    originalLength: z.ZodOptional<z.ZodInt>;
+    unsupported: z.ZodOptional<z.ZodString>;
+    about: z.ZodOptional<z.ZodObject<{
+        task: z.ZodString;
+        run: z.ZodNullable<z.ZodInt>;
+    }, z.core.$strict>>;
+    lead: z.ZodOptional<z.ZodLiteral<true>>;
+}, z.core.$strict>;
+/**
+ * A button: the one-time token it carried, or, when the app's callback came from the paired person but its data
+ * couldn't be read, the path-named line saying why — answered plainly, and nothing is done.
+ */
+export declare const chatTokenBodySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    token: z.ZodString;
+}, z.core.$strict>;
+export declare const chatProblemBodySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    problem: z.ZodString;
+}, z.core.$strict>;
+export declare const chatActionBodySchema: z.ZodUnion<readonly [z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    token: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    problem: z.ZodString;
+}, z.core.$strict>]>;
+/** A notice carries its parts, not a body. */
+export declare const chatNoticeBodySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+}, z.core.$strict>;
+export type ChatPairBody = z.infer<typeof chatPairBodySchema>;
+export type ChatMessageBody = z.infer<typeof chatMessageBodySchema>;
+export type ChatActionBody = z.infer<typeof chatActionBodySchema>;
+/** What a writer hands `ChatState.enqueue`: a body of the event's kind, without `version` (it is stamped on saving). */
+export type ChatEventBody = Omit<ChatPairBody, "version"> | Omit<ChatMessageBody, "version"> | {
+    token: string;
+} | {
+    problem: string;
+} | Record<string, never>;
+export declare function savedChatEventBody(body: ChatEventBody): string;
+/** A pair event's body. */
+export declare function readChatPairBody(raw: string): ContractResult<ChatPairBody>;
+/** A message event's body. */
+export declare function readChatMessageBody(raw: string): ContractResult<ChatMessageBody>;
+/** An action event's body: a token, or the reason its callback couldn't be read. */
+export declare function readChatActionBody(raw: string): ContractResult<ChatActionBody>;
+/** Words held for "Use this as your note?" (`chat_flow_note.words`): the held message's own text and length. */
+export declare const heldWordsSchema: z.ZodObject<{
+    text: z.ZodString;
+    originalLength: z.ZodOptional<z.ZodInt>;
+}, z.core.$strict>;
+export type HeldWords = z.infer<typeof heldWordsSchema>;
+export declare function readHeldWords(raw: string): ContractResult<HeldWords>;

package/dist/contracts/chat-content.js

@@ -0,0 +1,127 @@
+/**
+ * What Slack, Discord and Teams keep between steps (chat-delivery-state.ts): one schema for a received event's body
+ * (`chat_event.payload`, by the event's kind) and one for a planned message part (`chat_part.payload`), the message a
+ * button rides and the content a delivery repaints. Both are saved with `version`; a body or part saved before they
+ * carried one reads as it did then (its known fields; a reader then passed any others by unread).
+ *
+ * An event body lives only until the event is handled (then it is `{}`); a part lives as long as its message.
+ */
+import { z } from "zod";
+import { parseContract, readVersioned, versioned } from "./contract.js";
+const id = z.int().min(1);
+const link = z.strictObject({ label: z.string(), path: z.string() });
+/** One planned message part, as delivery reads it. */
+export const chatContentShape = {
+    text: z.string(),
+    /** Where the part is sent when not the binding's own DM: a room's channel. */
+    channel: z.string().optional(),
+    proposal: id.optional(),
+    image: z.strictObject({ taskId: z.string(), run: z.int(), artifact: z.int(), sha256: z.string() }).optional(),
+    /** A screenshot sent with a result (result-shots.ts): it follows that result's message part, in its thread when
+     * the app allows; a refused upload becomes one plain line, and one removed by retention goes quietly. */
+    shot: z.strictObject({ follows: z.int().nullable() }).optional(),
+    task: z.string().optional(),
+    run: z.int().optional(),
+    edit: z.string().optional(),
+    phase: z.literal("armed").optional(),
+    link: link.optional(),
+    /** More link buttons after `link`: [Look first] beside [Merge] or [Accept and finish]. */
+    also: z.array(link).optional(),
+    /** A flow decision's buttons ride this part (v88): minted when it is planned. */
+    flow: z.strictObject({ card: id, entry: z.int(), actions: z.array(z.enum(["approve", "edit", "send-back"])) }).optional(),
+    /** A flow's "Person chooses" buttons ride this part: minted when it is planned. */
+    choose: z.strictObject({ card: id, entry: z.int(), options: z.array(z.strictObject({ choice: z.int(), label: z.string() })) }).optional(),
+    /** "Use this as your note?" Yes / No about the person's message `held` (an event id), for one choice's visit. */
+    note: z.strictObject({ card: id, entry: z.int(), held: z.string() }).optional(),
+    /** A teammate's question's buttons ride this part (v93): each option, then one to answer in words (choice null). */
+    question: z.strictObject({ id, choices: z.array(z.strictObject({ choice: z.string().nullable(), label: z.string() })) }).optional(),
+    /** The lead's question to its owner rides this part: its options, then "Something else". */
+    ask: z.strictObject({ turn: id, options: z.array(z.string()) }).optional(),
+    /** The lead's own reply, already shaped (reply-shape.ts): the channel renders its bold anchors and labelled links in its own format. */
+    voice: z.literal(true).optional(),
+};
+export const chatContentSchema = z.strictObject(chatContentShape);
+export const CHAT_PART_VERSION = 1;
+export const savedChatPartSchema = versioned(CHAT_PART_VERSION, chatContentShape);
+/** A saved body or part from before `version`, as version `version`: the fields its schema knows, nothing else. */
+function knownFields(version, fields) {
+    return (body) => {
+        const out = { version };
+        for (const field of fields)
+            if (Object.hasOwn(body, field))
+                out[field] = body[field];
+        return out;
+    };
+}
+const PART_UPGRADES = { 0: knownFields(CHAT_PART_VERSION, Object.keys(chatContentShape)) };
+/** JSON text, then the schema; `payload: not JSON` for bytes that aren't. */
+function fromJson(raw, read) {
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, issues: [{ path: "payload", kind: "invalid", line: "payload: not JSON" }] };
+    }
+    return read(body);
+}
+/** A saved part's content (`version` is the saved form's, not the content's). */
+export function readChatPart(raw) {
+    const read = fromJson(raw, body => readVersioned(savedChatPartSchema, body, PART_UPGRADES));
+    if (!read.ok)
+        return read;
+    const { version: _version, ...content } = read.value;
+    return { ok: true, value: content };
+}
+/** A part as it is saved. */
+export function savedChatPart(content) {
+    return JSON.stringify({ version: CHAT_PART_VERSION, ...content });
+}
+// ---- event bodies ------------------------------------------------------------------------------------------------
+export const CHAT_EVENT_VERSION = 1;
+/** `pair <code>`: only the code's hash is kept. */
+export const chatPairBodySchema = versioned(CHAT_EVENT_VERSION, { hash: z.string() });
+/**
+ * A message: its words (cut at the lead's limit, `originalLength` saying how long it was), or a plain line to answer
+ * with instead (`unsupported`: a file the app can't take). A room's or notice's carrier event has none. `about` is the
+ * task its turn is about, once chosen; `lead` is a held message passed to the lead as it was (chat-flow.ts).
+ */
+export const chatMessageBodySchema = versioned(CHAT_EVENT_VERSION, {
+    text: z.string().optional(),
+    originalLength: z.int().min(0).optional(),
+    unsupported: z.string().optional(),
+    about: z.strictObject({ task: z.string(), run: z.int().nullable() }).optional(),
+    lead: z.literal(true).optional(),
+});
+/**
+ * A button: the one-time token it carried, or, when the app's callback came from the paired person but its data
+ * couldn't be read, the path-named line saying why — answered plainly, and nothing is done.
+ */
+export const chatTokenBodySchema = versioned(CHAT_EVENT_VERSION, { token: z.string().regex(/^[a-f0-9]{32}$/, { error: "must be a Toolroll button token" }) });
+export const chatProblemBodySchema = versioned(CHAT_EVENT_VERSION, { problem: z.string().min(1) });
+export const chatActionBodySchema = z.union([chatTokenBodySchema, chatProblemBodySchema]);
+/** A notice carries its parts, not a body. */
+export const chatNoticeBodySchema = versioned(CHAT_EVENT_VERSION, {});
+export function savedChatEventBody(body) {
+    return JSON.stringify({ version: CHAT_EVENT_VERSION, ...body });
+}
+const upgradeBody = (fields) => ({ 0: knownFields(CHAT_EVENT_VERSION, fields) });
+/** A pair event's body. */
+export function readChatPairBody(raw) {
+    return fromJson(raw, body => readVersioned(chatPairBodySchema, body, upgradeBody(["hash"])));
+}
+/** A message event's body. */
+export function readChatMessageBody(raw) {
+    return fromJson(raw, body => readVersioned(chatMessageBodySchema, body, upgradeBody(Object.keys(chatMessageBodySchema.shape))));
+}
+/** An action event's body: a token, or the reason its callback couldn't be read. */
+export function readChatActionBody(raw) {
+    return fromJson(raw, (body) => typeof body === "object" && body !== null && !Array.isArray(body) && Object.hasOwn(body, "problem")
+        ? readVersioned(chatProblemBodySchema, body, upgradeBody(["problem"]))
+        : readVersioned(chatTokenBodySchema, body, upgradeBody(["token"])));
+}
+/** Words held for "Use this as your note?" (`chat_flow_note.words`): the held message's own text and length. */
+export const heldWordsSchema = z.strictObject({ text: z.string(), originalLength: z.int().min(0).optional() });
+export function readHeldWords(raw) {
+    return fromJson(raw, body => parseContract(heldWordsSchema, body));
+}

package/dist/contracts/chat-tables.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The Slack, Discord and Teams receipt tables (chat-delivery-state.ts keeps their rows). A leaf: it imports nothing, so
+ * the store can create these tables without loading the chat state modules that themselves import the store.
+ */
+export declare const chatSchema: (channel: "slack" | "discord" | "teams") => string;
+export declare const chatTables: (channel: "slack" | "discord" | "teams") => string[];