toolroll 0.9.34 → 0.9.37

package/dist/teammates.js

@@ -24,6 +24,7 @@ import { strictJsonParse } from "./converse.js";
 import { scanForSecrets } from "./evidence.js";
 import { run } from "./exec.js";
 import { ALL_CREDENTIAL_ENV } from "./provider.js";
+import { readTurnAnswer, TURN_MODEL_SCHEMA } from "./contracts/teammate-turn.js";
 import { LIMITS } from "./decision.js";
 import { overruns, TEXT_LIMITS } from "./text-limits.js";
 export const SOUL_CHARS = 12_000;
@@ -121,23 +122,13 @@ export const TEAMMATE_TEMPLATES = [
 ];
 /** Each field's limit, in characters: stated in the prompt before it answers (turnPrompt), and an answer over one is
  * asked once to shorten (teammateTurn); one still over is kept whole, never cut. "text" is what the next zones read;
- * "note" is a decision or send-back note. */
-export const TURN_LIMITS = { answer: 60, text: TEXT_LIMITS.stageOutput, note: LIMITS.note, question: 600, reason: 400, remember: 300 };
+ * "note" is a decision or send-back note. Not in the turn's schema (src/contracts/teammate-turn.ts): the CLI would
+ * refuse an answer a few characters over one whole. */
+export const TURN_LIMITS = { answer: TEXT_LIMITS.teammateAnswer, text: TEXT_LIMITS.stageOutput, note: LIMITS.note, question: TEXT_LIMITS.teammateQuestion, reason: TEXT_LIMITS.teammateReason, remember: TEXT_LIMITS.teammateRemember };
 /** The fields of an answer over their limits. */
 export function turnOverruns(answer) {
     return overruns({ answer: answer.answer, text: answer.text, note: answer.note, question: answer.question, reason: answer.reason, remember: answer.remember }, TURN_LIMITS);
 }
-/** The shape Claude answers in: one flat object (a root union is refused). No length limits here: an answer
- * a few characters over one is refused whole by the CLI, so the limits are TURN_LIMITS, checked after. */
-export const TURN_SCHEMA = {
-    type: "object", additionalProperties: false,
-    required: ["action", "answer", "text", "note", "question", "options", "reason", "tool", "input", "remember"],
-    properties: {
-        action: { type: "string", enum: ["approve", "send_back", "hand_off", "route", "ask", "cant", "use_tool"] },
-        answer: { type: "string" }, text: { type: "string" }, note: { type: "string" }, question: { type: "string" },
-        options: { type: "array", items: { type: "string" } }, reason: { type: "string" }, tool: { type: "string" }, input: { type: "string" }, remember: { type: "string" },
-    },
-};
 const clip = (text, cap) => text.length <= cap ? text : `${text.slice(0, cap - 1)}…`;
 export function turnPrompt(context) {
     const actions = context.kind === "decide"
@@ -192,41 +183,49 @@ export function turnPrompt(context) {
         ...(context.shorten === undefined ? [] : ["", "YOUR LAST ANSWER, WHICH IS OVER A LIMIT", context.shorten.answer, "", context.shorten.ask]),
     ].join("\n");
 }
-/** A turn's answer, checked against what this zone allows; null when it isn't one. */
+/** How many options an ask offers, and the longest tool name and input a tool call may give. */
+const ASK_OPTIONS = 4, TOOL_NAME_CHARS = 140, TOOL_INPUT_CHARS = 8000;
+/**
+ * A turn's answer, read through its contract (src/contracts/teammate-turn.ts) and then checked against what this zone
+ * allows, each refusal naming its path (`action: "route" isn't one this zone allows`). Text is trimmed and kept whole
+ * (a field over its limit is asked to shorten, turnOverruns); blank options are dropped, and an ask offers at most 4,
+ * each cut to an answer's length, and a tool name is cut to 140, as they always were.
+ */
 export function readTurn(value, context) {
-    if (value === null || typeof value !== "object" || Array.isArray(value))
-        return null;
-    const raw = value;
-    // Whole: a field over its limit is asked to shorten (turnOverruns), never cut here.
-    const text = (key) => typeof raw[key] === "string" ? raw[key].trim() : "";
-    const action = raw["action"];
+    const read = readTurnAnswer(value);
+    if (!read.ok)
+        return read;
+    const raw = read.value;
+    const answer = { action: raw.action, answer: raw.answer.trim(), text: raw.text.trim(), note: raw.note.trim(), question: raw.question.trim(),
+        options: raw.options.filter(one => one.trim() !== "").map(one => one.trim().slice(0, TURN_LIMITS.answer)).slice(0, ASK_OPTIONS), reason: raw.reason.trim(),
+        tool: raw.tool.trim().slice(0, TOOL_NAME_CHARS), input: raw.input.trim(), remember: raw.remember.trim() };
     const allowed = [...(context.kind === "decide" ? ["approve", "hand_off", ...(context.canSendBack ? ["send_back"] : [])] : ["route", "ask", "cant"]),
         ...((context.tools ?? []).length > 0 ? ["use_tool"] : [])];
-    if (typeof action !== "string" || !allowed.includes(action))
-        return null;
-    const answer = { action: action, answer: text("answer"), text: text("text"), note: text("note"), question: text("question"),
-        options: Array.isArray(raw["options"]) ? raw["options"].filter((one) => typeof one === "string" && one.trim() !== "").map(one => one.trim().slice(0, TURN_LIMITS.answer)).slice(0, 4) : [], reason: text("reason"),
-        tool: text("tool").slice(0, 140), input: typeof raw["input"] === "string" ? raw["input"].trim() : "", remember: text("remember") };
+    const refuse = (path, what) => ({ ok: false, issues: [{ path, kind: "bad-value", line: `${path}: ${what}` }] });
+    if (!allowed.includes(answer.action))
+        return refuse("action", `"${answer.action}" isn't one this zone allows (${allowed.map(one => `"${one}"`).join(", ")})`);
     // A tool call is checked against the teammate's rules where it's carried out; here only that it names one and fits.
-    if (answer.action === "use_tool" && (answer.tool === "" || answer.input.length > 8000))
-        return null;
+    if (answer.action === "use_tool" && answer.tool === "")
+        return refuse("tool", "required for use_tool");
+    if (answer.action === "use_tool" && answer.input.length > TOOL_INPUT_CHARS)
+        return refuse("input", `at most ${TOOL_INPUT_CHARS.toLocaleString("en-US")} characters`);
     if (answer.action === "route" && !context.answers.some(one => one.toLowerCase() === answer.answer.toLowerCase()))
-        return null;
+        return refuse("answer", `"${answer.answer}" isn't one of this zone's answers`);
     if (answer.action === "send_back" && answer.note === "")
-        return null;
+        return refuse("note", "required for send_back");
     if (answer.action === "ask" && answer.question === "")
-        return null;
-    return answer;
+        return refuse("question", "required for ask");
+    return { ok: true, value: answer };
 }
 export const TURN_TIMEOUT_MS = 180_000;
-/** The production runner: Claude through this computer's sign-in, answering in TURN_SCHEMA, with no tools, no MCP servers and no repository. */
+/** The production runner: Claude through this computer's sign-in, answering in the turn schema (TURN_MODEL_SCHEMA), with no tools, no MCP servers and no repository. */
 export function claudeTurnRunner(runner = run) {
     return async (request) => {
         const dir = mkdtempSync(join(tmpdir(), "standing-orders-teammate-"));
         const started = Date.now();
         try {
             const result = await runner("claude", [
-                "-p", "--output-format", "json", "--json-schema", JSON.stringify(TURN_SCHEMA), "--safe-mode", "--no-session-persistence", "--tools", "", "--permission-mode", "dontAsk",
+                "-p", "--output-format", "json", "--json-schema", JSON.stringify(TURN_MODEL_SCHEMA), "--safe-mode", "--no-session-persistence", "--tools", "", "--permission-mode", "dontAsk",
                 "--permission-prompts", "none", "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}',
                 ...(request.model === "default" ? [] : ["--model", request.model]),
             ], { cwd: dir, stdin: request.prompt, timeoutMs: request.timeoutMs, maxBuffer: 512 * 1024, omitEnv: ALL_CREDENTIAL_ENV, processGroup: true });

package/dist/teams-chat.js

@@ -3,7 +3,7 @@
 import { resultShotsPruned } from "./result-shots.js";
 import { chatQuestionButtons } from "./teammate-question.js";
 import { chatAskButtons } from "./chat-ask.js";
-import { ChatState, chatHash } from "./chat-delivery-state.js";
+import { ChatDeliveryError, ChatState, chatHash, partContent } from "./chat-delivery-state.js";
 import { channelAccess, chatObject as object, planChatNotifications, planRoomMessages, processChatEvent, splitChatText } from "./chat-delivery.js";
 import { PLATFORM_LIMITS } from "./text-limits.js";
 import { roomCommand } from "./chat-rooms.js";
@@ -14,6 +14,7 @@ import { chatFlowButtons } from "./chat-flow.js";
 import { channelInbox } from "./chat-inbox.js";
 import { chatResultHref } from "./chat-controls.js";
 import { TeamsError } from "./teams-api.js";
+import { readTeamsSubmit } from "./contracts/teams-callback.js";
 const serviceKey = (conversation) => `serviceUrl:${conversation}`;
 export const teamsUserId = (v) => typeof v === "string" && /^29:[A-Za-z0-9_=-]{10,200}$/.test(v);
 /** A conversation id; a channel post's carries its thread as ";messageid=<first message>" (v89). */
@@ -91,13 +92,16 @@ export function receiveTeams(state, identity, raw, serviceUrlClaim, now) {
         return false;
     if (!isRoom && conversation.conversationType !== "personal")
         return false;
-    const value = object(activity.value);
-    const submitted = typeof value.so === "string" && /^[a-f0-9]{32}$/.test(value.so) ? value.so : null;
+    // A card's button: its data is Toolroll's. One that can't be read is answered with why, once the tap is proved to
+    // be the paired person's below. A button carries no words of its own: other data beside words is a message, as before.
+    const read = activity.value === undefined || activity.value === null ? null : readTeamsSubmit(activity.value);
+    const button = read !== null && (read.ok || typeof activity.text !== "string") ? read : null;
+    const submitted = button?.ok === true ? button.value : null;
     let kind, payload, eventId;
-    if (submitted !== null) {
+    if (button !== null) {
         kind = "action";
-        payload = { token: submitted };
-        eventId = chatHash(`${identity.installation}:action:${member}:${activity.replyToId ?? id}:${submitted}`);
+        payload = button.ok ? { token: button.value } : { problem: button.issues.map(issue => issue.line).join("; ") };
+        eventId = chatHash(`${identity.installation}:action:${member}:${activity.replyToId ?? id}:${submitted ?? JSON.stringify(activity.value) ?? ""}`);
     }
     else {
         if (typeof activity.text !== "string")
@@ -109,9 +113,10 @@ export function receiveTeams(state, identity, raw, serviceUrlClaim, now) {
             ...(Array.isArray(activity.attachments) && activity.attachments.length > 0 ? { unsupported: "Incoming files are not supported yet. Describe the request in a message; saved result screenshots open from their links." } : {}) };
         eventId = chatHash(`${identity.installation}:message:${id}`);
     }
+    const words = "text" in payload ? payload.text ?? "" : "";
     // v89: a channel that feeds a flow takes anyone's message (as a card, with no say over anything); "flow 12" connects one.
-    const inbox = isRoom && kind === "message" ? channelInbox(state.store, "teams", identity.installation, channel, String(payload.text ?? "")) : { watched: false, command: false };
-    const roomish = isRoom && (state.room(identity.installation, channel) !== null || (kind === "message" && roomCommand(String(payload.text ?? "")) !== null) || inbox.watched || inbox.command);
+    const inbox = isRoom && kind === "message" ? channelInbox(state.store, "teams", identity.installation, channel, words) : { watched: false, command: false };
+    const roomish = isRoom && (state.room(identity.installation, channel) !== null || (kind === "message" && roomCommand(words) !== null) || inbox.watched || inbox.command);
     if (isRoom && !roomish)
         return false;
     const binding = state.bindingFor(identity.installation, member);
@@ -122,8 +127,8 @@ export function receiveTeams(state, identity, raw, serviceUrlClaim, now) {
         state.setMeta(identity.installation, serviceKey(channel), activity.serviceUrl, now);
         return state.enqueue({
             id: eventId, installation: identity.installation, binding: kind === "pair" || binding === null ? null : binding.id, kind, channel, member,
-            ts: submitted !== null ? String(activity.replyToId ?? id) : id, thread: submitted !== null ? String(activity.replyToId ?? id) : id,
-            payload: JSON.stringify(payload), created: now.toISOString(),
+            ts: kind === "action" ? String(activity.replyToId ?? id) : id, thread: kind === "action" ? String(activity.replyToId ?? id) : id,
+            payload, created: now.toISOString(),
         });
     });
 }
@@ -175,7 +180,7 @@ export async function deliverTeamsPart(options) {
         const repos = await channelAccess(shared, binding, session?.ceilingDigest);
         if (event.kind === "notice" && options.canNotify?.() === false)
             return false;
-        const content = JSON.parse(row.payload);
+        const content = partContent(row.payload);
         const destination = content.channel ?? binding.channel;
         const serviceUrl = state.meta(identity.installation, serviceKey(destination));
         if (serviceUrl === null)
@@ -237,6 +242,10 @@ export async function deliverTeamsPart(options) {
         return true;
     }
     catch (error) {
+        if (error instanceof ChatDeliveryError && error.permanent) {
+            state.prepare("UPDATE chat_part SET state='dropped',next_at=NULL,problem=? WHERE id=?").run(error.message, row.id);
+            return true;
+        }
         const problem = error instanceof TeamsError ? error : new TeamsError("Teams delivery failed", 15_000, true);
         state.prepare("UPDATE chat_part SET attempts=attempts+1,uncertain=?,next_at=?,problem=?,state=CASE WHEN attempts>=20 THEN 'dropped' ELSE state END WHERE id=?")
             .run(problem.uncertain ? 1 : 0, new Date(now.getTime() + problem.retryMs).toISOString(), problem.message, row.id);

package/dist/telegram-flow.js

@@ -26,6 +26,7 @@ import { decideFlowCard, draftFor, flowDefinitionOf } from "./flow-engine.js";
 import { chooseFlowCard, flowChoiceAt, flowSendPaths, readFlowSend } from "./flow-send.js";
 import { deciderOf } from "./flows.js";
 import { phoneLinkButton } from "./telegram-mate.js";
+import { telegramButton } from "./contracts/telegram-callback.js";
 export const FLOW_DECIDE_KEY = /^flow-decide:([1-9][0-9]{0,14}):([1-9][0-9]{0,9})$/;
 const DRAFT_LIMIT = 4000;
 /** The card, if it is still at that visit, waiting at a decision. */
@@ -48,9 +49,9 @@ export function flowButtons(store, binding, waiting, now) {
     const back = waiting.stage.onFail !== null ? mint("send-back") : null;
     const all = [approve, edit, back].filter((one) => one !== null);
     store.createTelegramFlowActions({ binding: binding.id, chatId: binding.chatId, card: waiting.card.id, entry: waiting.card.entry }, all, now);
-    const second = [edit === null ? null : { text: "✏️ Edit", callback_data: edit.token }, back === null ? null : { text: "↩️ Send back", callback_data: back.token }]
+    const second = [edit === null ? null : telegramButton("✏️ Edit", edit.token), back === null ? null : telegramButton("↩️ Send back", back.token)]
         .filter((one) => one !== null);
-    return { keyboard: [[{ text: "✅ Approve", callback_data: approve.token }], ...(second.length === 0 ? [] : [second])], tokens: all.map(one => one.token) };
+    return { keyboard: [[telegramButton("✅ Approve", approve.token)], ...(second.length === 0 ? [] : [second])], tokens: all.map(one => one.token) };
 }
 /** What a "Send to me" or "Person chooses" visit sent, read back for its message. */
 export function flowSentContent(store, card, entry) {
@@ -68,7 +69,7 @@ export function flowChoiceButtons(store, binding, visit, content, now) {
     // Only the options the zone still offers as they were sent: a flow changed since sends no stale button.
     const options = (content.options ?? []).filter(one => visit.stage.options?.[one.choice]?.label === one.label).map(one => ({ ...one, token: randomBytes(16).toString("hex") }));
     store.createTelegramFlowChoices({ binding: binding.id, chatId: binding.chatId, card: visit.card.id, entry: visit.card.entry }, options, now);
-    return { keyboard: options.map(one => [{ text: one.label, callback_data: one.token }]), tokens: options.map(one => one.token) };
+    return { keyboard: options.map(one => [telegramButton(one.label, one.token)]), tokens: options.map(one => one.token) };
 }
 /** A tapped option, applied inside the update's transaction. */
 export function applyFlowChoiceTap(store, binding, choice, message, repos, now) {

package/dist/telegram-mate.d.ts

@@ -4,6 +4,7 @@ import { type DoorOptions } from "./mate-doors.js";
 import { type MateAsk, type Store, type TelegramBinding } from "./store.js";
 import type { SubscriptionMateRunner } from "./subscription-chat.js";
 import type { TelegramTransport } from "./telegram.js";
+import { type TelegramCallbackButton, type TelegramUpdate } from "./contracts/telegram-callback.js";
 /** How long one claimed turn may go without a heartbeat before another poller may take it over. */
 export declare const CONVERSATION_CLAIM_MS: number;
 /** A busy engine (one turn at a time) defers a queued message this long, up to the age bound below. */
@@ -74,19 +75,13 @@ export declare function phoneLinkButton(origin: string | null, link: PhoneLink |
 /** The buttons under the lead's question: options two to a row, then "Something else". Each names the turn and the
  * option's place, nothing more; a tap re-proves that the question is still open and is the tapper's own. */
 export declare function askKeyboard(ask: MateAsk): CallbackKeyboard;
-export type InlineButton = {
-    text: string;
-    callback_data: string;
-} | {
+export type InlineButton = TelegramCallbackButton | {
     text: string;
     url: string;
 };
 type Keyboard = InlineButton[][];
 /** What a part persists: callback tokens only. A url is minted at send time, never stored. */
-type CallbackKeyboard = {
-    text: string;
-    callback_data: string;
-}[][];
+type CallbackKeyboard = TelegramCallbackButton[][];
 /** Mint the card's tokens before the send, so a tap can never name a token that does not exist. */
 export declare function mintCardTokens(store: Store, binding: TelegramBinding, proposal: number, now: Date, messageId?: string, chatId?: string): {
     keyboard: CallbackKeyboard;
@@ -111,12 +106,7 @@ export type CardEffect = {
  * ceiling; the door re-proves standing, ceiling, session and the
  * proposal's own terms again inside its transaction.
  */
-export declare function applyProposalTap(store: Store, binding: TelegramBinding, token: string, message: {
-    message_id: number;
-    chat?: {
-        id: number;
-    };
-}, repos: readonly string[] | null, options: TelegramConversationOptions, now: Date): {
+export declare function applyProposalTap(store: Store, binding: TelegramBinding, token: string, message: NonNullable<NonNullable<TelegramUpdate["callback_query"]>["message"]>, repos: readonly string[] | null, options: TelegramConversationOptions, now: Date): {
     effects: CardEffect[];
     confirmed: boolean;
     ignored: boolean;

package/dist/telegram-mate.js

@@ -33,6 +33,7 @@ import { WARM_EMOJI, warmTurn } from "./chat-warmth.js";
 import { TeamLeads } from "./team-leads.js";
 import { chatResultHref } from "./chat-controls.js";
 import { resultImageFileName, safeResultImageCaption, verifyResultImage } from "./chat-evidence.js";
+import { telegramButton } from "./contracts/telegram-callback.js";
 /** How long one claimed turn may go without a heartbeat before another poller may take it over. */
 export const CONVERSATION_CLAIM_MS = 2 * 60_000;
 /** A busy engine (one turn at a time) defers a queued message this long, up to the age bound below. */
@@ -110,8 +111,8 @@ function keyboardWith(callbacks, link) {
 export function askKeyboard(ask) {
     const rows = [];
     for (let at = 0; at < ask.options.length; at += 2)
-        rows.push(ask.options.slice(at, at + 2).map((label, offset) => ({ text: label.slice(0, 60), callback_data: `ask:${ask.turn}:${at + offset}` })));
-    rows.push([{ text: MATE_ASK_OTHER, callback_data: `ask:${ask.turn}:x` }]);
+        rows.push(ask.options.slice(at, at + 2).map((label, offset) => telegramButton(label.slice(0, 60), `ask:${ask.turn}:${at + offset}`)));
+    rows.push([telegramButton(MATE_ASK_OTHER, `ask:${ask.turn}:x`)]);
     return rows;
 }
 /** Mint the card's tokens before the send, so a tap can never name a token that does not exist. */
@@ -121,7 +122,7 @@ export function mintCardTokens(store, binding, proposal, now, messageId, chatId
     for (const [token, phase] of [[confirm, "confirm"], [dismiss, "dismiss"]]) {
         store.createTelegramProposalAction({ token, binding: binding.id, proposal, phase, chatId, ttlMs: CARD_TTL_MS, ...(messageId === undefined ? {} : { messageId }) }, now);
     }
-    return { keyboard: [[{ text: "Confirm", callback_data: confirm }, { text: "Dismiss", callback_data: dismiss }]], tokens: [confirm, dismiss] };
+    return { keyboard: [[telegramButton("Confirm", confirm), telegramButton("Dismiss", dismiss)]], tokens: [confirm, dismiss] };
 }
 /**
  * One tap on a proposal card, applied inside the update's own transaction
@@ -249,15 +250,15 @@ export function applyProposalTap(store, binding, token, message, repos, options,
         if (challenged) {
             ack("confirm it");
             edit(`${body}\n\nThis records that you handled this exact result. Confirm?`, [
-                [{ text: `✓ Yes, ${CHAT_ACTIONS[sharedAction.operation].label.toLowerCase()}`, callback_data: yes }],
-                [{ text: "Cancel", callback_data: cancel }],
+                [telegramButton(`✓ Yes, ${CHAT_ACTIONS[sharedAction.operation].label.toLowerCase()}`, yes)],
+                [telegramButton("Cancel", cancel)],
             ]);
             return;
         }
         ack("irreversible — confirm it");
         edit(`⚠ This answer is IRREVERSIBLE.\n\n${body}\n\nConfirm?`, [
-            [{ text: "⚠ Yes, answer it", callback_data: yes }],
-            [{ text: "Cancel", callback_data: cancel }],
+            [telegramButton("⚠ Yes, answer it", yes)],
+            [telegramButton("Cancel", cancel)],
         ]);
     };
     if (action.phase === "confirm" && (irreversible || challenged)) {

package/dist/telegram-team.d.ts

@@ -9,6 +9,7 @@
 import type { Store } from "./store.js";
 import { type InlineButton } from "./telegram-mate.js";
 import type { TelegramTransport } from "./telegram.js";
+import type { TelegramMessage } from "./contracts/telegram-callback.js";
 export type TeamCommand = {
     kind: "list";
 } | {
@@ -36,25 +37,7 @@ export type TeamInbound = {
     projects: readonly string[] | null;
     phoneOrigin: (() => string | null) | undefined;
     updateId: number;
-    message: {
-        message_id: number;
-        text?: string;
-        chat?: {
-            id: number;
-            type?: string;
-        };
-        from?: {
-            id: number;
-        };
-        reply_to_message?: {
-            message_id: number;
-        };
-        forward_origin?: unknown;
-        forward_date?: unknown;
-        via_bot?: unknown;
-        sender_chat?: unknown;
-        caption?: string;
-    };
+    message: TelegramMessage;
     /** Queue one reply for after the update's transaction commits. */
     say: (chatId: string, text: string, keyboard?: InlineButton[][]) => void;
 };

package/dist/telegram.d.ts

@@ -37,7 +37,7 @@ export declare function telegramHookSecret(dir: string, make?: boolean): string
 export declare function telegramPushUrl(hooksBase: string | null): string | null;
 /** A push is Telegram's when its secret header matches ours (compared in constant time). */
 export declare function pushedByTelegram(header: unknown, secret: string | null): boolean;
-/** Keep one pushed update for the bridge: a JSON object with a positive integer update_id. */
+/** Keep one pushed update for the bridge. A schema-invalid JSON update is logged and acknowledged, never retried. */
 export declare function keepPushedUpdate(store: Store, botId: string, body: Buffer, now: Date): {
     ok: true;
     kept: boolean;

package/dist/telegram.js

@@ -46,6 +46,7 @@ import { phoneCommand, phoneStatus, phoneTaskView, PHONE_CONSOLE_FOOTER, PHONE_H
 import { MATE_MESSAGE_MAX_CHARS } from "./mate.js";
 import { envValue } from "./names.js";
 import { applyProposalTap, processTelegramConversations, phoneLinkButton, replyContextFor, telegramConversationRepos, telegramRequestId, tooLongText, whichTaskText, } from "./telegram-mate.js";
+import { askOf, parseTelegramUpdate, pickOf, readTelegramButtonData, readTelegramUpdate, telegramButton } from "./contracts/telegram-callback.js";
 /** The environment name — and therefore the name the builder strips from agents (both names; see names.ts). */
 export { TELEGRAM_TOKEN_ENV as TOKEN_ENV, TELEGRAM_TOKEN_ENVS as TOKEN_ENVS } from "./names.js";
 /** BotFather's shape: numeric bot id, colon, secret. */
@@ -99,19 +100,21 @@ export function pushedByTelegram(header, secret) {
     const given = Buffer.from(header), wanted = Buffer.from(secret);
     return given.length === wanted.length && timingSafeEqual(given, wanted);
 }
-/** Keep one pushed update for the bridge: a JSON object with a positive integer update_id. */
+/** Keep one pushed update for the bridge. A schema-invalid JSON update is logged and acknowledged, never retried. */
 export function keepPushedUpdate(store, botId, body, now) {
-    let update;
+    let raw;
     try {
-        update = JSON.parse(body.toString("utf8"));
+        raw = JSON.parse(body.toString("utf8"));
     }
     catch {
         return { ok: false };
     }
-    const id = update?.update_id;
-    if (update === null || typeof update !== "object" || typeof id !== "number" || !Number.isSafeInteger(id) || id <= 0)
-        return { ok: false };
-    return { ok: true, kept: store.queueTelegramUpdate(botId, id, JSON.stringify(update), now) };
+    const update = readTelegramUpdate(raw);
+    if (!update.ok) {
+        console.warn(`Ignoring a pushed Telegram update: ${update.issues.map(issue => issue.line).join("; ")}`);
+        return { ok: true, kept: false };
+    }
+    return { ok: true, kept: store.queueTelegramUpdate(botId, update.value.update_id, JSON.stringify(raw), now) };
 }
 /**
  * Environment wins, the credential file beside the database otherwise.
@@ -623,7 +626,7 @@ function decideKeyboard(phoneOrigin, rows) {
     catch {
         origin = null;
     }
-    return rows.map(row => row.flatMap((one) => "token" in one ? [{ text: one.label, callback_data: one.token }]
+    return rows.map(row => row.flatMap((one) => "token" in one ? [telegramButton(one.label, one.token)]
         : phoneLinkButton(origin, one.link) ?? [])).filter(row => row.length > 0);
 }
 /** What this card may act on in the chat now, for this person under their current ceiling; null keeps its link. */
@@ -1311,10 +1314,7 @@ async function deliverOne(store, botId, binding, sender, notification, clock, ph
         }, clock());
     }
     const keyboard = tokens.map(({ option, token }) => [
-        {
-            text: `${option.label}${option.id === decision.recommendation ? " ✓" : ""}${option.reversible ? "" : " ⚠"}`,
-            callback_data: token,
-        },
+        telegramButton(`${option.label}${option.id === decision.recommendation ? " ✓" : ""}${option.reversible ? "" : " ⚠"}`, token),
     ]);
     const last = parts[parts.length - 1];
     const sent = await sender(last, keyboard);
@@ -1433,12 +1433,22 @@ async function drainUpdates(store, botId, transport, owner, generation, cursor,
             report.problems.push(`getUpdates: ${said}`);
             return;
         }
-        const updates = answer.result ?? [];
+        const updates = Array.isArray(answer.result) ? answer.result : [];
         if (updates.length === 0)
             return;
-        for (const update of updates) {
-            await processUpdate(context, update, owner, generation);
-            offset = update.update_id + 1;
+        for (const raw of updates) {
+            const update = readTelegramUpdate(raw);
+            if (!update.ok) {
+                // Telegram's own update in a shape this bridge doesn't read: said, and passed over so the next one is read.
+                const id = raw?.update_id;
+                report.problems.push(`an update Telegram sent couldn't be read: ${update.issues.map(issue => issue.line).join("; ")}`);
+                if (typeof id !== "number" || !Number.isSafeInteger(id))
+                    return;
+                offset = id + 1;
+                continue;
+            }
+            await processUpdate(context, update.value, owner, generation);
+            offset = update.value.update_id + 1;
         }
     }
     // The budget ran out with Telegram still holding pages: said, not hidden.
@@ -1473,15 +1483,11 @@ async function processUpdate(context, update, owner, generation) {
 async function drainInbox(context, owner, generation) {
     let applied = 0;
     for (const queued of context.store.telegramInbox(context.botId, PAGE_BUDGET * 100)) {
-        let update = null;
-        try {
-            update = JSON.parse(queued.payload);
-        }
-        catch {
-            update = null;
-        }
-        if (update !== null && update.update_id === queued.updateId)
-            await processUpdate(context, update, owner, generation);
+        const update = parseTelegramUpdate(queued.payload);
+        if (update.ok && update.value.update_id === queued.updateId)
+            await processUpdate(context, update.value, owner, generation);
+        else if (!update.ok)
+            context.report.problems.push(`a pushed update couldn't be read: ${update.issues.map(issue => issue.line).join("; ")}`);
         context.store.dropTelegramInbox(queued.updateId);
         applied++;
     }
@@ -1843,10 +1849,10 @@ function pickKeyboard(store, choices, focused) {
     for (const one of choices) {
         const ref = store.lookupRef(one.id);
         if (ref !== null)
-            rows.push([{ text: `${one.title} · ${one.label}`.slice(0, 60), callback_data: `pick:${ref.id}` }]);
+            rows.push([telegramButton(`${one.title} · ${one.label}`.slice(0, 60), `pick:${ref.id}`)]);
     }
     if (focused)
-        rows.push([{ text: "Back to the lead", callback_data: "pick:lead" }]);
+        rows.push([telegramButton("Back to the lead", "pick:lead")]);
     return rows;
 }
 /** The title of the task this Telegram chat chose to talk about, if any. */
@@ -2106,23 +2112,30 @@ function applyCallback(context, update, effects) {
         report.ignored++;
         return;
     }
+    // The paired person, in their chat: a button whose data isn't one Toolroll makes is answered with why, and does nothing.
+    const data = readTelegramButtonData(callback.data);
+    if (!data.ok) {
+        report.ignored++;
+        ack(`That button couldn't be read (${data.issues.map(issue => issue.line).join("; ")}). Nothing was done.`.slice(0, 190));
+        return;
+    }
     // A task picked from /tasks: this private chat now talks about it (or,
     // "Back to the lead", about everything again). The task is re-proved
     // against the chat's ceiling at the tap.
-    if (token.startsWith("pick:")) {
+    const pick = pickOf(token);
+    if (pick !== null) {
         if (tapChat !== binding.chatId) {
             report.ignored++;
             return;
         }
-        if (token === "pick:lead") {
+        if (pick.ref === null) {
             store.setChatFocus("telegram", binding.id, null, clock());
             store.recordTelegramTaskMessage(binding, String(message.message_id), null, null, clock());
             ack("Back to the lead");
             editText(PHONE_BACK_TO_LEAD);
             return;
         }
-        const refId = /^pick:([1-9][0-9]{0,14})$/.exec(token)?.[1];
-        const taskId = refId === undefined ? null : store.externalIdFor(Number(refId));
+        const taskId = store.externalIdFor(pick.ref);
         const repos = context.projects === null ? null : telegramConversationRepos(store, binding.approver, context.projects);
         if (taskId === null || repos === null || !taskInCeiling(store, taskId, repos)) {
             ack("That task isn't available here now.");
@@ -2136,7 +2149,7 @@ function applyCallback(context, update, effects) {
         const current = store.taskFamilyOf(taskId, repos, false)?.current.id ?? id;
         const view = phoneTaskView(store, repos, current, clock());
         store.recordTelegramTaskMessage(binding, String(message.message_id), current, view.run, clock());
-        editText(phoneFocusText(view.text), [[{ text: "Back to the lead", callback_data: "pick:lead" }]]);
+        editText(phoneFocusText(view.text), [[telegramButton("Back to the lead", "pick:lead")]]);
         return;
     }
     // A teammate's question (v93): an option answers it; "Answer in words" asks for a reply.
@@ -2206,13 +2219,13 @@ function applyCallback(context, update, effects) {
         return;
     }
     // The lead's question to its owner: an option is sent as their next message; "Something else" asks them to type it.
-    const askTap = /^ask:([1-9][0-9]{0,14}):([0-3]|x)$/.exec(token);
+    const askTap = askOf(token);
     if (askTap !== null) {
         if (tapChat !== binding.chatId || context.conversation === undefined) {
             report.ignored++;
             return;
         }
-        const turn = Number(askTap[1]);
+        const turn = askTap.turn;
         const found = store.getMateTurn(turn)?.approver === binding.approver ? store.mateAskState(turn, clock()) : { state: "expired" };
         if (found.state !== "open") {
             const line = found.state === "answered" ? "That question was already answered." : "That question expired. Send your answer as a message.";
@@ -2225,11 +2238,11 @@ function applyCallback(context, update, effects) {
             ack("Your answer is on its way.");
             return;
         }
-        if (askTap[2] === "x") {
+        if (askTap.option === "x") {
             ack("Type your answer as a message.");
             return;
         }
-        const option = ask.options[Number(askTap[2])];
+        const option = ask.options[askTap.option];
         if (option === undefined) {
             ack("That option is no longer there.");
             return;
@@ -2370,8 +2383,8 @@ function applyCallback(context, update, effects) {
             store.createTelegramAction({ token: cancel, binding: binding.id, decision: decision.id, optionId: option.id, phase: "cancel", chatId: binding.chatId, messageId: placedOn, ttlMs: CONFIRM_TTL_MS }, clock());
             ack("irreversible — confirm it");
             editText(`⚠ ${option.label} is IRREVERSIBLE.\n${option.consequence}\n${draft === null ? "" : `\nWith your note:\n${draft.note.split("\n").map(line => `| ${line}`).join("\n")}\n`}\nConfirm?`, [
-                [{ text: `⚠ Yes, ${option.label}`, callback_data: confirm }],
-                [{ text: "Cancel", callback_data: cancel }],
+                [telegramButton(`⚠ Yes, ${option.label}`, confirm)],
+                [telegramButton("Cancel", cancel)],
             ]);
             return;
         }
@@ -2418,10 +2431,7 @@ function applyCallback(context, update, effects) {
     }
     ack("cancelled");
     editText(`Q: ${decision.question}`, fresh.map(({ option, token: choose }) => [
-        {
-            text: `${option.label}${option.id === decision.recommendation ? " ✓" : ""}${option.reversible ? "" : " ⚠"}`,
-            callback_data: choose,
-        },
+        telegramButton(`${option.label}${option.id === decision.recommendation ? " ✓" : ""}${option.reversible ? "" : " ⚠"}`, choose),
     ]));
 }
 function answerNow(context, decision, choice, binding, ack, editText) {