toolroll 0.9.36 → 0.9.37

package/dist/contracts/coding-context.js

@@ -0,0 +1,60 @@
+/**
+ * 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({
+    version: z.literal(1),
+    repo: z.string(),
+    identity: z.string(),
+    baseRevision: z.string(),
+    knowledge: z.strictObject({
+        revision: z.int(),
+        selectionSha256: z.string(),
+        references: z.array(z.strictObject({
+            id: z.string(),
+            title: z.string(),
+            path: z.string().nullable(),
+            sourceSha: z.string().nullable(),
+            sourceRevision: z.string().nullable(),
+        })),
+        omitted: z.array(z.strictObject({ title: z.string(), reason: z.string() })),
+    }),
+    skills: z.strictObject({
+        revision: z.int(),
+        packages: z.array(z.strictObject({ name: z.string(), sha256: z.string(), skillFile: z.string() })),
+    }),
+    directory: z.string().nullable(),
+    files: z.array(z.strictObject({ path: z.string(), sha256: z.string() })),
+});
+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) {
+        if (Object.prototype.hasOwnProperty.call(body, field) && body[field] !== undefined)
+            out[field] = body[field];
+    }
+    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 });
+}

package/dist/contracts/coding-handoff.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 { type ContractResult } from "./contract.js";
+export declare const CODING_HANDOFF_VERSION = 1;
+export declare const codingHandoffReceiptSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    repo: z.ZodString;
+    base: z.ZodString;
+    candidate: z.ZodString;
+    title: z.ZodString;
+    originalPrompt: z.ZodString;
+    changedPaths: z.ZodArray<z.ZodString>;
+    version: z.ZodLiteral<1>;
+    identity: z.ZodString;
+    actor: z.ZodString;
+    generation: z.ZodInt;
+    goal: z.ZodString;
+    acceptance: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        statement: z.ZodString;
+        how: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        evidence: z.ZodArray<z.ZodEnum<{
+            "changed-path": "changed-path";
+            check: "check";
+            "manual-review": "manual-review";
+            screenshot: "screenshot";
+        }>>;
+    }, z.core.$strict>>;
+    outOfScope: z.ZodString;
+    id: z.ZodString;
+    taskId: z.ZodString;
+    branch: z.ZodString;
+}, z.core.$strict>;
+export type CodingHandoffReceipt = z.infer<typeof codingHandoffReceiptSchema>;
+/** Read a receipt: version 1 as itself, a newer one refused plainly. Receipts have always carried `version`. */
+export declare function readCodingHandoffReceipt(input: unknown): ContractResult<CodingHandoffReceipt>;
+/** Read a receipt's saved bytes: JSON first, then the schema. */
+export declare function parseCodingHandoffReceipt(raw: string): ContractResult<CodingHandoffReceipt>;

package/dist/contracts/coding-handoff.js

@@ -0,0 +1,47 @@
+/**
+ * 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";
+export const CODING_HANDOFF_VERSION = 1;
+export const codingHandoffReceiptSchema = z.strictObject({
+    sessionId: z.string(),
+    repo: z.string(),
+    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),
+    identity: z.string(),
+    actor: z.string(),
+    generation: z.int(),
+    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 {
+        body = JSON.parse(raw);
+    }
+    catch {
+        return { ok: false, issues: [{ path: "payload", kind: "invalid", line: "payload: not JSON" }] };
+    }
+    return readCodingHandoffReceipt(body);
+}

package/dist/contracts/coding-workspace.d.ts

@@ -0,0 +1,165 @@
+/**
+ * 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 { type ContractResult } from "./contract.js";
+export declare const CODING_STATUSES: readonly ["starting", "ready", "working", "needs-input", "stopping", "interrupted", "failed", "uncertain", "closed"];
+export declare const codingSessionSchema: z.ZodObject<{
+    id: z.ZodString;
+    owner: z.ZodString;
+    generation: z.ZodInt;
+    repo: z.ZodString;
+    title: z.ZodString;
+    provider: z.ZodLiteral<"codex">;
+    model: z.ZodNullable<z.ZodString>;
+    branch: z.ZodString;
+    base: z.ZodString;
+    worktree: z.ZodString;
+    nativeThreadId: z.ZodNullable<z.ZodString>;
+    turnId: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+        closed: "closed";
+        failed: "failed";
+        interrupted: "interrupted";
+        "needs-input": "needs-input";
+        ready: "ready";
+        starting: "starting";
+        stopping: "stopping";
+        uncertain: "uncertain";
+        working: "working";
+    }>;
+    error: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    deliveryReviewRequired: z.ZodOptional<z.ZodBoolean>;
+    initialRequest: z.ZodOptional<z.ZodObject<{
+        requestId: z.ZodString;
+        prompt: z.ZodString;
+    }, z.core.$strict>>;
+    context: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        text: z.ZodString;
+        metadata: z.ZodObject<{
+            version: z.ZodLiteral<1>;
+            repo: z.ZodString;
+            identity: z.ZodString;
+            baseRevision: z.ZodString;
+            knowledge: z.ZodObject<{
+                revision: z.ZodInt;
+                selectionSha256: z.ZodString;
+                references: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    title: z.ZodString;
+                    path: z.ZodNullable<z.ZodString>;
+                    sourceSha: z.ZodNullable<z.ZodString>;
+                    sourceRevision: z.ZodNullable<z.ZodString>;
+                }, z.core.$strict>>;
+                omitted: z.ZodArray<z.ZodObject<{
+                    title: z.ZodString;
+                    reason: z.ZodString;
+                }, z.core.$strict>>;
+            }, z.core.$strict>;
+            skills: z.ZodObject<{
+                revision: z.ZodInt;
+                packages: z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    sha256: z.ZodString;
+                    skillFile: z.ZodString;
+                }, z.core.$strict>>;
+            }, z.core.$strict>;
+            directory: z.ZodNullable<z.ZodString>;
+            files: z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                sha256: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        sha256: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const CODING_SESSION_VERSION = 1;
+export declare const codingSessionRecordSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    id: z.ZodString;
+    owner: z.ZodString;
+    generation: z.ZodInt;
+    repo: z.ZodString;
+    title: z.ZodString;
+    provider: z.ZodLiteral<"codex">;
+    model: z.ZodNullable<z.ZodString>;
+    branch: z.ZodString;
+    base: z.ZodString;
+    worktree: z.ZodString;
+    nativeThreadId: z.ZodNullable<z.ZodString>;
+    turnId: z.ZodNullable<z.ZodString>;
+    status: z.ZodEnum<{
+        closed: "closed";
+        failed: "failed";
+        interrupted: "interrupted";
+        "needs-input": "needs-input";
+        ready: "ready";
+        starting: "starting";
+        stopping: "stopping";
+        uncertain: "uncertain";
+        working: "working";
+    }>;
+    error: z.ZodNullable<z.ZodString>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    deliveryReviewRequired: z.ZodOptional<z.ZodBoolean>;
+    initialRequest: z.ZodOptional<z.ZodObject<{
+        requestId: z.ZodString;
+        prompt: z.ZodString;
+    }, z.core.$strict>>;
+    context: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        text: z.ZodString;
+        metadata: z.ZodObject<{
+            version: z.ZodLiteral<1>;
+            repo: z.ZodString;
+            identity: z.ZodString;
+            baseRevision: z.ZodString;
+            knowledge: z.ZodObject<{
+                revision: z.ZodInt;
+                selectionSha256: z.ZodString;
+                references: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    title: z.ZodString;
+                    path: z.ZodNullable<z.ZodString>;
+                    sourceSha: z.ZodNullable<z.ZodString>;
+                    sourceRevision: z.ZodNullable<z.ZodString>;
+                }, z.core.$strict>>;
+                omitted: z.ZodArray<z.ZodObject<{
+                    title: z.ZodString;
+                    reason: z.ZodString;
+                }, z.core.$strict>>;
+            }, z.core.$strict>;
+            skills: z.ZodObject<{
+                revision: z.ZodInt;
+                packages: z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    sha256: z.ZodString;
+                    skillFile: z.ZodString;
+                }, z.core.$strict>>;
+            }, z.core.$strict>;
+            directory: z.ZodNullable<z.ZodString>;
+            files: z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                sha256: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>;
+        sha256: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CodingStatus = z.infer<typeof codingSessionSchema>["status"];
+export type CodingSession = z.infer<typeof codingSessionSchema>;
+/**
+ * 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 declare function readCodingSessionRecord(input: unknown): ContractResult<CodingSession>;
+/** Read a saved `coding_session.document`, throwing a path-named refusal; the catalog was written by Toolroll alone. */
+export declare function parseCodingSessionDocument(document: string): CodingSession;
+/** Stamp the current version only if the entire record fits, without dropping any legacy fields. */
+export declare function codingSessionDocument(session: CodingSession): string;

package/dist/contracts/coding-workspace.js

@@ -0,0 +1,71 @@
+/**
+ * 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";
+export const CODING_STATUSES = ["starting", "ready", "working", "needs-input", "stopping", "interrupted", "failed", "uncertain", "closed"];
+export const codingSessionSchema = z.strictObject({
+    id: z.string(),
+    owner: z.string(),
+    generation: z.int(),
+    repo: z.string(),
+    title: z.string(),
+    provider: z.literal("codex"),
+    model: z.string().nullable(),
+    branch: z.string(),
+    base: z.string(),
+    worktree: z.string(),
+    nativeThreadId: z.string().nullable(),
+    turnId: z.string().nullable(),
+    status: z.enum(CODING_STATUSES),
+    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);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * 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 };
+    const read = readVersioned(codingSessionRecordSchema, input, {}, { distinguishNull: true });
+    if (!read.ok)
+        return read;
+    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 {
+        body = JSON.parse(document);
+    }
+    catch {
+        throw Error("A saved coding session could not be read: payload: not JSON");
+    }
+    const read = readCodingSessionRecord(body);
+    if (!read.ok)
+        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")) {
+        record.context = { ...record.context, version: CODING_CONTEXT_VERSION };
+    }
+    return JSON.stringify(codingSessionRecordSchema.safeParse(record).success ? record : session);
+}

package/dist/contracts/contract.d.ts

@@ -12,9 +12,12 @@ import { type TextLimitKey } from "../text-limits.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.
+ * 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 declare function limited(field: string, limitKey: TextLimitKey): z.ZodString;
+export declare function limited(field: string, limitKey: TextLimitKey, options?: {
+    shorten?: boolean;
+}): z.ZodString;
 /** A versioned payload envelope: a strict object whose `version` is exactly `version`. */
 export declare function versioned<V extends number, S extends z.ZodRawShape>(version: V, shape: S): z.ZodObject<{
     version: z.ZodLiteral<V>;
@@ -36,6 +39,8 @@ export declare function pathOf(path: readonly PropertyKey[]): string;
  */
 export type ContractOptions = {
     aliases?: Readonly<Record<string, readonly string[]>>;
+    /** Report explicit null as a wrong value; omitted keeps the historical wording for existing contracts. */
+    distinguishNull?: boolean;
 };
 type Where = {
     schema?: z.ZodType;

package/dist/contracts/contract.js

@@ -12,12 +12,13 @@ import { limitRule, TEXT_LIMITS } from "../text-limits.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.
+ * 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) {
+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));
+    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) {
@@ -42,12 +43,15 @@ function got(input) {
     return typeof input === "object" ? "an object" : `a ${typeof input}`;
 }
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-/** The keys an object schema allows at `path` in `input`, following arrays, wrappers and (by its discriminator) a union. */
-function keysAt(schema, input, path) {
+/** 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;
     for (let at = 0; node !== undefined;) {
         const def = node._zod.def;
         if (def.type === "optional" || def.type === "nullable" || def.type === "readonly") {
+            if (def.type === "optional")
+                optional = true;
             node = def["innerType"];
             continue;
         }
@@ -71,8 +75,9 @@ function keysAt(schema, input, path) {
             continue;
         }
         if (at === path.length)
-            return def.type === "object" ? Object.keys(def["shape"]) : null;
+            return { def, optional };
         const part = path[at++];
+        optional = false;
         if (def.type === "array" && typeof part === "number") {
             node = def["element"];
             value = Array.isArray(value) ? value[part] : undefined;
@@ -120,7 +125,8 @@ function issuesOf(issue, where = {}) {
     const one = (kind, what) => ({ path: at, kind, line: `${at}: ${what}` });
     switch (issue.code) {
         case "unrecognized_keys": {
-            const known = where.schema === undefined ? null : keysAt(where.schema, where.input, issue.path);
+            const def = where.schema === undefined ? undefined : nodeAt(where.schema, where.input, issue.path)?.def;
+            const known = def?.type === "object" ? Object.keys(def["shape"]) : null;
             return issue.keys.map(key => {
                 const meant = suggestion(key, known, where.options ?? {});
                 return { path: at, kind: "unknown-key", line: `${at}: unknown key '${key}'${meant === null ? "" : ` (did you mean ${meant}?)`}` };
@@ -128,10 +134,12 @@ function issuesOf(issue, where = {}) {
         }
         case "invalid_type": {
             const missing = "input" in issue ? issue.input === undefined : / received undefined$/.test(issue.message);
-            // A null where a value belongs is a value left out.
-            if (missing || ("input" in issue && issue.input === null && issue.expected !== "null"))
+            // 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")];
-            const expected = issue.expected === "array" ? "an array" : issue.expected === "object" ? "an object" : issue.expected === "null" ? "null" : `a ${issue.expected}`;
+            const expected = issue.expected === "array" ? "an array" : issue.expected === "object" ? "an object" : issue.expected === "int" ? "an integer" : issue.expected === "null" ? "null" : `a ${issue.expected}`;
             return [one("wrong-type", `must be ${expected}${"input" in issue ? ` (got ${got(issue.input)})` : ""}`)];
         }
         case "too_big":
@@ -156,8 +164,9 @@ function issuesOf(issue, where = {}) {
             if (typeof by === "string" && Array.isArray(options)) {
                 const given = "input" in issue && isRecord(issue.input) ? issue.input[by] : undefined;
                 const path = at === "payload" || issue.path.at(-1) === by ? at : `${at}.${by}`;
-                const line = given === undefined || given === null ? "required" : `must be one of ${options.map(value => JSON.stringify(value)).join(", ")}`;
-                return [{ path, kind: given === undefined || given === null ? "required" : "bad-value", line: `${path}: ${line}` }];
+                const missing = given === undefined || (given === null && !where.options?.distinguishNull);
+                const line = missing ? "required" : `must be one of ${options.map(value => JSON.stringify(value)).join(", ")}`;
+                return [{ path, kind: missing ? "required" : "bad-value", line: `${path}: ${line}` }];
             }
             return [one("invalid", "does not match any allowed shape")];
         }

package/dist/contracts/decision.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 { type ContractResult } from "./contract.js";
+/** How many options fit on one screen, and the fewest that make a decision. */
+export declare const DECISION_OPTIONS_MIN = 2;
+export declare const DECISION_OPTIONS_MAX = 6;
+/** Option ids travel in URLs, CLI arguments, and CAS updates — they are identifiers, not prose. */
+export declare const OPTION_ID: RegExp;
+/** One option: its id, a one-line label, what choosing it does, and whether it can be undone (never defaulted). */
+export declare const decisionOptionSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodString;
+    consequence: z.ZodString;
+    reversible: z.ZodBoolean;
+}, z.core.$strip>;
+export type DecisionOption = z.infer<typeof decisionOptionSchema>;
+export declare const decisionSchema: z.ZodObject<{
+    urgency: z.ZodLiteral<"blocking">;
+    recap: z.ZodString;
+    question: z.ZodString;
+    options: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        consequence: z.ZodString;
+        reversible: z.ZodBoolean;
+    }, z.core.$strip>>;
+    recommendation: z.ZodString;
+    assignee: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    deadline: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+export type DecisionPayload = z.infer<typeof decisionSchema>;
+/** The decision schema for the scout migration's question branch. */
+export declare const DECISION_MODEL_SCHEMA: Readonly<Record<string, unknown>>;
+/** Read the existing decision format, ignoring keys it never used. */
+export declare function readDecisionPayload(input: unknown): ContractResult<DecisionPayload>;

package/dist/contracts/decision.js

@@ -0,0 +1,45 @@
+/**
+ * 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),
+    consequence: limited("option consequence", "decisionConsequence", NO_SHORTEN).min(1),
+    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/discord-callback.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 { type ContractResult } from "./contract.js";
+/** The interaction around a tap (type 3: a message component): the app, the person, the channel, the message. */
+export declare const discordComponentInteractionSchema: z.ZodObject<{
+    type: z.ZodLiteral<3>;
+    id: z.ZodString;
+    application_id: z.ZodString;
+    channel_id: z.ZodString;
+    guild_id: z.ZodOptional<z.ZodString>;
+    channel: z.ZodObject<{
+        type: z.ZodInt;
+    }, z.core.$strip>;
+    member: z.ZodOptional<z.ZodObject<{
+        user: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    user: z.ZodOptional<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>>;
+    message: z.ZodObject<{
+        id: z.ZodString;
+        channel_id: z.ZodString;
+        author: z.ZodObject<{
+            id: z.ZodString;
+        }, z.core.$strip>;
+    }, z.core.$strip>;
+    data: z.ZodObject<{
+        custom_id: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type DiscordComponentInteraction = z.infer<typeof discordComponentInteractionSchema>;
+/** Toolroll's button data: `so_` and a one-time token. */
+export declare const discordButtonSchema: z.ZodObject<{
+    custom_id: z.ZodString;
+}, z.core.$strip>;
+export declare function readDiscordComponentInteraction(body: unknown): ContractResult<DiscordComponentInteraction>;
+/** The tapped button's one-time token. */
+export declare function readDiscordButtonToken(interaction: DiscordComponentInteraction): ContractResult<string>;