toolroll 0.9.36 → 0.9.38

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[];

package/dist/contracts/stage-output.js

@@ -0,0 +1,166 @@
+/**
+ * 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 { parseContract, readVersioned, versioned } from "./contract.js";
+/** One zone's handoff to the zones after it. */
+export const stageHandoffSchema = z.strictObject({
+    text: z.string().describe("{{stage.<id>}}: what the zone produced, whole up to TEXT_LIMITS.stageOutput characters; a longer one says where it is kept whole."),
+    items: z.string().optional().describe("{{stage.<id>.items}}: what a research zone found, as a numbered list (title, why, link)."),
+    report: z.string().optional().describe("{{stage.<id>.report}}: a research zone's whole report (REPORT_FILL_LIMIT)."),
+});
+const words = stageHandoffSchema.pick({ text: true });
+/**
+ * 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 const STAGE_HANDOFFS = {
+    inbox: null, task: words, report: stageHandoffSchema, approval: null, check: words, "pull-request": words, update: words, notify: null,
+    sort: words, draft: words, request: words, email: words, tool: words, wait: words, teammate: words, send: words, choose: null, done: null,
+};
+/** The extra `{{stage.<id>.<field>}}` fields a zone kind hands on. */
+export function stageFieldsOf(kind) {
+    const schema = STAGE_HANDOFFS[kind];
+    return schema === null ? [] : Object.keys(schema.shape).filter(field => field !== "text");
+}
+/** One zone's handoff, read from the card's flat outputs (a field it never wrote is left out; no words read as ""). */
+export function stageHandoffOf(outputs, zone) {
+    const fields = Object.keys(stageHandoffSchema.shape).filter(field => field !== "text");
+    return { text: outputs[zone] ?? "", ...Object.fromEntries(fields.flatMap(field => outputs[`${zone}.${field}`] === undefined ? [] : [[field, outputs[`${zone}.${field}`]]])) };
+}
+/** 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 function withStageHandoff(outputs, zone, handoff) {
+    const read = stageHandoffSchema.parse(handoff);
+    const next = { ...outputs, [zone]: read.text };
+    for (const field of Object.keys(stageHandoffSchema.shape).filter(one => one !== "text")) {
+        const value = read[field];
+        if (value === undefined)
+            delete next[`${zone}.${field}`];
+        else
+            next[`${zone}.${field}`] = value;
+    }
+    return next;
+}
+// ------------------------------------------------------------------ what the card keeps
+export const CARD_OUTPUTS_VERSION = 1;
+export const cardOutputsSchema = versioned(CARD_OUTPUTS_VERSION, {
+    outputs: z.object({}).catchall(z.string()).describe("Every {{stage.…}} value by its name: <zone>, and a research zone's <zone>.items and <zone>.report."),
+    attached: z.object({}).catchall(z.string()).describe("A zone's output in full when it was over TEXT_LIMITS.stageOutput characters, by zone."),
+});
+/** Version 0, the flat map every release before wrote: its string values, as they read them; anything else is skipped. */
+export function upgradeFlatOutputs(raw) {
+    const outputs = raw !== null && typeof raw === "object" ? Object.fromEntries(Object.entries(raw).filter((entry) => typeof entry[1] === "string")) : {};
+    return { version: CARD_OUTPUTS_VERSION, outputs, attached: {} };
+}
+/**
+ * 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 function readCardOutputs(input) {
+    const legacy = input === null || typeof input !== "object" || Array.isArray(input) || typeof input["version"] !== "number";
+    return legacy ? parseContract(cardOutputsSchema, upgradeFlatOutputs(input)) : readVersioned(cardOutputsSchema, input);
+}
+/** 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 function cardOutputsFromStore(json) {
+    let raw;
+    try {
+        raw = JSON.parse(json);
+    }
+    catch {
+        raw = {};
+    }
+    const read = readCardOutputs(raw);
+    if (read.ok)
+        return { outputs: read.value.outputs, attached: read.value.attached, issues: [], newer: false };
+    return { outputs: {}, attached: {}, issues: read.issues, newer: read.issues.some(one => one.kind === "newer-version") };
+}
+/** 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 function cardOutputsForStore(outputs, attached) {
+    const kept = Object.fromEntries(Object.entries(attached).filter(([zone]) => outputs[zone] !== undefined));
+    return JSON.stringify(cardOutputsSchema.parse({ version: CARD_OUTPUTS_VERSION, outputs, attached: kept }));
+}
+// ------------------------------------------------------------------ template references, checked at save
+/** 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 function templateFields(stage) {
+    const fields = [];
+    const add = (path, text) => { if (typeof text === "string")
+        fields.push({ path, text }); };
+    add("instructions", stage.instructions);
+    add("message", stage.message);
+    if (stage.request !== undefined) {
+        add("request.url", stage.request.url);
+        for (const [name, value] of Object.entries(stage.request.headers))
+            add(`request.headers.${name}`, value);
+        add("request.body", stage.request.body);
+    }
+    if (stage.email !== undefined) {
+        add("email.to", stage.email.to);
+        add("email.subject", stage.email.subject);
+        add("email.body", stage.email.body);
+    }
+    if (stage.tool !== undefined)
+        add("tool.args", stage.tool.args);
+    return fields;
+}
+/** Every `{{stage.…}}` in some words, as written between the braces (`stage.research.items`). */
+const STAGE_REFERENCE = /\{\{\s*(stage\.[^{}]*?)\s*\}\}/g;
+export function stageReferences(text) {
+    return [...text.matchAll(STAGE_REFERENCE)].map(match => match[1]);
+}
+/** What one `{{stage.…}}` reference can't be, against the drawing: null when its zone hands that field on. */
+export function stageReferenceProblem(definition, reference) {
+    const [zone = "", ...rest] = reference.slice("stage.".length).split(".");
+    const field = rest.join(".");
+    const stage = definition.stages.find(one => one.id === zone);
+    if (stage === undefined)
+        return `${reference} is not available: there's no zone called ${zone === "" ? "(none)" : zone}`;
+    if (STAGE_HANDOFFS[stage.kind] === null)
+        return `${reference} is not available: ${stage.title} hands nothing on`;
+    if (field === "")
+        return null;
+    const fields = stageFieldsOf(stage.kind);
+    if (fields.includes(field))
+        return null;
+    const offered = [`{{stage.${zone}}}`, ...fields.map(one => `{{stage.${zone}.${one}}}`)];
+    return `${reference} is not available (${stage.title} hands on ${offered.length === 1 ? offered[0] : `${offered.slice(0, -1).join(", ")} and ${offered.at(-1)}`})`;
+}
+/**
+ * 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 function stageReferenceProblems(definition, previous) {
+    const had = new Set((previous?.stages ?? []).flatMap(stage => templateFields(stage).flatMap(field => stageReferences(field.text))));
+    const problems = [];
+    definition.stages.forEach((stage, index) => {
+        for (const field of templateFields(stage)) {
+            for (const reference of new Set(stageReferences(field.text))) {
+                if (had.has(reference))
+                    continue;
+                const problem = stageReferenceProblem(definition, reference);
+                const path = `stages[${index}].${field.path}`;
+                if (problem !== null)
+                    problems.push({ path, kind: "bad-value", line: `${path}: ${problem}` });
+            }
+        }
+    });
+    return problems;
+}

package/dist/contracts/task-sizing.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The task sizing classifier's answer (task-sizing.ts): one schema for the JSON Schema a Claude sizer is given
+ * (`--json-schema`) and the reader that takes an answer back. Jev answers through OpenRouter's Decisions API, which
+ * takes questions rather than a JSON Schema; its choice and yes/no are read into this same answer before they count.
+ *
+ * An answer is never kept as it is (it becomes the task's sizing, phase-routing.ts `TaskSizing`), so it carries no
+ * version.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+export declare const sizeAnswerSchema: z.ZodObject<{
+    size: z.ZodEnum<{
+        large: "large";
+        medium: "medium";
+        small: "small";
+    }>;
+    risky: z.ZodBoolean;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type SizeAnswer = z.infer<typeof sizeAnswerSchema>;
+/** What a Claude sizer's `--json-schema` is: the answer schema, exactly. */
+export declare const SIZING_MODEL_SCHEMA: Readonly<Record<string, unknown>>;
+/** Keep the old reason defaults and clipping before checking the normalized answer's contract. */
+export declare function readSizeAnswer(value: unknown): ContractResult<SizeAnswer>;

package/dist/contracts/task-sizing.js

@@ -0,0 +1,28 @@
+/**
+ * The task sizing classifier's answer (task-sizing.ts): one schema for the JSON Schema a Claude sizer is given
+ * (`--json-schema`) and the reader that takes an answer back. Jev answers through OpenRouter's Decisions API, which
+ * takes questions rather than a JSON Schema; its choice and yes/no are read into this same answer before they count.
+ *
+ * An answer is never kept as it is (it becomes the task's sizing, phase-routing.ts `TaskSizing`), so it carries no
+ * version.
+ */
+import { z } from "zod";
+import { TASK_SIZES } from "../phase-routing.js";
+import { TEXT_LIMITS } from "../text-limits.js";
+import { limited, parseContract, toModelSchema } from "./contract.js";
+export const sizeAnswerSchema = z.object({
+    size: z.enum(TASK_SIZES),
+    risky: z.boolean(),
+    reason: limited("reason", "sizingReason").describe(`reason: at most ${TEXT_LIMITS.sizingReason} characters.`),
+});
+/** What a Claude sizer's `--json-schema` is: the answer schema, exactly. */
+export const SIZING_MODEL_SCHEMA = toModelSchema(sizeAnswerSchema);
+/** Keep the old reason defaults and clipping before checking the normalized answer's contract. */
+export function readSizeAnswer(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const body = value;
+        const reason = typeof body["reason"] === "string" ? body["reason"].replace(/\s+/g, " ").trim() : "";
+        value = { ...body, reason: reason.length <= TEXT_LIMITS.sizingReason ? reason : `${reason.slice(0, TEXT_LIMITS.sizingReason - 1)}…` };
+    }
+    return parseContract(sizeAnswerSchema, value);
+}

package/dist/contracts/teammate-turn.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A teammate's turn (teammates.ts): one schema for the JSON Schema Claude answers in (`--json-schema`) and the reader
+ * that takes the answer back. One flat object with every field (a root union is refused by the API); fields a turn
+ * does not use are "" (or [] for options).
+ *
+ * The text limits (TURN_LIMITS, from TEXT_LIMITS) are deliberately not in the schema: the CLI refuses an answer a few
+ * characters over one whole, so they are checked after parsing and an answer over one is asked once to shorten
+ * (teammate-work.ts), then kept whole. What the zone allows — which actions, which answers, a note for a send-back, a
+ * question for an ask, a tool for a tool call — is checked after parsing too (`readTurn`), by path.
+ *
+ * A turn is kept as the step's decision (`flow_step_run.decision_json`) as it was read, so a saved one is this shape.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+/** What a teammate may do on one turn. A decision zone: approve, send back, or hand it to a person. A work zone: pick
+ * where it goes, ask its person, or say it can't. v94: "use_tool" asks for one tool call. */
+export declare const TURN_ACTIONS: readonly ["approve", "send_back", "hand_off", "route", "ask", "cant", "use_tool"];
+export type TurnAction = (typeof TURN_ACTIONS)[number];
+export declare const teammateTurnSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        approve: "approve";
+        ask: "ask";
+        cant: "cant";
+        hand_off: "hand_off";
+        route: "route";
+        send_back: "send_back";
+        use_tool: "use_tool";
+    }>;
+    answer: z.ZodString;
+    text: z.ZodString;
+    note: z.ZodString;
+    question: z.ZodString;
+    options: z.ZodArray<z.ZodString>;
+    reason: z.ZodString;
+    tool: z.ZodString;
+    input: z.ZodString;
+    remember: z.ZodString;
+}, z.core.$strip>;
+export type TurnAnswer = z.infer<typeof teammateTurnSchema>;
+/** What Claude's `--json-schema` is for a turn: the turn schema, exactly. */
+export declare const TURN_MODEL_SCHEMA: Readonly<Record<string, unknown>>;
+/** Older and plain-text turns default absent or non-text fields to "", and keep only string options. */
+export declare function readTurnAnswer(value: unknown): ContractResult<TurnAnswer>;

package/dist/contracts/teammate-turn.js

@@ -0,0 +1,51 @@
+/**
+ * A teammate's turn (teammates.ts): one schema for the JSON Schema Claude answers in (`--json-schema`) and the reader
+ * that takes the answer back. One flat object with every field (a root union is refused by the API); fields a turn
+ * does not use are "" (or [] for options).
+ *
+ * The text limits (TURN_LIMITS, from TEXT_LIMITS) are deliberately not in the schema: the CLI refuses an answer a few
+ * characters over one whole, so they are checked after parsing and an answer over one is asked once to shorten
+ * (teammate-work.ts), then kept whole. What the zone allows — which actions, which answers, a note for a send-back, a
+ * question for an ask, a tool for a tool call — is checked after parsing too (`readTurn`), by path.
+ *
+ * A turn is kept as the step's decision (`flow_step_run.decision_json`) as it was read, so a saved one is this shape.
+ */
+import { z } from "zod";
+import { parseContract, toModelSchema } from "./contract.js";
+/** What a teammate may do on one turn. A decision zone: approve, send back, or hand it to a person. A work zone: pick
+ * where it goes, ask its person, or say it can't. v94: "use_tool" asks for one tool call. */
+export const TURN_ACTIONS = ["approve", "send_back", "hand_off", "route", "ask", "cant", "use_tool"];
+export const teammateTurnSchema = z.object({
+    action: z.enum(TURN_ACTIONS),
+    /** route: one of the zone's answers, exactly as written. */
+    answer: z.string(),
+    /** What the next zones read, or the draft as rewritten. */
+    text: z.string(),
+    /** A decision or send-back note. */
+    note: z.string(),
+    /** ask: one short question, with up to 4 options to tap. */
+    question: z.string(),
+    options: z.array(z.string()),
+    /** One plain sentence saying why, for its manager's log. */
+    reason: z.string(),
+    /** use_tool: the tool's name, and its input as a JSON object written as text. */
+    tool: z.string(),
+    input: z.string(),
+    /** v95: one short fact worth keeping for later cards ("": none). */
+    remember: z.string(),
+});
+/** What Claude's `--json-schema` is for a turn: the turn schema, exactly. */
+export const TURN_MODEL_SCHEMA = toModelSchema(teammateTurnSchema);
+/** Older and plain-text turns default absent or non-text fields to "", and keep only string options. */
+export function readTurnAnswer(value) {
+    if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const body = { ...value };
+        for (const key of Object.keys(teammateTurnSchema.shape)) {
+            if (key !== "action" && key !== "options" && typeof body[key] !== "string")
+                body[key] = "";
+        }
+        body["options"] = Array.isArray(body["options"]) ? body["options"].filter(one => typeof one === "string") : [];
+        value = body;
+    }
+    return parseContract(teammateTurnSchema, value);
+}

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

@@ -0,0 +1,14 @@
+/**
+ * A Teams button tap (teams-chat.ts `receiveTeams`): an Adaptive Card `Action.Submit` arrives as a message activity
+ * whose `value` is the data Toolroll put on the button, `{ so: <one-time token> }`. The activity is Microsoft's (read
+ * by `receiveTeams`); only `value.so` is read, as before, and extra submit keys are ignored. A tap from the paired person whose data can't be read
+ * is answered with why (`value.so: must be a Toolroll button token`), and nothing is done.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+export declare const teamsSubmitSchema: z.ZodObject<{
+    so: z.ZodString;
+}, z.core.$strip>;
+export type TeamsSubmit = z.infer<typeof teamsSubmitSchema>;
+/** A submit's one-time token. */
+export declare function readTeamsSubmit(value: unknown): ContractResult<string>;