toolroll 0.9.104 → 0.9.105

package/dist/contracts/coding-handoff.js

@@ -1,10 +1,3 @@
-/**
- * The coding handoff receipt: the immutable terms under which a committed desktop coding session became an ordinary
- * review task (`coding_handoff.payload`, coding-handoff.ts). Its bytes are hashed and sealed, and its id is the hash of
- * its terms, so the keys are listed in the order the receipt has always been written in — `version` after the
- * preview — and a parsed receipt serializes to exactly the bytes it was read from. The saved hash, derived identity,
- * branch and scope seal are checked in plain code: the hash before parsing, the rest after.
- */
 import { z } from "zod";
 import { readVersioned } from "./contract.js";
 import { acceptanceCriterionSchema } from "./plan.js";
@@ -15,7 +8,6 @@ export const codingHandoffReceiptSchema = z.strictObject({
     base: z.string(),
     candidate: z.string(),
     title: z.string(),
-    /** The session's first message, as the person wrote it. */
     originalPrompt: z.string(),
     changedPaths: z.array(z.string()),
     version: z.literal(CODING_HANDOFF_VERSION),
@@ -25,16 +17,13 @@ export const codingHandoffReceiptSchema = z.strictObject({
     goal: z.string(),
     acceptance: z.array(acceptanceCriterionSchema),
     outOfScope: z.string(),
-    /** The first 32 hex of learningSha over every field above, in this order. */
     id: z.string(),
     taskId: z.string(),
     branch: z.string(),
 });
-/** Read a receipt: version 1 as itself, a newer one refused plainly. Receipts have always carried `version`. */
 export function readCodingHandoffReceipt(input) {
     return readVersioned(codingHandoffReceiptSchema, input, {}, { distinguishNull: true });
 }
-/** Read a receipt's saved bytes: JSON first, then the schema. */
 export function parseCodingHandoffReceipt(raw) {
     let body;
     try {

package/dist/contracts/coding-workspace.js

@@ -1,8 +1,3 @@
-/**
- * The workspace record: one desktop coding session as the coding catalog saves it (`coding_session.document`). The
- * session itself is what the console, chat and the coding handoff read; the record is that session with its
- * `version`. Row ownership, generation and recovery state are checked in plain code by the workspace after parsing.
- */
 import { z } from "zod";
 import { readVersioned, versioned } from "./contract.js";
 import { CODING_CONTEXT_VERSION, codingContextSchema } from "./coding-context.js";
@@ -25,19 +20,12 @@ export const codingSessionSchema = z.strictObject({
     error: z.string().nullable(),
     createdAt: z.string(),
     updatedAt: z.string(),
-    /** Set once startup or the last message could not be confirmed; absent on sessions that never needed it. */
     deliveryReviewRequired: z.boolean().optional(),
-    /** The request the session started with, kept so it is never resent. */
     initialRequest: z.strictObject({ requestId: z.string(), prompt: z.string() }).optional(),
-    /** Absent when no managed context was captured. */
     context: codingContextSchema.optional(),
 });
 export const CODING_SESSION_VERSION = 1;
 export const codingSessionRecordSchema = versioned(CODING_SESSION_VERSION, codingSessionSchema.shape);
-/**
- * Unversioned records were read as a cast, including partial fields, nulls and unknown nested keys. Preserve that
- * boundary exactly; only records explicitly written as version 1 are subject to its strict schema.
- */
 export function readCodingSessionRecord(input) {
     if (isRecord(input) && !Object.prototype.hasOwnProperty.call(input, "version"))
         return { ok: true, value: input };
@@ -47,7 +35,6 @@ export function readCodingSessionRecord(input) {
     const { version: _version, ...session } = read.value;
     return { ok: true, value: session };
 }
-/** Read a saved `coding_session.document`, throwing a path-named refusal; the catalog was written by Toolroll alone. */
 export function parseCodingSessionDocument(document) {
     let body;
     try {
@@ -61,7 +48,6 @@ export function parseCodingSessionDocument(document) {
         throw Error(`A saved coding session could not be read: ${read.issues.map(issue => issue.line).join("; ")}`);
     return read.value;
 }
-/** Stamp the current version only if the entire record fits, without dropping any legacy fields. */
 export function codingSessionDocument(session) {
     const record = { version: CODING_SESSION_VERSION, ...session };
     if (isRecord(record.context) && !Object.prototype.hasOwnProperty.call(record.context, "version")) {

package/dist/contracts/console-api.js

@@ -1,33 +1,10 @@
-/**
- * The console's form bodies and JSON API (docs/plans/zod-revamp.md, item 13): one schema for every URL-encoded body a
- * console route reads, and one for each `?format=json` response.
- *
- * A form is read exactly as before. Each field is what `URLSearchParams` holds for it — every value in the order
- * sent, so `get()` is the first and `getAll()` the list — and every field may be left out, because each handler
- * already supplies its own default, trimming, clipping, number conversion and refusal after reading. Unknown fields
- * are ignored (browsers send `csrf`, buttons send their own names, and older pages send fields no longer read). What a
- * handler may read is the schema's field list: `readForm` hands it a view typed by that list, so reading a field the
- * contract doesn't name fails the typecheck instead of drifting. Nothing a person or script sent before is refused
- * now; the CSRF, nonce, digest, password and duplicate-field checks stay in the handlers, in their order.
- *
- * The JSON responses are checked as they are sent (unversioned, unknown keys allowed, their bytes unchanged — an
- * evidence pack carries sealed ledger entries); a response that disagrees is logged and sent anyway.
- *
- * Not here: Telegram's pushed updates (item 11), flow webhooks and public flow forms (item 15).
- */
 import { z } from "zod";
 import { parseContract } from "./contract.js";
-/** One form field: every value sent for it, in order. Text only — a URL-encoded body has nothing else. */
 const formField = z.array(z.string());
-/** A form's contract: a loose object of optional text fields (unknown fields ignored, as the handlers always did). */
 export function formContract(route, fields, more = {}) {
     const schema = z.looseObject(Object.fromEntries(fields.map(field => [field, formField.optional()]))).catchall(formField);
     return { route, fields, prefixes: more.prefixes ?? [], dynamic: more.dynamic ?? false, schema: schema };
 }
-/**
- * A body as its schema sees it: each field name once, in first-sent order, with all its values in sent order. Built
- * with `Object.fromEntries`, so a field named `__proto__` is an ordinary field.
- */
 export function formFields(body) {
     const fields = new Map();
     for (const [name, value] of body) {
@@ -42,10 +19,6 @@ export function formFields(body) {
 const toStderr = (what, issues) => {
     process.stderr.write(`${what}: disagrees with its contract — ${issues.map(one => one.line).join("; ")}\n`);
 };
-/**
- * Read a form through its contract. It never refuses: every value is text and every field optional, so a body that
- * somehow disagrees is reported and read as it was sent (the handler's own checks decide, as before).
- */
 export function readForm(body, contract, report = toStderr) {
     const parsed = parseContract(contract.schema, formFields(body));
     if (!parsed.ok)
@@ -58,20 +31,12 @@ export function readForm(body, contract, report = toStderr) {
         sent: body,
     };
 }
-// ---- every console form ------------------------------------------------------------------------------------------
-//
-// One per route (or per verb, where one route takes several bodies). A family whose sub-routes share one dispatch —
-// `/code/*`, `/flows/*`, the subagent pages, Slack/Teams/Discord — has one contract naming every field its handlers
-// read. Every body also passes through `mutationGuardForm` (the shared CSRF and duplicate check, unchanged) and
-// `ledgerTargetForm` (the project a request is recorded against).
 export const CONSOLE_FORMS = {
-    // Before sign-in.
     signup: formContract("POST /signup", ["code", "name", "password"]),
     login: formContract("POST /login", ["name", "token", "return"]),
     join: formContract("POST /join/<invite>", ["name", "password"]),
     rekey: formContract("POST /login/rekey", ["token", "return"]),
     passwordSet: formContract("POST /password/set", ["csrf", "password", "again", "next", "return", "toolroll-key"]),
-    // Shared by every signed-in POST.
     mutationGuard: formContract("POST (every signed-in form)", ["csrf", "token", "digest", "nonce", "confirm", "toolroll-key"]),
     ledgerTarget: formContract("POST (the action ledger's project)", ["repo"]),
     projectCeiling: formContract("POST (project ceiling)", ["repo"]),
@@ -121,12 +86,8 @@ export const CONSOLE_FORMS = {
     toolsChange: formContract("POST /settings/tools/change", ["repo", "shown", "action", "name", "password", "catalog", "transport", "target", "secrets", "import", "secret", "value"]),
     appearance: formContract("POST /settings/appearance", ["accent", "quiet", "return", "theme"]),
     models: formContract("POST /settings/models/check, /settings/models/watch, /settings/models/update", ["enabled", "tool"]),
-    // The one Models editor (docs/plans/spend-dashboard.md slice 3): every role at a scope in one save, or a previewed
-    // preset or switch; the digest is what the page showed, and the change digest what the preview showed.
     modelsChange: formContract("POST /settings/models/agent, /settings/models/apply", ["password", "scope", "digest", "change", "preset", "switch", "to",
         "plan", "plan-strong", "build-light", "build", "build-strong", "repair", "review", "review-strong"]),
-    // Settings → Models → Suggested (results routing): the project, a suggestion's id or a rule's number, and the step-up
-    // password for accepting, keeping and switching suggestions on.
     modelsRules: formContract("POST /settings/models/accept, /settings/models/keep, /settings/models/suggest-on, /settings/models/turn-off, /settings/models/not-now, /settings/models/suggest-off, /settings/models/try, /settings/models/stop", ["password", "scope", "id", "rule"]),
     knowledgeRefresh: formContract("POST /settings/knowledge/refresh", ["repo"]),
     knowledgeProposal: formContract("POST /settings/knowledge/proposal", ["repo", "decision", "proposal"]),
@@ -147,7 +108,6 @@ export const CONSOLE_FORMS = {
     notifications: formContract("POST /settings/notifications", ["mode", "digest", "screenshots"]),
     notificationsMute: formContract("POST /settings/notifications/mute", ["repo", "pings"]),
     telegramDigest: formContract("POST /settings/telegram-digest", ["every"]),
-    // Check again sits in the provider-key form and the setup card; Refresh models in the setup form.
     pullRequestsCheck: formContract("POST /settings/pull-requests/check", ["repo"]),
     connectionCheck: formContract("POST /settings/connection/check", ["provider", "auth-mode", "value", "return"]),
     modelsRefresh: formContract("POST /control/models-refresh", ["repo", "nonce", "fingerprint", "token", "provider", "model", "command", "seconds", "task"]),
@@ -184,6 +144,7 @@ export const CONSOLE_FORMS = {
     leadAbout: formContract("POST /settings/lead/about", ["about"]),
     leadPromiseCancel: formContract("POST /settings/lead/promise/cancel", ["promise"]),
     leadQuick: formContract("POST /settings/lead/quick", ["enabled"]),
+    advancedView: formContract("POST /settings/advanced", ["advanced"]),
     leadCheck: formContract("POST /lead/check", ["return"]),
     leadOn: formContract("POST /settings/lead/on", ["agent", "return"]),
     welcomeSample: formContract("POST /welcome/sample", []),
@@ -193,7 +154,6 @@ export const CONSOLE_FORMS = {
     leadEnd: formContract("POST /chat/mate/end", ["return"]),
     leadStop: formContract("POST /chat/mate/stop", ["return", "turn"]),
     leadQueuedRemove: formContract("POST /chat/queued/<message>/remove", ["return"]),
-    // Easy-start C1 (N1): what a page load used to write, now a keyed POST from the shell.
     agentSeen: formContract("POST /agents/seen", ["run"]),
     agentWatch: formContract("POST /agents/watch", ["run", "view", "op"]),
     leadProposal: formContract("POST /chat/proposal/<id>/confirm|dismiss", ["return", "nonce", "confirm", "token"]),
@@ -201,7 +161,6 @@ export const CONSOLE_FORMS = {
     chat: formContract("POST /chat", ["task", "project", "result", "mode", "request", "request-session", "message", "token"]),
     chatFile: formContract("POST /chat/file/<id>", ["token"]),
     chatAck: formContract("POST /chat/ack/<id>", ["token", "nonce"]),
-    // A recipe's own answers and editor fields are read by recipes.ts from the whole form (`sent`; item 17).
     recipes: formContract("POST /recipes/prepare, /recipes/preview, /recipes/import, /recipes/launch, /recipes/save", ["repo", "projectRevision", "recipe", "recipeRevision", "document", "purpose", "source", "sourceRevision", "preview", "next"]),
     runNote: formContract("POST /r/<run>/note", ["note"]),
     diffComment: formContract("POST /r/<run>/comment", ["return", "tab", "intent", "batch", "source", "note", "path", "line", "request", "image", "comment"]),
@@ -212,7 +171,6 @@ export const CONSOLE_FORMS = {
     taskArchive: formContract("POST /t/<task>/archive", ["reason", "return"]),
     taskRestore: formContract("POST /t/<task>/restore", ["return"]),
     tasksPutAway: formContract("POST /work/put-away", ["digest", "days", "task", "password"]),
-    // A task's verbs (/t/<task>/<verb>), one body each.
     taskSteer: formContract("POST /t/<task>/steer", ["note", "return", "run", "key", "after", "request"]),
     taskReply: formContract("POST /t/<task>/reply", ["question", "answer"]),
     taskHold: formContract("POST /t/<task>/hold", ["reason"]),
@@ -220,9 +178,7 @@ export const CONSOLE_FORMS = {
     taskRepairDependency: formContract("POST /t/<task>/repair-dependency", ["blocker", "operation", "replacement"]),
     taskNext: formContract("POST /t/<task>/next", ["undo"]),
     taskReopen: formContract("POST /t/<task>/reopen", ["token"]),
-    // Local-owner slice 3: the build and approved plan the page read (`run`, `digest`), read only for the laptop's local owner.
     taskRequeue: formContract("POST /t/<task>/requeue", ["note", "return", "run", "digest"]),
-    // Local-owner slice 2: the planning source the page read (planner-source.ts), read only for the laptop's local owner.
     taskPlan: formContract("POST /t/<task>/plan", ["source"]),
     taskFollowUp: formContract("POST /t/<task>/follow-up", ["index"]),
     taskPlanEdit: formContract("POST /t/<task>/plan-edit", ["saw-plan", "plan-document"]),
@@ -234,12 +190,9 @@ export const CONSOLE_FORMS = {
     taskAcceptProof: formContract("POST /t/<task>/accept-proof", ["run", "note", "return"]),
     taskComplete: formContract("POST /t/<task>/complete", ["receipt", "run", "accept", "note", "publish", "return"]),
     taskStop: formContract("POST /t/<task>/stop", ["run", "return"]),
-    // Pause, or Pause and steer when a note rides along, or Resume (mode=resume): the exact run shown, and the page's own
-    // request id.
     taskPause: formContract("POST /t/<task>/pause", ["run", "request", "note", "mode", "return", "key"]),
     taskResume: formContract("POST /t/<task>/resume|resume-arm", ["run", "token", "nonce", "return"]),
 };
-/** The console POSTs whose handlers read no field (sign-out not even the shared guard): their contract is the empty form. */
 export const BODILESS_POSTS = [
     "POST /settings/models/<unknown action>",
     "POST /r/<run>/draft-repair",
@@ -252,24 +205,20 @@ export const BODILESS_POSTS = [
     "POST /t/<task>/unhold",
     "POST /t/<task>/stop-carrying",
     "POST /t/<task>/retry-review",
-    // Check now and its kin (docs/plans/get-side-effects.md): the form token only, no fields read.
     "POST /settings/updates/check",
     "POST /settings/storage/check",
     "POST /projects/github",
     "POST /code/<session>/ship/preview",
 ];
-// ---- the JSON API ------------------------------------------------------------------------------------------------
 const ledgerEntrySchema = z.looseObject({
     id: z.number(), at: z.string(), actor: z.string(), repo: z.string().nullable(), taskId: z.string().nullable(), runId: z.number().nullable(),
     action: z.string(), outcome: z.string(), source: z.string(), detail: z.string().nullable(),
 });
-/** `GET /ledger?format=json`: the chain's state, a page of entries (newest first) and the cursor for the next. */
 export const ledgerPageSchema = z.looseObject({
     chain: z.looseObject({ ok: z.boolean(), entries: z.number(), through: z.number().nullable(), head: z.string(), problem: z.looseObject({ id: z.number().nullable(), what: z.string() }).nullable() }),
     entries: z.array(ledgerEntrySchema),
     nextBefore: z.number().nullable(),
 });
-/** `GET /t/<task>/evidence?format=json`: a task's evidence pack, as `evidence-pack.ts` builds and digests it. */
 export const evidencePackSchema = z.looseObject({
     format: z.string(),
     generatedAt: z.string(),
@@ -288,7 +237,6 @@ export const evidencePackSchema = z.looseObject({
     }),
     digest: z.string(),
 });
-/** `GET /flows/<id>?format=json`: the flow page's view (the same one the workspace renders). */
 export const flowViewSchema = z.looseObject({
     kind: z.literal("flow"),
     flow: z.looseObject({ id: z.number(), name: z.string(), project: z.string(), revision: z.number(), href: z.string(), owner: z.string() }),
@@ -318,7 +266,6 @@ export const CONSOLE_RESPONSES = {
     evidencePack: { route: "GET /t/<task>/evidence?format=json", schema: evidencePackSchema },
     flowView: { route: "GET /flows/<id>?format=json", schema: flowViewSchema },
 };
-/** Check a JSON response just before it is sent; a disagreement is reported, and the payload is returned unchanged. */
 export function checkResponse(name, payload, report = toStderr) {
     const { route, schema } = CONSOLE_RESPONSES[name];
     const parsed = parseContract(schema, payload);

package/dist/contracts/contract-test.js

@@ -1,15 +1,5 @@
-/**
- * The contract test every schema gets (docs/plans/zod-revamp.md, ground rule 7), framework-neutral so any test file
- * can use it: each check returns the failures it found (empty when the contract holds), and `assertContract` throws
- * them all at once.
- *
- * - The round trip toJSONSchema → fromJSONSchema → toJSONSchema loses no keyword.
- * - Listed valid samples parse, including payloads saved by older versions.
- * - Listed invalid samples are refused, and the refusal names each listed path (`steps[0].routes[0].goesTo: ...`).
- */
 import { z } from "zod";
 import { toModelSchema } from "./contract.js";
-/** Every keyword in a JSON Schema as `pointer keyword=value`, sorted, so two schemas compare keyword by keyword. */
 export function jsonSchemaKeywords(schema, pointer = "") {
     if (Array.isArray(schema))
         return schema.flatMap((item, index) => jsonSchemaKeywords(item, `${pointer}/${index}`)).sort();
@@ -29,14 +19,12 @@ export function jsonSchemaKeywords(schema, pointer = "") {
     }
     return out.sort();
 }
-/** The keywords the JSON Schema round trip drops or changes; empty when it loses nothing. */
 export function roundTripLoss(schema) {
     const before = toModelSchema(schema);
     const after = toModelSchema(z.fromJSONSchema(before));
     const kept = new Set(jsonSchemaKeywords(after));
     return jsonSchemaKeywords(before).filter(keyword => !kept.has(keyword)).map(keyword => `lost in the round trip: ${keyword}`);
 }
-/** Every way the samples disagree with the contract: a valid one refused, an invalid one accepted, a path unnamed. */
 export function replaySamples(spec) {
     const failures = [];
     for (const sample of spec.valid) {
@@ -57,11 +45,9 @@ export function replaySamples(spec) {
     }
     return failures;
 }
-/** Every failure of the contract test, round trip and samples together. */
 export function contractFailures(spec) {
     return [...(spec.schema === undefined ? [] : roundTripLoss(spec.schema)), ...replaySamples(spec)];
 }
-/** Throws every failure at once; returns quietly when the contract holds. */
 export function assertContract(spec) {
     const failures = contractFailures(spec);
     if (failures.length > 0)

package/dist/contracts/contract.js

@@ -1,31 +1,14 @@
-/**
- * The one way Toolroll describes a contract (docs/plans/zod-revamp.md): one Zod schema, and everything else — the
- * TypeScript type, the runtime check, the JSON Schema a model gets, the text limits — derived from it.
- *
- * The helpers here hold the ground rules every contract shares: limits come from TEXT_LIMITS, persisted payloads are
- * versioned, refusals name the path, and a model-facing schema is exactly what its JSON Schema says (no refinements or
- * transforms; those checks run in plain code after parsing, with a named error).
- */
 import { z } from "zod";
 import { limitRule, TEXT_LIMITS } from "../text-limits.js";
 import { isRecord } from "../is-record.js";
-/**
- * A string bounded by its TEXT_LIMITS entry, never a literal. The limit rule rides along as the field's description,
- * so a model reads the bound before it writes. Zod counts UTF-16 code units; for a limit named in bytes this is the
- * schema's necessary bound (a string within N bytes is within N code units), and the byte count itself is checked in
- * plain code after parsing. `shorten: false` is for a contract with no shorten turn (a parked decision): its
- * description states the bound without promising one.
- */
 export function limited(field, limitKey, options = {}) {
     const limit = TEXT_LIMITS[limitKey];
     const unit = limitKey.endsWith("Bytes") ? "bytes" : "characters";
     return z.string().max(limit, { error: `over ${limit.toLocaleString("en-US")} ${unit}` }).describe(limitRule(field, limit, unit, options.shorten ?? true));
 }
-/** A versioned payload envelope: a strict object whose `version` is exactly `version`. */
 export function versioned(version, shape) {
     return z.strictObject({ version: z.literal(version), ...shape });
 }
-/** `["steps", 0, "routes", 0, "goesTo"]` as `steps[0].routes[0].goesTo`. */
 export function pathOf(path) {
     let out = "";
     for (const part of path) {
@@ -43,7 +26,6 @@ function got(input) {
         return "an array";
     return typeof input === "object" ? "an object" : `a ${typeof input}`;
 }
-/** The schema at `path`, including whether that value may be omitted, following arrays, wrappers and unions. */
 function nodeAt(schema, input, path) {
     let node = schema, value = input;
     let optional = false;
@@ -93,7 +75,6 @@ function nodeAt(schema, input, path) {
     }
     return null;
 }
-/** Edit distance, for "did you mean" (short strings only). */
 function distance(a, b) {
     const row = Array.from({ length: b.length + 1 }, (_, index) => index);
     for (let i = 1; i <= a.length; i++) {
@@ -107,7 +88,6 @@ function distance(a, b) {
     }
     return row[b.length];
 }
-/** The allowed key an unknown one most likely meant, or null. */
 function suggestion(key, known, options) {
     if (known === null || known.length === 0)
         return null;
@@ -134,8 +114,6 @@ function issuesOf(issue, where = {}) {
         }
         case "invalid_type": {
             const missing = "input" in issue ? issue.input === undefined : / received undefined$/.test(issue.message);
-            // Keep required-null wording for required fields; an optional field given null has the wrong type, and so does
-            // any null when the caller distinguishes null from missing.
             const optional = where.schema !== undefined && nodeAt(where.schema, where.input, issue.path)?.optional === true;
             if (missing || (!optional && !where.options?.distinguishNull && "input" in issue && issue.input === null && issue.expected !== "null"))
                 return [one("required", "required")];
@@ -159,7 +137,6 @@ function issuesOf(issue, where = {}) {
         case "invalid_value":
             return [one("bad-value", `must be ${issue.values.length === 1 ? JSON.stringify(issue.values[0]) : `one of ${issue.values.map(value => JSON.stringify(value)).join(", ")}`}`)];
         case "invalid_union": {
-            // A discriminated union names its choices (`steps[0].kind: must be one of "inbox", "task", ...`).
             const by = issue.discriminator, options = issue.options;
             if (typeof by === "string" && Array.isArray(options)) {
                 const given = "input" in issue && isRecord(issue.input) ? issue.input[by] : undefined;
@@ -171,28 +148,17 @@ function issuesOf(issue, where = {}) {
             return [one("invalid", "does not match any allowed shape")];
         }
         case "invalid_format":
-            // A pattern's own words say what it wants (`must be a short id: lowercase letters, numbers and dashes`).
             return [one("bad-value", issue.message.startsWith("Invalid") ? `must match ${issue.format === "regex" ? issue.pattern ?? "its pattern" : issue.format}` : issue.message)];
         default:
             return [one("invalid", issue.message)];
     }
 }
-/**
- * A Zod error as path-named issues, in the error's own order. Given the schema and input it came from, an unknown key
- * also says which allowed key it most likely meant (`unknown key 'onFail' (did you mean ifFails?)`).
- */
 export function contractIssues(error, where = {}) {
     return error.issues.flatMap(issue => issuesOf(issue, where));
 }
-/** A Zod error as path-named lines: `steps[0].routes[0].goesTo: required`, `routes[0]: unknown key 'to'`. */
 export function contractError(error, where = {}) {
     return contractIssues(error, where).map(issue => issue.line);
 }
-/**
- * A contract issue as a problem with a reason code built from its path — `missing-goal`, `criteria[0].how-too-long`,
- * `checks-too-many`, `payload-unknown-key`, `bad-version`, `newer-version` — so callers that branch on a reason, and
- * durable outcomes that recorded one, read the same as before the contract.
- */
 export function contractProblemOf(issue) {
     const at = issue.path;
     const reason = (() => {
@@ -215,16 +181,10 @@ export function contractProblemOf(issue) {
     })();
     return { reason, message: issue.line };
 }
-/** Parse with the input reported, so a missing field reads `required` rather than a wrong type. */
 export function parseContract(schema, input, options = {}) {
     const parsed = schema.safeParse(input, { reportInput: true });
     return parsed.success ? { ok: true, value: parsed.data } : { ok: false, issues: contractIssues(parsed.error, { schema, input, options }) };
 }
-/**
- * Read a versioned payload. The current version parses as itself; an older known version (0 for a payload saved
- * before it carried `version`) is upgraded by its adapter and then parsed by the same schema; a newer version is
- * refused plainly; anything else is an unknown version.
- */
 export function readVersioned(schema, input, upgrades = {}, options = {}) {
     const current = schema.shape.version.value;
     if (typeof input !== "object" || input === null || Array.isArray(input)) {
@@ -243,11 +203,8 @@ export function readVersioned(schema, input, upgrades = {}, options = {}) {
     }
     return parseContract(schema, upgrade(body), options);
 }
-/** The Zod node kinds a model-facing schema may use: each says exactly what its JSON Schema says. */
 const MODEL_FACING_TYPES = new Set(["string", "number", "int", "boolean", "null", "literal", "enum", "array", "object", "optional", "nullable", "union", "tuple", "record", "lazy", "readonly", "unknown", "any"]);
-/** Checks that only constrain (never rewrite) and that JSON Schema can state. */
 const MODEL_FACING_CHECKS = new Set(["max_length", "min_length", "length_equals", "greater_than", "less_than", "multiple_of", "number_format", "string_format", "size_equals", "max_size", "min_size"]);
-/** Every node of a schema graph, refusing a refinement, transform, preprocess or unknown node by its schema path. */
 function assertModelFacing(schema, at, seen) {
     if (seen.has(schema))
         return;
@@ -277,7 +234,6 @@ function assertModelFacing(schema, at, seen) {
         case "object":
             for (const [key, value] of Object.entries(def["shape"]))
                 child(value, join(key));
-            // A strict object's catchall is `never` (additionalProperties: false); any other catchall is a schema too.
             if (def["catchall"] !== undefined && def["catchall"]._zod.def.type !== "never")
                 child(def["catchall"], join("*"));
             break;
@@ -306,10 +262,6 @@ function assertModelFacing(schema, at, seen) {
             break;
     }
 }
-/**
- * The JSON Schema a model gets for `schema` (Claude's `--json-schema`). Throws when the schema uses refine,
- * superRefine, transform or preprocess anywhere: what a model is told must be everything the schema checks.
- */
 export function toModelSchema(schema) {
     assertModelFacing(schema, "", new Set());
     const { $schema: _dialect, ...json } = z.toJSONSchema(schema, { target: "draft-2020-12", unrepresentable: "throw" });

package/dist/contracts/decision.js

@@ -1,24 +1,9 @@
-/**
- * A parked decision (§7): one schema for the question an agent puts to a person — its recap, the question, two to six
- * options each saying whether it can be undone, and the option it recommends. Agents hand it back as a file (the park
- * mailbox); `DECISION_MODEL_SCHEMA` is exported for the scout contract migration to wire into structured output.
- * `parseDecision` (decision.ts) reads decisions through `readDecisionPayload`. The options are what the `decision`
- * row keeps. The existing unversioned format ignores unknown fields, including a field named `version`.
- *
- * What JSON Schema cannot say runs after parsing, in decision.ts, each with a path-named error: text is not blank once
- * trimmed, carries no control characters (a label or assignee is one line), option ids are unique, the recommendation
- * names one of them, and a deadline is a timestamp.
- */
 import { z } from "zod";
 import { limited, parseContract, toModelSchema } from "./contract.js";
-/** How many options fit on one screen, and the fewest that make a decision. */
 export const DECISION_OPTIONS_MIN = 2;
 export const DECISION_OPTIONS_MAX = 6;
-/** Option ids travel in URLs, CLI arguments, and CAS updates — they are identifiers, not prose. */
 export const OPTION_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
-/** Decisions have no shorten turn: an over-long field is refused, so the model is not told it will be asked. */
 const NO_SHORTEN = { shorten: false };
-/** One option: its id, a one-line label, what choosing it does, and whether it can be undone (never defaulted). */
 export const decisionOptionSchema = z.object({
     id: limited("option id", "decisionOptionId", NO_SHORTEN).regex(OPTION_ID, { error: "must be letters, digits, - or _, starting with a letter or digit" }),
     label: limited("option label", "decisionLabel", NO_SHORTEN).min(1),
@@ -26,20 +11,15 @@ export const decisionOptionSchema = z.object({
     reversible: z.boolean(),
 });
 export const decisionSchema = z.object({
-    /** Required rather than defaulted: an agent that did not say whether the loop can continue has not composed a decision. */
     urgency: z.literal("blocking"),
     recap: limited("recap", "decisionRecap", NO_SHORTEN).min(1),
     question: limited("question", "decisionQuestion", NO_SHORTEN).min(1),
     options: z.array(decisionOptionSchema).min(DECISION_OPTIONS_MIN).max(DECISION_OPTIONS_MAX),
-    /** An option's id, alone or as "<id>: why". */
     recommendation: limited("recommendation (an option's id, or \"<id>: why\")", "decisionRecommendation", NO_SHORTEN).min(1),
     assignee: limited("assignee", "decisionAssignee", NO_SHORTEN).min(1).nullable().optional(),
-    /** An ISO 8601 timestamp. */
     deadline: z.string().nullable().optional(),
 });
-/** The decision schema for the scout migration's question branch. */
 export const DECISION_MODEL_SCHEMA = toModelSchema(decisionSchema);
-/** Read the existing decision format, ignoring keys it never used. */
 export function readDecisionPayload(input) {
     return parseContract(decisionSchema, input);
 }

package/dist/contracts/diff-stat.js

@@ -1,15 +1,5 @@
-/**
- * The terminal diff-stat (`terminal-diff-stat.json`): one schema for what `parseNumstat` and `budgetedStatJson`
- * write, and the two candidate-inventory reads that use it as a gate's evidence. Toolroll writes it from typed values
- * in its own key order and never rewrites it, so the stored bytes (and every sha256 bound to them) stay as written.
- *
- * Both reads take only the fields their checks use and ignore the rest, exactly as the hand-written checks did: a
- * legacy gate's endpoints, and a saved assessment's file list. Whether those fields match the run is plain code after
- * parsing; anything the schema refuses was refused before too.
- */
 import { z } from "zod";
 import { parseContract } from "./contract.js";
-/** One file's row. null additions/deletions = binary. */
 export const diffStatFileSchema = z.object({
     path: z.string(),
     additions: z.int().nullable(),
@@ -25,21 +15,15 @@ export const diffStatSchema = z.object({
     deletions: z.int(),
     binaryCount: z.int(),
     files: z.array(diffStatFileSchema),
-    /** True when the file list was cut to fit the cap — counts stay complete. */
     filesTruncated: z.boolean(),
 });
-/** What a legacy gate reads of its candidate inventory. `base` may be null, as a run without a base revision has. */
 export const candidateEndpointsSchema = diffStatSchema.pick({ head: true, filesTruncated: true }).extend({ base: z.string().nullable() });
-/** What a saved assessment reads: the inventory's identity and every changed path. */
 export const savedInventorySchema = diffStatSchema
     .pick({ schema: true, head: true, base: true, filesTruncated: true, fileCount: true })
     .extend({ files: z.array(diffStatFileSchema.pick({ path: true })) });
-/** A legacy gate's endpoints, from the inventory's parsed JSON (the gate names unreadable JSON itself). */
 export function readCandidateEndpoints(input) {
     return parseContract(candidateEndpointsSchema, input);
 }
-/** The changed paths of a complete inventory for exactly this candidate, or null: wrong identity, a cut or
- * miscounted list, or a path named twice. */
 export function savedInventoryPaths(text, head, base) {
     let input;
     try {

package/dist/contracts/discord-callback.js

@@ -1,14 +1,7 @@
-/**
- * A Discord button tap (discord-chat.ts `receiveDiscord`): the component interaction Discord sends over the gateway,
- * and the button data Toolroll put on it. The interaction is Discord's, so fields Toolroll doesn't read are ignored;
- * the button's `custom_id` (`so_` and a one-time token) is Toolroll's. A tap from the paired person on Toolroll's own
- * message whose button can't be read is answered with why (`data.custom_id: not a Toolroll button`), and nothing is done.
- */
 import { z } from "zod";
 import { CHAT_BUTTON_TOKEN } from "./chat-content.js";
 import { parseContract } from "./contract.js";
 const user = z.object({ id: z.string() });
-/** The interaction around a tap (type 3: a message component): the app, the person, the channel, the message. */
 export const discordComponentInteractionSchema = z.object({
     type: z.literal(3),
     id: z.string(),
@@ -21,14 +14,12 @@ export const discordComponentInteractionSchema = z.object({
     message: z.object({ id: z.string(), channel_id: z.string(), author: user }),
     data: z.object({ custom_id: z.unknown().optional() }),
 });
-/** Toolroll's button data: `so_` and a one-time token. */
 export const discordButtonSchema = z.object({
     custom_id: z.string().regex(new RegExp(`^so_${CHAT_BUTTON_TOKEN.source.slice(1)}`), { error: "not a Toolroll button" }),
 });
 export function readDiscordComponentInteraction(body) {
     return parseContract(discordComponentInteractionSchema, body);
 }
-/** The tapped button's one-time token. */
 export function readDiscordButtonToken(interaction) {
     const read = parseContract(z.object({ data: discordButtonSchema }), { data: interaction.data });
     return read.ok ? { ok: true, value: read.value.data.custom_id.slice(3) } : read;

package/dist/contracts/flow-card.js

@@ -1,12 +1,3 @@
-/**
- * A flow card's state (docs/plans/zod-revamp.md, item 8): what the flow engine, its steps and its Send to me and
- * Person chooses zones read and write (flow-engine.ts, flow-steps.ts, flow-send.ts), as the store keeps it in
- * `flow_card`. Its columns are versioned by the database's own schema version; the one payload in it, what finished
- * zones handed on (`outputs_json`), carries its own version (stage-output.ts).
- *
- * `flowCardSchema` is the card as read; `flowCardChangeSchema` what one update may change. Where it came from
- * (`source_json`, written by triggers) keeps its own type in the store.
- */
 import { z } from "zod";
 import { cardOutputsSchema } from "./stage-output.js";
 export const FLOW_CARD_STATES = ["active", "done", "cancelled"];
@@ -15,30 +6,21 @@ export const flowCardSchema = z.strictObject({
     flow: z.int().min(1),
     title: z.string(),
     description: z.string().nullable(),
-    /** The zone it is in, and which visit to that zone this is (each move is a fresh one). */
     stage: z.string(),
     entry: z.int().min(1),
     state: z.enum(FLOW_CARD_STATES),
-    /** The task its zone filed this visit, and the card's main build. */
     task: z.string().nullable(),
     primaryTask: z.string().nullable(),
-    /** The latest note it was sent back or replied to with ({{note}}). */
     note: z.string().nullable(),
-    /** What it waits for, in words. */
     waiting: z.string().nullable(),
-    /** What finished zones handed on ({{stage.…}}), and any too long to pass on, whole. */
     outputs: cardOutputsSchema.shape.outputs,
     attached: cardOutputsSchema.shape.attached,
     createdBy: z.string(),
-    /** v126: whether a person or an automation (a delivery, a poll, a schedule, a public form) made it. Decided where it
-     * was made, never read from its label: filing passes it on as the requester's kind. */
     createdKind: z.enum(["person", "automation"]),
     createdAt: z.string(),
     updatedAt: z.string(),
     owner: z.string().nullable(),
 });
-/** What one update of a card may change; whatever is left out stays as it is. Outputs replace the card's whole;
- * an attachment goes with the output it belongs to. */
 export const flowCardChangeSchema = z.strictObject({
     task: flowCardSchema.shape.task.optional(),
     primaryTask: z.string().optional(),

package/dist/contracts/flow-propose.js

@@ -1,8 +1,3 @@
-/**
- * The lead's `propose_flow` input (docs/plans/zod-revamp.md, item 3): one schema, built from the flow contract's own
- * step and trigger schemas, that is both the JSON Schema the lead is given and the check its call is read with
- * (mate-tools.ts). The lead-tools contract (item 5) imports it from here rather than restating it.
- */
 import { z } from "zod";
 import { LIMITS } from "../decision.js";
 import { STARTER_IDS } from "../flow-starters.js";
@@ -16,10 +11,8 @@ const id = z.int().min(1);
 const enumOf = (values) => z.enum(values);
 export const proposeFlowInputSchema = z.strictObject({
     operation: z.enum(PROPOSE_FLOW_OPERATIONS),
-    /** A project as list_repos names it (r1, r2). */
     repo: z.string().regex(/^r[0-9]{1,3}$/, { error: "must be a project from list_repos, like r1" }).optional(),
     flow: id.optional(), card: id.optional(),
-    /** allow_unattended: how long it runs on its own, what it may spend, and the schedules chosen beyond the plain ones. */
     days: z.int().min(1).optional(), budget: z.string().max(20).optional(), runs: z.string().max(20).optional(), include: z.array(id).max(50).optional(),
     kit: enumOf(KITS.map(one => one.id)).optional(),
     starter: z.enum(STARTER_IDS).optional(),
@@ -39,5 +32,4 @@ export const proposeFlowInputSchema = z.strictObject({
     }).optional(),
     settings: leadTriggerSchema.optional(),
 });
-/** What the lead is told propose_flow takes: exactly the schema its call is read with. */
 export const PROPOSE_FLOW_MODEL_SCHEMA = toModelSchema(proposeFlowInputSchema);