toolroll 0.9.36 → 0.9.37

package/dist/discord-chat.js

@@ -5,7 +5,9 @@ import { chatFlowButtons } from "./chat-flow.js";
 import { refuseResultShots, resultShotsPruned, shotWaitsUntil } from "./result-shots.js";
 import { channelInbox } from "./chat-inbox.js";
 import { roomCommand } from "./chat-rooms.js";
-import { ChatState, ChatDeliveryError, chatHash, } from "./chat-delivery-state.js";
+import { ChatState, ChatDeliveryError, chatHash, partContent, } from "./chat-delivery-state.js";
+import { readChatPart } from "./contracts/chat-content.js";
+import { readDiscordButtonToken, readDiscordComponentInteraction } from "./contracts/discord-callback.js";
 import { processChatEvent, planChatNotifications, channelAccess, chatObject as object, planRoomMessages, } from "./chat-delivery.js";
 import { chatResultHref } from "./chat-controls.js";
 import { MATE_MESSAGE_MAX_CHARS } from "./mate.js";
@@ -69,21 +71,25 @@ export function receiveDiscord(state, identity, type, raw, now) {
             };
     }
     else if (type === "INTERACTION_CREATE") {
-        const data = object(body.data), message = object(body.message);
-        if (body.type !== 3 ||
-            body.application_id !== identity.app ||
-            (isRoom ? object(body.channel).type !== 0 : object(body.channel).type !== 1) ||
-            object(message.author).id !== identity.bot ||
-            message.channel_id !== body.channel_id ||
-            !/^so_[a-f0-9]{32}$/.test(String(data.custom_id)))
+        // Only a tap on one of this bot's own messages, in a DM (or a followed guild text channel), from this app.
+        const interaction = readDiscordComponentInteraction(body);
+        if (!interaction.ok)
             return false;
-        member = isRoom ? object(object(body.member).user).id : object(body.user).id;
-        channel = body.channel_id;
-        id = body.id;
-        ts = message.id;
-        thread = message.id;
+        const tap = interaction.value;
+        if (tap.application_id !== identity.app ||
+            tap.channel.type !== (isRoom ? 0 : 1) ||
+            tap.message.author.id !== identity.bot ||
+            tap.message.channel_id !== tap.channel_id)
+            return false;
+        member = isRoom ? tap.member?.user.id : tap.user?.id;
+        channel = tap.channel_id;
+        id = tap.id;
+        ts = tap.message.id;
+        thread = tap.message.id;
         kind = "action";
-        payload = { token: String(data.custom_id).slice(3) };
+        // A button that isn't one Toolroll made is answered with why, once the tap is proved to be the paired person's below.
+        const button = readDiscordButtonToken(tap);
+        payload = button.ok ? { token: button.value } : { problem: button.issues.map(issue => issue.line).join("; ") };
     }
     else
         return false;
@@ -94,9 +100,10 @@ export function receiveDiscord(state, identity, type, raw, now) {
         !discordId(thread) ||
         member === identity.bot)
         return false;
+    const words = "text" in payload ? payload.text ?? "" : "";
     // v89: a channel that feeds a flow takes anyone's message (as a card, with no say over anything); "flow 12" connects one.
-    const inbox = isRoom && kind === "message" ? channelInbox(state.store, "discord", identity.installation, String(channel), String(payload.text ?? "")) : { watched: false, command: false };
-    const roomish = isRoom && (state.room(identity.installation, String(channel)) !== null || (kind === "message" && roomCommand(String(payload.text ?? "")) !== null) || inbox.watched || inbox.command);
+    const inbox = isRoom && kind === "message" ? channelInbox(state.store, "discord", identity.installation, String(channel), words) : { watched: false, command: false };
+    const roomish = isRoom && (state.room(identity.installation, String(channel)) !== null || (kind === "message" && roomCommand(words) !== null) || inbox.watched || inbox.command);
     if (isRoom && !roomish)
         return false;
     const binding = state.bindingFor(identity.installation, member);
@@ -116,7 +123,7 @@ export function receiveDiscord(state, identity, type, raw, now) {
         member,
         ts,
         thread,
-        payload: JSON.stringify(payload),
+        payload,
         created: now.toISOString(),
     });
 }
@@ -200,7 +207,7 @@ export async function deliverDiscordPart(options) {
         const session = event.session === null ? null : store.getMateSession(event.session), repos = await channelAccess(shared, binding, session?.ceilingDigest);
         if (event.kind === "notice" && options.canNotify?.() === false)
             return false;
-        const content = JSON.parse(row.payload);
+        const content = partContent(row.payload);
         const destination = content.channel ?? binding.channel;
         if (content.task &&
             !repos.includes(store.lookupRef(content.task)?.repo ?? ""))
@@ -398,9 +405,13 @@ export async function deliverDiscordPart(options) {
         return true;
     }
     catch (error) {
+        if (error instanceof ChatDeliveryError && error.permanent) {
+            state.prepare("UPDATE chat_part SET state='dropped',next_at=NULL,problem=? WHERE id=?").run(error.message, row.id);
+            return true;
+        }
         // No permission to attach files here: one plain line instead of the result's screenshots.
-        const content = JSON.parse(row.payload);
-        if (content.image && content.shot && error instanceof DiscordError && error.code === DISCORD_REFUSED) {
+        const saved = readChatPart(row.payload), content = saved.ok ? saved.value : null;
+        if (content !== null && content.image && content.shot && error instanceof DiscordError && error.code === DISCORD_REFUSED) {
             refuseResultShots(state, store, row, content, "Discord", options.clock?.() ?? new Date());
             return true;
         }

package/dist/flow-engine.js

@@ -19,6 +19,7 @@ import { cardFollowers, notifyPeople } from "./flow-people.js";
 import { DRAFT_CHARS, keptDraft } from "./flow-draft.js";
 import { chooseStep, flowPersonOf, sendStep } from "./flow-send.js";
 import { parseSoul, teammateLabel } from "./teammates.js";
+import { withStageHandoff } from "./contracts/stage-output.js";
 /** The flow's drawing, or null when it can't be read (the card then says so and waits). */
 export function flowDefinitionOf(flow) {
     try {
@@ -302,7 +303,7 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
             const checks = assignmentOf(store, current, now, { principal: "operator", repos: [repo] }, options.evidenceRoot)?.receipt?.checks ?? null;
             if (checks?.status === "failed") {
                 const said = `The checks failed on its result: ${checks.detail}`;
-                store.updateFlowCard(card.id, { outputs: { ...card.outputs, [stage.id]: `${said} (task ${current})` }, primaryTask: current }, now);
+                store.updateFlowCard(card.id, { outputs: withStageHandoff(card.outputs, stage.id, { text: `${said} (task ${current})` }), primaryTask: current }, now);
                 if (stage.onFail !== null)
                     onward("fail", said);
                 else if (card.waiting !== `${said} Look at the result, then move the card on or back.`)
@@ -310,27 +311,21 @@ function workStage(store, flow, definition, stage, card, now, options, outcome,
                 return;
             }
         }
-        const outputs = { ...card.outputs };
+        let handoff = { text: `Result ready on task ${current}.` };
         if (stage.kind === "report") {
             const ref = store.lookupRef(current);
             const summary = ref === null ? null : reportSummaryFor(store, options.evidenceRoot, ref.id);
-            // The summary whole (a report's summary is within TEXT_LIMITS.reportSummary bytes; an older, longer one is linked).
-            outputs[stage.id] = summary !== null && "summary" in summary ? passOn(summary.summary, TEXT_LIMITS.stageOutput, { label: `task ${current}`, href: null }).text : "The report is ready on its task.";
             // {{stage.<id>.items}} and {{stage.<id>.report}}: what it found and the whole report, for the zones after it.
             // A visit's report replaces the last visit's, so nothing stale is left behind.
             const view = ref === null || options.evidenceRoot === undefined ? null : readVerifiedReport(store, options.evidenceRoot, ref.id);
             const found = view?.ok === true ? reportFillIns(view.report) : { items: "", report: "" };
-            for (const [part, text] of Object.entries(found)) {
-                if (text === "")
-                    delete outputs[`${stage.id}.${part}`];
-                else
-                    outputs[`${stage.id}.${part}`] = text;
-            }
-        }
-        else {
-            outputs[stage.id] = `Result ready on task ${current}.`;
+            handoff = {
+                // The summary whole (a report's summary is within TEXT_LIMITS.reportSummary bytes; an older, longer one is linked).
+                text: summary !== null && "summary" in summary ? passOn(summary.summary, TEXT_LIMITS.stageOutput, { label: `task ${current}`, href: null }).text : "The report is ready on its task.",
+                ...(found.items === "" ? {} : { items: found.items }), ...(found.report === "" ? {} : { report: found.report }),
+            };
         }
-        store.updateFlowCard(card.id, { outputs, ...(stage.kind === "task" ? { primaryTask: current } : {}), waiting: null }, now);
+        store.updateFlowCard(card.id, { outputs: withStageHandoff(card.outputs, stage.id, handoff), ...(stage.kind === "task" ? { primaryTask: current } : {}), waiting: null }, now);
         // A "Send to me" or "Person chooses" zone next reads what this task produced: the task goes with the card there.
         const following = stage.next === null ? undefined : flowDefinitionStage(definition, stage.next);
         onward("ok", undefined, following?.kind === "send" || following?.kind === "choose" ? current : undefined);
@@ -380,8 +375,10 @@ function goalCuts(store, taskId, goal) {
         if (seen.has(match[1]))
             continue;
         seen.add(match[1]);
-        const text = fillFlowText(`{{${match[1]}}}`, card);
-        if (text === "" || goal.includes(text))
+        // An output too long to pass on is kept whole on the card (src/contracts/stage-output.ts): the agent gets it whole.
+        const whole = match[2] !== undefined && match[3] === undefined ? card.attached[match[2]] : undefined;
+        const text = whole ?? fillFlowText(`{{${match[1]}}}`, card);
+        if (text === "" || (whole === undefined && goal.includes(text)))
             continue;
         cuts.push({ label: flowValueLabel(match[1], id => titleIn(definition, id)), text: text.slice(0, FLOW_ATTACHED_LIMIT) });
     }
@@ -496,7 +493,7 @@ export function decideFlowCard(store, input, now) {
             return { ok: false, message: `Keep the draft to ${DRAFT_CHARS.toLocaleString("en-US")} characters; this is ${input.draft.trim().length.toLocaleString("en-US")}.` };
         }
         if (draft !== null && typeof input.draft === "string" && input.draft.trim() !== "" && input.draft.trim() !== card.outputs[draft.id]?.trim()) {
-            store.updateFlowCard(card.id, { outputs: { ...card.outputs, [draft.id]: keptDraft(input.draft) } }, now);
+            store.updateFlowCard(card.id, { outputs: withStageHandoff(card.outputs, draft.id, { text: keptDraft(input.draft) }) }, now);
             store.addFlowComment({ card: card.id, author: input.actor, body: "Edited the draft before approving it.", mentions: [] }, now);
         }
         if (stage.next === null) {

package/dist/flow-items.d.ts

@@ -8,17 +8,10 @@
  * in its own format. Its words go through the channel's own cleaner first. Fitted to a channel's limit, each why is
  * shortened evenly first; then the summary, then the titles; past that it is split into parts. Links are never cut.
  */
-export type FlowSendItem = {
-    title: string;
-    why: string;
-    url: string;
-    /** Where the link goes, by name: "Mobbin", "Linear", "Apple". */
-    source: string;
-    /** One line: how it plugs in (from the why, else the image's own caption). */
-    plug: string;
-    /** The item's screenshot (its evidence id in the report's run), when it has one. */
-    shot: number | null;
-};
+import type { FlowSendItem } from "./contracts/flow-send.js";
+/** One item as the message lists it, and kept items read back (src/contracts/flow-send.ts). */
+export type { FlowSendItem };
+export { readFlowItems } from "./contracts/flow-send.js";
 /** A link's source by name: a few known sites as they write themselves, else the site's own name from its address. */
 export declare function itemSource(url: string): string;
 /** A why as plain lines: its own lines, or "the pattern; why it fits us; how it plugs in" one to a line. */
@@ -42,5 +35,3 @@ export declare function cleanFlowMessage(message: FlowMessage, clean: (text: str
  * blocks (else between lines). Every link stays.
  */
 export declare function fitFlowMessage(message: FlowMessage, limit: number, measure: (shaped: string) => number): string[];
-/** Items read back from a kept content; anything malformed is left out. */
-export declare function readFlowItems(raw: unknown): FlowSendItem[];

package/dist/flow-items.js

@@ -8,6 +8,7 @@
  * in its own format. Its words go through the channel's own cleaner first. Fitted to a channel's limit, each why is
  * shortened evenly first; then the summary, then the titles; past that it is split into parts. Links are never cut.
  */
+export { readFlowItems } from "./contracts/flow-send.js";
 const PLUG_CHARS = 160;
 const NAMES = {
     "mobbin.com": "Mobbin", "github.com": "GitHub", "figma.com": "Figma", "dribbble.com": "Dribbble", "behance.net": "Behance",
@@ -135,18 +136,3 @@ export function fitFlowMessage(message, limit, measure) {
         return [compose(message, 0, 0, title)];
     return pack(blocks(message, Infinity, Infinity, Infinity), "\n\n", fits, block => pack(block.split("\n"), "\n", fits, line => chop(line, fits)));
 }
-/** Items read back from a kept content; anything malformed is left out. */
-export function readFlowItems(raw) {
-    if (!Array.isArray(raw))
-        return [];
-    return raw.flatMap((one) => {
-        if (typeof one !== "object" || one === null)
-            return [];
-        const item = one;
-        const text = (key) => typeof item[key] === "string" ? item[key] : null;
-        const [title, why, url, source, plug] = [text("title"), text("why"), text("url"), text("source"), text("plug")];
-        if (title === null || why === null || url === null || source === null || plug === null || !/^https?:\/\//.test(url))
-            return [];
-        return [{ title, why, url, source, plug, shot: typeof item["shot"] === "number" && Number.isSafeInteger(item["shot"]) ? item["shot"] : null }];
-    });
-}

package/dist/flow-send.d.ts

@@ -1,5 +1,5 @@
 import { type FlowDecision } from "./flow-engine.js";
-import { type FlowSendItem } from "./flow-items.js";
+import { type FlowChoiceAnswer, type FlowSendContent, type FlowSendLink } from "./contracts/flow-send.js";
 import { type FlowDefinition, type FlowStage } from "./flows.js";
 import { type FlowCardRow, type FlowRow, type Store } from "./store.js";
 /** The notice a "Send to me" visit sends: `flow-send:<card>:<entry>`. */
@@ -8,39 +8,14 @@ export declare const FLOW_SEND_KEY: RegExp;
 export declare const FLOW_CHOOSE_KEY: RegExp;
 /** What the person is asked under the buttons. */
 export declare const REPLY_ASK = "Or reply with what you'd change.";
-export type FlowSendLink = {
-    label: string;
-    path: string;
-} | {
-    label: string;
-    url: string;
-};
-export type FlowSendContent = {
-    /** The card's title and the step it comes from. */
-    title: string;
-    /** The step it comes from, when known. */
-    from?: string;
-    summary: string;
-    links: FlowSendLink[];
-    /** The build's result whose screenshots go with it, when it saved any. */
-    shots: {
-        taskId: string;
-        run: number;
-    } | null;
-    /** After research: the report's items, numbered in this order in every message and screenshot caption (flow-items.ts). */
-    items?: FlowSendItem[];
-    /** choose: the options as they were offered, and whether a reply is taken. */
-    options?: {
-        choice: number;
-        label: string;
-    }[];
-    reply?: boolean;
-};
+/** A visit's content and its links (src/contracts/flow-send.ts). */
+export type { FlowSendContent, FlowSendLink };
 /** Who a card's "Send to me" and "Person chooses" zones are for: its owner, else the flow's. */
 export declare function flowPersonOf(card: Pick<FlowCardRow, "owner">, flow: Pick<FlowRow, "owner">): string;
 /** What a visit sends its person, worked out from the card as it is now. */
 export declare function flowSendContent(store: Store, flow: FlowRow, definition: FlowDefinition, stage: FlowStage, card: FlowCardRow, now: Date, evidenceRoot?: string): FlowSendContent;
-/** A kept content, read back; null when it can't be. */
+/** A kept content, read back (src/contracts/flow-send.ts: one kept before it carried a version reads as it did); null
+ * when it can't be, and the visit's content is worked out again. */
 export declare function readFlowSend(json: string): FlowSendContent | null;
 /** The words of a sent visit: its title, summary and pull request (the one link that isn't a page of Toolroll's). */
 export declare function flowSendText(content: FlowSendContent): string;
@@ -71,13 +46,7 @@ export declare function flowChoiceAt(store: Store, cardId: number, entry: number
  * reply (`choice` null) that becomes the note for where replies go. `where` names the place it was made, for the card's
  * history and the ledger: "Telegram", "Slack", "the console".
  */
-export declare function chooseFlowCard(store: Store, input: {
-    card: number;
-    entry?: number;
-    choice: number | null;
-    label?: string;
-    to?: string;
-    note: string | null;
+export declare function chooseFlowCard(store: Store, input: FlowChoiceAnswer & {
     actor: string;
     where: string;
     repos: readonly string[];

package/dist/flow-send.js

@@ -17,7 +17,9 @@ import { assignmentOf } from "./assignment.js";
 import { TEXT_LIMITS } from "./text-limits.js";
 import { withActor } from "./actor.js";
 import { flowCardHref, flowDefinitionOf, revisionWithNote } from "./flow-engine.js";
-import { itemPlug, itemSource, readFlowItems } from "./flow-items.js";
+import { itemPlug, itemSource } from "./flow-items.js";
+import { withStageHandoff } from "./contracts/stage-output.js";
+import { flowSendForStore, readFlowChoiceAnswer, readFlowItems, readFlowSendPayload } from "./contracts/flow-send.js";
 import { notifyPeople } from "./flow-people.js";
 import { readVerifiedReport } from "./evidence.js";
 import { FLOW_END, replyTarget } from "./flows.js";
@@ -120,21 +122,18 @@ export function flowSendContent(store, flow, definition, stage, card, now, evide
         ...(options === undefined ? {} : { options, reply: replyTarget(stage) !== null }),
     };
 }
-/** A kept content, read back; null when it can't be. */
+/** A kept content, read back (src/contracts/flow-send.ts: one kept before it carried a version reads as it did); null
+ * when it can't be, and the visit's content is worked out again. */
 export function readFlowSend(json) {
+    let raw;
     try {
-        const raw = JSON.parse(json);
-        if (typeof raw.title !== "string" || typeof raw.summary !== "string" || !Array.isArray(raw.links))
-            return null;
-        if (raw.items === undefined)
-            return raw;
-        const items = readFlowItems(raw.items);
-        const { items: _, ...rest } = raw;
-        return items.length === 0 ? rest : { ...rest, items };
+        raw = JSON.parse(json);
     }
     catch {
         return null;
     }
+    const read = readFlowSendPayload(raw);
+    return read.ok ? read.value : null;
 }
 /** The words of a sent visit: its title, summary and pull request (the one link that isn't a page of Toolroll's). */
 export function flowSendText(content) {
@@ -153,7 +152,7 @@ function keep(store, flow, definition, stage, card, now, evidenceRoot) {
     if (kept !== null && read !== null)
         return { content: read, person: kept.person, fresh: false };
     const content = flowSendContent(store, flow, definition, stage, card, now, evidenceRoot);
-    const fresh = store.recordFlowSend({ card: card.id, entry: card.entry, stage: stage.id, person, contentJson: JSON.stringify(content) }, now);
+    const fresh = store.recordFlowSend({ card: card.id, entry: card.entry, stage: stage.id, person, contentJson: flowSendForStore(content) }, now);
     return { content, person, fresh };
 }
 /** One notice to the person, and its screenshots after it. Never as anyone's own act: they asked for it in the flow. */
@@ -174,7 +173,7 @@ export function sendStep(store, flow, definition, stage, card, now, evidenceRoot
     const { content, person, fresh } = keep(store, flow, definition, stage, card, now, evidenceRoot);
     if (!fresh)
         return;
-    store.updateFlowCard(card.id, { outputs: { ...card.outputs, [stage.id]: flowSendText(content) } }, now);
+    store.updateFlowCard(card.id, { outputs: withStageHandoff(card.outputs, stage.id, { text: flowSendText(content) }) }, now);
     enqueue(store, flow, card, person, content, { key: `flow-send:${card.id}:${card.entry}`, kind: "flow-card", attention: false,
         subject: `${flow.name}: ${content.title}`, body: [content.summary, ...content.links.filter((one) => "url" in one).map(one => `${one.label}: ${one.url}`)].join("\n\n") }, now);
 }
@@ -217,11 +216,16 @@ const via = (where) => where === "" ? "" : ` in ${where}`;
  * history and the ledger: "Telegram", "Slack", "the console".
  */
 export function chooseFlowCard(store, input, now) {
-    const card = store.getFlowCard(input.card);
+    // The answer itself (src/contracts/flow-send.ts): an option that isn't one of the places offered is a changed option.
+    const { actor: _actor, where: _where, repos: _repos, evidenceRoot: _root, ...given } = input;
+    const answer = readFlowChoiceAnswer(given);
+    if (!answer.ok)
+        return { ok: false, message: answer.issues.every(one => one.path === "choice") ? "Those options changed since; nothing was changed." : "That card is no longer waiting." };
+    const card = store.getFlowCard(answer.value.card);
     const flow = card === null ? null : store.getFlow(card.flow);
     if (card === null || flow === null || card.state !== "active" || !input.repos.includes(flow.repo))
         return { ok: false, message: "That card is no longer waiting." };
-    const visit = flowChoiceAt(store, card.id, input.entry ?? card.entry);
+    const visit = flowChoiceAt(store, card.id, answer.value.entry ?? card.entry);
     if (visit === null)
         return { ok: false, message: "That card has moved on since; nothing was changed." };
     const { stage, definition, person } = visit;

package/dist/flow-share.js

@@ -22,6 +22,7 @@ import { readFlowSecrets } from "./flow-secrets.js";
 import { scriptDigest, validateScript } from "./flow-scripts.js";
 import { addFlowTriggerTo, describeTrigger, HOOK_PATH, readHooksBase, triggerConfigOf, validateTriggerConfig } from "./flow-triggers.js";
 import { durationMinutes, durationWords, FlowContractError, flowTerms, inStepWords, LANGUAGE_WORDS, validateFlowDefinition } from "./flows.js";
+import { stageReferenceProblems } from "./contracts/stage-output.js";
 import { readVersioned } from "./contracts/contract.js";
 import { FLOW_ALIASES, FLOW_FILE_FORMAT, FLOW_FILE_VERSION, flowFileSchema, PARAMETER_ID } from "./contracts/flow.js";
 import { parseSchedule } from "./routine.js";
@@ -319,7 +320,12 @@ function definitionOf(zones) {
     const stages = zones.map((step, index) => stageInputOf(step, index, find));
     // Its zones are the file's, in order: a zone's problem names the file's zone.
     try {
-        return validateFlowDefinition({ version: 1, start: stages[0]?.["id"], stages });
+        const definition = validateFlowDefinition({ version: 1, start: stages[0]?.["id"], stages });
+        // An imported flow is a new one: each {{stage.…}} must be one its zone hands on.
+        const references = stageReferenceProblems(definition, null);
+        if (references.length > 0)
+            throw new FlowContractError(references.map(one => one.line));
+        return definition;
     }
     catch (error) {
         return refuse(error instanceof FlowContractError ? error.lines.map(line => inStepWords(line, "zones", zones.map(one => typeof one["kind"] === "string" ? one["kind"] : undefined))).join("\n") : error instanceof Error ? error.message : "Those zones aren't a flow.");

package/dist/flow-sort.d.ts

@@ -1,29 +1,8 @@
-import { type FlowSort, type FlowStage } from "./flows.js";
+import { type SortDecision } from "./contracts/sort-answer.js";
+import type { FlowSort, FlowStage } from "./flows.js";
 export declare const JEV_URL = "https://openrouter.ai/api/alpha/decisions";
 export declare const JEV_MODEL = "~typesafe/jev-latest";
-export type SortNoteAnswer = {
-    id: string;
-    question: string;
-    kind: "score" | "yes-no";
-    answer: string;
-    sure: number;
-};
-/** What a sort step decided, kept on its run (decision_json) and shown on the card. */
-export type SortDecision = {
-    model: string;
-    /** The answer as the zone names it, and how sure Jev was (0–1). */
-    answer: string;
-    sure: number;
-    sureAt: number;
-    /** Sure enough to act alone, and where the card went (null: it waited in the zone). */
-    confident: boolean;
-    to: string | null;
-    /** Every answer's chance, by name. */
-    chances: Record<string, number>;
-    notes: SortNoteAnswer[];
-    cost: number | null;
-    ms: number;
-};
+export type { SortDecision, SortNoteAnswer } from "./contracts/sort-answer.js";
 export type SortCard = {
     title: string;
     description: string | null;
@@ -67,7 +46,10 @@ export type JevAsked = {
 };
 /** Ask Jev through OpenRouter. Trouble reaching it (or a refused key, or no credit) is a reason to try again, in words. */
 export declare function askJev(fetcher: typeof fetch, key: string, request: JevRequest): Promise<JevAsked>;
-/** Jev's answers, read back against the zone's own options only; anything else is a problem, never a route. */
+/**
+ * Jev's answers, read through the reply's contract (src/contracts/sort-answer.ts) and then against the zone's own
+ * options only; anything else is a problem, never a route. Confidences and chances are clamped into 0–1.
+ */
 export declare function readJevAnswers(stage: FlowStage, body: Record<string, unknown>, ms: number): SortDecision | {
     problem: string;
 };
@@ -79,4 +61,3 @@ export declare function sortLog(stage: FlowStage, decision: SortDecision): strin
 export declare function parseSortDecision(json: string | null): SortDecision | null;
 /** A card's chip on the canvas: the answer and how sure, and the first score's short level. */
 export declare function sortChip(decision: SortDecision): string;
-export {};

package/dist/flow-sort.js

@@ -8,7 +8,8 @@
  * is instructions: an answer is only ever one of the zone's own options.
  */
 import { redactSecretLines, scanForSecrets } from "./evidence.js";
-import { sortKeyOf } from "./flows.js";
+import { SORT_ROUTE_KEY, sortKeyOf, sortNoteKeyOf } from "./contracts/flow.js";
+import { readJevReply } from "./contracts/sort-answer.js";
 export const JEV_URL = "https://openrouter.ai/api/alpha/decisions";
 export const JEV_MODEL = "~typesafe/jev-latest";
 /** Jev reads up to 32,000 tokens; the card is kept well under that. */
@@ -39,10 +40,10 @@ export function sortState(card, earlier) {
 /** The one request for a card: the zone's question over its answers, plus what it also notes. */
 export function sortRequest(sort, state) {
     const questions = {
-        route: { type: "choice", instructions: `${sort.question} Read the card's title and details.`, criteria: Object.fromEntries(sort.answers.map(one => [sortKeyOf(one.answer), one.means])) },
+        [SORT_ROUTE_KEY]: { type: "choice", instructions: `${sort.question} Read the card's title and details.`, criteria: Object.fromEntries(sort.answers.map(one => [sortKeyOf(one.answer), one.means])) },
     };
     for (const note of sort.notes) {
-        questions[`note_${note.id.replace(/-/g, "_")}`] = note.kind === "score" && note.levels !== null
+        questions[sortNoteKeyOf(note.id)] = note.kind === "score" && note.levels !== null
             ? { type: "score", instructions: note.question, criteria: note.levels }
             : { type: "noul", instructions: note.question };
     }
@@ -80,38 +81,42 @@ export async function askJev(fetcher, key, request) {
     return { ok: true, body, ms: Date.now() - started };
 }
 const shortLevel = (level) => level.split(":")[0].trim();
-/** Jev's answers, read back against the zone's own options only; anything else is a problem, never a route. */
+/**
+ * Jev's answers, read through the reply's contract (src/contracts/sort-answer.ts) and then against the zone's own
+ * options only; anything else is a problem, never a route. Confidences and chances are clamped into 0–1.
+ */
 export function readJevAnswers(stage, body, ms) {
     const sort = stage.sort;
-    const answers = body["answers"];
-    const route = answers?.["route"];
-    if (route === undefined || typeof route["choice"] !== "string")
-        return { problem: "Jev's answer didn't say which way to go." };
-    const picked = sort.answers.find(one => sortKeyOf(one.answer) === route["choice"]);
+    const read = readJevReply(body);
+    if (!read.ok)
+        return { problem: `Jev's answer didn't say which way to go (${read.issues.map(issue => issue.line).join("; ")}).` };
+    const reply = read.value;
+    const route = reply.answers[SORT_ROUTE_KEY];
+    const picked = sort.answers.find(one => sortKeyOf(one.answer) === route.choice);
     if (picked === undefined)
-        return { problem: "Jev picked an answer this zone doesn't have." };
+        return { problem: "answers.route.choice: Jev picked an answer this zone doesn't have." };
     const number = (value) => typeof value === "number" && Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 0;
-    const sure = number(route["confidence"]);
-    const probabilities = (route["probabilities"] ?? {});
+    const sure = number(route.confidence);
+    const probabilities = (route.probabilities ?? {});
     const chances = Object.fromEntries(sort.answers.map(one => [one.answer, Math.round(number(probabilities[sortKeyOf(one.answer)]) * 100) / 100]));
     const notes = [];
     for (const note of sort.notes) {
-        const said = answers?.[`note_${note.id.replace(/-/g, "_")}`];
+        const said = reply.answers[sortNoteKeyOf(note.id)];
         if (said === undefined)
             continue;
-        if (note.kind === "score" && note.levels !== null && typeof said["score"] === "number") {
-            const level = note.levels[Math.min(note.levels.length - 1, Math.max(0, Math.round(said["score"])))];
-            notes.push({ id: note.id, question: note.question, kind: "score", answer: level, sure: Math.round(number(said["confidence"]) * 100) / 100 });
+        if (note.kind === "score" && note.levels !== null && typeof said.score === "number") {
+            const level = note.levels[Math.min(note.levels.length - 1, Math.max(0, Math.round(said.score)))];
+            notes.push({ id: note.id, question: note.question, kind: "score", answer: level, sure: Math.round(number(said.confidence) * 100) / 100 });
         }
-        else if (typeof said["noul"] === "number") {
-            const yes = number(said["noul"]);
+        else if (typeof said.noul === "number") {
+            const yes = number(said.noul);
             notes.push({ id: note.id, question: note.question, kind: "yes-no", answer: yes >= 0.5 ? "yes" : "no", sure: Math.round(Math.max(yes, 1 - yes) * 100) / 100 });
         }
     }
     const confident = sure >= sort.sureAt;
-    const usage = body["usage"];
+    const usage = reply.usage;
     return {
-        model: typeof body["model"] === "string" ? body["model"] : JEV_MODEL,
+        model: typeof reply.model === "string" ? reply.model : JEV_MODEL,
         answer: picked.answer, sure: Math.round(sure * 100) / 100, sureAt: sort.sureAt,
         confident, to: confident ? picked.to : stage.onFail, chances, notes,
         cost: typeof usage?.cost === "number" ? usage.cost : null, ms,

package/dist/flow-steps.js

@@ -44,6 +44,7 @@ import { ASKED, teammateReady, teammateTurn } from "./teammate-work.js";
 import { budgetHoldWords, claudeMachineBilling, monthOf } from "./spend.js";
 import { toolRefusal } from "./policy.js";
 import { pullRequestStep } from "./flow-pull-request.js";
+import { withStageHandoff } from "./contracts/stage-output.js";
 const RETRY_MS = [5 * 60_000, 15 * 60_000];
 /** A teammate's turn tries again sooner: a card waiting on a person's colleague shouldn't wait long for a hiccup. */
 const TEAMMATE_RETRY_MS = [60_000, 5 * 60_000];
@@ -248,12 +249,12 @@ function settle(store, definition, stage, card, outcome, now, durationMs) {
     }
     store.finishFlowStep(card.id, card.entry, { state: outcome.state === "passed" ? "passed" : "failed", result: outcome.said, ...kept }, now);
     // What the steps after it read: whole up to TEXT_LIMITS.stageOutput; longer is attached whole to the card's discussion,
-    // and they read a link to it. Never cut.
+    // and they read a link to it, while a task filed after it is given it whole (the card keeps it attached). Never cut.
     const whole = outcome.output ?? outcome.said;
     const passed = passOn(whole, TEXT_LIMITS.stageOutput, { label: "the card's discussion", href: flowCardHref(card.flow, card.id) });
     if (passed.kept)
         store.addFlowComment({ card: card.id, author: "flow", body: `What ${stage.title} produced, in full (${whole.length.toLocaleString("en-US")} characters):\n\n${whole}`, mentions: [] }, now);
-    store.updateFlowCard(card.id, { outputs: { ...card.outputs, [stage.id]: passed.text }, waiting: null }, now);
+    store.updateFlowCard(card.id, { outputs: withStageHandoff(card.outputs, stage.id, { text: passed.text }), ...(passed.kept ? { attached: { [stage.id]: whole } } : {}), waiting: null }, now);
     const titleOf = (id) => definition.stages.find(one => one.id === id)?.title ?? "another zone";
     if (outcome.state === "passed") {
         // A sort names where the card goes; one it isn't sure about is a person's to place.

package/dist/flows.d.ts

@@ -1,6 +1,6 @@
 import { type ContractIssue, type ContractResult } from "./contracts/contract.js";
-import { CHOICES_MAX, CHOICES_MIN, FLOW_COLORS, FLOW_END, FLOW_MERGE_METHODS, FLOW_STAGE_KINDS, LONGEST_WAIT_MINUTES, SCRIPT_LANGUAGES, SCRIPT_NAME, type FlowDefinition, type FlowStage, type FlowStageKind, type FlowStepFields, type FlowWait, type ScriptLanguage, type TriggerInput } from "./contracts/flow.js";
-export { CHOICES_MAX, CHOICES_MIN, FLOW_COLORS, FLOW_END, FLOW_MERGE_METHODS, FLOW_STAGE_KINDS, LONGEST_WAIT_MINUTES, SCRIPT_LANGUAGES, SCRIPT_NAME };
+import { CHOICES_MAX, CHOICES_MIN, FLOW_COLORS, FLOW_END, FLOW_MERGE_METHODS, FLOW_STAGE_KINDS, LONGEST_WAIT_MINUTES, SCRIPT_LANGUAGES, SCRIPT_NAME, sortKeyOf, type FlowDefinition, type FlowStage, type FlowStageKind, type FlowStepFields, type FlowWait, type ScriptLanguage, type TriggerInput } from "./contracts/flow.js";
+export { CHOICES_MAX, CHOICES_MIN, FLOW_COLORS, FLOW_END, FLOW_MERGE_METHODS, FLOW_STAGE_KINDS, LONGEST_WAIT_MINUTES, SCRIPT_LANGUAGES, SCRIPT_NAME, sortKeyOf };
 export type { FlowChoice, FlowColor, FlowDefinition, FlowEmail, FlowLimit, FlowMergeMethod, FlowRequest, FlowSort, FlowSortAnswer, FlowSortNote, FlowStage, FlowStageKind, FlowStepInput, FlowTool, FlowWait, FlowZone, ScriptLanguage, } from "./contracts/flow.js";
 /** What each kind is called and does, in the words the canvas uses. */
 export declare const FLOW_KIND_WORDS: Record<FlowStageKind, {
@@ -8,8 +8,6 @@ export declare const FLOW_KIND_WORDS: Record<FlowStageKind, {
     about: string;
 }>;
 export declare const LANGUAGE_WORDS: Record<ScriptLanguage, string>;
-/** How an answer is named to Jev: its words as a short key. */
-export declare const sortKeyOf: (answer: string) => string;
 /** The default for "sure enough to act alone". */
 export declare const SORT_SURE_AT = 0.8;
 /** "3 days", "4 hours", "90 minutes", "1 week" (or a number of minutes) as minutes; null when it isn't one. */

package/dist/flows.js

@@ -50,8 +50,9 @@
 import { TEXT_LIMITS } from "./text-limits.js";
 import { createHash } from "node:crypto";
 import { parseContract, readVersioned } from "./contracts/contract.js";
-import { CHOICES_MAX, CHOICES_MIN, FLOW_ALIASES, FLOW_COLORS, FLOW_DEFINITION_VERSION, FLOW_END, FLOW_MERGE_METHODS, FLOW_STAGE_KINDS, flowDefinitionSchema, flowStepsSchema, HEADERS_MAX, LONGEST_WAIT_MINUTES, savedFlowDefinitionSchema, SCRIPT_LANGUAGES, SCRIPT_NAME, SURE_AT_MAX, SURE_AT_MIN, ZONE_ID, } from "./contracts/flow.js";
-export { CHOICES_MAX, CHOICES_MIN, FLOW_COLORS, FLOW_END, FLOW_MERGE_METHODS, FLOW_STAGE_KINDS, LONGEST_WAIT_MINUTES, SCRIPT_LANGUAGES, SCRIPT_NAME };
+import { stageReferenceProblems } from "./contracts/stage-output.js";
+import { CHOICES_MAX, CHOICES_MIN, FLOW_ALIASES, FLOW_COLORS, FLOW_DEFINITION_VERSION, FLOW_END, FLOW_MERGE_METHODS, FLOW_STAGE_KINDS, flowDefinitionSchema, flowStepsSchema, HEADERS_MAX, LONGEST_WAIT_MINUTES, savedFlowDefinitionSchema, SCRIPT_LANGUAGES, SCRIPT_NAME, sortKeyOf, SURE_AT_MAX, SURE_AT_MIN, ZONE_ID, } from "./contracts/flow.js";
+export { CHOICES_MAX, CHOICES_MIN, FLOW_COLORS, FLOW_END, FLOW_MERGE_METHODS, FLOW_STAGE_KINDS, LONGEST_WAIT_MINUTES, SCRIPT_LANGUAGES, SCRIPT_NAME, sortKeyOf };
 /** What each kind is called and does, in the words the canvas uses. */
 export const FLOW_KIND_WORDS = {
     inbox: { label: "Holding", about: "Cards wait here until someone moves them." },
@@ -74,8 +75,6 @@ export const FLOW_KIND_WORDS = {
     done: { label: "Done", about: "The end of the flow." },
 };
 export const LANGUAGE_WORDS = { shell: "Shell", python: "Python", node: "Node" };
-/** How an answer is named to Jev: its words as a short key. */
-export const sortKeyOf = (answer) => answer.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "answer";
 /** The default for "sure enough to act alone". */
 export const SORT_SURE_AT = 0.8;
 const HEADER = /^[A-Za-z0-9][A-Za-z0-9-]{0,63}$/;
@@ -813,8 +812,13 @@ export function flowFromSteps(input, previous = null) {
     });
     // The drawing is checked as the canvas's is; its zones are the steps, in order, so a zone's problem names its step.
     const drawn = readFlowDefinition({ version: FLOW_DEFINITION_VERSION, start: stages[0].id, stages });
+    const refuse = (issues) => new FlowContractError(issues.map(one => inStepWords(one.line, "steps", stages.map(stage => stage.kind))));
     if (!drawn.ok)
-        throw new FlowContractError(drawn.issues.map(one => inStepWords(one.line, "steps", stages.map(stage => stage.kind))));
+        throw refuse(drawn.issues);
+    // A {{stage.…}} these steps add must be one its zone hands on (src/contracts/stage-output.ts); ones the flow had stay.
+    const references = stageReferenceProblems(drawn.value, previous);
+    if (references.length > 0)
+        throw refuse(references);
     return drawn.value;
 }
 /** A choose step's options: each with its words and the step it goes to ("end", or no step, ignores the card); kept ones carry over. */