toolroll 0.9.36 → 0.9.37

package/dist/task-sizing.js

@@ -20,12 +20,13 @@ import { randomUUID } from "node:crypto";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { readSizeAnswer, SIZING_MODEL_SCHEMA } from "./contracts/task-sizing.js";
 import { strictJsonParse } from "./converse.js";
 import { redactSecretLines, scanForSecrets } from "./evidence.js";
 import { run, terminateOwnedProcesses } from "./exec.js";
 import { JEV_MODEL, JEV_URL } from "./flow-sort.js";
 import { readProviderKey } from "./keys.js";
-import { isTaskSize } from "./phase-routing.js";
+import {} from "./phase-routing.js";
 import { ALL_CREDENTIAL_ENV } from "./provider.js";
 /** The classifier's whole budget, from asking to answer. */
 export const SIZING_BUDGET_MS = 5_000;
@@ -49,8 +50,11 @@ export function heuristicSizing(input, why = null) {
 const clip = (text, cap) => (text.length <= cap ? text : `${text.slice(0, cap - 1)}…`);
 /** Key-shaped lines never leave the machine. */
 const blank = (text) => redactSecretLines(text, scanForSecrets(text));
-/** One plain line, bounded. */
-const oneLine = (text) => clip(text.replace(/\s+/g, " ").trim(), 160);
+/** An answer read through the contract (src/contracts/task-sizing.ts), its reason on one line; null when it isn't one. */
+function answerOf(value) {
+    const read = readSizeAnswer(value);
+    return read.ok ? read.value : null;
+}
 const SIZE_MEANS = {
     small: "a contained change a fast model can make directly: copy, a style, a config value, one small function, one or two files",
     medium: "ordinary feature or fix work across a few files that benefits from the everyday model",
@@ -66,25 +70,6 @@ export function sizingText(input) {
         ...(input.touches === undefined || input.touches.length === 0 ? [] : [`Paths: ${clip(input.touches.slice(0, 40).join(", "), 1500)}`]),
     ].join("\n");
 }
-export const SIZING_SCHEMA = {
-    type: "object",
-    properties: {
-        size: { type: "string", enum: ["small", "medium", "large"] },
-        risky: { type: "boolean" },
-        reason: { type: "string", maxLength: 160 },
-    },
-    required: ["size", "risky", "reason"],
-    additionalProperties: false,
-};
-/** Read an answer back: only the three sizes, a boolean, and a short reason. */
-export function readSizeAnswer(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value))
-        return null;
-    const v = value;
-    if (!isTaskSize(v["size"]) || typeof v["risky"] !== "boolean")
-        return null;
-    return { size: v["size"], risky: v["risky"], reason: typeof v["reason"] === "string" ? oneLine(v["reason"]) : "" };
-}
 /** A small Claude model on this computer's sign-in: no tools, no MCP servers, no repository, credential keys stripped.
  * The abort ends it: a late answer never keeps a command (or its process) waiting. */
 export function claudeSizer(runner = run, model = SIZING_CLAUDE_MODEL, budgetMs = SIZING_BUDGET_MS) {
@@ -108,7 +93,7 @@ export function claudeSizer(runner = run, model = SIZING_CLAUDE_MODEL, budgetMs
                 sizingText(input),
             ].join("\n");
             const result = await runner("claude", [
-                "-p", "--output-format", "json", "--json-schema", JSON.stringify(SIZING_SCHEMA), "--safe-mode", "--no-session-persistence", "--tools", "", "--permission-mode", "dontAsk",
+                "-p", "--output-format", "json", "--json-schema", JSON.stringify(SIZING_MODEL_SCHEMA), "--safe-mode", "--no-session-persistence", "--tools", "", "--permission-mode", "dontAsk",
                 "--permission-prompts", "none", "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}', "--model", model,
             ], { cwd: dir, stdin: prompt, timeoutMs: budgetMs, maxBuffer: 256 * 1024, omitEnv: ALL_CREDENTIAL_ENV, processGroup: true, owner, beforeSpawn: () => !signal.aborted });
             if (signal.aborted || result.notFound || result.timedOut || result.code !== 0)
@@ -117,7 +102,7 @@ export function claudeSizer(runner = run, model = SIZING_CLAUDE_MODEL, budgetMs
             const body = parsed.ok && typeof parsed.value === "object" && parsed.value !== null && !Array.isArray(parsed.value) ? parsed.value : null;
             if (body === null || body["is_error"] === true || body["subtype"] !== "success")
                 return null;
-            return readSizeAnswer(body["structured_output"]);
+            return answerOf(body["structured_output"]);
         }
         finally {
             signal.removeEventListener("abort", stop);
@@ -149,10 +134,10 @@ export function jevSizer(fetcher, key) {
         const answers = (body["answers"] ?? {});
         const size = answers["size"]?.["choice"];
         const risky = answers["risky"]?.["noul"];
-        if (!isTaskSize(size) || typeof risky !== "number" || !Number.isFinite(risky))
+        if (typeof risky !== "number" || !Number.isFinite(risky))
             return null;
         const sure = answers["size"]?.["confidence"];
-        return { size, risky: risky >= 0.5, reason: typeof sure === "number" && Number.isFinite(sure) ? `Jev is ${Math.round(Math.min(1, Math.max(0, sure)) * 100)}% sure` : "" };
+        return answerOf({ size, risky: risky >= 0.5, reason: typeof sure === "number" && Number.isFinite(sure) ? `Jev is ${Math.round(Math.min(1, Math.max(0, sure)) * 100)}% sure` : "" });
     };
 }
 /** The owner's own classifier: Jev when an OpenRouter key is set up, otherwise Claude on this computer's sign-in. */

package/dist/task-text.d.ts

@@ -3,11 +3,6 @@ export declare const TASK_TEXT_LIMITS: {
     readonly text: 8000;
     readonly textBytes: 32000;
 };
-export declare const TASK_SCOPE_TEXT_SCHEMA: {
-    readonly type: "string";
-    readonly maxLength: 8000;
-    readonly description: `At most ${string} characters (UTF-16 code units) and ${string} UTF-8 bytes; no control or disguised text. Longer text is refused with its length, not cut: shorten it and call again.`;
-};
 export type TaskTextRefusal = {
     ok: false;
     reason: "bad-title" | "bad-goal";

package/dist/task-text.js

@@ -6,10 +6,8 @@
  * runtime with lower limits. */
 import { hasForbiddenControls, hasDisguisedText } from "./decision.js";
 import { TEXT_LIMITS } from "./text-limits.js";
-export const TASK_TEXT_LIMITS = { title: 200, text: TEXT_LIMITS.goal, textBytes: TEXT_LIMITS.goalBytes };
+export const TASK_TEXT_LIMITS = { title: TEXT_LIMITS.taskTitle, text: TEXT_LIMITS.goal, textBytes: TEXT_LIMITS.goalBytes };
 const n = (value) => value.toLocaleString("en-US");
-export const TASK_SCOPE_TEXT_SCHEMA = { type: "string", maxLength: TASK_TEXT_LIMITS.text,
-    description: `At most ${n(TASK_TEXT_LIMITS.text)} characters (UTF-16 code units) and ${n(TASK_TEXT_LIMITS.textBytes)} UTF-8 bytes; no control or disguised text. Longer text is refused with its length, not cut: shorten it and call again.` };
 const dishonest = (text) => hasForbiddenControls(text) || hasDisguisedText(text);
 const overBytes = (text, cap) => Buffer.byteLength(text, "utf8") > cap;
 const BYTE_CAPS = { title: 800, text: TASK_TEXT_LIMITS.textBytes, path: 800 };

package/dist/teammate-question.js

@@ -11,8 +11,10 @@
  * the person it was asked of. Answered anywhere, every button retires.
  */
 import { randomBytes } from "node:crypto";
+import { partContent, savedChatPart } from "./chat-delivery-state.js";
 import { answerTeammateQuestion } from "./teammate-work.js";
 import { labelOf } from "./teammate-admin.js";
+import { telegramButton } from "./contracts/telegram-callback.js";
 /** The key notifyPeople gives a teammate's question: flow-card:<card>:teammate-q:<question>:<person>. */
 export const TEAMMATE_Q_KEY = /^flow-card:[1-9][0-9]{0,14}:teammate-q:([1-9][0-9]{0,14}):/;
 export const IN_WORDS = "Answer in words";
@@ -41,8 +43,8 @@ export function telegramQuestionButtons(store, binding, question, now) {
     const rows = [];
     const options = choices.filter(one => one.choice !== null);
     for (let at = 0; at < options.length; at += 2)
-        rows.push(options.slice(at, at + 2).map(one => ({ text: one.label.slice(0, 60), callback_data: one.token })));
-    rows.push([{ text: choices.at(-1).label, callback_data: choices.at(-1).token }]);
+        rows.push(options.slice(at, at + 2).map(one => telegramButton(one.label.slice(0, 60), one.token)));
+    rows.push([telegramButton(choices.at(-1).label, choices.at(-1).token)]);
     return { keyboard: rows, tokens: choices.map(one => one.token) };
 }
 /** A tapped question button, inside the update's transaction. */
@@ -90,7 +92,7 @@ export function questionParts(store, notification, binding) {
 /** The live buttons on one part, in the order they were minted. */
 export function chatQuestionButtons(state, part, now) {
     const row = state.prepare("SELECT payload FROM chat_part WHERE id=?").get(part);
-    const content = row === undefined ? null : JSON.parse(String(row["payload"]));
+    const content = row === undefined ? null : partContent(String(row["payload"]));
     const labels = new Map((content?.question?.choices ?? []).map(one => [one.choice ?? "", one.label]));
     return state.prepare("SELECT token,choice FROM chat_question_action WHERE part=? AND consumed IS NULL AND expires>? ORDER BY rowid").all(part, now.toISOString())
         .map(one => ({ token: String(one.token), label: (labels.get(one.choice ?? "") ?? IN_WORDS).slice(0, 75), words: one.choice === null }));
@@ -98,9 +100,9 @@ export function chatQuestionButtons(state, part, now) {
 /** Show the tapped notice again with the answer, and without its buttons. */
 function repaint(state, part, event, line) {
     const row = state.prepare("SELECT payload FROM chat_part WHERE id=?").get(part);
-    const before = row === undefined ? { text: "" } : JSON.parse(String(row["payload"]));
+    const before = row === undefined ? { text: "" } : partContent(String(row["payload"]));
     const content = { text: `${before.text}\n\n${line}`.slice(0, 3400), edit: event.ts, ...(before.link === undefined ? {} : { link: before.link }), ...(before.channel === undefined ? {} : { channel: before.channel }) };
-    state.prepare("UPDATE chat_part SET payload=?,state='pending',next_at=NULL WHERE id=?").run(JSON.stringify(content), part);
+    state.prepare("UPDATE chat_part SET payload=?,state='pending',next_at=NULL WHERE id=?").run(savedChatPart(content), part);
 }
 /** A tapped question button, inside the action's transaction; false when the token isn't one. */
 export function applyChatQuestionTap(options, event, binding, token, now) {

package/dist/teammate-work.js

@@ -111,9 +111,10 @@ export async function teammateTurn(store, flow, definition, stage, card, mate, n
         store.addTeammateTurn({ teammate: mate.id, card: card.id, model, ok: reply.ok, ms: reply.ok ? reply.ms : Date.now() - asked, costUsd: reply.costUsd ?? null, tokensIn: reply.tokensIn ?? null, tokensOut: reply.tokensOut ?? null }, now);
         if (!reply.ok)
             return { state: "retry", said: reply.said, ...(log.length === 0 ? {} : { log: log.join("\n\n") }) };
-        const answer = readTurn(reply.value, context);
-        if (answer === null)
-            return { state: "retry", said: `${context.name}'s answer wasn't one this zone allows.`, log: [...log, JSON.stringify(reply.value).slice(0, 4000)].join("\n\n") };
+        const read = readTurn(reply.value, context);
+        if (!read.ok)
+            return { state: "retry", said: `${context.name}'s answer wasn't one this zone allows.`, log: [...log, read.issues.map(issue => issue.line).join("\n"), JSON.stringify(reply.value).slice(0, 4000)].join("\n\n") };
+        const answer = read.value;
         const header = `${context.name} (${model}) · ${(reply.ms / 1000).toFixed(1)} s`;
         const over = turnOverruns(answer);
         if (over.length > 0 && !shortened) {
@@ -243,8 +244,11 @@ function carryOut(store, flow, definition, stage, card, mate, context, answer, n
     // route: the answer names where the card goes; its text is what the next zones use.
     const picked = handleAnswers(stage).find(one => one.answer.toLowerCase() === answer.answer.toLowerCase());
     // What the next zones read: whole up to what a step passes on; longer is attached whole to the card, and they read a link to it.
-    if (answer.text !== "")
-        store.updateFlowCard(card.id, { outputs: { ...card.outputs, [stage.id]: keptWhole(store, flow, card, actor, wholeDraft(answer.text), TEXT_LIMITS.stageOutput, "a step passes on", `What ${label} wrote for the next zones`, now) } }, now);
+    if (answer.text !== "") {
+        const whole = wholeDraft(answer.text);
+        const text = keptWhole(store, flow, card, actor, whole, TEXT_LIMITS.stageOutput, "a step passes on", `What ${label} wrote for the next zones`, now);
+        store.updateFlowCard(card.id, { outputs: { ...card.outputs, [stage.id]: text }, ...(text === whole ? {} : { attached: { [stage.id]: whole } }) }, now);
+    }
     const said = `Sent “${card.title}” to ${titleOf(picked.to)}${picked.answer === CARRY_ON ? "" : ` (${picked.answer})`}${answer.reason === "" ? "" : `: ${answer.reason}`}`;
     event("handled", said);
     // v96: a zone that answers whoever asked sends what it wrote back to them, under its name.

package/dist/teammates.d.ts

@@ -1,4 +1,6 @@
 import { run, type ExecResult } from "./exec.js";
+import type { ContractResult } from "./contracts/contract.js";
+import { type TurnAnswer } from "./contracts/teammate-turn.js";
 import { type Overrun } from "./text-limits.js";
 export declare const SOUL_CHARS = 12000;
 export type Soul = {
@@ -29,25 +31,11 @@ export declare const TEAMMATE_TEMPLATES: readonly {
     about: string;
     soul: string;
 }[];
-/** 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. */
-export type TurnAction = "approve" | "send_back" | "hand_off" | "route" | "ask" | "cant" | "use_tool";
-/** v94: "use_tool" asks for one tool call (`tool`: its name, `input`: a JSON object as text); the turn goes on with its answer. */
-export type TurnAnswer = {
-    action: TurnAction;
-    answer: string;
-    text: string;
-    note: string;
-    question: string;
-    options: string[];
-    reason: string;
-    tool: string;
-    input: string;
-    /** v95: one short fact worth keeping for later cards ("": none). */
-    remember: string;
-};
+export type { TurnAction, TurnAnswer } from "./contracts/teammate-turn.js";
 /** 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. */
+ * "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 declare const TURN_LIMITS: {
     readonly answer: 60;
     readonly text: 12000;
@@ -58,49 +46,6 @@ export declare const TURN_LIMITS: {
 };
 /** The fields of an answer over their limits. */
 export declare function turnOverruns(answer: TurnAnswer): Overrun[];
-/** 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 declare const TURN_SCHEMA: {
-    readonly type: "object";
-    readonly additionalProperties: false;
-    readonly required: readonly ["action", "answer", "text", "note", "question", "options", "reason", "tool", "input", "remember"];
-    readonly properties: {
-        readonly action: {
-            readonly type: "string";
-            readonly enum: readonly ["approve", "send_back", "hand_off", "route", "ask", "cant", "use_tool"];
-        };
-        readonly answer: {
-            readonly type: "string";
-        };
-        readonly text: {
-            readonly type: "string";
-        };
-        readonly note: {
-            readonly type: "string";
-        };
-        readonly question: {
-            readonly type: "string";
-        };
-        readonly options: {
-            readonly type: "array";
-            readonly items: {
-                readonly type: "string";
-            };
-        };
-        readonly reason: {
-            readonly type: "string";
-        };
-        readonly tool: {
-            readonly type: "string";
-        };
-        readonly input: {
-            readonly type: "string";
-        };
-        readonly remember: {
-            readonly type: "string";
-        };
-    };
-};
 /** Everything one turn is told: the zone, the card as data, and what its people said. */
 export type TurnContext = {
     soul: string;
@@ -165,8 +110,13 @@ export type TurnContext = {
     };
 };
 export declare function turnPrompt(context: TurnContext): string;
-/** A turn's answer, checked against what this zone allows; null when it isn't one. */
-export declare function readTurn(value: unknown, context: Pick<TurnContext, "kind" | "canSendBack" | "answers" | "tools">): TurnAnswer | null;
+/**
+ * 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 declare function readTurn(value: unknown, context: Pick<TurnContext, "kind" | "canSendBack" | "answers" | "tools">): ContractResult<TurnAnswer>;
 export type TurnRequest = {
     model: string;
     prompt: string;
@@ -190,10 +140,9 @@ export type TurnReply = ({
 export type TurnRunner = (request: TurnRequest) => Promise<TurnReply>;
 export declare const TURN_TIMEOUT_MS = 180000;
 type CommandRunner = (file: string, args: readonly string[], options: Parameters<typeof run>[2]) => Promise<ExecResult>;
-/** 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 declare function claudeTurnRunner(runner?: CommandRunner): TurnRunner;
 /** How a teammate is named to people: "Maya · Support". */
 export declare const teammateLabel: (soul: Pick<Soul, "name" | "role">) => string;
 /** How its acts read in a card's history: "Maya (AI)". */
 export declare const teammateActor: (soul: Pick<Soul, "name">) => string;
-export {};

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)) {