toolroll 0.9.36 → 0.9.38

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.d.ts

@@ -11,6 +11,12 @@ type Waiting = {
 };
 /** The card, if it is still at that visit, waiting at a decision. */
 export declare function flowDecisionAt(store: Store, cardId: number, entry: number): Waiting | null;
+/**
+ * A flow decision as Telegram shows it: the action and where each button takes the card first, then the draft (as
+ * the card holds it now, so what is approved is what is read) and why a teammate handed it over, then the flow and
+ * zone. `said` is the saved notice's body: the words before its instruction are the teammate's handoff.
+ */
+export declare function flowDecisionText(waiting: Waiting, said: string | null, head?: string): string;
 /** Buttons for one visit, minted before the send; `place` stamps the message they landed on. */
 export declare function flowButtons(store: Store, binding: TelegramBinding, waiting: Waiting, now: Date): {
     keyboard: InlineButton[][];
@@ -20,6 +26,9 @@ export declare function flowButtons(store: Store, binding: TelegramBinding, wait
 export declare function flowSentContent(store: Store, card: number, entry: number): FlowSendContent | null;
 /** A sent visit's links as one row of buttons: Toolroll's pages under the trusted origin, and its pull request. */
 export declare function flowSendKeyboardRow(origin: string | null, content: FlowSendContent): InlineButton[];
+/** A choice as Telegram shows it, first: what to choose, then where each option (and a reply) takes the card. The
+ * options are the ones its buttons carry: offered when sent, and still offered. */
+export declare function flowChoiceHead(visit: FlowChoiceVisit, content: FlowSendContent): string[];
 /** A choice's buttons for one visit, one option to a row, minted before the send; `place` stamps the message they landed on. */
 export declare function flowChoiceButtons(store: Store, binding: TelegramBinding, visit: FlowChoiceVisit, content: FlowSendContent, now: Date): {
     keyboard: InlineButton[][];

package/dist/telegram-flow.js

@@ -24,8 +24,9 @@ import { LIMITS } from "./decision.js";
 import { keptDraft } from "./flow-draft.js";
 import { decideFlowCard, draftFor, flowDefinitionOf } from "./flow-engine.js";
 import { chooseFlowCard, flowChoiceAt, flowSendPaths, readFlowSend } from "./flow-send.js";
-import { deciderOf } from "./flows.js";
+import { deciderOf, FLOW_END, replyTarget } 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. */
@@ -40,6 +41,29 @@ export function flowDecisionAt(store, cardId, entry) {
         return null;
     return { card, flow, stage, draft: draftFor(definition, stage) };
 }
+/** Where Approve and Send back take the card, on one line. */
+function decisionTerms(waiting) {
+    const approve = waiting.stage.next === null ? "Approve → done" : `Approve → ${titleOf(waiting, waiting.stage.next)}`;
+    return [approve, ...(waiting.stage.onFail === null ? [] : [`Send back → ${titleOf(waiting, waiting.stage.onFail)}, with your note`])].join(" · ");
+}
+/**
+ * A flow decision as Telegram shows it: the action and where each button takes the card first, then the draft (as
+ * the card holds it now, so what is approved is what is read) and why a teammate handed it over, then the flow and
+ * zone. `said` is the saved notice's body: the words before its instruction are the teammate's handoff.
+ */
+export function flowDecisionText(waiting, said, head = `Approve “${waiting.card.title}”`) {
+    const at = said === null ? -1 : said.indexOf(`${waiting.stage.title}: approve`);
+    const handoff = at > 0 ? said.slice(0, at).trim() : "";
+    const draft = waiting.draft === null ? undefined : waiting.card.outputs[waiting.draft.id]?.trim();
+    return [
+        head,
+        decisionTerms(waiting),
+        ...(handoff === "" ? [] : ["", handoff]),
+        ...(draft === undefined || draft === "" ? [] : ["", "Draft:", draft]),
+        "",
+        `${waiting.flow.name} · ${waiting.stage.title}`,
+    ].join("\n");
+}
 /** Buttons for one visit, minted before the send; `place` stamps the message they landed on. */
 export function flowButtons(store, binding, waiting, now) {
     const mint = (action) => ({ action, token: randomBytes(16).toString("hex") });
@@ -48,9 +72,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) {
@@ -63,12 +87,23 @@ export function flowSendKeyboardRow(origin, content) {
     const pull = content.links.flatMap(one => "url" in one ? [{ text: one.label, url: one.url }] : []);
     return [...pages.slice(0, 1), ...pull, ...pages.slice(1)].slice(0, 3);
 }
+/** A choice as Telegram shows it, first: what to choose, then where each option (and a reply) takes the card. The
+ * options are the ones its buttons carry: offered when sent, and still offered. */
+export function flowChoiceHead(visit, content) {
+    const titleIn = (id) => visit.definition.stages.find(one => one.id === id)?.title ?? id;
+    const options = (content.options ?? []).flatMap(one => {
+        const option = visit.stage.options?.[one.choice];
+        return option === undefined || option.label !== one.label ? [] : [`${one.label} → ${option.to === FLOW_END ? "closes the card" : titleIn(option.to)}`];
+    });
+    const reply = content.reply === true ? replyTarget(visit.stage) : null;
+    return [`Choose what happens to “${visit.card.title}”`, [...options, ...(reply === null ? [] : [`or reply → ${titleIn(reply)}, with your note`])].join(" · ")];
+}
 /** A choice's buttons for one visit, one option to a row, minted before the send; `place` stamps the message they landed on. */
 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) {
@@ -87,7 +122,9 @@ export function applyFlowChoiceTap(store, binding, choice, message, repos, now)
     if (!chosen.ok)
         return [{ kind: "ack", text: chosen.message.slice(0, 190) }];
     store.retireFlowChoices(choice.card, choice.entry, now);
-    return [{ kind: "ack", text: choice.label.slice(0, 190) }, { kind: "edit", text: `${message.text}\n\n✅ You chose “${choice.label}”. ${chosen.said}`.slice(0, 4000) }];
+    // The door's words name the option already ("Ship it. Moved to Ship."); an ending says what happened instead.
+    const said = chosen.said.startsWith(`${choice.label}.`) ? chosen.said : `You chose “${choice.label}”. ${chosen.said}`;
+    return [{ kind: "ack", text: choice.label.slice(0, 190) }, { kind: "edit", text: `${message.text}\n\n✅ ${said}`.slice(0, 4000) }];
 }
 /** A tapped flow button, applied inside the update's transaction. */
 export function applyFlowTap(store, binding, action, message, repos, now) {
@@ -106,7 +143,7 @@ export function applyFlowTap(store, binding, action, message, repos, now) {
         if (!decided.ok)
             return [{ kind: "ack", text: decided.message.slice(0, 190) }];
         store.retireTelegramFlowVisit(action.card, action.entry, now);
-        return [{ kind: "ack", text: "Approved" }, { kind: "edit", text: `${message.text}\n\n✅ You approved it. ${decided.said}`.slice(0, 4000) }];
+        return [{ kind: "ack", text: "Approved" }, { kind: "edit", text: `${message.text}\n\n✅ ${decided.said}`.slice(0, 4000) }];
     }
     const prompt = { chatId: binding.chatId, binding: binding.id, card: action.card, entry: action.entry, mode: action.action };
     if (action.action === "edit") {
@@ -156,8 +193,7 @@ export function applyFlowReply(store, binding, prompt, text, repos, now) {
         store.retireTelegramFlowVisit(prompt.card, prompt.entry, now);
         const fresh = flowDecisionAt(store, prompt.card, prompt.entry);
         const buttons = flowButtons(store, binding, fresh, now);
-        return [{ kind: "decide", keyboard: buttons.keyboard, tokens: buttons.tokens,
-                text: `${waiting.flow.name}: your version of the draft for “${waiting.card.title}”\n\n${kept}\n\nApprove to send it as written.` }];
+        return [{ kind: "decide", keyboard: buttons.keyboard, tokens: buttons.tokens, text: flowDecisionText(fresh, null, `Approve your version of “${waiting.card.title}”`) }];
     }
     // A note over its limit is refused with the limit, never cut.
     if (said.length > LIMITS.note)