toolroll 0.9.34 → 0.9.37

package/dist/contracts/stage-output.js

@@ -0,0 +1,166 @@
+/**
+ * What a finished zone hands the zones after it (docs/plans/zod-revamp.md, item 8): its `{{stage.<id>}}` words and, by
+ * kind, more fields (a research zone's `{{stage.<id>.items}}` and `{{stage.<id>.report}}`), kept on the card as one
+ * versioned payload (`flow_card.outputs_json`) with any output too long to pass on attached whole.
+ *
+ * - `stageHandoffSchema` is one zone's handoff; `STAGE_HANDOFFS` says which of its fields each zone kind hands on. A
+ *   template's `{{stage.<id>.<field>}}` is checked against it when a flow is saved (`stageReferenceProblems`), so a
+ *   refusal names the path: `stages[1].instructions: stage.research.unknown is not available`.
+ * - `cardOutputsSchema` is what the card keeps: every handoff's fields flat (`<zone>`, `<zone>.items`, `<zone>.report`,
+ *   as `{{stage.…}}` names them) and, for a zone whose output was over TEXT_LIMITS.stageOutput, the output whole: its
+ *   `{{stage.<zone>}}` says where it is kept, and a task filed after it is given it whole (flowGoalCuts).
+ *
+ * Saved before this contract (version 0), a card's outputs were the flat map alone; they read exactly as every release
+ * read them: the string values, anything else skipped.
+ */
+import { z } from "zod";
+import { parseContract, readVersioned, versioned } from "./contract.js";
+/** One zone's handoff to the zones after it. */
+export const stageHandoffSchema = z.strictObject({
+    text: z.string().describe("{{stage.<id>}}: what the zone produced, whole up to TEXT_LIMITS.stageOutput characters; a longer one says where it is kept whole."),
+    items: z.string().optional().describe("{{stage.<id>.items}}: what a research zone found, as a numbered list (title, why, link)."),
+    report: z.string().optional().describe("{{stage.<id>.report}}: a research zone's whole report (REPORT_FILL_LIMIT)."),
+});
+const words = stageHandoffSchema.pick({ text: true });
+/**
+ * What each zone kind hands on, or null when it hands nothing on (it holds, asks, messages or ends). A sort hands on its
+ * decision in words (`sortWords` of the small-answers contract's SortDecision, src/contracts/sort-answer.ts), and a
+ * Send to me zone what it sent.
+ */
+export const STAGE_HANDOFFS = {
+    inbox: null, task: words, report: stageHandoffSchema, approval: null, check: words, "pull-request": words, update: words, notify: null,
+    sort: words, draft: words, request: words, email: words, tool: words, wait: words, teammate: words, send: words, choose: null, done: null,
+};
+/** The extra `{{stage.<id>.<field>}}` fields a zone kind hands on. */
+export function stageFieldsOf(kind) {
+    const schema = STAGE_HANDOFFS[kind];
+    return schema === null ? [] : Object.keys(schema.shape).filter(field => field !== "text");
+}
+/** One zone's handoff, read from the card's flat outputs (a field it never wrote is left out; no words read as ""). */
+export function stageHandoffOf(outputs, zone) {
+    const fields = Object.keys(stageHandoffSchema.shape).filter(field => field !== "text");
+    return { text: outputs[zone] ?? "", ...Object.fromEntries(fields.flatMap(field => outputs[`${zone}.${field}`] === undefined ? [] : [[field, outputs[`${zone}.${field}`]]])) };
+}
+/** The card's flat outputs with one zone's handoff in place of its last: a field this visit didn't hand on is gone, so
+ * nothing stale is left behind. */
+export function withStageHandoff(outputs, zone, handoff) {
+    const read = stageHandoffSchema.parse(handoff);
+    const next = { ...outputs, [zone]: read.text };
+    for (const field of Object.keys(stageHandoffSchema.shape).filter(one => one !== "text")) {
+        const value = read[field];
+        if (value === undefined)
+            delete next[`${zone}.${field}`];
+        else
+            next[`${zone}.${field}`] = value;
+    }
+    return next;
+}
+// ------------------------------------------------------------------ what the card keeps
+export const CARD_OUTPUTS_VERSION = 1;
+export const cardOutputsSchema = versioned(CARD_OUTPUTS_VERSION, {
+    outputs: z.object({}).catchall(z.string()).describe("Every {{stage.…}} value by its name: <zone>, and a research zone's <zone>.items and <zone>.report."),
+    attached: z.object({}).catchall(z.string()).describe("A zone's output in full when it was over TEXT_LIMITS.stageOutput characters, by zone."),
+});
+/** Version 0, the flat map every release before wrote: its string values, as they read them; anything else is skipped. */
+export function upgradeFlatOutputs(raw) {
+    const outputs = raw !== null && typeof raw === "object" ? Object.fromEntries(Object.entries(raw).filter((entry) => typeof entry[1] === "string")) : {};
+    return { version: CARD_OUTPUTS_VERSION, outputs, attached: {} };
+}
+/**
+ * Read a card's outputs. Version 1 as itself and a newer version refused plainly. Anything without a numeric `version`
+ * was saved before outputs carried one (a zone may be called `version`; its words were a string), and is read as the
+ * flat map it is.
+ */
+export function readCardOutputs(input) {
+    const legacy = input === null || typeof input !== "object" || Array.isArray(input) || typeof input["version"] !== "number";
+    return legacy ? parseContract(cardOutputsSchema, upgradeFlatOutputs(input)) : readVersioned(cardOutputsSchema, input);
+}
+/** A card's outputs as the store keeps them: unreadable JSON is the empty card it always was; `newer` is a row a newer
+ * Toolroll wrote, which this one reads as empty and never writes over. */
+export function cardOutputsFromStore(json) {
+    let raw;
+    try {
+        raw = JSON.parse(json);
+    }
+    catch {
+        raw = {};
+    }
+    const read = readCardOutputs(raw);
+    if (read.ok)
+        return { outputs: read.value.outputs, attached: read.value.attached, issues: [], newer: false };
+    return { outputs: {}, attached: {}, issues: read.issues, newer: read.issues.some(one => one.kind === "newer-version") };
+}
+/** A card's outputs as the store saves them. A zone's attachment is kept only while its output is the pointer to it. */
+export function cardOutputsForStore(outputs, attached) {
+    const kept = Object.fromEntries(Object.entries(attached).filter(([zone]) => outputs[zone] !== undefined));
+    return JSON.stringify(cardOutputsSchema.parse({ version: CARD_OUTPUTS_VERSION, outputs, attached: kept }));
+}
+// ------------------------------------------------------------------ template references, checked at save
+/** Where a zone's words take fill-ins, by the drawing's path: its instructions and message, a request's address,
+ * headers and body, an email's fields and a tool's arguments. */
+export function templateFields(stage) {
+    const fields = [];
+    const add = (path, text) => { if (typeof text === "string")
+        fields.push({ path, text }); };
+    add("instructions", stage.instructions);
+    add("message", stage.message);
+    if (stage.request !== undefined) {
+        add("request.url", stage.request.url);
+        for (const [name, value] of Object.entries(stage.request.headers))
+            add(`request.headers.${name}`, value);
+        add("request.body", stage.request.body);
+    }
+    if (stage.email !== undefined) {
+        add("email.to", stage.email.to);
+        add("email.subject", stage.email.subject);
+        add("email.body", stage.email.body);
+    }
+    if (stage.tool !== undefined)
+        add("tool.args", stage.tool.args);
+    return fields;
+}
+/** Every `{{stage.…}}` in some words, as written between the braces (`stage.research.items`). */
+const STAGE_REFERENCE = /\{\{\s*(stage\.[^{}]*?)\s*\}\}/g;
+export function stageReferences(text) {
+    return [...text.matchAll(STAGE_REFERENCE)].map(match => match[1]);
+}
+/** What one `{{stage.…}}` reference can't be, against the drawing: null when its zone hands that field on. */
+export function stageReferenceProblem(definition, reference) {
+    const [zone = "", ...rest] = reference.slice("stage.".length).split(".");
+    const field = rest.join(".");
+    const stage = definition.stages.find(one => one.id === zone);
+    if (stage === undefined)
+        return `${reference} is not available: there's no zone called ${zone === "" ? "(none)" : zone}`;
+    if (STAGE_HANDOFFS[stage.kind] === null)
+        return `${reference} is not available: ${stage.title} hands nothing on`;
+    if (field === "")
+        return null;
+    const fields = stageFieldsOf(stage.kind);
+    if (fields.includes(field))
+        return null;
+    const offered = [`{{stage.${zone}}}`, ...fields.map(one => `{{stage.${zone}.${one}}}`)];
+    return `${reference} is not available (${stage.title} hands on ${offered.length === 1 ? offered[0] : `${offered.slice(0, -1).join(", ")} and ${offered.at(-1)}`})`;
+}
+/**
+ * Template references a save adds that its zones don't hand on, each named by its path
+ * (`stages[1].instructions: stage.research.unknown is not available ...`). A reference the flow already had before
+ * this save (`previous`, the saved drawing) is never refused, nor is any reference when a flow is only read or run:
+ * this checks new and changed words alone.
+ */
+export function stageReferenceProblems(definition, previous) {
+    const had = new Set((previous?.stages ?? []).flatMap(stage => templateFields(stage).flatMap(field => stageReferences(field.text))));
+    const problems = [];
+    definition.stages.forEach((stage, index) => {
+        for (const field of templateFields(stage)) {
+            for (const reference of new Set(stageReferences(field.text))) {
+                if (had.has(reference))
+                    continue;
+                const problem = stageReferenceProblem(definition, reference);
+                const path = `stages[${index}].${field.path}`;
+                if (problem !== null)
+                    problems.push({ path, kind: "bad-value", line: `${path}: ${problem}` });
+            }
+        }
+    });
+    return problems;
+}

package/dist/contracts/task-sizing.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The task sizing classifier's answer (task-sizing.ts): one schema for the JSON Schema a Claude sizer is given
+ * (`--json-schema`) and the reader that takes an answer back. Jev answers through OpenRouter's Decisions API, which
+ * takes questions rather than a JSON Schema; its choice and yes/no are read into this same answer before they count.
+ *
+ * An answer is never kept as it is (it becomes the task's sizing, phase-routing.ts `TaskSizing`), so it carries no
+ * version.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+export declare const sizeAnswerSchema: z.ZodObject<{
+    size: z.ZodEnum<{
+        large: "large";
+        medium: "medium";
+        small: "small";
+    }>;
+    risky: z.ZodBoolean;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type SizeAnswer = z.infer<typeof sizeAnswerSchema>;
+/** What a Claude sizer's `--json-schema` is: the answer schema, exactly. */
+export declare const SIZING_MODEL_SCHEMA: Readonly<Record<string, unknown>>;
+/** Keep the old reason defaults and clipping before checking the normalized answer's contract. */
+export declare function readSizeAnswer(value: unknown): ContractResult<SizeAnswer>;

package/dist/contracts/task-sizing.js

@@ -0,0 +1,28 @@
+/**
+ * The task sizing classifier's answer (task-sizing.ts): one schema for the JSON Schema a Claude sizer is given
+ * (`--json-schema`) and the reader that takes an answer back. Jev answers through OpenRouter's Decisions API, which
+ * takes questions rather than a JSON Schema; its choice and yes/no are read into this same answer before they count.
+ *
+ * An answer is never kept as it is (it becomes the task's sizing, phase-routing.ts `TaskSizing`), so it carries no
+ * version.
+ */
+import { z } from "zod";
+import { TASK_SIZES } from "../phase-routing.js";
+import { TEXT_LIMITS } from "../text-limits.js";
+import { limited, parseContract, toModelSchema } from "./contract.js";
+export const sizeAnswerSchema = z.object({
+    size: z.enum(TASK_SIZES),
+    risky: z.boolean(),
+    reason: limited("reason", "sizingReason").describe(`reason: at most ${TEXT_LIMITS.sizingReason} characters.`),
+});
+/** What a Claude sizer's `--json-schema` is: the answer schema, exactly. */
+export const SIZING_MODEL_SCHEMA = toModelSchema(sizeAnswerSchema);
+/** Keep the old reason defaults and clipping before checking the normalized answer's contract. */
+export function readSizeAnswer(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const body = value;
+        const reason = typeof body["reason"] === "string" ? body["reason"].replace(/\s+/g, " ").trim() : "";
+        value = { ...body, reason: reason.length <= TEXT_LIMITS.sizingReason ? reason : `${reason.slice(0, TEXT_LIMITS.sizingReason - 1)}…` };
+    }
+    return parseContract(sizeAnswerSchema, value);
+}

package/dist/contracts/teammate-turn.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A teammate's turn (teammates.ts): one schema for the JSON Schema Claude answers in (`--json-schema`) and the reader
+ * that takes the answer back. One flat object with every field (a root union is refused by the API); fields a turn
+ * does not use are "" (or [] for options).
+ *
+ * The text limits (TURN_LIMITS, from TEXT_LIMITS) are deliberately not in the schema: the CLI refuses an answer a few
+ * characters over one whole, so they are checked after parsing and an answer over one is asked once to shorten
+ * (teammate-work.ts), then kept whole. What the zone allows — which actions, which answers, a note for a send-back, a
+ * question for an ask, a tool for a tool call — is checked after parsing too (`readTurn`), by path.
+ *
+ * A turn is kept as the step's decision (`flow_step_run.decision_json`) as it was read, so a saved one is this shape.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** What a teammate may do on one turn. A decision zone: approve, send back, or hand it to a person. A work zone: pick
+ * where it goes, ask its person, or say it can't. v94: "use_tool" asks for one tool call. */
+export declare const TURN_ACTIONS: readonly ["approve", "send_back", "hand_off", "route", "ask", "cant", "use_tool"];
+export type TurnAction = (typeof TURN_ACTIONS)[number];
+export declare const teammateTurnSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        approve: "approve";
+        ask: "ask";
+        cant: "cant";
+        hand_off: "hand_off";
+        route: "route";
+        send_back: "send_back";
+        use_tool: "use_tool";
+    }>;
+    answer: z.ZodString;
+    text: z.ZodString;
+    note: z.ZodString;
+    question: z.ZodString;
+    options: z.ZodArray<z.ZodString>;
+    reason: z.ZodString;
+    tool: z.ZodString;
+    input: z.ZodString;
+    remember: z.ZodString;
+}, z.core.$strip>;
+export type TurnAnswer = z.infer<typeof teammateTurnSchema>;
+/** What Claude's `--json-schema` is for a turn: the turn schema, exactly. */
+export declare const TURN_MODEL_SCHEMA: Readonly<Record<string, unknown>>;
+/** Older and plain-text turns default absent or non-text fields to "", and keep only string options. */
+export declare function readTurnAnswer(value: unknown): ContractResult<TurnAnswer>;

package/dist/contracts/teammate-turn.js

@@ -0,0 +1,51 @@
+/**
+ * A teammate's turn (teammates.ts): one schema for the JSON Schema Claude answers in (`--json-schema`) and the reader
+ * that takes the answer back. One flat object with every field (a root union is refused by the API); fields a turn
+ * does not use are "" (or [] for options).
+ *
+ * The text limits (TURN_LIMITS, from TEXT_LIMITS) are deliberately not in the schema: the CLI refuses an answer a few
+ * characters over one whole, so they are checked after parsing and an answer over one is asked once to shorten
+ * (teammate-work.ts), then kept whole. What the zone allows — which actions, which answers, a note for a send-back, a
+ * question for an ask, a tool for a tool call — is checked after parsing too (`readTurn`), by path.
+ *
+ * A turn is kept as the step's decision (`flow_step_run.decision_json`) as it was read, so a saved one is this shape.
+ */
+import { z } from "zod";
+import { parseContract, toModelSchema } from "./contract.js";
+/** What a teammate may do on one turn. A decision zone: approve, send back, or hand it to a person. A work zone: pick
+ * where it goes, ask its person, or say it can't. v94: "use_tool" asks for one tool call. */
+export const TURN_ACTIONS = ["approve", "send_back", "hand_off", "route", "ask", "cant", "use_tool"];
+export const teammateTurnSchema = z.object({
+    action: z.enum(TURN_ACTIONS),
+    /** route: one of the zone's answers, exactly as written. */
+    answer: z.string(),
+    /** What the next zones read, or the draft as rewritten. */
+    text: z.string(),
+    /** A decision or send-back note. */
+    note: z.string(),
+    /** ask: one short question, with up to 4 options to tap. */
+    question: z.string(),
+    options: z.array(z.string()),
+    /** One plain sentence saying why, for its manager's log. */
+    reason: z.string(),
+    /** use_tool: the tool's name, and its input as a JSON object written as text. */
+    tool: z.string(),
+    input: z.string(),
+    /** v95: one short fact worth keeping for later cards ("": none). */
+    remember: z.string(),
+});
+/** What Claude's `--json-schema` is for a turn: the turn schema, exactly. */
+export const TURN_MODEL_SCHEMA = toModelSchema(teammateTurnSchema);
+/** Older and plain-text turns default absent or non-text fields to "", and keep only string options. */
+export function readTurnAnswer(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const body = { ...value };
+        for (const key of Object.keys(teammateTurnSchema.shape)) {
+            if (key !== "action" && key !== "options" && typeof body[key] !== "string")
+                body[key] = "";
+        }
+        body["options"] = Array.isArray(body["options"]) ? body["options"].filter(one => typeof one === "string") : [];
+        value = body;
+    }
+    return parseContract(teammateTurnSchema, value);
+}

package/dist/contracts/teams-callback.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A Teams button tap (teams-chat.ts `receiveTeams`): an Adaptive Card `Action.Submit` arrives as a message activity
+ * whose `value` is the data Toolroll put on the button, `{ so: <one-time token> }`. The activity is Microsoft's (read
+ * by `receiveTeams`); only `value.so` is read, as before, and extra submit keys are ignored. A tap from the paired person whose data can't be read
+ * is answered with why (`value.so: must be a Toolroll button token`), and nothing is done.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+export declare const teamsSubmitSchema: z.ZodObject<{
+    so: z.ZodString;
+}, z.core.$strip>;
+export type TeamsSubmit = z.infer<typeof teamsSubmitSchema>;
+/** A submit's one-time token. */
+export declare function readTeamsSubmit(value: unknown): ContractResult<string>;

package/dist/contracts/teams-callback.js

@@ -0,0 +1,14 @@
+/**
+ * A Teams button tap (teams-chat.ts `receiveTeams`): an Adaptive Card `Action.Submit` arrives as a message activity
+ * whose `value` is the data Toolroll put on the button, `{ so: <one-time token> }`. The activity is Microsoft's (read
+ * by `receiveTeams`); only `value.so` is read, as before, and extra submit keys are ignored. A tap from the paired person whose data can't be read
+ * is answered with why (`value.so: must be a Toolroll button token`), and nothing is done.
+ */
+import { z } from "zod";
+import { parseContract } from "./contract.js";
+export const teamsSubmitSchema = z.object({ so: z.string().regex(/^[a-f0-9]{32}$/, { error: "must be a Toolroll button token" }) });
+/** A submit's one-time token. */
+export function readTeamsSubmit(value) {
+    const read = parseContract(z.object({ value: teamsSubmitSchema }), { value });
+    return read.ok ? { ok: true, value: read.value.value.so } : read;
+}

package/dist/contracts/telegram-callback.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Telegram (telegram.ts): one schema for an update as Telegram sends it — polled, or pushed to /hooks/telegram and kept
+ * in the inbox until applied — and one for the data a Toolroll button carries.
+ *
+ * The update is Telegram's: only the fields Toolroll reads are described, and any others are ignored. A button's data
+ * is Toolroll's: one of the forms it mints, within Telegram's 64 bytes. A tap whose data isn't one of them is
+ * answered, after the sender and chat are proved, with the line that says why, and nothing is done.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+export declare const telegramMessageSchema: z.ZodObject<{
+    message_id: z.ZodInt;
+    text: z.ZodOptional<z.ZodString>;
+    chat: z.ZodOptional<z.ZodObject<{
+        id: z.ZodInt;
+        type: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    from: z.ZodOptional<z.ZodObject<{
+        id: z.ZodInt;
+        username: z.ZodOptional<z.ZodString>;
+        first_name: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    reply_to_message: z.ZodOptional<z.ZodObject<{
+        message_id: z.ZodInt;
+    }, z.core.$strip>>;
+    forward_origin: z.ZodOptional<z.ZodUnknown>;
+    forward_date: z.ZodOptional<z.ZodUnknown>;
+    via_bot: z.ZodOptional<z.ZodUnknown>;
+    sender_chat: z.ZodOptional<z.ZodUnknown>;
+    caption: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const telegramCallbackQuerySchema: z.ZodObject<{
+    id: z.ZodString;
+    data: z.ZodOptional<z.ZodString>;
+    from: z.ZodOptional<z.ZodObject<{
+        id: z.ZodInt;
+    }, z.core.$strip>>;
+    message: z.ZodOptional<z.ZodObject<{
+        message_id: z.ZodInt;
+        chat: z.ZodOptional<z.ZodObject<{
+            id: z.ZodInt;
+        }, z.core.$strip>>;
+        text: z.ZodOptional<z.ZodString>;
+        entities: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const telegramUpdateSchema: z.ZodObject<{
+    update_id: z.ZodInt;
+    message: z.ZodOptional<z.ZodObject<{
+        message_id: z.ZodInt;
+        text: z.ZodOptional<z.ZodString>;
+        chat: z.ZodOptional<z.ZodObject<{
+            id: z.ZodInt;
+            type: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        from: z.ZodOptional<z.ZodObject<{
+            id: z.ZodInt;
+            username: z.ZodOptional<z.ZodString>;
+            first_name: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        reply_to_message: z.ZodOptional<z.ZodObject<{
+            message_id: z.ZodInt;
+        }, z.core.$strip>>;
+        forward_origin: z.ZodOptional<z.ZodUnknown>;
+        forward_date: z.ZodOptional<z.ZodUnknown>;
+        via_bot: z.ZodOptional<z.ZodUnknown>;
+        sender_chat: z.ZodOptional<z.ZodUnknown>;
+        caption: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    callback_query: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+        data: z.ZodOptional<z.ZodString>;
+        from: z.ZodOptional<z.ZodObject<{
+            id: z.ZodInt;
+        }, z.core.$strip>>;
+        message: z.ZodOptional<z.ZodObject<{
+            message_id: z.ZodInt;
+            chat: z.ZodOptional<z.ZodObject<{
+                id: z.ZodInt;
+            }, z.core.$strip>>;
+            text: z.ZodOptional<z.ZodString>;
+            entities: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type TelegramUpdate = z.infer<typeof telegramUpdateSchema>;
+export type TelegramMessage = z.infer<typeof telegramMessageSchema>;
+/** One update, as Telegram sent it (refused by path: `callback_query.message.chat.id: must be a number`). */
+export declare function readTelegramUpdate(input: unknown): ContractResult<TelegramUpdate>;
+/** An inbox row's saved update: JSON first, then the schema. */
+export declare function parseTelegramUpdate(raw: string): ContractResult<TelegramUpdate>;
+/**
+ * Every form of data a Toolroll button carries: a one-time token (16 random bytes as hex) for a proposal, decision,
+ * flow, choice or question button; a decide token (chat-decide.ts); a task from /tasks, or back to the lead; and an
+ * option of the lead's question to its owner (by index, or `x` for "Something else").
+ */
+export declare const TELEGRAM_BUTTON_DATA: RegExp;
+export declare const telegramButtonDataSchema: z.ZodString;
+/** A button that calls back (the other kind opens a link). */
+export declare const telegramCallbackButtonSchema: z.ZodObject<{
+    text: z.ZodString;
+    callback_data: z.ZodString;
+}, z.core.$strict>;
+export type TelegramCallbackButton = z.infer<typeof telegramCallbackButtonSchema>;
+/** A tapped button's data: one Toolroll mints, or the path-named reason it isn't (`callback_data: required`). */
+export declare function readTelegramButtonData(data: unknown): ContractResult<string>;
+/**
+ * A button as Toolroll sends it. Data Telegram would refuse (over 64 bytes) or that a tap could not be read back is a
+ * fault in the code that made it, so it throws before anything is sent.
+ */
+export declare function telegramButton(text: string, data: string): TelegramCallbackButton;
+/** A /tasks pick: the task's ref id, or back to the lead (null); null for anything else. */
+export declare function pickOf(data: string): {
+    ref: number | null;
+} | null;
+/** An option of the lead's question to its owner: its turn and index, or `x` for "Something else"; null for anything else. */
+export declare function askOf(data: string): {
+    turn: number;
+    option: number | "x";
+} | null;

package/dist/contracts/telegram-callback.js

@@ -0,0 +1,97 @@
+/**
+ * Telegram (telegram.ts): one schema for an update as Telegram sends it — polled, or pushed to /hooks/telegram and kept
+ * in the inbox until applied — and one for the data a Toolroll button carries.
+ *
+ * The update is Telegram's: only the fields Toolroll reads are described, and any others are ignored. A button's data
+ * is Toolroll's: one of the forms it mints, within Telegram's 64 bytes. A tap whose data isn't one of them is
+ * answered, after the sender and chat are proved, with the line that says why, and nothing is done.
+ */
+import { z } from "zod";
+import { lengthIn, TEXT_LIMITS } from "../text-limits.js";
+import { limited, parseContract } from "./contract.js";
+const chat = z.object({ id: z.int(), type: z.string().optional() });
+const sender = z.object({ id: z.int(), username: z.string().optional(), first_name: z.string().optional() });
+export const telegramMessageSchema = z.object({
+    message_id: z.int(),
+    text: z.string().optional(),
+    chat: chat.optional(),
+    from: sender.optional(),
+    reply_to_message: z.object({ message_id: z.int() }).optional(),
+    /** Presence of any of these disqualifies a note: only direct, initial, plain text counts as authored-and-confirmed
+     * by the paired operator. */
+    forward_origin: z.unknown().optional(),
+    forward_date: z.unknown().optional(),
+    via_bot: z.unknown().optional(),
+    sender_chat: z.unknown().optional(),
+    caption: z.string().optional(),
+});
+export const telegramCallbackQuerySchema = z.object({
+    id: z.string(),
+    /** Read by `readTelegramButtonData`, after the sender and chat are proved. */
+    data: z.string().optional(),
+    from: z.object({ id: z.int() }).optional(),
+    message: z.object({ message_id: z.int(), chat: z.object({ id: z.int() }).optional(), text: z.string().optional(), entities: z.array(z.unknown()).optional() }).optional(),
+});
+export const telegramUpdateSchema = z.object({
+    update_id: z.int().min(1),
+    message: telegramMessageSchema.optional(),
+    callback_query: telegramCallbackQuerySchema.optional(),
+});
+/** One update, as Telegram sent it (refused by path: `callback_query.message.chat.id: must be a number`). */
+export function readTelegramUpdate(input) {
+    return parseContract(telegramUpdateSchema, input);
+}
+/** An inbox row's saved update: JSON first, then the schema. */
+export function parseTelegramUpdate(raw) {
+    let body;
+    try {
+        body = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, issues: [{ path: "payload", kind: "invalid", line: "payload: not JSON" }] };
+    }
+    return readTelegramUpdate(body);
+}
+/**
+ * Every form of data a Toolroll button carries: a one-time token (16 random bytes as hex) for a proposal, decision,
+ * flow, choice or question button; a decide token (chat-decide.ts); a task from /tasks, or back to the lead; and an
+ * option of the lead's question to its owner (by index, or `x` for "Something else").
+ */
+export const TELEGRAM_BUTTON_DATA = /^(?:[a-f0-9]{32}|d:[a-f0-9]{24}|pick:(?:lead|[1-9][0-9]{0,14})|ask:[1-9][0-9]{0,14}:(?:[0-3]|x))$/;
+export const telegramButtonDataSchema = limited("callback_data", "telegramCallbackDataBytes")
+    .regex(TELEGRAM_BUTTON_DATA, { error: "not a Toolroll button" });
+/** A button that calls back (the other kind opens a link). */
+export const telegramCallbackButtonSchema = z.strictObject({ text: z.string(), callback_data: telegramButtonDataSchema });
+/** The byte bound, which counts UTF-8 bytes where the schema counts characters. */
+function withinBytes(data) {
+    const limit = TEXT_LIMITS.telegramCallbackDataBytes, bytes = lengthIn(data, "bytes");
+    return bytes <= limit ? { ok: true, value: data } : { ok: false, issues: [{ path: "callback_data", kind: "too-long", line: `callback_data: over ${limit} bytes (${bytes})` }] };
+}
+/** A tapped button's data: one Toolroll mints, or the path-named reason it isn't (`callback_data: required`). */
+export function readTelegramButtonData(data) {
+    const read = parseContract(z.strictObject({ callback_data: telegramButtonDataSchema }), { callback_data: data });
+    return read.ok ? withinBytes(read.value.callback_data) : read;
+}
+/**
+ * A button as Toolroll sends it. Data Telegram would refuse (over 64 bytes) or that a tap could not be read back is a
+ * fault in the code that made it, so it throws before anything is sent.
+ */
+export function telegramButton(text, data) {
+    const read = parseContract(telegramCallbackButtonSchema, { text, callback_data: data });
+    const bytes = read.ok ? withinBytes(read.value.callback_data) : read;
+    if (!read.ok || !bytes.ok)
+        throw new Error(`a Telegram button: ${(read.ok ? bytes.ok ? [] : bytes.issues : read.issues).map(issue => issue.line).join("; ")}`);
+    return read.value;
+}
+/** A /tasks pick: the task's ref id, or back to the lead (null); null for anything else. */
+export function pickOf(data) {
+    if (data === "pick:lead")
+        return { ref: null };
+    const ref = /^pick:([1-9][0-9]{0,14})$/.exec(data)?.[1];
+    return ref === undefined ? null : { ref: Number(ref) };
+}
+/** An option of the lead's question to its owner: its turn and index, or `x` for "Something else"; null for anything else. */
+export function askOf(data) {
+    const tap = /^ask:([1-9][0-9]{0,14}):([0-3]|x)$/.exec(data);
+    return tap === null ? null : { turn: Number(tap[1]), option: tap[2] === "x" ? "x" : Number(tap[2]) };
+}