toolroll 0.9.103 → 0.9.105

package/dist/contracts/chat-actions.js

@@ -1,29 +1,10 @@
-/**
- * Shared chat actions (chat-actions.ts): one schema for each action's data — what the lead proposes and what a saved
- * proposal carries after `prepareSharedAction` has checked and rewritten it — and one for the saved proposal itself.
- * The allowed fields (`CHAT_ACTION_FIELDS`) and the request types are derived from these; what JSON Schema can't say
- * (credentials and control characters in text, each field's length, a zone or option that exists, who may act) runs
- * in `prepareSharedAction` after parsing, with its own named refusal.
- *
- * A flow drawing, trigger or script inside a request is read by its own contract (flows.ts `validateFlowDefinition`,
- * flow-triggers.ts `validateTriggerConfig`, flow-scripts.ts `validateScript`) when the action is prepared, in every
- * vocabulary those accept; here it is only "a value".
- */
 import { z } from "zod";
 import { parseContract, readVersioned, versioned } from "./contract.js";
-/** An id the store minted: a positive safe integer. */
 const id = z.int().min(1);
 const words = z.string();
-/** A drawing, trigger or script: read by its own contract when the action is prepared. */
 const nested = z.unknown();
 const skillFile = z.strictObject({ path: z.string(), base64: z.string() });
-/** An object whose keys its own reader knows (a script draft, an action's staleness fence). */
 const anyObject = z.object({}).catchall(z.unknown());
-/**
- * Each action's data, field order as the lead reads it in `get_actions`. Fields a branch ignores or reads through
- * its own validator stay unknown: 0.9.36 accepted null and other non-string values there. Preparation still checks
- * the selected branch and saves the same request bytes. No schema defaults or coercion may change its stamp.
- */
 export const chatActionRequestSchemas = {
     skill_import: z.strictObject({ repo: words, content: words.optional(), files: z.array(skillFile).optional() }),
     skill_enable: z.strictObject({ repo: words, version: words }),
@@ -41,7 +22,6 @@ export const chatActionRequestSchemas = {
     tool_remove: z.strictObject({ repo: words, name: words }),
     flow_create: z.strictObject({ repo: words, name: words, definition: nested, trigger: nested.optional() }),
     flow_starter: z.strictObject({ repo: words, starter: words }),
-    // Lead fan-out (docs/plans/lead-fan-out.md): N tasks under one brief, one yes.
     sweep_cancel_rest: z.strictObject({ sweep: id }),
     sweep_file: z.strictObject({ repo: words, title: words, brief: words, items: z.array(z.strictObject({ title: words, item: words })).min(2).max(20),
         acceptance: z.array(z.unknown()).min(1), maxParallel: z.number().int().min(1).max(8) }),
@@ -50,7 +30,6 @@ export const chatActionRequestSchemas = {
     flow_card_move: z.strictObject({ card: id, zone: words }),
     flow_card_approve: z.strictObject({ card: id, note: words.optional() }),
     flow_card_send_back: z.strictObject({ card: id, note: words.optional() }),
-    /** An option by its number (from 1), or a reply that becomes the note. */
     flow_card_choose: z.strictObject({ card: id, choice: z.int().nullable().optional(), note: z.unknown().optional() }),
     flow_card_cancel: z.strictObject({ card: id }),
     flow_card_comment: z.strictObject({ card: id, note: words }),
@@ -61,14 +40,12 @@ export const chatActionRequestSchemas = {
     flow_trigger_pause: z.strictObject({ trigger: id }),
     flow_trigger_resume: z.strictObject({ trigger: id }),
     flow_trigger_remove: z.strictObject({ trigger: id }),
-    /** Browser use in the flow's script zones (flow-browser.ts): allowing it takes the person's own password in the secure screen. */
     flow_browser: z.strictObject({ flow: id }),
     flow_browser_off: z.strictObject({ flow: id }),
     subagent_create: z.strictObject({ repo: words, template: z.unknown().optional(), name: z.unknown().optional(), soul: z.unknown().optional() }),
     subagent_soul: z.strictObject({ subagent: id, soul: words }),
     subagent_state: z.strictObject({ subagent: id, state: z.enum(["active", "paused", "removed"]) }),
     subagent_note: z.strictObject({ subagent: id, note: words }),
-    /** D5: the lead delegates — "ask Rosa to …" — as a card on the subagent's desk. */
     subagent_ask: z.strictObject({ subagent: id, text: words }),
     subagent_answer: z.strictObject({ question: id, choice: z.unknown().optional(), text: z.unknown().optional() }),
     subagent_tools: z.strictObject({
@@ -81,12 +58,9 @@ export const chatActionRequestSchemas = {
     kit_setup: z.strictObject({ repo: words, kit: words }),
     decision_record: z.strictObject({ repo: words, claim: words, why: words, supersedes: id.optional(), source: words.optional() }),
     decision_retire: z.strictObject({ repo: words, decision: id, reason: words }),
-    // Results routing: Not now on a suggested cheaper model (accepting stays in Settings → Models, behind a step-up).
     suggestion_not_now: z.strictObject({ repo: words, suggestion: words }),
-    // Slice 3: stopping a trial (starting one stays in Settings → Models, behind a step-up).
     trial_stop: z.strictObject({ repo: words, trial: id }),
     code_map_switch: z.strictObject({ repo: words, on: z.boolean() }),
-    // Chat and console parity (docs/plans/toolroll-cards.md): each runs the console's own write.
     mode_revoke: z.strictObject({ repo: words }),
     provider_resume: z.strictObject({ provider: words }),
     worker_note: z.strictObject({ runner: words, note: words }),
@@ -96,7 +70,6 @@ export const chatActionRequestSchemas = {
     flow_archive: z.strictObject({ flow: id }),
     flow_unattended_off: z.strictObject({ flow: id }),
     incident_resolve: z.strictObject({ incident: id }),
-    // Follow-through: send a finding to the task that owns the code. Text is checked and cleaned when the card is made.
     finding_send: z.strictObject({ task: words, summary: words.optional(), file: words.optional(), line: z.int().min(1).optional(), pointer: words.optional(), run: id.optional() }),
     finding_resend: z.strictObject({ finding: id }),
     task_reopen: z.strictObject({ task: words }),
@@ -105,29 +78,20 @@ export const chatActionRequestSchemas = {
     flow_unattended: z.strictObject({ flow: id, days: z.int().min(1), budget: words.optional(), runs: words.optional(), include: z.array(id).optional() }),
     memory_decide: z.strictObject({ repo: words, proposal: id, decision: z.enum(["accept", "reject"]) }),
     code_map_holdout_end: z.strictObject({ repo: words }),
-    /** The line, and (from 1) the line it replaces; 0 or none adds it. */
     lead_about_you: z.strictObject({ line: words, replaces: z.int().min(0).optional() }),
     scope_approve: z.strictObject({ task: words }),
     result_accept: z.strictObject({ task: words, run: id }),
     task_cancel: z.strictObject({ task: words }),
     task_resume: z.strictObject({ task: words, run: id }),
-    /** One-step start from chat: the project and the preview the lead's turn loop prepared (never the model's id). */
     task_start: z.strictObject({ repo: words, preview: words }),
 };
 export const CHAT_ACTION_OPERATIONS = Object.keys(chatActionRequestSchemas);
-/** The fields each action takes, from its schema. */
 export const CHAT_ACTION_FIELDS = Object.fromEntries(CHAT_ACTION_OPERATIONS.map(operation => [operation, Object.keys(chatActionRequestSchemas[operation].shape)]));
 const isOperation = (value) => typeof value === "string" && Object.hasOwn(chatActionRequestSchemas, value);
-/** One action's data, refused by path (`card: required`, `payload: unknown key 'cards' (did you mean card?)`). */
 export function readChatActionRequest(operation, input) {
     return parseContract(chatActionRequestSchemas[operation], input);
 }
 export const SHARED_ACTION_VERSION = 1;
-/**
- * A prepared action as a proposal saves it: the action, its checked request, the project, the card's title and
- * terms, the stamp that proves nothing changed before it is confirmed, and the state the stamp was taken over (each
- * action's own staleness fence, read back only by that action).
- */
 export const sharedActionSchema = versioned(SHARED_ACTION_VERSION, {
     operation: z.enum(CHAT_ACTION_OPERATIONS),
     request: anyObject,
@@ -138,10 +102,6 @@ export const sharedActionSchema = versioned(SHARED_ACTION_VERSION, {
     state: anyObject,
 });
 const SHARED_ACTION_FIELDS = Object.keys(sharedActionSchema.shape).filter(field => field !== "version");
-/**
- * A proposal saved before it carried `version` (every one through 0.9.36), as version 1. Its reader took the fields
- * it knew and passed any others through unread, so this keeps exactly the known fields.
- */
 export function upgradeUnversionedSharedAction(body) {
     const out = { version: SHARED_ACTION_VERSION };
     for (const field of SHARED_ACTION_FIELDS)
@@ -154,12 +114,6 @@ const under = (prefix, issues) => issues.map(issue => {
     const path = issue.path === "payload" ? prefix : `${prefix}.${issue.path}`;
     return { ...issue, path, line: `${path}${issue.line.slice(issue.path.length)}` };
 });
-/** Legacy readers checked only the envelope. Confirmation still prepares the request again before acting. */
-/**
- * D5 (schema v117): a subagent action was a "teammate_…" one, naming its "teammate", before. A saved card reads in today's
- * words, so a conversation's history still shows it; its stamp was made over the old words, so confirming it asks for
- * a fresh proposal, as any card drafted before a change does.
- */
 function legacySubagentAction(input) {
     if (input === null || typeof input !== "object" || Array.isArray(input))
         return input;

package/dist/contracts/chat-callback-rows.js

@@ -1,13 +1,6 @@
-/**
- * The saved side of a chat button: the row its one-time token names. A proposal card's buttons in Slack, Discord and
- * Teams (`chat_action`, read with the part and event it rides) and a result's, plan's, failure's or pull request's own
- * buttons (`chat_decide_action`, chat-decide.ts). SQLite's own CHECKs bound them when written; these say what a
- * reader may rely on, so a row that isn't that is refused by column, never read as a guess.
- */
 import { z } from "zod";
 import { parseContract } from "./contract.js";
 const when = z.string();
-/** A proposal card's button (chat-delivery.ts), with the part's message and the event's binding, channel and thread. */
 export const proposalActionRowSchema = z.strictObject({
     token: z.string(),
     part: z.int(),
@@ -25,7 +18,6 @@ export function readProposalActionRow(row) {
 }
 export const DECIDE_ACTS = ["accept", "changes", "retry", "approve", "not-now", "merge"];
 export const DECIDE_PHASES = ["offer", "yes", "cancel"];
-/** A decide button (chat-decide.ts): who and where it was sent, what it does to which task and run, and the stamp it holds. */
 export const decideActionRowSchema = z.strictObject({
     token: z.string().regex(/^d:[a-f0-9]{24}$/),
     channel: z.string(),

package/dist/contracts/chat-card.js

@@ -1,9 +1,3 @@
-/**
- * A Toolroll card as it is kept and shown (docs/plans/toolroll-cards.md): what a card's spec became once Toolroll filled
- * it from its own records. Every value here was written by Toolroll; the one exception is a `text` block, which a person
- * reads as a plain paragraph labelled as the lead's note, never as data. A saved card is read back through this
- * schema before any renderer sees it.
- */
 import { z } from "zod";
 export const CARD_LIMITS = { blocks: 8, columns: 6, rows: 20, points: 12, facts: 10, buttons: 4, actions: 4, cell: 80, label: 40, heading: 80, text: 600, note: 400, notes: 12 };
 const label = z.string().min(1).max(CARD_LIMITS.label);
@@ -15,14 +9,11 @@ const dividerBlock = z.strictObject({ kind: z.literal("divider") });
 const factsBlock = z.strictObject({ kind: z.literal("facts"), heading, items: z.array(z.strictObject({ label, value: cell })).min(1).max(CARD_LIMITS.facts) });
 const tableBlock = z.strictObject({
     kind: z.literal("table"), heading,
-    /** `report`: an agent's own report, shown as such; never a figure of Toolroll's. */
     origin: z.enum(["records", "report"]),
     columns: z.array(z.strictObject({ label, numeric: z.boolean() })).min(1).max(CARD_LIMITS.columns),
     rows: z.array(z.array(cell).max(CARD_LIMITS.columns)).max(CARD_LIMITS.rows),
-    /** Rows the records hold beyond the ones shown. */
     more: z.int().min(0),
 });
-/** Lines of saved words, whole: findings and a handover note. `report` as a table's: not Toolroll's figures. */
 const notesBlock = z.strictObject({ kind: z.literal("notes"), heading, origin: z.enum(["records", "report"]), items: z.array(z.string().min(1).max(CARD_LIMITS.note)).min(1).max(CARD_LIMITS.notes), more: z.int().min(0) });
 const chartBlock = z.strictObject({
     kind: z.literal("chart"), heading, chart: z.enum(CARD_CHART_TYPES),
@@ -31,17 +22,12 @@ const chartBlock = z.strictObject({
 export const chatCardSchema = z.strictObject({
     version: z.literal(1),
     title: heading,
-    /** When Toolroll read the records. */
     asOf: z.string().regex(/^\d{4}-\d{2}-\d{2}T[\d:.]+Z$/),
-    /** The projects the values came from: a card goes only where all of them are reachable. */
     repos: z.array(z.string()).max(200),
     blocks: z.array(z.discriminatedUnion("kind", [textBlock, dividerBlock, factsBlock, tableBlock, notesBlock, chartBlock])).min(1).max(CARD_LIMITS.blocks),
-    /** Fixed destinations in Toolroll: a path made by chat-controls.ts, never a model's address. */
     buttons: z.array(z.strictObject({ label, path: z.string().max(400).regex(/^\/(?![/\\])/) })).max(CARD_LIMITS.buttons),
-    /** Proposals this card leads to: each keeps its own Confirm message directly under the card. */
     actions: z.array(z.strictObject({ proposal: z.int().min(1), label: z.string().min(1).max(CARD_LIMITS.heading) })).max(CARD_LIMITS.actions),
 });
-/** A saved card, or null: it was changed, or a build that wrote it knew another shape. */
 export function readChatCard(value) {
     const read = chatCardSchema.safeParse(value);
     if (!read.success)

package/dist/contracts/chat-content.js

@@ -1,74 +1,39 @@
-/**
- * What every chat app keeps between steps (chat-delivery-state.ts, and Telegram's store methods): one schema for a received event's body
- * (`chat_event.payload`, by the event's kind) and one for a planned message part (`chat_part.payload`), the message a
- * button rides and the content a delivery repaints. Both are saved with `version`; a body or part saved before they
- * carried one reads as it did then (its known fields; a reader then passed any others by unread).
- *
- * An event body lives only until the event is handled (then it is `{}`; a Telegram message keeps its words as its
- * record until its chat is unpaired); a part lives as long as its message.
- */
 import { z } from "zod";
 import { parseContract, readVersioned, versioned } from "./contract.js";
 import { chatCardSchema } from "./chat-card.js";
 const id = z.int().min(1);
 const link = z.strictObject({ label: z.string(), path: z.string() });
-/** A Toolroll button's one-time token, as every chat app carries it: 32 hex, or `d:` and 24 hex for a decide button
- * (chat-decide.ts: a result's, plan's, failure's or pull request's own buttons). */
 export const CHAT_BUTTON_TOKEN = /^(?:[a-f0-9]{32}|d:[a-f0-9]{24})$/;
-/** One planned message part, as delivery reads it. */
 export const chatContentShape = {
     text: z.string(),
-    /** Where the part is sent when not the binding's own DM: a room's channel. */
     channel: z.string().optional(),
     proposal: id.optional(),
     image: z.strictObject({ taskId: z.string(), run: z.int(), artifact: z.int(), sha256: z.string() }).optional(),
-    /** A screenshot sent with a result (result-shots.ts): it follows that result's message part, in its thread when
-     * the app allows; a refused upload becomes one plain line, and one removed by retention goes quietly. */
     shot: z.strictObject({ follows: z.int().nullable() }).optional(),
     task: z.string().optional(),
     run: z.int().optional(),
-    /** A notice its person's watch may hold at the final fence (cockpit §3): set at planning only for a kind a watch
-     * can hold. Absent: never held (a security alert, the digest, anything unmarked). */
     watch: z.literal(true).optional(),
-    /** Every task (and agent) a `watch` part covers, when it covers more than one: it is held only while its person is
-     * watching every one of them. */
     subjects: z.array(z.strictObject({ ref: z.int().nullable(), run: z.int().nullable() })).max(100).optional(),
     edit: z.string().optional(),
     phase: z.literal("armed").optional(),
     link: link.optional(),
-    /** More link buttons after `link`: [Look first] beside [Merge] or [Accept and finish]. */
     also: z.array(link).optional(),
-    /** A flow decision's buttons ride this part (v88): minted when it is planned. */
     flow: z.strictObject({ card: id, entry: z.int(), actions: z.array(z.enum(["approve", "edit", "send-back"])) }).optional(),
-    /** A flow's "Person chooses" buttons ride this part: minted when it is planned. */
     choose: z.strictObject({ card: id, entry: z.int(), options: z.array(z.strictObject({ choice: z.int(), label: z.string() })) }).optional(),
-    /** "Use this as your note?" Yes / No about the person's message `held` (an event id), for one choice's visit. */
     note: z.strictObject({ card: id, entry: z.int(), held: z.string() }).optional(),
-    /** A subagent's question's buttons ride this part (v93): each option, then one to answer in words (choice null). */
     question: z.strictObject({ id, choices: z.array(z.strictObject({ choice: z.string().nullable(), label: z.string() })) }).optional(),
-    /** The lead's question to its owner rides this part: its options, then "Something else". */
     ask: z.strictObject({ turn: id, options: z.array(z.string()) }).optional(),
-    /** The lead's own reply, already shaped (reply-shape.ts): the channel renders its bold anchors and labelled links in its own format. */
     voice: z.literal(true).optional(),
-    /** Telegram: the person's message the first reply part answers. */
     replyTo: z.string().optional(),
-    /** Telegram: the part's buttons exactly as sent, their tokens minted with the part (a resend carries the same ones). */
     keyboard: z.array(z.array(z.looseObject({ text: z.string(), callback_data: z.string() }))).optional(),
-    /** Telegram: a proposal card, still one after its proposal is gone. */
     card: z.literal(true).optional(),
-    /** A result's, plan's, failure's or pull request's own buttons (chat-decide.ts), minted with the part: each an act's
-     * one-time token or a link. They ride the message once it is sent. */
     decide: z.strictObject({ rows: z.array(z.array(z.union([z.strictObject({ label: z.string(), token: z.string().regex(CHAT_BUTTON_TOKEN) }), z.strictObject({ label: z.string(), link })]))) }).optional(),
-    /** A Toolroll card (docs/plans/toolroll-cards.md): `text` stays its plain version, and `link`/`also` its buttons, so
-     * an app that can't show it, or refuses it, still has the whole message. */
     rich: chatCardSchema.optional(),
-    /** The "What should change?" this part asks (chat-decide.ts): a reply to its message is the feedback. */
     prompt: id.optional(),
 };
 export const chatContentSchema = z.strictObject(chatContentShape);
 export const CHAT_PART_VERSION = 1;
 export const savedChatPartSchema = versioned(CHAT_PART_VERSION, chatContentShape);
-/** A saved body or part from before `version`, as version `version`: the fields its schema knows, nothing else. */
 function knownFields(version, fields) {
     return (body) => {
         const out = { version };
@@ -79,7 +44,6 @@ function knownFields(version, fields) {
     };
 }
 const PART_UPGRADES = { 0: knownFields(CHAT_PART_VERSION, Object.keys(chatContentShape)) };
-/** JSON text, then the schema; `payload: not JSON` for bytes that aren't. */
 function fromJson(raw, read) {
     let body;
     try {
@@ -90,7 +54,6 @@ function fromJson(raw, read) {
     }
     return read(body);
 }
-/** A saved part's content (`version` is the saved form's, not the content's). */
 export function readChatPart(raw) {
     const read = fromJson(raw, body => readVersioned(savedChatPartSchema, body, PART_UPGRADES));
     if (!read.ok)
@@ -98,34 +61,20 @@ export function readChatPart(raw) {
     const { version: _version, ...content } = read.value;
     return { ok: true, value: content };
 }
-/** A part as it is saved. */
 export function savedChatPart(content) {
     return JSON.stringify({ version: CHAT_PART_VERSION, ...content });
 }
-// ---- event bodies ------------------------------------------------------------------------------------------------
 export const CHAT_EVENT_VERSION = 1;
-/** `pair <code>`: only the code's hash is kept. */
 export const chatPairBodySchema = versioned(CHAT_EVENT_VERSION, { hash: z.string() });
-/**
- * A message: its words (cut at the lead's limit, `originalLength` saying how long it was), or a plain line to answer
- * with instead (`unsupported`: a file the app can't take). A room's or notice's carrier event has none. `about` is the
- * task its turn is about, once chosen; `lead` is a held message passed to the lead as it was (chat-flow.ts).
- */
 export const chatMessageBodySchema = versioned(CHAT_EVENT_VERSION, {
     text: z.string().optional(),
     originalLength: z.int().min(0).optional(),
     unsupported: z.string().optional(),
     about: z.strictObject({ task: z.string(), run: z.int().nullable() }).optional(),
     lead: z.literal(true).optional(),
-    /** Telegram: the server-authored context its turn carries (the exact task or result a reply bound to). */
     context: z.string().optional(),
-    /** Telegram: the request identity the lead's engine receipts the turn under. */
     request: z.string().optional(),
 });
-/**
- * A button: the one-time token it carried, or, when the app's callback came from the paired person but its data
- * couldn't be read, the path-named line saying why — answered plainly, and nothing is done.
- */
 export const chatTokenBodySchema = versioned(CHAT_EVENT_VERSION, { token: z.string().regex(CHAT_BUTTON_TOKEN, { error: "must be a Toolroll button token" }) });
 export const chatProblemBodySchema = versioned(CHAT_EVENT_VERSION, { problem: z.string().min(1) });
 export const chatActionBodySchema = z.union([chatTokenBodySchema, chatProblemBodySchema]);
@@ -133,21 +82,17 @@ export function savedChatEventBody(body) {
     return JSON.stringify({ version: CHAT_EVENT_VERSION, ...body });
 }
 const upgradeBody = (fields) => ({ 0: knownFields(CHAT_EVENT_VERSION, fields) });
-/** A pair event's body. */
 export function readChatPairBody(raw) {
     return fromJson(raw, body => readVersioned(chatPairBodySchema, body, upgradeBody(["hash"])));
 }
-/** A message event's body. */
 export function readChatMessageBody(raw) {
     return fromJson(raw, body => readVersioned(chatMessageBodySchema, body, upgradeBody(Object.keys(chatMessageBodySchema.shape))));
 }
-/** An action event's body: a token, or the reason its callback couldn't be read. */
 export function readChatActionBody(raw) {
     return fromJson(raw, (body) => typeof body === "object" && body !== null && !Array.isArray(body) && Object.hasOwn(body, "problem")
         ? readVersioned(chatProblemBodySchema, body, upgradeBody(["problem"]))
         : readVersioned(chatTokenBodySchema, body, upgradeBody(["token"])));
 }
-/** Words held for "Use this as your note?" (`chat_flow_note.words`): the held message's own text and length. */
 export const heldWordsSchema = z.strictObject({ text: z.string(), originalLength: z.int().min(0).optional() });
 export function readHeldWords(raw) {
     return fromJson(raw, body => parseContract(heldWordsSchema, body));

package/dist/contracts/chat-tables.js

@@ -1,9 +1,3 @@
-/**
- * The one set of chat tables every chat app shares (v116): Telegram, Slack, Discord and Teams keep their pairings,
- * received events, planned message parts, buttons, rooms and delivery receipts here, each row keyed by `provider`.
- * A row's identity is (provider, id): ids carried over from the per-app tables keep their numbers, and nothing infers
- * the app from an id. A leaf: it imports nothing, so the store creates these tables without loading the chat modules.
- */
 export const CHAT_PROVIDERS = ["telegram", "slack", "discord", "teams"];
 export const isChatProvider = (value) => CHAT_PROVIDERS.includes(value);
 const PROVIDER = `provider TEXT NOT NULL CHECK (provider IN (${CHAT_PROVIDERS.map(one => `'${one}'`).join(",")}))`;
@@ -193,7 +187,6 @@ CREATE TABLE IF NOT EXISTS chat_digest (
  PRIMARY KEY (provider)
 );
 `;
-/** Every shared chat table, parents before children. */
 export const CHAT_TABLES = [
     "chat_binding",
     "chat_pair",

package/dist/contracts/cli.js

@@ -1,13 +1,3 @@
-/**
- * The CLI's machine contract (docs/plans/zod-revamp.md, item 14): one schema for the `--json` envelope, one for each
- * declared command's answer, and one for a row of the declared command guide that `contract --commands` dumps.
- *
- * Answers are what Toolroll writes and consumers are told to ignore keys they don't recognize, so every object here is
- * loose. A command answers with its own success shape or a refusal (`ok: false` with a stable `reason`). The commands
- * named in COMMAND_OUTPUTS describe their top-level fields; every other declared command is held to the envelope with
- * its own `command` name. An answer that disagrees is logged on stderr and written exactly as it was: the check never
- * changes, reorders or refuses the bytes a command writes.
- */
 import { z } from "zod";
 import { ENVELOPE_VERSION, envelopeJson } from "../envelope.js";
 import { parseContract } from "./contract.js";
@@ -18,7 +8,6 @@ const int = z.number().int();
 const list = z.array(z.unknown());
 const nullable = (schema) => schema.nullable();
 const rows = (shape) => z.array(z.looseObject(shape));
-/** Every `--json` answer: `envelopeVersion` first, then `ok` and `command`; a refusal adds `reason` and `message`. */
 export const envelopeSchema = z.looseObject({
     envelopeVersion: z.literal(ENVELOPE_VERSION),
     ok: z.boolean(),
@@ -26,47 +15,26 @@ export const envelopeSchema = z.looseObject({
     reason: str.optional(),
     message: str.optional(),
 });
-/** A command's refusal: its stable reason, usually with a message, and whatever the command adds. */
 function refusal(command) {
     return z.looseObject({ envelopeVersion: z.literal(ENVELOPE_VERSION), ok: z.literal(false), command: z.literal(command), reason: str, message: str.optional() });
 }
-/** A command's answer: its success shape (each `shape` field as written) or its refusal. */
 function answers(command, shape) {
     return z.discriminatedUnion("ok", [z.looseObject({ envelopeVersion: z.literal(ENVELOPE_VERSION), ok: z.literal(true), command: z.literal(command), ...shape }), refusal(command)]);
 }
-// ---- the declared command guide, as `contract --commands` dumps it ----
 export const commandFlagSchema = z.looseObject({ name: str, takesValue: z.boolean(), meaning: str }).readonly();
-/** The remote policy every command row states; see `remote` below. */
 export const REMOTE_POLICIES = ["yes", "no", "step-up"];
 export const commandRowSchema = z.looseObject({
-    /** What you type after `toolroll` (subcommands included). */
     invocation: str,
-    /** The `command` field the envelope answers with, where it differs from the invocation (the no-verb report answers
-     * as "scan"). */
     envelopeCommand: str.optional(),
     synopsis: str,
-    /** Who this act belongs to. "operator" rows are ceremonies or infrastructure: an agent must not invoke them even
-     * when credentials are within reach — the credential IS the person. The operator() helper omits flag detail on
-     * purpose; an explicit row may document flags when its command contract requires them. A schema is never
-     * permission. */
     audience: z.enum(["agent", "operator"]),
     agentMayInvoke: z.boolean(),
-    /** Truthful retry semantics, not a boolean:
-     *  keyed — takes --key; same key returns the first answer.
-     *  identity-idempotent — repeating it converges (same lease, same path, same managed file); no key needed.
-     *  unkeyed — a mutation without replay protection: do not blind-retry.
-     *  none — a read. */
     mutation: z.enum(["keyed", "identity-idempotent", "unkeyed", "none"]),
     positionals: z.array(z.looseObject({ name: str, required: z.boolean(), meaning: str }).readonly()).readonly().optional(),
     flags: z.array(commandFlagSchema).readonly().optional(),
     notableReasons: z.array(str).readonly().optional(),
-    /** Whether a person signed in to a central server with their own API token may run it there (`runOperateAs`):
-     *  yes — runs as that person, within their token's scope and project access.
-     *  no — this machine's own infrastructure, credentials or files; never run for a remote caller.
-     *  step-up — approvals, people and policy: a person's act in the console or chat, never a token's. */
     remote: z.enum(REMOTE_POLICIES),
 }).readonly();
-// ---- the commands that describe their fields ----
 const taskSchema = z.looseObject({ id: str, title: str, state: z.enum(LISTED_TASK_STATES), createdAt: str, updatedAt: str, priority: z.number() });
 const checkSummary = z.looseObject({ status: str, exitCode: nullable(int), suites: z.unknown() });
 const contractOutput = z.union([
@@ -74,7 +42,6 @@ const contractOutput = z.union([
     z.looseObject({ envelopeVersion: z.literal(ENVELOPE_VERSION), ok: z.literal(true), command: z.literal("contract"), schemaVersion: int, notes: z.record(str, str), commands: z.array(commandRowSchema) }),
     refusal("contract"),
 ]);
-/** The installation report (`lead-status.ts` InstallationStatus) and what `status` adds to it. */
 const statusOutput = answers("status", {
     generatedAt: str,
     running: z.looseObject({ count: int, phases: rows({ phase: str, count: int }), tasks: rows({ task: str, run: int, phase: str }) }),
@@ -85,19 +52,14 @@ const statusOutput = answers("status", {
     signIn: rows({ provider: str, reason: str, command: str, since: str }),
     tasks: rows({ task: str, title: str, headline: str, sentence: str }),
     lead: nullable(z.looseObject({ owner: str, doing: str, at: str, task: nullable(str), line: str })),
-    // Home's figures (home-groups.ts), the opening line's counts: each is the count of the Tasks list it names. An
-    // older Toolroll's answer has none.
     figures: z.looseObject({ waitingOnYou: int, running: int, queued: int, done: int }).optional(),
     projects: rows({ repo: str, name: str, running: int, limit: int }),
     update: z.looseObject({ current: str, latest: str, security: z.boolean(), updateCommand: str, url: str }).optional(),
     integrations: z.looseObject({ broken: rows({ key: str, name: str, fix: nullable(str) }) }).optional(),
     updateWaiting: z.looseObject({}).optional(),
     unsentReplies: rows({ since: str, error: nullable(str), retry: str }).optional(),
-    // This computer's console (easy-start D): proven live or not, its address and console process, and whether a
-    // background service runs it — ours, another on this database or the desktop app's, or none. Not for a person limited to some projects.
     laptop: z.looseObject({ running: z.boolean(), url: nullable(str), pid: nullable(int), background: z.enum(["on", "off", "other-service"]) }).optional(),
 });
-/** One integration (`integrations.ts` Integration): never a secret. */
 const integrationRow = z.looseObject({
     key: str,
     group: z.enum(["chat", "code", "mail", "tools", "monitoring", "agents"]),
@@ -150,7 +112,6 @@ const taskShowOutput = answers("task show", {
     proofAccepted: z.boolean(),
     stops: list,
 });
-/** `audit` (remote-audit.ts): one page of remote actions, newest first, and the filters it applied. */
 const auditOutput = answers("audit", {
     filters: z.looseObject({ person: nullable(str), token: nullable(str), source: nullable(z.enum(["api", "mcp"])), since: nullable(str) }),
     actions: rows({
@@ -161,10 +122,6 @@ const auditOutput = answers("audit", {
     nextCursor: nullable(str),
 });
 const flowListed = z.looseObject({ id: int, name: str, repo: str, project: str, zones: z.array(str), triggers: int, cardsWaiting: int, needDecision: int });
-/**
- * The commands whose answers name their fields: the most-used ones (contract, the no-verb scan, status,
- * integrations, task, flows, ready) and the plain lists. Keyed by the envelope's `command`.
- */
 export const COMMAND_OUTPUTS = {
     contract: contractOutput,
     scan: scanOutput,
@@ -177,16 +134,12 @@ export const COMMAND_OUTPUTS = {
     ]),
     "task add": z.union([
         answers("task add", { task: taskSchema, repo: nullable(str) }),
-        // Filed in an external backend: its id there, and the local mirror when one was made.
         answers("task add", { id: str, backend: str, mirror: str.optional() }),
     ]),
     "task list": taskListOutput,
     "task show": taskShowOutput,
-    // The task's pull request checks (store.ts ci_check, v146): each with its state and seconds (null: not started).
-    // `status` is the observation's own answer (the one merges read); the rows are each check's timing.
     "task ship": answers("task ship", { task: str, pullRequest: int, githubRepo: str, head: str, observedAt: str, status: z.enum(["passing", "failing", "running", "none"]),
         checks: rows({ name: str, workflow: nullable(str), state: z.enum(["queued", "running", "passed", "failed", "skipped", "cancelled", "neutral"]), startedAt: nullable(str), completedAt: nullable(str), url: nullable(str), kind: z.enum(["run", "status"]), seconds: nullable(int) }) }),
-    // "Can I merge?" (merge-checklist.ts): the answer, its sentence, and one row per fact, each blocker with its act.
     "task ready": answers("task ready", { taskId: str, activeTaskId: str, run: nullable(int), head: nullable(str), answer: z.enum(["yes", "no", "not-yet", "merged"]), sentence: str,
         rows: rows({ key: z.enum(["plan", "build", "checks", "requirements", "pull-request", "pr-ci", "up-to-date", "conflicts", "comments", "release"]), label: str,
             mark: z.enum(["yes", "no", "waiting", "unknown", "skip"]), say: str, act: nullable(z.looseObject({ kind: z.enum(["run-checks", "retry", "fix"]) })) }) }),
@@ -195,13 +148,11 @@ export const COMMAND_OUTPUTS = {
     "task wait": answers("task wait", { task: str, outcome: str }),
     "flows list": answers("flows list", { flows: z.array(flowListed) }),
     "flows show": answers("flows show", { flow: z.looseObject({ id: int, name: str, repo: str, project: str, readable: z.boolean(), zones: list, triggers: list,
-            // Whether the flow runs on its own, and until when (null: it doesn't).
             unattended: nullable(z.looseObject({ until: str, signedBy: str, budgetMicrousd: nullable(int), dailyRunCap: nullable(int), runsToday: int, covers: z.array(str) })) }) }),
     grants: answers("grants", { count: int, grants: list }),
     "runner list": answers("runner list", { count: int, runners: list }),
     "incident list": answers("incident list", { incidents: list }),
     "outbox list": answers("outbox list", { notifications: rows({ id: int, kind: str, subject: str, createdAt: str }) }),
-    // A pass with failed deliveries answers ok: false with its counts and no reason.
     "outbox deliver": z.union([
         z.looseObject({ envelopeVersion: z.literal(ENVELOPE_VERSION), ok: z.boolean(), command: z.literal("outbox deliver"), delivered: int, failed: int }),
         refusal("outbox deliver"),
@@ -213,7 +164,6 @@ export const COMMAND_OUTPUTS = {
     reap: answers("reap", { count: int, released: list }),
     audit: auditOutput,
     "skills list": answers("skills list", { guides: rows({ name: str, title: str, oneLiner: str }) }),
-    // The welcome's three steps (first-run.ts welcomeModel), the same model the console's /welcome shows.
     welcome: answers("welcome", {
         agent: z.looseObject({ done: z.boolean(), checking: z.boolean(), agents: rows({ id: str, name: str, state: str, command: nullable(str), inUse: z.boolean(), canUse: z.boolean() }), inUse: nullable(str), buildsWith: nullable(str) }),
         project: z.looseObject({ done: z.boolean(), projects: rows({ name: str, path: str }), sample: nullable(str), notTakingWork: z.boolean() }),
@@ -221,11 +171,9 @@ export const COMMAND_OUTPUTS = {
         next: nullable(z.enum(["agent", "project", "task"])),
         left: int,
     }),
-    // The first password set: whose, and the account generation every older session was bound to before it.
     "password set": answers("password set", { account: str, generation: int }),
 };
 const declared = new Map(Object.entries(COMMAND_OUTPUTS));
-/** The schema for `command`'s answer: its own when it names its fields, else the envelope under its own name. */
 export function commandOutputSchema(command) {
     let schema = declared.get(command);
     if (schema === undefined) {
@@ -234,11 +182,9 @@ export function commandOutputSchema(command) {
     }
     return schema;
 }
-/** Pair each guide row, in order, with the schema of the answer it names (the envelope command, else the invocation). */
 export function commandEntries(guide) {
     return guide.map(row => ({ guide: row, output: commandOutputSchema(row.envelopeCommand ?? row.invocation) }));
 }
-/** Path-named lines for each way `envelope` (as written, version first) disagrees with its command's schema; empty when it agrees. */
 export function envelopeProblems(envelope) {
     const top = parseContract(envelopeSchema, envelope);
     if (!top.ok)
@@ -246,10 +192,6 @@ export function envelopeProblems(envelope) {
     const read = parseContract(commandOutputSchema(top.value.command), envelope);
     return read.ok ? [] : read.issues.map(one => one.line);
 }
-/**
- * Serialize one envelope with the unchanged `envelopeJson`, after checking the value it writes. A disagreement is
- * logged on stderr and the envelope is written as it was; nothing here throws into a command's path.
- */
 export function checkedEnvelopeJson(payload) {
     try {
         const problems = envelopeProblems({ envelopeVersion: ENVELOPE_VERSION, ...payload });
@@ -257,7 +199,6 @@ export function checkedEnvelopeJson(payload) {
             process.stderr.write(`toolroll ${String(payload.command)} --json: its answer disagrees with its schema — ${problems.join("; ")}\n`);
     }
     catch {
-        // A check that breaks never reaches the command's envelope path.
     }
     return envelopeJson(payload);
 }

package/dist/contracts/coding-activity.js

@@ -1,13 +1,3 @@
-/**
- * What the coding workspace saves beside each session (docs/plans/zod-revamp.md, item 19): its activity items
- * (`coding_item.payload`), approval requests (`coding_request.payload` and `rpc_id`) and the native custody witness
- * (`coding_custody.payload`). The session record itself is src/contracts/coding-workspace.ts.
- *
- * These rows carry no `version` and are written byte for byte as before. They were read as casts, so the readers stay
- * tolerant: a row that is not JSON fails as it always did, and a row that does not match its schema is read as saved
- * and logged, never refused. The custody witness is only a recovery proof: one without the shape its checks read
- * proves nothing, as before.
- */
 import { z } from "zod";
 import { contractError } from "./contract.js";
 export const codingItemSchema = z.object({
@@ -15,7 +5,6 @@ export const codingItemSchema = z.object({
     type: z.string(),
     text: z.string(),
     status: z.string().nullable(),
-    /** The browser's submission key, on a user message it sent. */
     clientId: z.string().exactOptional(),
 });
 export const codingQuestionSchema = z.object({
@@ -32,9 +21,7 @@ export const codingRequestSchema = z.object({
     detail: z.string(),
     questions: z.array(codingQuestionSchema),
 });
-/** The native JSON-RPC id a request is answered with. */
 export const codingRpcIdSchema = z.union([z.string(), z.number()]);
-/** The fields recovery reads from a custody witness before it may count as proof that the prior agent is gone. */
 export const codingCustodyWitnessSchema = z.object({
     host: z.string(),
     descendants: z.array(z.unknown()),
@@ -45,13 +32,11 @@ function tolerant(schema, what, payload) {
     const read = schema.safeParse(value);
     if (!read.success)
         console.warn(`A saved ${what} does not match its contract and is read as saved: ${contractError(read.error, { schema, input: value }).join("; ")}`);
-    // The saved value itself: a row written again keeps its bytes.
     return value;
 }
 export const readCodingItem = (payload) => tolerant(codingItemSchema, "coding item", payload);
 export const readCodingRequest = (payload) => tolerant(codingRequestSchema, "coding request", payload);
 export const readCodingRpcId = (saved) => tolerant(codingRpcIdSchema, "coding request id", saved);
-/** The saved witness when it has the shape recovery checks, else null (it proves nothing). Not JSON throws. */
 export function readCodingCustodyWitness(payload) {
     const value = JSON.parse(payload);
     return codingCustodyWitnessSchema.safeParse(value).success ? value : null;

package/dist/contracts/coding-context.js

@@ -1,12 +1,3 @@
-/**
- * The managed context a desktop coding session captures once (`prepareCodingContext` in coding-context.ts): the
- * frozen text the agent is given, what it was selected from, and the digest that ties the two together. It is saved
- * inside the session's workspace record and checked again (`verifyCodingContext`) before every resume.
- *
- * `metadata` keeps its own `version: 1` because it is part of the digest; its keys are listed in the order the digest
- * was taken in, so a parsed capture digests exactly as it was saved. Repository identity, digest and the materialized
- * skill files are checked in plain code after parsing.
- */
 import { z } from "zod";
 import { readVersioned, versioned } from "./contract.js";
 export const codingContextMetadataSchema = z.strictObject({
@@ -37,14 +28,9 @@ export const CODING_CONTEXT_VERSION = 1;
 export const codingContextSchema = versioned(CODING_CONTEXT_VERSION, {
     text: z.string(),
     metadata: codingContextMetadataSchema,
-    /** learningSha of `{ text, metadata }`. */
     sha256: z.string(),
 });
 const CONTEXT_FIELDS = ["text", "metadata", "sha256"];
-/**
- * A capture saved before the envelope carried `version` (every session through 0.9.36), as version 1. Readers then
- * read only these three fields; the metadata is kept exactly as saved, since its bytes are what the digest covers.
- */
 export function upgradeUnversionedContext(body) {
     const out = { version: CODING_CONTEXT_VERSION };
     for (const field of CONTEXT_FIELDS) {
@@ -54,7 +40,6 @@ export function upgradeUnversionedContext(body) {
     return out;
 }
 export const CODING_CONTEXT_UPGRADES = { 0: upgradeUnversionedContext };
-/** Read a saved capture: version 1 as itself, an unversioned one upgraded, a newer one refused plainly. */
 export function readCodingContext(input) {
     return readVersioned(codingContextSchema, input, CODING_CONTEXT_UPGRADES, { distinguishNull: true });
 }