toolroll 0.9.34 → 0.9.37

package/dist/flow-share.d.ts

@@ -1,39 +1,11 @@
-import { type ScriptDraft } from "./flow-scripts.js";
 import { type FlowDefinition } from "./flows.js";
+import { FLOW_FILE_FORMAT, FLOW_FILE_VERSION, type FlowFile, type FlowFileParameter, type FlowFileScript } from "./contracts/flow.js";
 import type { FlowRow, Store } from "./store.js";
-export declare const FLOW_FILE_FORMAT = "toolroll-flow";
-export declare const FLOW_FILE_VERSION = 1;
+export { FLOW_FILE_FORMAT, FLOW_FILE_VERSION };
+export type { FlowFile, FlowFileParameter, FlowFileScript };
 /** The largest flow file Toolroll reads or fetches. */
 export declare const FLOW_FILE_MAX_BYTES: number;
 export declare const FLOW_FILE_SUFFIX = ".toolroll-flow.json";
-/** Something the import asks for: `{{param.<id>}}` in a zone or trigger is replaced by its value. */
-export type FlowFileParameter = {
-    id: string;
-    about: string;
-    default?: string;
-    optional?: boolean;
-};
-export type FlowFileScript = {
-    name: string;
-    about: string;
-    language: ScriptDraft["language"];
-    timeoutMinutes: number;
-    body?: string;
-    file?: string;
-};
-export type FlowFile = {
-    format: typeof FLOW_FILE_FORMAT;
-    version: typeof FLOW_FILE_VERSION;
-    name: string;
-    about: string;
-    needs: string[];
-    parameters: FlowFileParameter[];
-    /** The zones in the lead's step vocabulary, the start first. */
-    zones: Record<string, unknown>[];
-    /** Each trigger's settings, as `toolroll flows trigger add` takes them. */
-    triggers: Record<string, unknown>[];
-    scripts: FlowFileScript[];
-};
 export type FlowExported = {
     file: FlowFile;
     json: string;
@@ -42,9 +14,15 @@ export type FlowExported = {
 };
 /** A flow as a file: its zones and paths, its triggers' settings and the scripts it runs, nothing of this installation's. */
 export declare function exportFlow(store: Store, flow: FlowRow, dir: string | null): FlowExported;
+/** A flow file refused: why, in plain words, each problem naming its path in the file (`zones[0].routes[0]: ...`). */
 export declare class FlowFileError extends Error {
 }
-/** Read a flow file: its size, its JSON, its format and version, and every zone, trigger, script and parameter. Throws FlowFileError in plain words. */
+/**
+ * Read a flow file: its size, its JSON and format, then its one schema (flowFileSchema: every zone, trigger, script
+ * and parameter, strict about unknown keys — `zones[0].routes[0]: unknown key 'to' (did you mean goesTo?)`), and a
+ * newer version refused plainly. Then what the schema can't say: no keys in a trigger, ids and names used once, each
+ * {{param.x}} declared, every script valid and the zones a flow. Throws FlowFileError in plain words.
+ */
 export declare function parseFlowFile(text: string): FlowFile;
 /** --param k=v lines (or a form's fields) as values; refuses parameters the file doesn't ask for. */
 export declare function parameterValues(file: FlowFile, given: Record<string, string>): Record<string, string>;

package/dist/flow-share.js

@@ -21,29 +21,31 @@ import { flowDefinitionOf } from "./flow-engine.js";
 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, flowTerms, LANGUAGE_WORDS, validateFlowDefinition } from "./flows.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";
-export const FLOW_FILE_FORMAT = "toolroll-flow";
-export const FLOW_FILE_VERSION = 1;
+export { FLOW_FILE_FORMAT, FLOW_FILE_VERSION };
 /** The largest flow file Toolroll reads or fetches. */
 export const FLOW_FILE_MAX_BYTES = 256 * 1024;
 export const FLOW_FILE_SUFFIX = ".toolroll-flow.json";
 const PARAM = /\{\{\s*param\.([a-z0-9][a-z0-9-]{0,39})\s*\}\}/g;
-const PARAM_ID = /^[a-z0-9][a-z0-9-]{0,39}$/;
 const REMOVED = "[removed]";
 // ------------------------------------------------------------------ export
 /** A zone in the lead's words: only what it says, in the order a person reads it. */
 function stepOf(stage, ask) {
     const step = { id: stage.id, title: stage.title, kind: stage.kind };
     const words = (minutes) => durationMinutes(durationWords(minutes)) === minutes ? durationWords(minutes) : minutes;
-    if (stage.instructions !== null)
+    // Only what the step's kind says: words a zone kept from a kind it was before stay behind.
+    if (stage.instructions !== null && (stage.kind === "task" || stage.kind === "report" || stage.kind === "draft" || stage.kind === "teammate"))
         step["instructions"] = stage.instructions;
     if (stage.kind === "task")
         step["planning"] = stage.planning;
     if (stage.kind === "approval")
         step["decider"] = stage.toOwner === true ? "owner" : stage.approver === null ? "anyone"
             : ask({ id: `decider-${stage.id}`.slice(0, 40), about: `Who decides at ${stage.title}: a person's sign-in name, owner (the flow's owner) or anyone`, default: "owner" });
-    if (stage.message !== null)
+    if (stage.message !== null && (stage.kind === "notify" || stage.kind === "update"))
         step["message"] = stage.message;
     if (stage.kind === "update")
         step["close"] = stage.close;
@@ -239,26 +241,28 @@ export function exportFlow(store, flow, dir) {
         format: FLOW_FILE_FORMAT, version: FLOW_FILE_VERSION, name: flow.name,
         about: ordered.map(one => one.title).join(" → "),
         needs: needsOf(definition, triggers, scripts.map(one => one.name)),
-        parameters, zones, triggers, scripts,
+        // Zones and triggers in the file's words (stepOf, triggerOf): what flowFileSchema reads back (flow-share.test.ts).
+        parameters, zones: zones, triggers: triggers, scripts,
     };
     const file = scrubDeep(raw, scrubber(values, names), null, false);
     const slug = flow.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 60) || "flow";
     return { file, json: `${JSON.stringify(file, null, 2)}\n`, fileName: `${slug}${FLOW_FILE_SUFFIX}`, left };
 }
 // ------------------------------------------------------------------ reading
+/** A flow file refused: why, in plain words, each problem naming its path in the file (`zones[0].routes[0]: ...`). */
 export class FlowFileError extends Error {
 }
 const refuse = (message) => { throw new FlowFileError(message); };
 /** A zone from the file as the canvas stores it: references by id (or by title), the rest checked by validateFlowDefinition. */
 function stageInputOf(step, index, find) {
-    const title = typeof step["title"] === "string" ? step["title"] : `zone ${index + 1}`;
+    const at = `zones[${index}]`;
     const kind = step["kind"];
     const object = (key) => {
         const value = step[key];
         if (value === undefined || value === null)
             return undefined;
         if (typeof value !== "object" || Array.isArray(value))
-            refuse(`Zone ${title}: ${key} must be an object.`);
+            refuse(`${at}.${key}: must be an object`);
         return value;
     };
     const list = (key) => {
@@ -266,59 +270,65 @@ function stageInputOf(step, index, find) {
         if (value === undefined || value === null)
             return undefined;
         if (!Array.isArray(value) || value.some(one => one === null || typeof one !== "object" || Array.isArray(one)))
-            refuse(`Zone ${title}: ${key} must be a list.`);
+            refuse(`${at}.${key}: must be a list of objects`);
         return value;
     };
     const decider = step["decider"];
     if (decider !== undefined && decider !== null && typeof decider !== "string")
-        refuse(`Zone ${title}: decider must be plain text.`);
+        refuse(`${at}.decider: must be a string`);
     const toOwner = kind === "approval" && typeof decider === "string" && decider.trim().toLowerCase() === "owner";
     const anyone = decider === undefined || decider === null || (typeof decider === "string" && /^(anyone|any approver|)$/i.test(decider.trim()));
-    const at = object("at") ?? {};
-    const failKey = step["ifNotSure"] ?? step["ifNoReply"] ?? step["ifReplied"] ?? step["ifFails"];
-    const minutes = (value) => value === undefined ? undefined : durationMinutes(value) ?? refuse(`Zone ${title}: say a time like "3 days" (up to 30 days).`);
+    const place = object("at") ?? {};
+    const [failKey, fail] = ["ifNotSure", "ifNoReply", "ifReplied", "ifFails"].map(key => [key, step[key]]).find(([, value]) => value !== undefined && value !== null) ?? ["ifFails", undefined];
+    const minutes = (value, key) => value === undefined ? undefined : durationMinutes(value) ?? refuse(`${at}.${key}: say a time like "3 days" (up to 30 days)`);
     const sureAt = step["sureAt"];
     return {
         id: step["id"], title: step["title"], kind,
-        zone: { x: at["x"], y: at["y"] ?? 0, w: at["w"], h: at["h"], color: at["color"] },
+        zone: { x: place["x"], y: place["y"] ?? 0, w: place["w"], h: place["h"], color: place["color"] },
         instructions: step["instructions"], planning: step["planning"],
         ...(toOwner ? { toOwner: true } : { approver: anyone ? null : decider }),
         message: step["message"], close: step["close"], script: step["script"], runIn: step["runIn"],
-        routes: list("routes")?.map(one => ({ answer: one["answer"], to: find(one["goesTo"], title) })),
+        routes: list("routes")?.map((one, n) => ({ answer: one["answer"], to: find(one["goesTo"], `${at}.routes[${n}].goesTo`) })),
         secrets: step["secrets"],
-        ...(kind === "sort" ? { sort: { question: step["question"], answers: (list("answers") ?? []).map(one => ({ answer: one["answer"], means: one["means"], to: find(one["goesTo"], title) })),
+        ...(kind === "sort" ? { sort: { question: step["question"], answers: (list("answers") ?? []).map((one, n) => ({ answer: one["answer"], means: one["means"], to: find(one["goesTo"], `${at}.answers[${n}].goesTo`) })),
                 sureAt: typeof sureAt === "number" && sureAt > 1 ? sureAt / 100 : sureAt, notes: list("alsoNote") ?? [] } } : {}),
         ...(kind === "request" ? { request: { method: step["method"], url: step["url"], headers: object("headers") ?? {}, body: step["body"] } } : {}),
         ...(kind === "email" ? { email: { to: step["to"], subject: step["subject"], body: step["body"] } } : {}),
         ...(kind === "tool" ? { tool: { server: step["server"], name: step["tool"], args: typeof step["args"] === "object" && step["args"] !== null ? JSON.stringify(step["args"]) : step["args"] } } : {}),
-        ...(kind === "wait" ? { wait: step["waitFor"] === "hours" ? { for: "hours", from: step["from"], to: step["until"], timeZone: step["timeZone"] } : { for: step["waitFor"] ?? "reply", minutes: minutes(step["wait"] ?? "3 days") } } : {}),
+        ...(kind === "wait" ? { wait: step["waitFor"] === "hours" ? { for: "hours", from: step["from"], to: step["until"], timeZone: step["timeZone"] } : { for: step["waitFor"] ?? "reply", minutes: minutes(step["wait"] ?? "3 days", "wait") } } : {}),
         merge: step["merge"], teammate: step["teammate"], reply: step["reply"],
-        ...(kind === "choose" ? { options: (list("options") ?? []).map(one => ({ label: one["label"], to: one["goesTo"] === "end" ? "end" : find(one["goesTo"], title) })) } : {}),
-        ...(step["remindAfter"] === undefined ? {} : { limit: { minutes: minutes(step["remindAfter"]), to: find(step["thenMoveTo"], title) } }),
-        next: find(step["next"], title), onFail: find(failKey, title),
+        ...(kind === "choose" ? { options: (list("options") ?? []).map((one, n) => ({ label: one["label"], to: one["goesTo"] === "end" ? "end" : find(one["goesTo"], `${at}.options[${n}].goesTo`) })) } : {}),
+        ...(step["remindAfter"] === undefined ? {} : { limit: { minutes: minutes(step["remindAfter"], "remindAfter"), to: find(step["thenMoveTo"], `${at}.thenMoveTo`) } }),
+        next: find(step["next"], `${at}.next`), onFail: find(fail, `${at}.${failKey}`),
     };
 }
 /** The zones as a flow, checked whole. Throws in plain words. */
 function definitionOf(zones) {
     const ids = zones.map(one => one["id"]);
-    const find = (ref, from) => {
+    const find = (ref, path) => {
         if (ref === undefined || ref === null || ref === "")
             return null;
         if (typeof ref !== "string")
-            return refuse(`Zone ${from}: a path names a zone by its id.`);
+            return refuse(`${path}: names a zone by its id`);
         const hit = zones.find(one => one["id"] === ref.trim()) ?? zones.find(one => typeof one["title"] === "string" && one["title"].trim().toLowerCase() === ref.trim().toLowerCase());
         if (hit === undefined)
-            return refuse(`Zone ${from}: there's no zone called ${ref}.`);
-        return typeof hit["id"] === "string" ? hit["id"] : refuse(`Zone ${from}: every zone needs an id.`);
+            return refuse(`${path}: there's no zone called ${ref}`);
+        return typeof hit["id"] === "string" ? hit["id"] : refuse(`zones[${zones.indexOf(hit)}].id: required`);
     };
-    if (ids.some(one => typeof one !== "string"))
-        refuse("Every zone needs an id: lowercase letters, numbers and dashes.");
+    ids.forEach((one, index) => { if (typeof one !== "string")
+        refuse(`zones[${index}].id: required`); });
     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 Error ? error.message : "Those zones aren't a flow.");
+        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.");
     }
 }
 const plainText = (value, cap, what, required) => {
@@ -328,17 +338,22 @@ const plainText = (value, cap, what, required) => {
         return refuse(`The file's ${what} must be plain text.`);
     if (value.length > cap)
         return refuse(`The file's ${what} is longer than ${cap} characters.`);
-    if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f‪-‮⁦-⁩]/.test(value))
+    if (/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f\u202a-\u202e\u2066-\u2069]/.test(value))
         return refuse(`The file's ${what} has hidden characters in it.`);
     return value.trim();
 };
-/** Read a flow file: its size, its JSON, its format and version, and every zone, trigger, script and parameter. Throws FlowFileError in plain words. */
+/**
+ * Read a flow file: its size, its JSON and format, then its one schema (flowFileSchema: every zone, trigger, script
+ * and parameter, strict about unknown keys — `zones[0].routes[0]: unknown key 'to' (did you mean goesTo?)`), and a
+ * newer version refused plainly. Then what the schema can't say: no keys in a trigger, ids and names used once, each
+ * {{param.x}} declared, every script valid and the zones a flow. Throws FlowFileError in plain words.
+ */
 export function parseFlowFile(text) {
     if (Buffer.byteLength(text, "utf8") > FLOW_FILE_MAX_BYTES)
         refuse(`That file is too big: a flow file is at most ${FLOW_FILE_MAX_BYTES / 1024} KB.`);
     let raw;
     try {
-        raw = JSON.parse(text.replace(/^/, ""));
+        raw = JSON.parse(text.replace(/^\uFEFF/, ""));
     }
     catch {
         return refuse("That isn't a flow file: it isn't valid JSON.");
@@ -348,75 +363,48 @@ export function parseFlowFile(text) {
     const input = raw;
     if (input["format"] !== FLOW_FILE_FORMAT)
         refuse("That isn't a Toolroll flow file: its format isn't \"toolroll-flow\".");
-    if (input["version"] !== FLOW_FILE_VERSION)
-        refuse(typeof input["version"] === "number" && input["version"] > FLOW_FILE_VERSION
-            ? `This flow file is version ${input["version"]}; this Toolroll reads version ${FLOW_FILE_VERSION}. Update Toolroll, then import it.`
-            : `This flow file has no version Toolroll reads; it should say "version": ${FLOW_FILE_VERSION}.`);
-    const name = plainText(input["name"], 80, "name", true);
-    const about = plainText(input["about"], 600, "about line", false);
-    const array = (key, cap) => {
-        const value = input[key];
-        if (value === undefined || value === null)
-            return [];
-        if (!Array.isArray(value))
-            return refuse(`The file's ${key} must be a list.`);
-        if (value.length > cap)
-            return refuse(`The file has more than ${cap} ${key}.`);
-        return value;
-    };
-    const needs = array("needs", 40).map(one => plainText(one, 80, "needs", true));
-    const parameters = array("parameters", 20).map((one) => {
-        if (one === null || typeof one !== "object" || Array.isArray(one))
-            return refuse("Each parameter is an object with an id and what it asks for.");
-        const row = one;
-        const id = typeof row["id"] === "string" && PARAM_ID.test(row["id"]) ? row["id"] : refuse("Each parameter needs a short id: lowercase letters, numbers and dashes.");
-        const fallback = row["default"] === undefined || row["default"] === null ? undefined : plainText(row["default"], 200, `default for ${id}`, false);
-        return { id, about: plainText(row["about"], 200, `question for ${id}`, true), ...(fallback === undefined ? {} : { default: fallback }), ...(row["optional"] === true ? { optional: true } : {}) };
-    });
-    if (new Set(parameters.map(one => one.id)).size !== parameters.length)
-        refuse("Two parameters have the same id.");
-    const rawZones = array("zones", 24);
-    if (rawZones.length === 0)
-        refuse("The file has no zones.");
-    if (rawZones.some(one => one === null || typeof one !== "object" || Array.isArray(one)))
-        refuse("Each zone is an object with an id, a title and a kind.");
-    const zones = rawZones;
-    const triggers = array("triggers", 10).map(one => {
-        if (one === null || typeof one !== "object" || Array.isArray(one))
-            return refuse("Each trigger is an object with a kind.");
-        const kind = one["kind"];
+    // Triggers that name something on the installation they were made on stay there; say so, not that the kind is unknown.
+    (Array.isArray(input["triggers"]) ? input["triggers"] : []).forEach((one, index) => {
+        const kind = one !== null && typeof one === "object" ? one["kind"] : undefined;
         if (kind === "chat")
-            return refuse("A chat channel trigger can't come from a file: connect the channel from the channel itself.");
+            refuse(`triggers[${index}].kind: a chat channel trigger can't come from a file; connect the channel from the channel itself`);
         if (kind === "flow")
-            return refuse("A trigger from another flow can't come from a file: it names a flow on the installation it was made on.");
-        if (!["button", "schedule", "github", "linear", "webhook", "email", "plane-review"].includes(kind))
-            return refuse(`The file has a trigger Toolroll doesn't know: ${String(kind)}.`);
+            refuse(`triggers[${index}].kind: a trigger from another flow can't come from a file; it names a flow on the installation it was made on`);
+    });
+    const read = readVersioned(flowFileSchema, input, {}, FLOW_ALIASES);
+    if (!read.ok)
+        return refuse(read.issues.map(one => one.line).join("\n"));
+    const file = read.value;
+    const name = file.name.trim(), about = (file.about ?? "").trim();
+    if (name === "")
+        refuse("name: must not be empty");
+    const parameters = (file.parameters ?? []).map(one => ({ ...one, about: one.about.trim(), ...(one.default === undefined ? {} : { default: one.default.trim() }) }));
+    if (new Set(parameters.map(one => one.id)).size !== parameters.length)
+        refuse("parameters: two have the same id");
+    const triggers = file.triggers ?? [];
+    triggers.forEach((one, index) => {
         for (const [key, value] of Object.entries(one))
             if (typeof value === "string" && scanForSecrets(value).length > 0)
-                refuse(`A ${String(kind)} trigger's ${key} looks like a key or password. Keys never go in a flow file.`);
-        return one;
+                refuse(`triggers[${index}].${key}: looks like a key or password; keys never go in a flow file`);
     });
-    const scripts = array("scripts", 20).map((one) => {
-        if (one === null || typeof one !== "object" || Array.isArray(one))
-            return refuse("Each script is an object with a name.");
-        const row = one;
+    const scripts = (file.scripts ?? []).map((row, index) => {
         let draft;
         try {
             draft = validateScript(row);
         }
         catch (error) {
-            return refuse(`Script ${typeof row["name"] === "string" ? row["name"] : "(unnamed)"}: ${error instanceof Error ? error.message : "it isn't valid."}`);
+            return refuse(`scripts[${index}]: ${error instanceof Error ? error.message : "it isn't valid."}`);
         }
         return { name: draft.name, about: draft.about, language: draft.language, timeoutMinutes: draft.timeoutMinutes, ...(draft.file === null ? { body: draft.body } : { file: draft.file }) };
     });
     if (new Set(scripts.map(one => one.name)).size !== scripts.length)
-        refuse("Two scripts have the same name.");
+        refuse("scripts: two have the same name");
     // Every {{param.x}} names a parameter the file declares.
-    for (const match of JSON.stringify([zones, triggers]).matchAll(PARAM))
+    for (const match of JSON.stringify([file.zones, triggers]).matchAll(PARAM))
         if (!parameters.some(one => one.id === match[1]))
             refuse(`The file uses {{param.${match[1]}}} but doesn't say what it asks for.`);
-    definitionOf(zones);
-    return { format: FLOW_FILE_FORMAT, version: FLOW_FILE_VERSION, name, about, needs, parameters, zones, triggers, scripts };
+    definitionOf(file.zones);
+    return { format: FLOW_FILE_FORMAT, version: FLOW_FILE_VERSION, name, about, needs: (file.needs ?? []).map(one => one.trim()), parameters, zones: file.zones, triggers, scripts };
 }
 /** --param k=v lines (or a form's fields) as values; refuses parameters the file doesn't ask for. */
 export function parameterValues(file, given) {

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-starters.d.ts

@@ -1,4 +1,5 @@
 import { type FlowStepInput } from "./flows.js";
+import type { TriggerInput } from "./contracts/flow.js";
 import type { FlowRow, Store } from "./store.js";
 export declare const STARTER_IDS: readonly ["ci-fix", "issue-task", "overnight", "plane-review"];
 export type StarterId = (typeof STARTER_IDS)[number];
@@ -22,7 +23,7 @@ export type StarterFlow = {
     ownSteps?: FlowStepInput[];
     trigger: (where: {
         branch: string;
-    }) => Record<string, unknown>;
+    }) => TriggerInput;
 };
 export declare const STARTER_FLOWS: readonly StarterFlow[];
 /** The morning plane review's steps: find the cause, fix it, open a pull request; any failure waits for a person. */

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.