toolroll 0.9.36 → 0.9.37

package/CHANGELOG.md

@@ -1,5 +1,63 @@
 # Changelog
 
+## 0.9.37 — 2026-10-06
+
+- **Zod revamp, waves 1 and 2 finished.** Every handoff between a model and
+  Toolroll, and the context passed between steps, is now one schema each in
+  `src/contracts/`: the lead's 51 tools and the 25 MCP gateway tools, the
+  scout report, task sizing, reviewer findings, decisions, teammate turns and
+  sort answers, the lead's context bundle, project knowledge, memory and
+  skills, chat actions and channel callbacks, and the desktop coding handoff,
+  context and session record. A model gets the schema as `--json-schema`
+  where its harness takes one; a refusal names the field
+  (`steps[0].routes[0].goesTo: required`). Everything that was accepted before
+  is still accepted: tool calls with extra or loose arguments, model answers
+  with nulls or overlong text (clipped as before), saved reports, rows,
+  sessions, chat buttons and proposals. Replayed against real saved data
+  (scout reports, findings, decisions, 410 scopes and 796 routes, 279 chat
+  buttons, every saved flow and card), all of it reads the same.
+- **Research can read PostHog.** A research run gets a connected service's
+  query tool (PostHog's `exec`) only when the access the service actually
+  granted is read-only. Otherwise it skips it and says why on the run and the
+  integration, with a **Reconnect read-only** action. Connecting PostHog as
+  usual is unchanged, and builds keep every tool. Connections made before this
+  release didn't record what was granted, so research skips them until you
+  reconnect read-only.
+- **A question's recommendation can carry its reason.** `connect: because…`
+  now counts as recommending `connect`, instead of failing the question.
+- **A Telegram update Toolroll can't read** is logged and answered OK, so
+  Telegram doesn't keep resending it. A Slack, Discord or Teams message part
+  that can't be read is dropped with its reason instead of retried forever.
+- **Rolling back:** flow cards written by 0.9.37 read as empty in 0.9.36, so a
+  rollback loses the step outputs of cards still in progress.
+- **Scopes, acceptance criteria and sealed routes have one contract.** A task's
+  scope (goal, exclusions, touch paths, rubric) and an acceptance criterion are
+  described once from the plan contract's own fields (`src/contracts/scope.ts`);
+  a sealed agent route, in both versions it has been saved in, with its
+  overrides and task size, is one schema (`src/contracts/route.ts`). The shared
+  rubric input schema is ready for the lead-tool migration. Every saved scope,
+  standing order and sealed route reads and digests exactly as before, so no
+  approval changes.
+  Nothing new is refused: a scope still names up to 50 paths and a criterion
+  still ignores keys it doesn't use. Rubric and route refusals are now
+  field-named lines (`acceptance[0].statement over 1,000 bytes`), and a route
+  made by a newer Toolroll says so.
+- **What a flow's steps hand on has one contract.** A finished zone's
+  `{{stage.…}}` words, a card's saved outputs, and what Send to me and Person
+  chooses send are each described once (`src/contracts/stage-output.ts`,
+  `flow-send.ts`, `flow-card.ts`). Saved cards and sends read exactly as
+  before. A build or research task filed after a step whose output was too
+  long to pass on now gets that output whole, not just a link to it.
+- **Tightened, on purpose.** Saving a flow with a new `{{stage.…}}` that its
+  zone doesn't hand on is refused, naming where:
+  `stages[2].instructions: stage.research.unknown is not available (Research
+  hands on {{stage.research}}, {{stage.research.items}} and
+  {{stage.research.report}})`. This covers the canvas, `toolroll flows
+  create/edit/import`, the lead and templates. A reference a flow already had
+  is never refused, and nothing changes for flows that are only read or run.
+  Card outputs and kept sends are saved with a version; ones a newer Toolroll
+  wrote are refused rather than misread or overwritten.
+
 ## 0.9.36 — 2026-10-06
 
 - **Flows have one contract.** Every kind of zone, step, route, answer,

package/dist/assignment-adapters.d.ts

@@ -1,87 +1,52 @@
 import { type AssignmentSnapshot } from "./assignment.js";
 import type { Store } from "./store.js";
-export declare const ASSIGNMENT_ACTIONS: readonly ["show", "updates", "claim", "check", "brief", "inbox", "ack"];
-export type AssignmentOperation = typeof ASSIGNMENT_ACTIONS[number];
+import { type AssignmentInput, type AssignmentOperation } from "./contracts/gateway-tools.js";
+export declare const ASSIGNMENT_ACTIONS: AssignmentOperation[];
+export type { AssignmentOperation };
 type Args = Record<string, unknown>;
 type Failure = {
     ok: false;
     reason: string;
     message: string;
 };
+/** The gateway's assignment tools: names and words. Each one's input is ASSIGNMENT_INPUTS[operation]
+ * (src/contracts/gateway-tools.ts), which `toolroll assignment` reads its flags with too. */
 export declare const ASSIGNMENT_TOOLS: readonly [{
     readonly name: "get_assignment";
     readonly operation: "show";
     readonly description: "Read one assignment's root, current execution, owner, exact result and handoff receipt. Approval, proof and deployment remain separate facts.";
-    readonly inputSchema: {
-        type: string;
-        properties: Record<string, unknown>;
-        required: string[];
-        additionalProperties: boolean;
-    };
 }, {
     readonly name: "list_assignment_updates";
     readonly operation: "updates";
     readonly description: "Read durable assignment updates in your projects after a cursor. Save nextCursor after processing; repeated reads do not acknowledge or deliver anything.";
-    readonly inputSchema: {
-        type: string;
-        properties: Record<string, unknown>;
-        required: string[];
-        additionalProperties: boolean;
-    };
 }, {
     readonly name: "claim_assignment";
     readonly operation: "claim";
     readonly description: "Record yourself as this assignment's lead. Repeating your claim is safe; another active owner cannot be replaced. This grants no approval or execution authority.";
-    readonly inputSchema: {
-        type: string;
-        properties: Record<string, unknown>;
-        required: string[];
-        additionalProperties: boolean;
-    };
 }, {
     readonly name: "acknowledge_assignment";
     readonly operation: "check";
     readonly description: "Acknowledge the exact ready-to-check receipt as its lead, using the current receipt digest. This does not accept failed proof, answer decisions, approve work, publish or deploy.";
-    readonly inputSchema: {
-        type: string;
-        properties: Record<string, unknown>;
-        required: string[];
-        additionalProperties: boolean;
-    };
 }, {
     readonly name: "get_assignment_brief";
     readonly operation: "brief";
     readonly description: "Catch up from the local database: current work, decisions, saved results and project knowledge. Bounded read only; no model call or task mutation.";
-    readonly inputSchema: {
-        type: string;
-        properties: Record<string, unknown>;
-        required: string[];
-        additionalProperties: boolean;
-    };
 }, {
     readonly name: "get_assignment_inbox";
     readonly operation: "inbox";
     readonly description: "Receive a durable batch of your assignments' status changes. Use a stable consumer name. Until acknowledged, the same batch survives reconnects and restarts. Receiving never completes or reruns work.";
-    readonly inputSchema: {
-        type: string;
-        properties: Record<string, unknown>;
-        required: string[];
-        additionalProperties: boolean;
-    };
 }, {
     readonly name: "acknowledge_assignment_delivery";
     readonly operation: "ack";
     readonly description: "Acknowledge receipt of an inbox batch after handling its updates. This advances only your delivery cursor; it never marks work complete, answers a decision or starts a revision.";
-    readonly inputSchema: {
-        type: string;
-        properties: Record<string, unknown>;
-        required: string[];
-        additionalProperties: boolean;
-    };
 }];
-/** The CLI and MCP use the same bounded input contract. MCP also validates its
- * descriptor before dispatch; this check protects direct adapter callers. */
-export declare function assignmentArgumentProblem(operation: AssignmentOperation, args: Args): string | null;
+/** The CLI and MCP read an assignment call with the same schema; MCP reads it before dispatch too, and this protects
+ * direct adapter callers. A refusal is its path-named lines; a ref or project path with control characters, which
+ * JSON Schema can't say, is refused after parsing. */
+export declare function readAssignmentArgs<O extends AssignmentOperation>(operation: O, args: Args): {
+    ok: true;
+    value: AssignmentInput<O>;
+} | Failure;
 /** Every read and mutation authenticates inside the same transaction as its
  * projection. A cached name/allowlist cannot keep a revoked identity alive. */
 export declare function assignmentForCoordinator(store: Store, token: string, operation: AssignmentOperation, args: Args, now: Date, evidenceRoot?: string): Failure | {
@@ -179,4 +144,3 @@ export declare function coordinatorToken(flags: Map<string, string | true>, env:
     token: string | null;
 } | Failure;
 export declare function runAssignmentCommand(positional: readonly string[], flags: Map<string, string | true>, context: AssignmentCliContext): number;
-export {};

package/dist/assignment-adapters.js

@@ -8,47 +8,36 @@ import { assignmentCatchUp } from "./assignment-brief.js";
 import { assignmentInbox, acknowledgeAssignmentDelivery } from "./assignment-delivery.js";
 import { syncAssignmentStatuses } from "./assignment-status.js";
 import { envelopeJson } from "./envelope.js";
-export const ASSIGNMENT_ACTIONS = ["show", "updates", "claim", "check", "brief", "inbox", "ack"];
+import { parseContract } from "./contracts/contract.js";
+import { ASSIGNMENT_INPUTS } from "./contracts/gateway-tools.js";
+export const ASSIGNMENT_ACTIONS = Object.keys(ASSIGNMENT_INPUTS);
 const failure = (reason, message) => ({ ok: false, reason, message });
-const reference = { type: "string", minLength: 1, maxLength: 64 };
-const digest = { type: "string", minLength: 64, maxLength: 64, pattern: "^[a-f0-9]{64}$" };
-const batchId = { type: "string", minLength: 32, maxLength: 32, pattern: "^[a-f0-9]{32}$" };
-const consumer = { type: "string", minLength: 1, maxLength: 64, pattern: "^[a-z0-9][a-z0-9-]{0,63}$" };
-const object = (properties, required = []) => ({ type: "object", properties, required, additionalProperties: false });
+/** The gateway's assignment tools: names and words. Each one's input is ASSIGNMENT_INPUTS[operation]
+ * (src/contracts/gateway-tools.ts), which `toolroll assignment` reads its flags with too. */
 export const ASSIGNMENT_TOOLS = [
-    { name: "get_assignment", operation: "show", description: "Read one assignment's root, current execution, owner, exact result and handoff receipt. Approval, proof and deployment remain separate facts.", inputSchema: object({ ref: reference }, ["ref"]) },
-    { name: "list_assignment_updates", operation: "updates", description: "Read durable assignment updates in your projects after a cursor. Save nextCursor after processing; repeated reads do not acknowledge or deliver anything.", inputSchema: object({ after: { type: "integer", minimum: 0, maximum: Number.MAX_SAFE_INTEGER }, limit: { type: "integer", minimum: 1, maximum: 100 } }) },
-    { name: "claim_assignment", operation: "claim", description: "Record yourself as this assignment's lead. Repeating your claim is safe; another active owner cannot be replaced. This grants no approval or execution authority.", inputSchema: object({ ref: reference }, ["ref"]) },
-    { name: "acknowledge_assignment", operation: "check", description: "Acknowledge the exact ready-to-check receipt as its lead, using the current receipt digest. This does not accept failed proof, answer decisions, approve work, publish or deploy.", inputSchema: object({ ref: reference, digest }, ["ref", "digest"]) },
-    { name: "get_assignment_brief", operation: "brief", description: "Catch up from the local database: current work, decisions, saved results and project knowledge. Bounded read only; no model call or task mutation.", inputSchema: object({ repo: { type: "string", minLength: 1, maxLength: 4096 }, limit: { type: "integer", minimum: 1, maximum: 25 } }) },
-    { name: "get_assignment_inbox", operation: "inbox", description: "Receive a durable batch of your assignments' status changes. Use a stable consumer name. Until acknowledged, the same batch survives reconnects and restarts. Receiving never completes or reruns work.", inputSchema: object({ consumer, limit: { type: "integer", minimum: 1, maximum: 100 } }, ["consumer"]) },
-    { name: "acknowledge_assignment_delivery", operation: "ack", description: "Acknowledge receipt of an inbox batch after handling its updates. This advances only your delivery cursor; it never marks work complete, answers a decision or starts a revision.", inputSchema: object({ consumer, batchId }, ["consumer", "batchId"]) },
+    { name: "get_assignment", operation: "show", description: "Read one assignment's root, current execution, owner, exact result and handoff receipt. Approval, proof and deployment remain separate facts." },
+    { name: "list_assignment_updates", operation: "updates", description: "Read durable assignment updates in your projects after a cursor. Save nextCursor after processing; repeated reads do not acknowledge or deliver anything." },
+    { name: "claim_assignment", operation: "claim", description: "Record yourself as this assignment's lead. Repeating your claim is safe; another active owner cannot be replaced. This grants no approval or execution authority." },
+    { name: "acknowledge_assignment", operation: "check", description: "Acknowledge the exact ready-to-check receipt as its lead, using the current receipt digest. This does not accept failed proof, answer decisions, approve work, publish or deploy." },
+    { name: "get_assignment_brief", operation: "brief", description: "Catch up from the local database: current work, decisions, saved results and project knowledge. Bounded read only; no model call or task mutation." },
+    { name: "get_assignment_inbox", operation: "inbox", description: "Receive a durable batch of your assignments' status changes. Use a stable consumer name. Until acknowledged, the same batch survives reconnects and restarts. Receiving never completes or reruns work." },
+    { name: "acknowledge_assignment_delivery", operation: "ack", description: "Acknowledge receipt of an inbox batch after handling its updates. This advances only your delivery cursor; it never marks work complete, answers a decision or starts a revision." },
 ];
-/** The CLI and MCP use the same bounded input contract. MCP also validates its
- * descriptor before dispatch; this check protects direct adapter callers. */
-export function assignmentArgumentProblem(operation, args) {
+/** The CLI and MCP read an assignment call with the same schema; MCP reads it before dispatch too, and this protects
+ * direct adapter callers. A refusal is its path-named lines; a ref or project path with control characters, which
+ * JSON Schema can't say, is refused after parsing. */
+export function readAssignmentArgs(operation, args) {
     if (!ASSIGNMENT_ACTIONS.includes(operation))
-        return "Choose show, updates, claim, check, brief, inbox, or ack.";
-    const allowed = operation === "brief" ? ["repo", "limit"] : operation === "inbox" ? ["consumer", "limit"] : operation === "ack" ? ["consumer", "batchId"] : operation === "updates" ? ["after", "limit"] : operation === "check" ? ["ref", "digest"] : ["ref"];
-    for (const key of Object.keys(args))
-        if (!allowed.includes(key))
-            return `Unknown argument: ${key}.`;
-    if (["show", "claim", "check"].includes(operation) && (typeof args["ref"] !== "string" || args["ref"].length < 1 || args["ref"].length > 64 || /[\u0000-\u001f\u007f]/.test(args["ref"])))
-        return "Choose a task id, 1–64 characters without control characters.";
-    if (operation === "check" && (typeof args["digest"] !== "string" || !/^[a-f0-9]{64}$/.test(args["digest"])))
-        return "Use the exact 64-character receipt digest from assignment show.";
-    if ((operation === "inbox" || operation === "ack") && (typeof args["consumer"] !== "string" || !/^[a-z0-9][a-z0-9-]{0,63}$/.test(args["consumer"])))
-        return "Use a stable consumer name with 1–64 lowercase letters, digits or hyphens.";
-    if (operation === "ack" && (typeof args["batchId"] !== "string" || !/^[a-f0-9]{32}$/.test(args["batchId"])))
-        return "Use the exact batchId from assignment inbox.";
-    if (args["repo"] !== undefined && (typeof args["repo"] !== "string" || args["repo"].length < 1 || args["repo"].length > 4096 || /[\u0000-\u001f\u007f]/.test(args["repo"])))
-        return "Choose a project path without control characters.";
-    for (const [name, min, max] of [["after", 0, Number.MAX_SAFE_INTEGER], ["limit", 1, operation === "brief" ? 25 : 100]]) {
-        const value = args[name];
-        if (value !== undefined && (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max))
-            return `${name} must be an integer from ${min} to ${max}.`;
+        return failure("usage", "Choose show, updates, claim, check, brief, inbox, or ack.");
+    const read = parseContract(ASSIGNMENT_INPUTS[operation], args);
+    if (!read.ok)
+        return failure("usage", read.issues.map(one => one.line).join("; "));
+    const value = read.value;
+    for (const field of ["ref", "repo"]) {
+        if (typeof value[field] === "string" && /[\u0000-\u001f\u007f]/.test(value[field]))
+            return failure("usage", `${field}: must not contain control characters`);
     }
-    return null;
+    return { ok: true, value };
 }
 function readAssignment(store, operation, args, now, access, root) {
     if (operation === "brief")
@@ -61,9 +50,10 @@ function readAssignment(store, operation, args, now, access, root) {
 /** Every read and mutation authenticates inside the same transaction as its
  * projection. A cached name/allowlist cannot keep a revoked identity alive. */
 export function assignmentForCoordinator(store, token, operation, args, now, evidenceRoot) {
-    const problem = assignmentArgumentProblem(operation, args);
-    if (problem !== null)
-        return failure("usage", problem);
+    const read = readAssignmentArgs(operation, args);
+    if (!read.ok)
+        return read;
+    args = read.value;
     // Authenticate before maintenance, then authenticate again inside delivery.
     // Reconciliation owns one short transaction per family and cannot sit under
     // the delivery transaction's writer reservation.
@@ -225,11 +215,11 @@ export function runAssignmentCommand(positional, flags, context) {
     for (const flag of operationFlags) {
         const value = flags.get(flag);
         if (value !== undefined)
-            args[flag === "batch" ? "batchId" : flag] = ["after", "limit"].includes(flag) ? typeof value === "string" && /^\d+$/.test(value) ? Number(value) : NaN : value;
+            args[flag === "batch" ? "batchId" : flag] = ["after", "limit"].includes(flag) && typeof value === "string" && /^\d+$/.test(value) ? Number(value) : value;
     }
-    const problem = assignmentArgumentProblem(operation, args);
-    if (problem !== null)
-        return emit(failure("usage", problem));
+    const read = readAssignmentArgs(operation, args);
+    if (!read.ok)
+        return emit(read);
     const credential = coordinatorToken(flags, context.env ?? process.env);
     if ("ok" in credential)
         return emit(credential);

package/dist/build-review.d.ts

@@ -1,6 +1,6 @@
 import type { Store } from "./store.js";
 import type { Runner } from "./builder.js";
-import type { BuildFinding } from "./review-switch.js";
+import { type BuildFinding } from "./contracts/review-findings.js";
 export { buildReviewOf, buildReviewHeadline, buildReviewLines, findingWords, type BuildReviewView } from "./review-switch.js";
 export declare const AUTOMATIC_REVIEWER = "automatic review";
 /**

package/dist/build-review.js

@@ -29,6 +29,7 @@ import { runCheckLevel } from "./check-levels.js";
 import { requestResultChanges } from "./result-actions.js";
 import { revisionSourceOf } from "./result-review.js";
 import { parseBuildFindings, REVIEW_PATCH_NAME } from "./reviewer.js";
+import { FINDINGS_VERSION } from "./contracts/review-findings.js";
 import { heartbeat as runnerHeartbeat } from "./runner.js";
 import { TELEGRAM_TOKEN_ENVS } from "./names.js";
 import { CLAUDE_LIMITS } from "./scope.js";
@@ -90,7 +91,7 @@ function queueLocked(store, repo, runId, root, now) {
 }
 function settle(store, runId, state, fields, now) {
     store.handle.prepare("UPDATE build_review SET state = ?, findings_json = ?, reason = ?, sent_back_as = ?, finished_at = ? WHERE run = ? AND state = 'pending'")
-        .run(state, fields.findings === undefined ? null : JSON.stringify({ version: 1, findings: fields.findings }), fields.reason ?? null, fields.sentBackAs ?? null, now.toISOString(), runId);
+        .run(state, fields.findings === undefined ? null : JSON.stringify({ version: FINDINGS_VERSION, findings: fields.findings }), fields.reason ?? null, fields.sentBackAs ?? null, now.toISOString(), runId);
     store.bumpWake();
 }
 /** Only the first automatic send-back in a task family: its revision's HIGH goes to the person. */

package/dist/chat-acceptance.d.ts

@@ -39,7 +39,7 @@ export declare function readAcceptanceEvidence(store: Store, who: VerifiedApprov
             requirement: string | null;
             state: string;
             details: (string | null)[];
-            requiredEvidence: readonly import("./scope.js").EvidenceKind[];
+            requiredEvidence: readonly ("changed-path" | "check" | "manual-review" | "screenshot")[];
             reviewer: {
                 judgement: import("./proof.js").CriterionJudgementWord;
                 note: string | null;

package/dist/chat-actions.d.ts

@@ -1,5 +1,7 @@
 import { type Store } from "./store.js";
 import { type VerifiedApprover } from "./principal.js";
+import { CHAT_ACTION_FIELDS, type SharedAction } from "./contracts/chat-actions.js";
+export { CHAT_ACTION_FIELDS, type SharedAction };
 export declare const CHAT_ACTIONS: {
     readonly skill_import: {
         readonly label: "Add skill";
@@ -235,20 +237,11 @@ export declare const CHALLENGE_ACTIONS: ReadonlySet<ChatAction>;
 /** Actions about the person themselves, in no project: their card carries no project (repo ""). */
 export declare const OWNER_ACTIONS: ReadonlySet<ChatAction>;
 export declare function isChatAction(value: unknown): value is ChatAction;
-export type SharedAction = {
-    operation: ChatAction;
-    request: Record<string, unknown>;
-    repo: string;
-    title: string;
-    terms: string[];
-    stamp: string;
-    state: Record<string, unknown>;
-};
-export declare const CHAT_ACTION_FIELDS: Record<ChatAction, readonly string[]>;
 /** No writes, including at preview. Store-derived snapshots are never accepted
  * from a model. Rebuilding the same request before execution catches changes. */
 export declare function prepareSharedAction(store: Store, who: VerifiedApprover, operation: ChatAction, input: Record<string, unknown>, root?: string, now?: Date): SharedAction;
-export declare function sharedActionPayload(value: Record<string, unknown>): SharedAction | null;
+/** A saved proposal's action, read by its schema (contracts/chat-actions.ts); null when it can't be read. */
+export declare function sharedActionPayload(value: unknown): SharedAction | null;
 export declare function sharedActionNeedsReview(action: SharedAction): boolean;
 /** Whether a paired phone may confirm this protected action behind its own
  * explicit challenge: the action is on the challenge list, needs no
@@ -256,7 +249,20 @@ export declare function sharedActionNeedsReview(action: SharedAction): boolean;
 export declare function sharedActionAllowsChallenge(action: SharedAction): boolean;
 export declare function sharedActionReviewPath(id: number): string;
 export declare function mintSharedActionReview(store: Store, who: VerifiedApprover, id: number, root: string, now: Date): {
-    payload: SharedAction;
+    payload: {
+        version: 1;
+        operation: "decision_record" | "decision_retire" | "flow_card_add" | "flow_card_approve" | "flow_card_assign" | "flow_card_cancel" | "flow_card_choose" | "flow_card_comment" | "flow_card_move" | "flow_card_send_back" | "flow_card_watch" | "flow_create" | "flow_edit" | "flow_script_save" | "flow_starter" | "flow_trigger_add" | "flow_trigger_pause" | "flow_trigger_remove" | "flow_trigger_resume" | "kit_setup" | "knowledge_instructions" | "knowledge_remove" | "knowledge_restore" | "knowledge_save" | "lead_about_you" | "result_accept" | "scope_approve" | "skill_disable" | "skill_enable" | "skill_import" | "skill_restore" | "skill_test" | "task_cancel" | "task_resume" | "teammate_answer" | "teammate_create" | "teammate_memory" | "teammate_note" | "teammate_routine" | "teammate_soul" | "teammate_state" | "teammate_tools" | "teammate_undo" | "tool_add" | "tool_remove";
+        request: {
+            [x: string]: unknown;
+        };
+        repo: string;
+        title: string;
+        terms: string[];
+        stamp: string;
+        state: {
+            [x: string]: unknown;
+        };
+    };
     nonce: string;
 };
 export type SharedActionOptions = {

package/dist/chat-actions.js

@@ -35,6 +35,8 @@ import { starterFlowOf, starterOf, startersFor, starterTerms, STARTER_FLOWS, swi
 import { answerTeammateQuestion } from "./teammate-work.js";
 import { callWords, checkRule, defaultRule, grantListed, revokeTool, ruleWords, setToolRules } from "./teammate-tools.js";
 import { aboutYouOf, checkAboutYouLine, saveAboutYou, withAboutYouLine } from "./lead-about.js";
+import { CHAT_ACTION_FIELDS, readChatActionRequest, readSharedAction, SHARED_ACTION_VERSION } from "./contracts/chat-actions.js";
+export { CHAT_ACTION_FIELDS };
 /** A tool from the lead's card: a common tool by its id, or the operator's own program or address. */
 function toolSpecFromRequest(input) {
     if (input["catalog"] !== undefined) {
@@ -118,6 +120,9 @@ export const CHAT_ACTIONS = {
     task_cancel: { label: "Cancel task", protected: true, password: false },
     task_resume: { label: "Resume task", protected: true, password: true },
 };
+// Every action has a schema (contracts/chat-actions.ts) and every schema an action: a mismatch fails to compile.
+const SAME_ACTIONS = true;
+void SAME_ACTIONS;
 /** Protected actions a paired phone may confirm behind its own explicit
  * yes/cancel challenge instead of the console's secure screen. Password
  * actions and long or redacted terms never qualify. */
@@ -128,53 +133,6 @@ export function isChatAction(value) {
     return typeof value === "string" && Object.hasOwn(CHAT_ACTIONS, value);
 }
 const hash = (value) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
-export const CHAT_ACTION_FIELDS = {
-    skill_import: ["repo", "content", "files"],
-    skill_enable: ["repo", "version"],
-    skill_disable: ["repo", "version"],
-    skill_restore: ["repo", "restore"],
-    skill_test: ["repo", "version", "sample", "nonce"],
-    knowledge_instructions: ["repo", "instructions"],
-    knowledge_save: ["repo", "title", "content", "id"],
-    knowledge_remove: ["repo", "id"],
-    knowledge_restore: ["repo", "restore"],
-    tool_add: ["repo", "catalog", "name", "command", "args", "url", "secrets", "about"],
-    tool_remove: ["repo", "name"],
-    flow_create: ["repo", "name", "definition", "trigger"],
-    flow_starter: ["repo", "starter"],
-    flow_edit: ["flow", "name", "definition"],
-    flow_card_add: ["flow", "title", "description", "zone"],
-    flow_card_move: ["card", "zone"],
-    flow_card_approve: ["card", "note"],
-    flow_card_send_back: ["card", "note"],
-    flow_card_choose: ["card", "choice", "note"],
-    flow_card_cancel: ["card"],
-    flow_card_comment: ["card", "note"],
-    flow_card_assign: ["card", "owner"],
-    flow_card_watch: ["card", "watching"],
-    flow_script_save: ["repo", "script"],
-    flow_trigger_add: ["flow", "trigger"],
-    flow_trigger_pause: ["trigger"],
-    flow_trigger_resume: ["trigger"],
-    flow_trigger_remove: ["trigger"],
-    teammate_create: ["repo", "template", "name", "soul"],
-    teammate_soul: ["teammate", "soul"],
-    teammate_state: ["teammate", "state"],
-    teammate_note: ["teammate", "note"],
-    teammate_answer: ["question", "choice", "text"],
-    teammate_tools: ["teammate", "tool", "change", "action", "use", "limitField", "limitOver", "undoWith"],
-    teammate_memory: ["teammate", "memory", "change", "text"],
-    teammate_routine: ["teammate", "change", "routine", "schedule", "text"],
-    teammate_undo: ["teammate", "call"],
-    kit_setup: ["repo", "kit"],
-    decision_record: ["repo", "claim", "why", "supersedes", "source"],
-    decision_retire: ["repo", "decision", "reason"],
-    lead_about_you: ["line", "replaces"],
-    scope_approve: ["task"],
-    result_accept: ["task", "run"],
-    task_cancel: ["task"],
-    task_resume: ["task", "run"],
-};
 const nonceHash = (value) => createHash("sha256").update(value).digest("hex");
 function requireActor(store, who, repo, operation) {
     if (!store.schemaCurrent())
@@ -277,9 +235,11 @@ const quoted = (value) => `“${value}”`;
 export function prepareSharedAction(store, who, operation, input, root, now = new Date()) {
     if (!isChatAction(operation))
         throw Error("Choose an available action.");
-    const allowed = CHAT_ACTION_FIELDS[operation];
-    if (Object.keys(input).some((key) => !allowed.includes(key)))
-        throw Error("This action contains an unsupported field.");
+    // The action's own schema: its fields and their kinds, refused by path. The request itself is used as given, so a
+    // confirmation rebuilds the same stamp from the same bytes.
+    const read = readChatActionRequest(operation, input);
+    if (!read.ok)
+        throw Error(`This action can't be read — ${read.issues.map(issue => issue.line).join("; ")}.`);
     if (operation === "lead_about_you") {
         // The owner's own note: the card shows the line, and the line it replaces beside it.
         const checked = checkAboutYouLine(input["line"]);
@@ -300,7 +260,7 @@ export function prepareSharedAction(store, who, operation, input, root, now = ne
         const state = replaces === 0 ? {} : { was: lines[replaces - 1] };
         const title = replaces === 0 ? "Remember about you" : "Update what your lead knows about you";
         const stamp = hash({ operation, request, repo: "", state, terms, actor: who.name, generation: who.generation, ceiling: who.ceilingDigest });
-        return { operation, request, repo: "", title, terms, stamp, state };
+        return { version: SHARED_ACTION_VERSION, operation, request, repo: "", title, terms, stamp, state };
     }
     const task = operation.startsWith("skill_") || operation.startsWith("knowledge_") || operation.startsWith("decision_") || operation.startsWith("tool_") || operation.startsWith("flow_") || operation.startsWith("teammate_") || operation.startsWith("kit_")
         ? null
@@ -965,22 +925,12 @@ export function prepareSharedAction(store, who, operation, input, root, now = ne
         generation: who.generation,
         ceiling: who.ceilingDigest,
     });
-    return { operation, request, repo, title, terms, stamp, state };
+    return { version: SHARED_ACTION_VERSION, operation, request, repo, title, terms, stamp, state };
 }
+/** A saved proposal's action, read by its schema (contracts/chat-actions.ts); null when it can't be read. */
 export function sharedActionPayload(value) {
-    return isChatAction(value["operation"]) &&
-        typeof value["stamp"] === "string" &&
-        typeof value["repo"] === "string" &&
-        typeof value["title"] === "string" &&
-        Array.isArray(value["terms"]) &&
-        value["terms"].every((t) => typeof t === "string") &&
-        value["request"] !== null &&
-        typeof value["request"] === "object" &&
-        !Array.isArray(value["request"]) &&
-        value["state"] !== null &&
-        typeof value["state"] === "object"
-        ? value
-        : null;
+    const read = readSharedAction(value);
+    return read.ok ? read.value : null;
 }
 /** A shortened or redacted preview is not complete consent. This rule lives
  * in the shared door, so a forged transport callback cannot bypass it. */

package/dist/chat-ask.js

@@ -1,4 +1,4 @@
-import { chatHash } from "./chat-delivery-state.js";
+import { chatHash, partContent, savedChatPart } from "./chat-delivery-state.js";
 import { MATE_ASK_OTHER } from "./store.js";
 /** The question as text with its options, where no buttons are drawn. */
 export function chatAskText(ask) {
@@ -10,7 +10,7 @@ export function chatAskButtons(state, part, now) {
     const row = state.prepare("SELECT p.payload,e.channel,b.channel AS own FROM chat_part p JOIN chat_event e ON e.id=p.event JOIN chat_binding b ON b.id=e.binding WHERE p.id=?").get(part);
     if (row === undefined)
         return [];
-    const content = JSON.parse(String(row["payload"]));
+    const content = partContent(String(row["payload"]));
     if ((content.channel ?? row["channel"]) !== row["own"])
         return [];
     const options = content.ask?.options ?? [];
@@ -32,9 +32,9 @@ function repaint(state, part, event, line, now) {
         state.plan(event.id, [{ text: line }], now);
         return;
     }
-    const before = JSON.parse(String(row["payload"]));
+    const before = partContent(String(row["payload"]));
     const content = { text: `${before.text}\n\n${line}`.slice(0, 3400), edit: event.ts, ...(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);
     state.finish(event.id);
 }
 /** A tapped ask button, inside the action's transaction; false when the token isn't one. */
@@ -84,7 +84,7 @@ export function applyChatAskTap(options, event, binding, token, now) {
     state.enqueue({
         id: chatHash(`${state.channel}:ask:${event.id}`).slice(0, 32), installation: event.installation, binding: binding.id, kind: "message",
         channel: event.channel, member: event.member, ts: event.ts, thread: event.thread,
-        payload: JSON.stringify({ text: option, originalLength: option.length }), created: now.toISOString(),
+        payload: { text: option, originalLength: option.length }, created: now.toISOString(),
     });
     repaint(state, part, event, `You chose: ${option}`, now);
     return true;

package/dist/chat-decide.d.ts

@@ -1,9 +1,22 @@
+/** Decisions finish in the chat app. A pushed card about a result, a failed task, a plan waiting for approval or a
+ * pull request ready to merge carries buttons that act in place: Accept and finish, Request changes, Retry,
+ * Approve & start, Merge. Every act that changes something asks twice ("Accept and finish 'X'? [Yes] [Cancel]"),
+ * and each button is one opaque token bound to the exact result, receipt, plan or commit the card showed: a card a
+ * newer result, a finished task or a changed plan has overtaken says so and acts on nothing.
+ *
+ * Approving a plan or merging needs the password, which never goes in chat, so they act in chat only under a
+ * repository's signed mode that carries the chatApprove term, for the signer's own chat; otherwise, and for a plan
+ * that widens permissions, exceeds the mode's budget or touches protected paths, the card keeps its link.
+ *
+ * Channel-agnostic: Telegram renders these today, and Slack, Discord and Teams reach the same acts through the same
+ * tokens (the `channel` column). Every act runs through the door the console uses. */
+import { DECIDE_ACTS } from "./contracts/chat-callback-rows.js";
 import { type ModeTerms } from "./modes.js";
 import { type VerifiedApprover } from "./principal.js";
 import type { Scope } from "./scope.js";
 import type { Store } from "./store.js";
 /** The tokens live in chat_decide_action and the open "What should change?" in chat_decide_prompt (store.ts). */
-export type DecideAct = "accept" | "changes" | "retry" | "approve" | "not-now" | "merge";
+export type DecideAct = (typeof DECIDE_ACTS)[number];
 export type DecideTarget = {
     kind: "result";
     taskId: string;

package/dist/chat-decide.js

@@ -10,6 +10,7 @@
  *
  * Channel-agnostic: Telegram renders these today, and Slack, Discord and Teams reach the same acts through the same
  * tokens (the `channel` column). Every act runs through the door the console uses. */
+import { DECIDE_ACTS, readDecideActionRow } from "./contracts/chat-callback-rows.js";
 import { createHash, randomBytes } from "node:crypto";
 import { acceptAndCompleteAsOperator, assignmentOf, owedAcceptance } from "./assignment.js";
 import { chatControlHref, chatResultHref } from "./chat-controls.js";
@@ -258,11 +259,12 @@ function retryStamp(store, taskId, who) {
 export function offerFingerprint(offer) {
     return sha(JSON.stringify(offer));
 }
-function readAction(row) {
-    return { token: String(row["token"]), channel: String(row["channel"]), binding: Number(row["binding"]), chat: String(row["chat"]),
-        message: row["message"] == null ? null : String(row["message"]), act: String(row["act"]), phase: String(row["phase"]),
-        taskId: String(row["task_id"]), run: row["run"] == null ? null : Number(row["run"]), digest: String(row["digest"]),
-        expiresAt: String(row["expires_at"]), consumedAt: row["consumed_at"] == null ? null : String(row["consumed_at"]) };
+function readAction(raw) {
+    const read = readDecideActionRow(raw);
+    if (!read.ok)
+        return read;
+    const { task_id: taskId, expires_at: expiresAt, consumed_at: consumedAt, created_at: _created, ...row } = read.value;
+    return { ok: true, value: { ...row, taskId, expiresAt, consumedAt } };
 }
 function mint(store, seat, message, spec, taskId, phase, now) {
     const token = `d:${randomBytes(12).toString("hex")}`;
@@ -378,7 +380,11 @@ export function applyDecideTap(store, seat, input) {
     const raw = input.token.startsWith("d:") ? store.handle.prepare("SELECT * FROM chat_decide_action WHERE token = ?").get(input.token) : undefined;
     if (raw === undefined)
         return null;
-    const row = readAction(raw);
+    const read = readAction(raw);
+    // A saved button that can't be read acts on nothing, and says why.
+    if (!read.ok)
+        return { ack: `That button can't be read (${read.issues.map(issue => issue.line).join("; ")}). Nothing was done.`, ignored: true };
+    const row = read.value;
     const { now } = input;
     if (row.channel !== seat.channel || row.binding !== seat.binding || row.chat !== seat.chat || (row.message !== null && row.message !== input.message))
         return { ack: "That button isn't for this chat.", ignored: true };