toolroll 0.9.34 → 0.9.37

package/dist/contracts/scout-report.js

@@ -0,0 +1,141 @@
+/**
+ * The scout's report: one schema for the report a scout writes (its report file, or Claude's structured output), the
+ * JSON Schema a Claude scout is given (`--json-schema`, `SCOUT_OUTPUT_JSON_SCHEMA`) and the reader that takes it back
+ * (`parseReport` in scout-report.ts), which also reads every report already kept as evidence. The rules JSON Schema
+ * cannot state — UTF-8 byte limits, blank text, control characters, one-line titles, a one-paragraph summary, safe
+ * links, duplicate screenshots and items naming them — run in plain code after parsing, each with a path-named error.
+ */
+import { z } from "zod";
+import { limitRule, TEXT_LIMITS } from "../text-limits.js";
+import { limited, readVersioned, toModelSchema, versioned } from "./contract.js";
+/** How many follow-ups, items and screenshots a report may carry. */
+export const REPORT_COUNTS = { followUps: 5, items: 6, images: 8 };
+/** Caps are BYTES of UTF-8 (v4 review, finding 11): a 64 KiB report is 64 KiB whatever script it is written in. They
+ * hold what a scout writes; a stored report is read without them (`storedReportSchema`). */
+export const REPORT_LIMITS = {
+    payload: TEXT_LIMITS.reportPayloadBytes,
+    title: TEXT_LIMITS.reportTitleBytes,
+    summary: TEXT_LIMITS.reportSummary,
+    document: TEXT_LIMITS.reportDocumentBytes,
+    followUps: REPORT_COUNTS.followUps,
+    followUpTitle: TEXT_LIMITS.reportTitleBytes,
+    /** A follow-up files as a task: its goal is held to the task goal limit, in bytes of the same count. */
+    followUpGoal: TEXT_LIMITS.goal,
+    items: REPORT_COUNTS.items,
+    itemTitle: TEXT_LIMITS.reportTitleBytes,
+    itemWhy: TEXT_LIMITS.reportWhyBytes,
+    url: TEXT_LIMITS.reportUrlBytes,
+    images: REPORT_COUNTS.images,
+    caption: TEXT_LIMITS.reportCaptionBytes,
+};
+/** A screenshot's name in the scout's output folder: one plain file name, PNG or JPEG, never a path. */
+export const REPORT_IMAGE_FILE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}\.(?:png|jpe?g)$/i;
+/** Each text field, the limit it is written within, and whether it is one line or a web address. */
+export const REPORT_TEXT_FIELDS = {
+    title: { limit: "reportTitleBytes", oneLine: true },
+    summary: { limit: "reportSummary" },
+    report: { limit: "reportDocumentBytes" },
+};
+export const FOLLOW_UP_TEXT_FIELDS = { title: { limit: "reportTitleBytes", oneLine: true }, goal: { limit: "goal" } };
+export const ITEM_TEXT_FIELDS = { title: { limit: "reportTitleBytes", oneLine: true }, why: { limit: "reportWhyBytes" }, url: { limit: "reportUrlBytes", link: true } };
+// The image's file is any one line here: the runner refuses one that isn't a plain file name in its output folder, not the report.
+export const IMAGE_TEXT_FIELDS = { file: { limit: "reportCaptionBytes", oneLine: true }, caption: { limit: "reportCaptionBytes", oneLine: true }, url: { limit: "reportUrlBytes", link: true } };
+export const REPORT_VERSION = 1;
+function reportSchemaOf(text) {
+    // Limits named without "Bytes" that a report still counts in bytes: the model is told so.
+    const bytes = (field, limit) => text(field, limit).describe(limitRule(field, TEXT_LIMITS[limit], "bytes"));
+    const followUp = z.strictObject({
+        title: text("follow-up title", "reportTitleBytes").min(1),
+        goal: bytes("follow-up goal", "goal").min(1),
+    });
+    const item = z.strictObject({
+        title: text("item title", "reportTitleBytes").min(1),
+        why: text("item why", "reportWhyBytes").min(1),
+        url: text("item url", "reportUrlBytes").min(1),
+        image: z.string().nullable().optional().describe("the file of the one of images this item shows, if any"),
+    });
+    const image = z.strictObject({
+        file: text("image file", "reportCaptionBytes").min(1),
+        caption: text("image caption", "reportCaptionBytes").min(1),
+        url: text("image url", "reportUrlBytes").min(1),
+        /** Added by Toolroll once the screenshot is stored: its bytes' sha256 and the evidence that holds them. */
+        sha256: z.string().regex(/^[0-9a-f]{64}$/, { error: "must be a sha256 hex digest" }).optional().describe("set by Toolroll when it keeps the screenshot; leave out"),
+        artifact: z.int().positive().optional().describe("set by Toolroll when it keeps the screenshot; leave out"),
+    });
+    return versioned(REPORT_VERSION, {
+        title: text("title", "reportTitleBytes").min(1),
+        summary: bytes("summary", "reportSummary").min(1),
+        report: text("report", "reportDocumentBytes").min(1),
+        followUps: z.array(followUp).max(REPORT_COUNTS.followUps).optional(),
+        items: z.array(item).max(REPORT_COUNTS.items).optional(),
+        images: z.array(image).max(REPORT_COUNTS.images).optional(),
+    });
+}
+/** A report as a scout writes it now. */
+export const scoutReportSchema = reportSchemaOf(limited);
+/** A report kept as evidence: the same, except text keeps the length it was stored with. */
+export const storedReportSchema = reportSchemaOf(() => z.string());
+/** The park mailbox's decision as a scout hands it back: the same fields `parseDecision` reads, which stays its
+ * validator until the decision contract (docs/plans/zod-revamp.md, item 7) gives it one schema. */
+export const scoutDecisionSchema = z.strictObject({
+    urgency: z.literal("blocking"),
+    recap: z.string(),
+    question: z.string(),
+    options: z.array(z.strictObject({ id: z.string(), label: z.string(), consequence: z.string(), reversible: z.boolean() })),
+    recommendation: z.string(),
+});
+/**
+ * The scout's handback for Claude's `--json-schema` (run 2334's fix): plan mode only lets a session write its own plan
+ * file, so a Claude scout returns a report — or a question for the operator — as structured output on the terminal
+ * result event. The report branch is the report schema itself; the byte limits and rules JSON Schema cannot state are
+ * `parseReport`'s (and `parseDecision`'s), applied to the branch as handed back.
+ */
+export const scoutHandbackSchema = z.strictObject({
+    kind: z.enum(["report", "question"]),
+    report: scoutReportSchema.optional(),
+    decision: scoutDecisionSchema.optional(),
+});
+export const SCOUT_OUTPUT_JSON_SCHEMA = toModelSchema(scoutHandbackSchema);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function pick(body, fields) {
+    const out = {};
+    for (const field of fields) {
+        if (Object.prototype.hasOwnProperty.call(body, field) && body[field] !== undefined)
+            out[field] = body[field];
+    }
+    return out;
+}
+const ENTRY_FIELDS = {
+    followUps: Object.keys(FOLLOW_UP_TEXT_FIELDS),
+    items: [...Object.keys(ITEM_TEXT_FIELDS), "image"],
+    images: [...Object.keys(IMAGE_TEXT_FIELDS), "sha256", "artifact"],
+};
+/**
+ * Known reports keep the old parser's field-picking, whether unversioned (including `version: null`) or version 1:
+ * unknown fields in the report, follow-ups, items and images are ignored, and a null list means none. Known field
+ * values are never rewritten, and anything that is not an object is left for the schema to refuse by path.
+ */
+function normalizeReportV1(body) {
+    const out = { version: REPORT_VERSION, ...pick(body, [...Object.keys(REPORT_TEXT_FIELDS), "followUps", "items", "images"]) };
+    for (const list of ["followUps", "items", "images"]) {
+        if (out[list] === null)
+            delete out[list];
+        else if (Array.isArray(out[list]))
+            out[list] = out[list].map(entry => (isRecord(entry) ? pick(entry, ENTRY_FIELDS[list]) : entry));
+    }
+    return out;
+}
+export const REPORT_UPGRADES = { 0: normalizeReportV1 };
+/** Normalize current and unversioned reports; leave other versions for readVersioned to check. */
+export function reportPayloadBody(input) {
+    if (!isRecord(input))
+        return null;
+    return !Object.prototype.hasOwnProperty.call(input, "version") || input["version"] === null || input["version"] === REPORT_VERSION
+        ? normalizeReportV1(input)
+        : input;
+}
+/** Read current and unversioned reports with the same field-picking, then the strict schema; refuse newer versions
+ * plainly. `stored`: one kept as evidence, read without the length limits. */
+export function readReportPayload(input, options = {}) {
+    return readVersioned(options.stored === true ? storedReportSchema : scoutReportSchema, reportPayloadBody(input) ?? input, REPORT_UPGRADES);
+}

package/dist/contracts/slack-callback.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A Slack button tap (slack-chat.ts `receiveSlack`): the `block_actions` interaction Slack sends, and the button data
+ * Toolroll put on it. The interaction is Slack's, so fields Toolroll doesn't read are ignored; the button (its
+ * `action_id` and one-time token `value`) is Toolroll's. A tap from the paired person whose button can't be read is
+ * answered with why (`actions[0].value: must be a Toolroll button token`), and nothing is done.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** Toolroll's buttons: toolroll_* since the rename; standing_orders_* buttons on older messages still work. */
+export declare const SLACK_BUTTON_ACTION: RegExp;
+/** A link button opens its page in Slack's own client; Slack still reports the tap, and there is nothing to do. */
+export declare const SLACK_LINK_ACTION: RegExp;
+/** The interaction around a tap: who, and the message the button is on. */
+export declare const slackBlockActionsSchema: z.ZodObject<{
+    type: z.ZodLiteral<"block_actions">;
+    user: z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>;
+    container: z.ZodObject<{
+        type: z.ZodString;
+        channel_id: z.ZodOptional<z.ZodString>;
+        message_ts: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    message: z.ZodOptional<z.ZodObject<{
+        thread_ts: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    actions: z.ZodArray<z.ZodObject<{
+        action_id: z.ZodOptional<z.ZodString>;
+        value: z.ZodOptional<z.ZodString>;
+        action_ts: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SlackBlockActions = z.infer<typeof slackBlockActionsSchema>;
+/** The one tapped button, as Toolroll made it. */
+export declare const slackButtonSchema: z.ZodObject<{
+    action_id: z.ZodString;
+    value: z.ZodString;
+    action_ts: z.ZodString;
+}, z.core.$strip>;
+export type SlackButton = z.infer<typeof slackButtonSchema>;
+export declare function readSlackBlockActions(body: unknown): ContractResult<SlackBlockActions>;
+/** The tapped button: exactly one, Toolroll's (`actions[0].action_id: not a Toolroll button`). */
+export declare function readSlackButton(interaction: SlackBlockActions): ContractResult<SlackButton>;

package/dist/contracts/slack-callback.js

@@ -0,0 +1,35 @@
+/**
+ * A Slack button tap (slack-chat.ts `receiveSlack`): the `block_actions` interaction Slack sends, and the button data
+ * Toolroll put on it. The interaction is Slack's, so fields Toolroll doesn't read are ignored; the button (its
+ * `action_id` and one-time token `value`) is Toolroll's. A tap from the paired person whose button can't be read is
+ * answered with why (`actions[0].value: must be a Toolroll button token`), and nothing is done.
+ */
+import { z } from "zod";
+import { parseContract } from "./contract.js";
+/** Toolroll's buttons: toolroll_* since the rename; standing_orders_* buttons on older messages still work. */
+export const SLACK_BUTTON_ACTION = /^(?:toolroll|standing_orders)_(?:confirm|dismiss|yes|cancel|flow_approve|flow_edit|flow_send_back|flow_choose_[0-3]|flow_note_(?:yes|no)|question_choice|question_words)$/;
+/** A link button opens its page in Slack's own client; Slack still reports the tap, and there is nothing to do. */
+export const SLACK_LINK_ACTION = /^(?:toolroll|standing_orders)_link(?:_[0-9]+)?$/;
+const token = z.string().regex(/^[a-f0-9]{32}$/, { error: "must be a Toolroll button token" });
+/** The interaction around a tap: who, and the message the button is on. */
+export const slackBlockActionsSchema = z.object({
+    type: z.literal("block_actions"),
+    user: z.object({ id: z.string() }),
+    container: z.object({ type: z.string(), channel_id: z.string().optional(), message_ts: z.string().optional() }),
+    message: z.object({ thread_ts: z.string().optional() }).optional(),
+    actions: z.array(z.object({ action_id: z.string().optional(), value: z.string().optional(), action_ts: z.string().optional() })),
+});
+/** The one tapped button, as Toolroll made it. */
+export const slackButtonSchema = z.object({
+    action_id: z.string().regex(SLACK_BUTTON_ACTION, { error: "not a Toolroll button" }),
+    value: token,
+    action_ts: z.string().regex(/^\d{10,16}\.\d{6}$/, { error: "must be a Slack timestamp" }),
+});
+export function readSlackBlockActions(body) {
+    return parseContract(slackBlockActionsSchema, body);
+}
+/** The tapped button: exactly one, Toolroll's (`actions[0].action_id: not a Toolroll button`). */
+export function readSlackButton(interaction) {
+    const read = parseContract(z.object({ actions: z.array(slackButtonSchema).length(1) }), { actions: interaction.actions });
+    return read.ok ? { ok: true, value: read.value.actions[0] } : read;
+}

package/dist/contracts/sort-answer.d.ts

@@ -0,0 +1,83 @@
+/**
+ * A Sort zone's answer (flow-sort.ts): what Jev, through OpenRouter's Decisions API, says about a card, and what a
+ * sort step keeps of it. The Decisions API takes questions, not a JSON Schema, so there is no model-facing schema:
+ * the request's keys come from the flow contract (`SORT_ROUTE_KEY`, `sortNoteKeyOf`, `sortKeyOf` in flow.ts), and
+ * `jevReplySchema` is how the reply is read before anything routes on it.
+ *
+ * The reply is an outside service's: keys Toolroll does not read (ids, token counts) are ignored rather than refused.
+ * Optional metadata can have any type, as before: the reader defaults non-numeric confidences/chances to zero,
+ * skips non-numeric notes, and defaults the model and cost. The route choice must still be text.
+ *
+ * `sortDecisionSchema` is the decision a sort step keeps (`flow_step_run.decision_json`), unversioned as every release
+ * has written it; the card, Insights and spend read saved ones as before.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** Jev's answer to the zone's question: the key of the answer it picked, how sure it is (0–1), and every answer's chance. */
+export declare const jevChoiceSchema: z.ZodObject<{
+    choice: z.ZodString;
+    confidence: z.ZodOptional<z.ZodUnknown>;
+    probabilities: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+/** Jev's answer to something else the zone notes: a score's level (as a number) or a yes/no's chance of yes. */
+export declare const jevNoteSchema: z.ZodObject<{
+    score: z.ZodOptional<z.ZodUnknown>;
+    noul: z.ZodOptional<z.ZodUnknown>;
+    confidence: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+/** What Toolroll reads of Jev's reply. */
+export declare const jevReplySchema: z.ZodObject<{
+    model: z.ZodOptional<z.ZodUnknown>;
+    answers: z.ZodObject<{
+        route: z.ZodObject<{
+            choice: z.ZodString;
+            confidence: z.ZodOptional<z.ZodUnknown>;
+            probabilities: z.ZodOptional<z.ZodUnknown>;
+        }, z.core.$strip>;
+    }, z.core.$catchall<z.ZodObject<{
+        score: z.ZodOptional<z.ZodUnknown>;
+        noul: z.ZodOptional<z.ZodUnknown>;
+        confidence: z.ZodOptional<z.ZodUnknown>;
+    }, z.core.$strip>>>;
+    usage: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+export type JevReply = z.infer<typeof jevReplySchema>;
+/** Read Jev's reply, or path-named lines saying what it lacks (`answers.route.choice: required`). */
+export declare function readJevReply(input: unknown): ContractResult<JevReply>;
+/** One thing the zone also noted, as the card shows it: the level or yes/no, and how sure (0–1). */
+export declare const sortNoteAnswerSchema: z.ZodObject<{
+    id: z.ZodString;
+    question: z.ZodString;
+    kind: z.ZodEnum<{
+        score: "score";
+        "yes-no": "yes-no";
+    }>;
+    answer: z.ZodString;
+    sure: z.ZodNumber;
+}, z.core.$strict>;
+export type SortNoteAnswer = z.infer<typeof sortNoteAnswerSchema>;
+/** What a sort step decided, kept on its run (decision_json) and shown on the card. */
+export declare const sortDecisionSchema: z.ZodObject<{
+    model: z.ZodString;
+    answer: z.ZodString;
+    sure: z.ZodNumber;
+    sureAt: z.ZodNumber;
+    confident: z.ZodBoolean;
+    to: z.ZodNullable<z.ZodString>;
+    chances: z.ZodObject<{}, z.core.$catchall<z.ZodNumber>>;
+    notes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        question: z.ZodString;
+        kind: z.ZodEnum<{
+            score: "score";
+            "yes-no": "yes-no";
+        }>;
+        answer: z.ZodString;
+        sure: z.ZodNumber;
+    }, z.core.$strict>>;
+    cost: z.ZodNullable<z.ZodNumber>;
+    ms: z.ZodNumber;
+}, z.core.$strict>;
+export type SortDecision = z.infer<typeof sortDecisionSchema>;
+/** Read a sort decision as a step keeps it. */
+export declare function readSortDecision(input: unknown): ContractResult<SortDecision>;

package/dist/contracts/sort-answer.js

@@ -0,0 +1,77 @@
+/**
+ * A Sort zone's answer (flow-sort.ts): what Jev, through OpenRouter's Decisions API, says about a card, and what a
+ * sort step keeps of it. The Decisions API takes questions, not a JSON Schema, so there is no model-facing schema:
+ * the request's keys come from the flow contract (`SORT_ROUTE_KEY`, `sortNoteKeyOf`, `sortKeyOf` in flow.ts), and
+ * `jevReplySchema` is how the reply is read before anything routes on it.
+ *
+ * The reply is an outside service's: keys Toolroll does not read (ids, token counts) are ignored rather than refused.
+ * Optional metadata can have any type, as before: the reader defaults non-numeric confidences/chances to zero,
+ * skips non-numeric notes, and defaults the model and cost. The route choice must still be text.
+ *
+ * `sortDecisionSchema` is the decision a sort step keeps (`flow_step_run.decision_json`), unversioned as every release
+ * has written it; the card, Insights and spend read saved ones as before.
+ */
+import { z } from "zod";
+import { parseContract } from "./contract.js";
+import { flowSortAnswerSchema, flowSortNoteSchema, SORT_ROUTE_KEY } from "./flow.js";
+/** Jev's answer to the zone's question: the key of the answer it picked, how sure it is (0–1), and every answer's chance. */
+export const jevChoiceSchema = z.object({
+    choice: z.string(),
+    confidence: z.unknown().optional(),
+    probabilities: z.unknown().optional(),
+});
+/** Jev's answer to something else the zone notes: a score's level (as a number) or a yes/no's chance of yes. */
+export const jevNoteSchema = z.object({
+    score: z.unknown().optional(),
+    noul: z.unknown().optional(),
+    confidence: z.unknown().optional(),
+});
+/** What Toolroll reads of Jev's reply. */
+export const jevReplySchema = z.object({
+    model: z.unknown().optional(),
+    answers: z.object({ [SORT_ROUTE_KEY]: jevChoiceSchema }).catchall(jevNoteSchema),
+    usage: z.unknown().optional(),
+});
+/** Read Jev's reply, or path-named lines saying what it lacks (`answers.route.choice: required`). */
+export function readJevReply(input) {
+    if (typeof input === "object" && input !== null && !Array.isArray(input)) {
+        const body = input;
+        const answers = body["answers"];
+        if (typeof answers === "object" && answers !== null && !Array.isArray(answers)) {
+            // Extra answers are not necessarily notes. Non-objects have no note fields to read, so ignore them.
+            input = { ...body, answers: Object.fromEntries(Object.entries(answers).map(([key, value]) => [key,
+                    key === SORT_ROUTE_KEY || (typeof value === "object" && value !== null && !Array.isArray(value)) ? value : {},
+                ])) };
+        }
+    }
+    return parseContract(jevReplySchema, input);
+}
+const noteShape = flowSortNoteSchema.options[0].shape;
+/** One thing the zone also noted, as the card shows it: the level or yes/no, and how sure (0–1). */
+export const sortNoteAnswerSchema = z.strictObject({
+    id: noteShape.id,
+    question: noteShape.question.describe("The question the zone also notes."),
+    kind: z.enum(["score", "yes-no"]),
+    answer: z.string(),
+    sure: z.number().min(0).max(1),
+});
+/** What a sort step decided, kept on its run (decision_json) and shown on the card. */
+export const sortDecisionSchema = z.strictObject({
+    model: z.string(),
+    /** The answer as the zone names it, and how sure Jev was (0–1). */
+    answer: flowSortAnswerSchema.shape.answer.describe("The zone's chosen answer."),
+    sure: z.number().min(0).max(1),
+    sureAt: z.number(),
+    /** Sure enough to act alone, and where the card went (null: it waited in the zone). */
+    confident: z.boolean(),
+    to: flowSortAnswerSchema.shape.to.nullable(),
+    /** Every answer's chance, by name. */
+    chances: z.object({}).catchall(z.number()),
+    notes: z.array(sortNoteAnswerSchema),
+    cost: z.number().nullable(),
+    ms: z.number(),
+});
+/** Read a sort decision as a step keeps it. */
+export function readSortDecision(input) {
+    return parseContract(sortDecisionSchema, input);
+}

package/dist/contracts/stage-output.d.ts

@@ -0,0 +1,127 @@
+/**
+ * What a finished zone hands the zones after it (docs/plans/zod-revamp.md, item 8): its `{{stage.<id>}}` words and, by
+ * kind, more fields (a research zone's `{{stage.<id>.items}}` and `{{stage.<id>.report}}`), kept on the card as one
+ * versioned payload (`flow_card.outputs_json`) with any output too long to pass on attached whole.
+ *
+ * - `stageHandoffSchema` is one zone's handoff; `STAGE_HANDOFFS` says which of its fields each zone kind hands on. A
+ *   template's `{{stage.<id>.<field>}}` is checked against it when a flow is saved (`stageReferenceProblems`), so a
+ *   refusal names the path: `stages[1].instructions: stage.research.unknown is not available`.
+ * - `cardOutputsSchema` is what the card keeps: every handoff's fields flat (`<zone>`, `<zone>.items`, `<zone>.report`,
+ *   as `{{stage.…}}` names them) and, for a zone whose output was over TEXT_LIMITS.stageOutput, the output whole: its
+ *   `{{stage.<zone>}}` says where it is kept, and a task filed after it is given it whole (flowGoalCuts).
+ *
+ * Saved before this contract (version 0), a card's outputs were the flat map alone; they read exactly as every release
+ * read them: the string values, anything else skipped.
+ */
+import { z } from "zod";
+import { type ContractIssue, type ContractResult } from "./contract.js";
+import type { FlowDefinition, FlowStage, FlowStageKind } from "./flow.js";
+/** One zone's handoff to the zones after it. */
+export declare const stageHandoffSchema: z.ZodObject<{
+    text: z.ZodString;
+    items: z.ZodOptional<z.ZodString>;
+    report: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type StageHandoff = z.infer<typeof stageHandoffSchema>;
+export type StageField = Exclude<keyof StageHandoff, "text">;
+/**
+ * What each zone kind hands on, or null when it hands nothing on (it holds, asks, messages or ends). A sort hands on its
+ * decision in words (`sortWords` of the small-answers contract's SortDecision, src/contracts/sort-answer.ts), and a
+ * Send to me zone what it sent.
+ */
+export declare const STAGE_HANDOFFS: {
+    readonly inbox: null;
+    readonly task: z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strict>;
+    readonly report: z.ZodObject<{
+        text: z.ZodString;
+        items: z.ZodOptional<z.ZodString>;
+        report: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    readonly approval: null;
+    readonly check: z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strict>;
+    readonly "pull-request": z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strict>;
+    readonly update: z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strict>;
+    readonly notify: null;
+    readonly sort: z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strict>;
+    readonly draft: z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strict>;
+    readonly request: z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strict>;
+    readonly email: z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strict>;
+    readonly tool: z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strict>;
+    readonly wait: z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strict>;
+    readonly teammate: z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strict>;
+    readonly send: z.ZodObject<{
+        text: z.ZodString;
+    }, z.core.$strict>;
+    readonly choose: null;
+    readonly done: null;
+};
+/** The extra `{{stage.<id>.<field>}}` fields a zone kind hands on. */
+export declare function stageFieldsOf(kind: FlowStageKind): StageField[];
+/** One zone's handoff, read from the card's flat outputs (a field it never wrote is left out; no words read as ""). */
+export declare function stageHandoffOf(outputs: Readonly<Record<string, string>>, zone: string): StageHandoff;
+/** The card's flat outputs with one zone's handoff in place of its last: a field this visit didn't hand on is gone, so
+ * nothing stale is left behind. */
+export declare function withStageHandoff(outputs: Readonly<Record<string, string>>, zone: string, handoff: StageHandoff): Record<string, string>;
+export declare const CARD_OUTPUTS_VERSION = 1;
+export declare const cardOutputsSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    outputs: z.ZodObject<{}, z.core.$catchall<z.ZodString>>;
+    attached: z.ZodObject<{}, z.core.$catchall<z.ZodString>>;
+}, z.core.$strict>;
+export type CardOutputs = z.infer<typeof cardOutputsSchema>;
+/** Version 0, the flat map every release before wrote: its string values, as they read them; anything else is skipped. */
+export declare function upgradeFlatOutputs(raw: unknown): CardOutputs;
+/**
+ * Read a card's outputs. Version 1 as itself and a newer version refused plainly. Anything without a numeric `version`
+ * was saved before outputs carried one (a zone may be called `version`; its words were a string), and is read as the
+ * flat map it is.
+ */
+export declare function readCardOutputs(input: unknown): ContractResult<CardOutputs>;
+/** A card's outputs as the store keeps them: unreadable JSON is the empty card it always was; `newer` is a row a newer
+ * Toolroll wrote, which this one reads as empty and never writes over. */
+export declare function cardOutputsFromStore(json: string): {
+    outputs: Record<string, string>;
+    attached: Record<string, string>;
+    issues: ContractIssue[];
+    newer: boolean;
+};
+/** A card's outputs as the store saves them. A zone's attachment is kept only while its output is the pointer to it. */
+export declare function cardOutputsForStore(outputs: Readonly<Record<string, string>>, attached: Readonly<Record<string, string>>): string;
+/** Where a zone's words take fill-ins, by the drawing's path: its instructions and message, a request's address,
+ * headers and body, an email's fields and a tool's arguments. */
+export declare function templateFields(stage: FlowStage): {
+    path: string;
+    text: string;
+}[];
+export declare function stageReferences(text: string): string[];
+/** What one `{{stage.…}}` reference can't be, against the drawing: null when its zone hands that field on. */
+export declare function stageReferenceProblem(definition: FlowDefinition, reference: string): string | null;
+/**
+ * Template references a save adds that its zones don't hand on, each named by its path
+ * (`stages[1].instructions: stage.research.unknown is not available ...`). A reference the flow already had before
+ * this save (`previous`, the saved drawing) is never refused, nor is any reference when a flow is only read or run:
+ * this checks new and changed words alone.
+ */
+export declare function stageReferenceProblems(definition: FlowDefinition, previous: FlowDefinition | null): ContractIssue[];