toolroll 0.9.19 → 0.9.21

package/dist/flows-cli.js

@@ -10,7 +10,7 @@
 import { readFileSync, statSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { envelopeJson } from './envelope.js';
-import { addCardToFlow, advanceFlows, flowDefinitionOf } from './flow-engine.js';
+import { addCardToFlow, advanceFlows, crossProjectProblem, flowDefinitionOf } from './flow-engine.js';
 import { saveScript } from './flow-scripts.js';
 import { exportFlow, fetchFlowFile, FLOW_FILE_MAX_BYTES, FlowFileError, importFlow, parseFlowFile, planFlowImport } from './flow-share.js';
 import { STARTER_FLOWS, starterFlowOf, starterOf, startersFor, starterTerms, switchOnStarter } from './flow-starters.js';
@@ -213,6 +213,9 @@ export async function runFlowsCommand(positional, flags, context) {
         const flowName = name || template?.label || '';
         if (flowName === '')
             return fail('usage', 'Name the flow with --name.', EXIT.usage);
+        const elsewhere = crossProjectProblem(store, definition, { repo: project, owner: who });
+        if (elsewhere !== null)
+            return refuse(project, 'invalid-steps', elsewhere);
         const terms = flowTerms(definition, null);
         if (template?.trigger !== undefined) {
             const draft = { id: 0, repo: project, name: flowName, definitionJson: JSON.stringify(definition), revision: 1, state: 'active', createdBy: who, createdAt: now.toISOString(), updatedBy: who, updatedAt: now.toISOString(), owner: who };
@@ -377,6 +380,9 @@ export async function runFlowsCommand(positional, flags, context) {
         const redrawn = flowDigest(next) !== flowDigest(definition);
         if (!redrawn && name === flow.name)
             return fail('no-change', 'That\'s the flow as it is now.');
+        const elsewhere = crossProjectProblem(store, next, flow, who);
+        if (elsewhere !== null)
+            return refuse(flow.repo, 'invalid-steps', elsewhere);
         if (!flags.has('yes'))
             return preview(flow.repo, `Change the ${flow.name} flow`, [...(name === flow.name ? [] : [`Renames it to ${name}.`]), ...(redrawn ? flowTerms(next, definition) : [])], { flowId: flow.id, revision: flow.revision, definition: next });
         if (!store.saveFlow(flow.id, { name, definitionJson: JSON.stringify(next), sawRevision: flow.revision, by: who }, now))
@@ -454,7 +460,7 @@ function listed(store, flow) {
     const cards = store.flowCards(flow.id, false);
     return { id: flow.id, name: flow.name, repo: flow.repo, project: projectName(flow.repo), zones: definition?.stages.map(one => one.title) ?? [],
         triggers: store.flowTriggers(flow.id).filter(one => one.state === 'active').length, cardsWaiting: cards.length,
-        needDecision: cards.filter(card => definition?.stages.find(one => one.id === card.stage)?.kind === 'approval').length };
+        needDecision: cards.filter(card => ['approval', 'choose'].includes(definition?.stages.find(one => one.id === card.stage)?.kind ?? '')).length };
 }
 /** One zone and every path out of it, by zone id. */
 function zoneOf(stage, flow) {
@@ -468,6 +474,8 @@ function zoneOf(stage, flow) {
         ...(stage.script === null ? {} : { script: stage.script }),
         ...(stage.merge === undefined ? {} : { merge: stage.merge }),
         ...(stage.teammate === undefined ? {} : { teammate: stage.teammate }),
+        ...(stage.options === undefined ? {} : { options: stage.options.map(one => ({ label: one.label, to: one.to })) }),
+        ...(stage.repo === undefined ? {} : { repo: stage.repo }),
     };
 }
 function cardOf(definition, card) {
@@ -499,7 +507,7 @@ function showLines(flow) {
             ...('answers' in zone && zone.answers !== undefined ? zone.answers.map(one => `     ${one.answer} → ${title(one.to)}`) : []),
             ...('routes' in zone && zone.routes !== undefined ? zone.routes.map(one => `     ${one.answer} → ${title(one.to)}`) : []),
             ...(zone.next === null ? [] : [`     next → ${title(zone.next)}`]),
-            ...(zone.ifFails === null ? [] : [`     ${zone.kind === 'approval' ? 'sent back' : zone.kind === 'sort' ? 'not sure' : zone.kind === 'wait' ? 'no reply' : 'if it fails'} → ${title(zone.ifFails)}`]),
+            ...(zone.ifFails === null ? [] : [`     ${zone.kind === 'approval' ? 'sent back' : zone.kind === 'sort' ? 'not sure' : zone.kind === 'wait' ? 'no reply' : zone.kind === 'choose' ? 'a reply' : 'if it fails'} → ${title(zone.ifFails)}`]),
         ]),
         '', 'Triggers',
         ...(flow.triggers.length === 0 ? ['  none — add one with toolroll flows trigger add'] : flow.triggers.map(one => `  #${one.id} ${one.state === 'active' ? '' : `(${one.state}) `}${one.words} → ${title(one.zone)}${one.lastOutcome === null ? '' : ` · last: ${one.lastOutcome}`}`)),

package/dist/flows-ui.js

@@ -1,11 +1,12 @@
 import { draftFor, flowDefinitionOf } from "./flow-engine.js";
-import { describeTrigger, triggerHeadline, FLOW_TRIGGER_KINDS, FLOW_TRIGGER_WORDS, githubRepoOf, HOOK_PATH, hookReady, readHooksBase, readLinearKey, takesDeliveries, triggerConfigOf } from "./flow-triggers.js";
+import { describeTrigger, triggerHeadline, FLOW_TRIGGER_KINDS, FLOW_TRIGGER_WORDS, githubRepoOf, HOOK_PATH, hookReady, planeStatusLink, readHooksBase, readLinearKey, takesDeliveries, triggerConfigOf } from "./flow-triggers.js";
 import { deciderOf, FLOW_COLORS, FLOW_KIND_WORDS, FLOW_STAGE_KINDS } from "./flows.js";
 import { flowInsights, troubleWords } from "./flow-insights.js";
 import { parseSortDecision, sortChip } from "./flow-sort.js";
 import { flowSecretNames, readEmailSettings, sendingReady } from "./flow-actions.js";
 import { projectToolsOf, secretsSetFor, toolStanding } from "./project-tools.js";
 import { flowFingerprint } from "./flow-live.js";
+import { flowChoiceAt, readFlowSend } from "./flow-send.js";
 import { FLOW_FILE_MAX_BYTES } from "./flow-share.js";
 import { googleConnected } from "./google-mail.js";
 import { mailboxReady } from "./mailbox.js";
@@ -20,7 +21,7 @@ export function flowsListHtml(store, flows, projects, csrf, canCreate, problem)
     const rows = flows.map(flow => {
         const cards = store.flowCards(flow.id, false);
         const definition = flowDefinitionOf(flow);
-        const waiting = cards.filter(card => definition?.stages.find(one => one.id === card.stage)?.kind === "approval").length;
+        const waiting = cards.filter(card => ["approval", "choose"].includes(definition?.stages.find(one => one.id === card.stage)?.kind ?? "")).length;
         const buttons = store.flowTriggers(flow.id).filter(one => one.state === "active").flatMap(one => { const config = triggerConfigOf(one); return config?.kind === "button" ? [{ id: one.id, label: config.label }] : []; });
         const trouble = troubleWords(flowInsights(store, flow, new Date(), 7));
         return `<article class="card"><div class="flow-row"><h2><a href="/flows/${flow.id}">${e(flow.name)}</a></h2><span class="flow-counts">${e(projectName(flow.repo))} · ${cards.length} card${cards.length === 1 ? "" : "s"} in progress${waiting > 0 ? ` · ${waiting} waiting for a decision` : ""}${trouble === null ? "" : ` · ${e(trouble)}`}</span></div>` +
@@ -68,7 +69,8 @@ const historyText = (event, title, sorts = new Set()) => {
         case "approved": return `Approved${who}${note}`;
         case "sent-back": return `Sent back to ${title(event.toStage)}${who}${note}`;
         case "fail": return `Moved to ${title(event.toStage)} after a problem${note}`;
-        case "cancelled": return `Cancelled${who}`;
+        // "Ignore" on a choice closes the card (flow-send.ts): said as such, with what was chosen and where.
+        case "cancelled": return event.note?.startsWith("Ignored") ? `Ignored${who}${event.note.slice("Ignored".length)}` : `Cancelled${who}`;
         case "ok": return event.fromStage !== null && sorts.has(event.fromStage) ? `Sorted into ${title(event.toStage)}` : `Moved on to ${title(event.toStage)}${note}`;
         default: return `Moved to ${title(event.toStage)}${who}${note}`;
     }
@@ -121,21 +123,34 @@ export function flowView(store, flow, viewer, selectedCard, setup = { dir: null,
             }
         }
         const asker = asked === null || asked.state !== "open" ? null : store.getTeammate(asked.teammate);
+        // "Person chooses" (flow-send.ts): what was sent, and the options, for the person it waits on; the latest send otherwise.
+        const choosing = card.state === "active" && stage?.kind === "choose" ? flowChoiceAt(store, card.id, card.entry) : null;
+        const latest = store.flowSends(card.id)[0] ?? null;
+        const sentContent = latest === null ? null : readFlowSend(latest.contentJson);
+        // On the card itself: where it came from (the card's title is right above), and only the links the panel doesn't already have.
+        const own = new Set([`/flows/${flow.id}?card=${card.id}`, ...(task === null ? [] : [`/t/${encodeURIComponent(task)}`])]);
+        const sentView = (content) => ({ title: content.from === undefined ? "What was done" : `From ${content.from}`, summary: content.summary,
+            links: content.links.map(one => ({ label: one.label, href: "url" in one ? one.url : one.path })).filter(one => !own.has(one.href)) });
         return {
             id: card.id, title: card.title, description: card.description, stage: card.stage, state: card.state, waiting: card.waiting,
             task: task === null ? null : { id: task, href: `/t/${encodeURIComponent(task)}` },
             createdBy: card.createdBy, updatedAt: card.updatedAt,
             canDecide,
-            outputs: Object.entries(card.outputs).map(([id, text]) => ({ stage: id, title: title(id), text })),
+            // What a "Send to me" sent shows once, in its own box (sent), not again here; a report zone's items and full report
+            // (`<id>.items`, `<id>.report`) are for later zones, and its summary is shown.
+            outputs: Object.entries(card.outputs).filter(([id]) => !id.includes(".") && stages.find(one => one.id === id)?.kind !== "send").map(([id, text]) => ({ stage: id, title: title(id), text })),
             history: [...moves, ...owned].sort((a, b) => b.at.localeCompare(a.at)).slice(0, 30),
             source: card.source,
             owner: card.owner, watchers, watching: watchers.includes(viewer.name),
-            mine: card.owner === viewer.name || watchers.includes(viewer.name) || canDecide,
+            mine: card.owner === viewer.name || watchers.includes(viewer.name) || canDecide || choosing?.person === viewer.name,
             comments: discussion.filter(one => one.kind === "comment").map(one => ({ id: one.id, author: one.author, body: one.body, mentions: one.mentions, at: one.at })),
             sorted: decision === null ? null : { chip: sortChip(decision), confident: decision.confident },
             draft: shown === null || card.state !== "active" || card.outputs[shown.id] === undefined ? null : { zone: shown.id, title: shown.title, text: card.outputs[shown.id] },
             deadline,
             handoff,
+            choose: choosing === null || sentContent === null || latest?.entry !== card.entry ? null : { entry: card.entry, ...sentView(sentContent), person: choosing.person, mine: choosing.person === viewer.name,
+                options: (sentContent.options ?? []).filter(one => choosing.stage.options?.[one.choice]?.label === one.label), reply: sentContent.reply === true },
+            sent: sentContent === null || (choosing !== null && latest?.entry === card.entry) ? null : { ...sentView(sentContent), person: latest.person, at: latest.createdAt },
             question: asked === null || asked.state !== "open" || asker === null ? null
                 : { id: asked.id, from: labelOf(asker), question: asked.question, options: asked.options, askedOf: asked.askedOf, mine: asked.askedOf === viewer.name,
                     call: pending === null ? null : { why: pending.why, rule: pending.result ?? "" } },
@@ -152,7 +167,7 @@ export function flowView(store, flow, viewer, selectedCard, setup = { dir: null,
         return {
             id: trigger.id, kind: trigger.kind, words: config === null ? "This trigger can't be read." : describeTrigger(config, store),
             ...(config === null ? { name: "Trigger", detail: "Can't be read" } : triggerHeadline(config, store)),
-            zone: title(config?.zone ?? definition?.start ?? ""), zoneId: config?.zone ?? definition?.start ?? "", state: trigger.state, status: trigger.lastOutcome, statusAt: trigger.lastAt, failing: trigger.failures > 0,
+            zone: title(config?.zone ?? definition?.start ?? ""), zoneId: config?.zone ?? definition?.start ?? "", state: trigger.state, status: trigger.lastOutcome, statusLink: planeStatusLink(config, trigger.lastOutcome), statusAt: trigger.lastAt, failing: trigger.failures > 0,
             button: config?.kind === "button" ? { label: config.label, questions: config.questions } : null,
             hook: config !== null && takesDeliveries(config) ? { ready: hookReady(trigger, setup.dir), needsSecret: config.kind === "linear" } : null,
             checkable: ((config?.kind === "github" || config?.kind === "linear") && config.delivery === "poll") || config?.kind === "email" || (config?.kind === "schedule" && config.script !== undefined) || config?.kind === "plane-review",
@@ -188,6 +203,7 @@ export function flowView(store, flow, viewer, selectedCard, setup = { dir: null,
         live: flowFingerprint(store, flow.id),
         canEdit: viewer.approver,
         approvers: store.listApprovers().map(one => one.name).filter(name => store.accountCanAccess(name, flow.repo)),
+        projects: [flow.repo, ...setup.repos.filter(one => one !== flow.repo)].map(path => ({ path, name: projectName(path) })),
         kinds: FLOW_STAGE_KINDS.map(kind => ({ kind, label: FLOW_KIND_WORDS[kind].label, about: FLOW_KIND_WORDS[kind].about })),
         colors: [...FLOW_COLORS],
     };

package/dist/flows.d.ts

@@ -1,4 +1,4 @@
-export declare const FLOW_STAGE_KINDS: readonly ["inbox", "task", "report", "approval", "check", "pull-request", "update", "notify", "sort", "draft", "request", "email", "tool", "wait", "teammate", "done"];
+export declare const FLOW_STAGE_KINDS: readonly ["inbox", "task", "report", "approval", "check", "pull-request", "update", "notify", "sort", "draft", "request", "email", "tool", "wait", "teammate", "send", "choose", "done"];
 export type FlowStageKind = (typeof FLOW_STAGE_KINDS)[number];
 export declare const FLOW_COLORS: readonly ["slate", "blue", "violet", "amber", "green", "rose"];
 export type FlowColor = (typeof FLOW_COLORS)[number];
@@ -60,6 +60,15 @@ export type FlowWait = {
 /** How a Pull request zone merges once checks pass. */
 export declare const FLOW_MERGE_METHODS: readonly ["squash", "merge", "rebase"];
 export type FlowMergeMethod = (typeof FLOW_MERGE_METHODS)[number];
+/** A choose zone's option: its button's words, and the zone it leads to (FLOW_END closes the card as Ignored). */
+export type FlowChoice = {
+    label: string;
+    to: string;
+};
+/** Where a choose option that ends the card leads. */
+export declare const FLOW_END = "end";
+/** How many options a choose zone offers. */
+export declare const CHOICES_MIN = 2, CHOICES_MAX = 4;
 /** A time limit on a zone (v91): after this long, the person it waits on is reminded, and a Holding or
  * "Person decides" zone can move the card on (`to`). */
 export type FlowLimit = {
@@ -109,6 +118,10 @@ export type FlowStage = {
     teammate?: string;
     /** v96: a "Teammate handles it" zone sends what the teammate writes back to whoever asked (the person who added the card, its chat thread, or the teammate's manager). */
     reply?: boolean;
+    /** choose: the buttons the person picks from, in order. Its onFail is where a reply goes, with the reply as {{note}}. */
+    options?: FlowChoice[];
+    /** task: the project it builds in, when not the flow's own (one the flow's owner may file in). */
+    repo?: string;
     /** pull-request: merge once checks pass, this way. Only allowed after a "Person decides" zone, and a card merges only when a person approved it after it was built. */
     merge?: FlowMergeMethod;
     /** Where a card goes when this zone's step succeeds, and when it fails or is sent back (sort: when it isn't sure). */
@@ -156,6 +169,10 @@ export declare function validateFlowDefinition(input: unknown, options?: {
 }): FlowDefinition;
 /** The zones a card can reach from `start` without passing through a zone `stop` picks (those zones aren't included). */
 export declare function reachableWithout(stages: readonly FlowStage[], start: string, stop: (stage: FlowStage) => boolean): Set<string>;
+/** The zones a choose zone's options lead to (an option that ends the card leads to none). */
+export declare function choiceTargets(stage: Pick<FlowStage, "options">): string[];
+/** Where a reply to a choice goes, as its {{note}}: the zone's reply path, else its first option that leads somewhere; null when none does. */
+export declare function replyTarget(stage: Pick<FlowStage, "options" | "onFail">): string | null;
 /** What a card's work is held to: the zones' steps and paths, never where they sit on the canvas. */
 export declare function flowDigest(definition: FlowDefinition): string;
 type FlowFillCard = {
@@ -243,6 +260,15 @@ export type FlowStepInput = {
     teammate?: string;
     /** v96: a teammate step sends what it writes back to whoever asked. */
     reply?: boolean;
+    /** choose: 2 to 4 buttons, each with its words and the step it goes to ("end" ignores the card); where a reply goes instead
+     * (the reply is its {{note}}; the nearest earlier build or research step when left out). ifNoReply (with remindAfter) moves it on. */
+    options?: {
+        label?: string;
+        goesTo?: string;
+    }[];
+    ifReplied?: string;
+    /** task: the project it builds in (path), when not the flow's own. */
+    repo?: string;
     next?: string;
     ifFails?: string;
     ifNotSure?: string;

package/dist/flows.js

@@ -35,16 +35,27 @@
  *               waits for CI, and moves on when it passes or down the
  *               failure path, naming the failing check, when it fails. It
  *               can merge once checks pass, only after a person approved.
+ * - send      — "Send to me": sends the card's person (its owner, else the
+ *               flow's) what the step before produced — its summary, links
+ *               and images — in each chat app they paired and on the card,
+ *               then moves on.
+ * - choose    — "Person chooses": the same content, with 2 to 4 buttons the
+ *               flow names (each leads to a zone, or ends the card as
+ *               Ignored). A reply instead is the {{note}} for where replies go.
  * - done      — the end.
  *
  * The engine is deterministic and model-free: it runs in the worker's pass
  * beside routines, and no card ever skips an approval the task itself needs.
  */
 import { createHash } from "node:crypto";
-export const FLOW_STAGE_KINDS = ["inbox", "task", "report", "approval", "check", "pull-request", "update", "notify", "sort", "draft", "request", "email", "tool", "wait", "teammate", "done"];
+export const FLOW_STAGE_KINDS = ["inbox", "task", "report", "approval", "check", "pull-request", "update", "notify", "sort", "draft", "request", "email", "tool", "wait", "teammate", "send", "choose", "done"];
 export const FLOW_COLORS = ["slate", "blue", "violet", "amber", "green", "rose"];
 /** How a Pull request zone merges once checks pass. */
 export const FLOW_MERGE_METHODS = ["squash", "merge", "rebase"];
+/** Where a choose option that ends the card leads. */
+export const FLOW_END = "end";
+/** How many options a choose zone offers. */
+export const CHOICES_MIN = 2, CHOICES_MAX = 4;
 /** 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." },
@@ -62,6 +73,8 @@ export const FLOW_KIND_WORDS = {
     sort: { label: "Sort", about: "Jev reads the card in under a second and sends it where its answer leads. Cards it isn't sure about take the not-sure path." },
     wait: { label: "Wait", about: "Waits for a reply to the card's email, or for a set time. A reply moves the card on; if none comes in time, it takes the no-reply path." },
     teammate: { label: "Teammate handles it", about: "An AI teammate reads the card, decides where it goes within its rules, and writes what the next zones send. When its rules say to ask, it asks you first." },
+    send: { label: "Send to me", about: "Sends the card's owner what the step before produced: its summary, links and any screenshots, in each chat app they use and on the card. Then moves on." },
+    choose: { label: "Person chooses", about: "Sends the card's owner what was done with 2 to 4 buttons you name, in their chat apps and here. Each leads to a zone or ignores the card; a reply instead goes where replies go, as the note." },
     done: { label: "Done", about: "The end of the flow." },
 };
 const ID = /^[a-z0-9][a-z0-9-]{0,31}$/;
@@ -264,8 +277,8 @@ function validateLimit(input, kind, title) {
     if (minutes === null)
         throw new Error(`Zone ${title}: say how long a card may wait, from 1 minute to 30 days.`);
     const to = text(raw["to"], 32);
-    if (to !== null && kind !== "inbox" && kind !== "approval")
-        throw new Error(`Zone ${title}: only Holding and "Person decides" zones move a card on when it waits too long; other zones remind.`);
+    if (to !== null && kind !== "inbox" && kind !== "approval" && kind !== "choose")
+        throw new Error(`Zone ${title}: only Holding, "Person decides" and "Person chooses" zones move a card on when it waits too long; other zones remind.`);
     return { minutes, to };
 }
 /** Who decides at an approval zone: its named person, the flow's owner, or null for anyone who approves on the project. */
@@ -314,8 +327,10 @@ export function validateFlowDefinition(input, options = {}) {
             ...((kind === "approval" || kind === "teammate") && stage["teammate"] !== undefined && stage["teammate"] !== null && stage["teammate"] !== "" ? { teammate: validateTeammate(stage["teammate"], title) } : {}),
             ...(kind === "teammate" ? validateRoutes(stage, title) : {}),
             ...(kind === "teammate" && stage["reply"] === true ? { reply: true } : {}),
+            ...(kind === "choose" ? { options: validateChoices(stage["options"], title) } : {}),
+            ...(kind === "task" && stage["repo"] !== undefined && stage["repo"] !== null && stage["repo"] !== "" ? { repo: validateRepo(stage["repo"], title) } : {}),
             ...(() => { const limit = validateLimit(stage["limit"], kind, title); return limit === null ? {} : { limit }; })(),
-            next: kind === "sort" ? null : text(stage["next"], 32),
+            next: kind === "sort" || kind === "choose" ? null : text(stage["next"], 32),
             onFail: text(stage["onFail"], 32),
         };
     });
@@ -326,9 +341,13 @@ export function validateFlowDefinition(input, options = {}) {
         ids.add(stage.id);
     }
     for (const stage of stages) {
-        for (const target of [stage.next, stage.onFail, stage.limit?.to ?? null, ...(stage.sort?.answers.map(one => one.to) ?? []), ...(stage.routes?.map(one => one.to) ?? [])])
+        for (const target of [stage.next, stage.onFail, stage.limit?.to ?? null, ...(stage.sort?.answers.map(one => one.to) ?? []), ...(stage.routes?.map(one => one.to) ?? []), ...choiceTargets(stage)])
             if (target !== null && !ids.has(target))
                 throw new Error(`Zone ${stage.title} points at a zone that no longer exists.`);
+        if (stage.options !== undefined && ids.has(FLOW_END) && stage.options.some(one => one.to === FLOW_END))
+            throw new Error(`Zone ${stage.title}: an option that ends the card can't be told apart from the zone called ${FLOW_END}. Rename that zone.`);
+        if (stage.options?.some(one => one.to === stage.id))
+            throw new Error(`Zone ${stage.title}: an option can't send cards back into the same zone.`);
         if (stage.limit?.to === stage.id)
             throw new Error(`Zone ${stage.title}: a card that waits too long can't move back into the same zone.`);
         if (stage.routes?.some(one => one.to === stage.id))
@@ -380,10 +399,43 @@ export function reachableWithout(stages, start, stop) {
         if (stage === undefined || seen.has(stage.id) || stop(stage))
             continue;
         seen.add(stage.id);
-        queue.push(...[stage.next, stage.onFail, stage.limit?.to ?? null, ...(stage.sort?.answers.map(one => one.to) ?? []), ...(stage.routes?.map(one => one.to) ?? [])].filter((one) => one !== null));
+        queue.push(...[stage.next, stage.onFail, stage.limit?.to ?? null, ...(stage.sort?.answers.map(one => one.to) ?? []), ...(stage.routes?.map(one => one.to) ?? []), ...choiceTargets(stage)].filter((one) => one !== null));
     }
     return seen;
 }
+/** The zones a choose zone's options lead to (an option that ends the card leads to none). */
+export function choiceTargets(stage) {
+    return (stage.options ?? []).map(one => one.to).filter(to => to !== FLOW_END);
+}
+/** Where a reply to a choice goes, as its {{note}}: the zone's reply path, else its first option that leads somewhere; null when none does. */
+export function replyTarget(stage) {
+    return stage.onFail ?? choiceTargets(stage)[0] ?? null;
+}
+/** A choose zone's options, checked: 2 to 4, each with short words of its own and where it leads. */
+function validateChoices(input, title) {
+    const raw = Array.isArray(input) ? input : [];
+    if (raw.length < CHOICES_MIN || raw.length > CHOICES_MAX)
+        throw new Error(`Zone ${title}: give it ${CHOICES_MIN} to ${CHOICES_MAX} options.`);
+    const seen = new Set();
+    return raw.map(one => {
+        const row = (one ?? {});
+        const label = text(row["label"], 40);
+        const to = text(row["to"], 32);
+        if (label === null || to === null)
+            throw new Error(`Zone ${title}: each option needs a few words and where it leads.`);
+        if (seen.has(label.toLowerCase()))
+            throw new Error(`Zone ${title}: two options are called ${label}.`);
+        seen.add(label.toLowerCase());
+        return { label, to };
+    });
+}
+/** A build zone's project, when it isn't the flow's: its path. Whether the flow's owner may file there is checked when work is filed. */
+function validateRepo(value, title) {
+    const repo = text(value, 1000);
+    if (repo === null)
+        throw new Error(`Zone ${title}: choose the project it builds in.`);
+    return repo;
+}
 /** A teammate's handle on a zone (v92): which teammate works it. Whether it exists is the project's to say, when a card arrives. */
 function validateTeammate(value, title) {
     if (typeof value !== "string" || !/^[a-z0-9][a-z0-9-]{0,31}$/.test(value))
@@ -440,7 +492,8 @@ export function flowDigest(definition) {
     const terms = definition.stages.map(({ zone: _zone, ...rest }) => rest);
     return createHash("sha256").update(JSON.stringify({ start: definition.start, terms })).digest("hex").slice(0, 32);
 }
-const FILLED = /\{\{\s*(card\.title|card\.description|card\.email|note|stage\.([a-z0-9-]+))\s*\}\}/g;
+/** {{stage.<id>}} is an earlier zone's output; a report zone also fills {{stage.<id>.items}} and {{stage.<id>.report}}. */
+const FILLED = /\{\{\s*(card\.title|card\.description|card\.email|note|stage\.([a-z0-9-]+(?:\.(?:items|report))?))\s*\}\}/g;
 /** Fill a zone's text from the card: title, description, the latest note and earlier zones' reports. */
 export function fillFlowText(template, card, encode = value => value) {
     return template.replace(FILLED, (_match, key, stage) => encode(fillOne(key, stage, card))).trim();
@@ -524,7 +577,7 @@ function fillOne(key, stage, card) {
         return stage === undefined ? "" : card.outputs[stage] ?? "";
     }
 }
-const KIND_COLORS = { inbox: "slate", task: "blue", report: "violet", approval: "amber", check: "blue", "pull-request": "blue", update: "green", notify: "green", sort: "violet", draft: "violet", request: "blue", email: "green", tool: "blue", wait: "slate", teammate: "violet", done: "green" };
+const KIND_COLORS = { inbox: "slate", task: "blue", report: "violet", approval: "amber", check: "blue", "pull-request": "blue", update: "green", notify: "green", sort: "violet", draft: "violet", request: "blue", email: "green", tool: "blue", wait: "slate", teammate: "violet", send: "green", choose: "amber", done: "green" };
 /** A step id as the lead may write it (sort_by_hand, Sort-By-Hand) in the one form zones use. */
 const idOf = (value) => value.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 32);
 const slugOf = (title) => title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 28) || "zone";
@@ -617,18 +670,21 @@ export function flowFromSteps(input, previous = null) {
     drafts.forEach(({ step, old, id, title, kind }, index) => {
         const earlier = stages.slice();
         const following = drafts.slice(index + 1).find(() => true) ?? null;
-        const next = kind === "done" || kind === "sort" ? null
+        const next = kind === "done" || kind === "sort" || kind === "choose" ? null
             : typeof step.next === "string" && step.next.trim() !== "" ? find(step.next, title)
                 : following?.id ?? drafts.find(one => one.kind === "done").id;
         const keptFail = old?.onFail !== null && old?.onFail !== undefined && drafts.some(one => one.id === old.onFail) ? old.onFail : null;
         const worker = [...earlier].reverse().find(one => one.kind === "task" || one.kind === "report");
         const notSure = kind === "sort" && typeof step.ifNotSure === "string" && step.ifNotSure.trim() !== "" ? step.ifNotSure
-            : kind === "wait" && typeof step.ifNoReply === "string" && step.ifNoReply.trim() !== "" ? step.ifNoReply : step.ifFails;
+            : kind === "wait" && typeof step.ifNoReply === "string" && step.ifNoReply.trim() !== "" ? step.ifNoReply
+                : kind === "choose" ? step.ifReplied : step.ifFails;
         const onFail = kind === "done" ? null
             : typeof notSure === "string" && notSure.trim() !== "" ? find(notSure, title)
                 : keptFail ?? (kind === "approval" ? worker?.id ?? (drafts[0].id === id ? null : drafts[0].id)
-                    // Red CI goes back to the build before it, carrying the failing check.
-                    : kind === "pull-request" ? [...earlier].reverse().find(one => one.kind === "task")?.id ?? null : null);
+                    // A reply to a choice says what to change: it goes back to the work before it, as its note.
+                    : kind === "choose" ? worker?.id ?? null
+                        // Red CI goes back to the build before it, carrying the failing check.
+                        : kind === "pull-request" ? [...earlier].reverse().find(one => one.kind === "task")?.id ?? null : null);
         // "owner": whoever owns the flow when the card arrives.
         const toOwner = kind === "approval" && (step.decider === undefined ? old?.toOwner === true : typeof step.decider === "string" && /^(owner|the owner|flow owner|the flow owner|the flow's owner)$/i.test(step.decider.trim()));
         const approver = kind !== "approval" || toOwner ? null
@@ -636,7 +692,7 @@ export function flowFromSteps(input, previous = null) {
                 : step.decider === null || /^(anyone|any approver|anybody)$/i.test(step.decider.trim()) ? null : step.decider.trim();
         stages.push({
             id, title, kind,
-            zone: old?.zone ?? { x: 0, y: 0, w: 260, h: kind === "done" || kind === "notify" ? 220 : 300, color: KIND_COLORS[kind] },
+            zone: old?.zone ?? { x: 0, y: 0, w: 260, h: kind === "done" || kind === "notify" || kind === "send" ? 220 : 300, color: KIND_COLORS[kind] },
             // A kept step on our default instructions gets the default again, so it reads any research step added before it.
             instructions: kind === "teammate" ? step.instructions?.trim() || old?.instructions || "Read the card and decide what happens next."
                 : kind === "draft" ? step.instructions?.trim() || old?.instructions || DRAFT_DEFAULT
@@ -666,15 +722,24 @@ export function flowFromSteps(input, previous = null) {
             ...((kind === "approval" || kind === "teammate") && (step.teammate === undefined ? old?.teammate !== undefined : !/^(nobody|none|no one)$/i.test(step.teammate.trim())) ? { teammate: idOf(step.teammate ?? old.teammate) } : {}),
             ...(kind === "teammate" ? step.routes !== undefined ? step.routes.length === 0 ? {} : { routes: step.routes.map(one => ({ answer: String(one.answer ?? "").trim(), to: find(String(one.goesTo ?? ""), title) })) } : old?.routes === undefined ? {} : { routes: old.routes } : {}),
             ...(kind === "teammate" && (step.reply ?? old?.reply) === true ? { reply: true } : {}),
-            ...(() => { const limit = kind === "wait" || kind === "done" ? null : limitFromStep(step, old?.limit ?? null, title, ref => find(ref, title)); return limit === null ? {} : { limit }; })(),
+            ...(kind === "choose" ? { options: choicesFromStep(step, old?.options ?? null, title, ref => find(ref, title)) } : {}),
+            ...(kind === "task" && (step.repo ?? old?.repo) !== undefined && (step.repo ?? old?.repo).trim() !== "" ? { repo: (step.repo ?? old?.repo).trim() } : {}),
+            ...(() => {
+                // "If no reply" on a choice is where it moves once the reminder comes.
+                const asked = kind === "choose" && step.thenMoveTo === undefined && typeof step.ifNoReply === "string" ? { ...step, thenMoveTo: step.ifNoReply } : step;
+                if (kind === "choose" && asked.thenMoveTo !== undefined && asked.remindAfter === undefined && old?.limit === undefined)
+                    throw new Error(`Step ${title}: say how long to wait for a choice first, with remindAfter (like "2 days").`);
+                const limit = kind === "wait" || kind === "done" ? null : limitFromStep(asked, old?.limit ?? null, title, ref => find(ref, title));
+                return limit === null ? {} : { limit };
+            })(),
             next, onFail,
         });
     });
     // {{stage.<ref>}} in a step's words names a step as the lead wrote it (draftReply, Draft reply):
     // it is rewritten to that step's id, the same way the steps themselves are named.
-    const refs = (text) => text.replace(/\{\{\s*stage\.([A-Za-z0-9_ -]{1,60}?)\s*\}\}/g, (whole, ref) => {
+    const refs = (text) => text.replace(/\{\{\s*stage\.([A-Za-z0-9_ -]{1,60}?)(\.items|\.report)?\s*\}\}/g, (whole, ref, part) => {
         const hit = drafts.find(one => one.id === ref) ?? drafts.find(one => one.id === idOf(ref) || one.id.replace(/-/g, "") === idOf(ref).replace(/-/g, "") || one.title.toLowerCase() === ref.trim().toLowerCase());
-        return hit === undefined ? whole : `{{stage.${hit.id}}}`;
+        return hit === undefined ? whole : `{{stage.${hit.id}${part ?? ""}}}`;
     });
     for (const stage of stages) {
         if (stage.instructions !== null)
@@ -692,14 +757,14 @@ export function flowFromSteps(input, previous = null) {
     // A new flow that branches (a sort, or a script's answers) is laid out in columns by step instead,
     // each branch below the one before, so no arrow crosses a zone.
     const placed = stages.filter(one => kept.get(one.id)?.zone === one.zone).map(one => one.zone);
-    const branches = previous === null && stages.some(one => (one.sort?.answers.length ?? 0) > 0 || (one.routes?.length ?? 0) > 0);
+    const branches = previous === null && stages.some(one => (one.sort?.answers.length ?? 0) > 0 || (one.routes?.length ?? 0) > 0 || choiceTargets(one).length > 0);
     const columns = new Map();
     if (branches) {
         const queue = [stages[0].id];
         columns.set(stages[0].id, 0);
         while (queue.length > 0) {
             const id = queue.shift(), stage = stages.find(one => one.id === id);
-            for (const to of [...(stage.sort?.answers.map(one => one.to) ?? []), ...(stage.routes?.map(one => one.to) ?? []), stage.next, stage.onFail]) {
+            for (const to of [...(stage.sort?.answers.map(one => one.to) ?? []), ...(stage.routes?.map(one => one.to) ?? []), ...choiceTargets(stage), stage.next, stage.onFail]) {
                 if (to === null || to === "" || columns.has(to))
                     continue;
                 columns.set(to, columns.get(id) + 1);
@@ -735,6 +800,19 @@ export function flowFromSteps(input, previous = null) {
     });
     return validateFlowDefinition({ version: 1, start: stages[0].id, stages });
 }
+/** 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. */
+function choicesFromStep(step, old, title, find) {
+    if (!Array.isArray(step.options) || step.options.length === 0) {
+        if (old !== null)
+            return old;
+        throw new Error(`Step ${title}: give it ${CHOICES_MIN} to ${CHOICES_MAX} options, each with a label and the step it goes to (or "end").`);
+    }
+    return step.options.map(one => {
+        const label = String(one?.label ?? "").trim();
+        const goes = typeof one?.goesTo === "string" ? one.goesTo.trim() : "";
+        return { label, to: goes === "" || /^(end|ignore|ignored|stop|close)$/i.test(goes) ? FLOW_END : find(goes) };
+    });
+}
 /** A sort step as the lead describes it: answers name the steps they go to; what it leaves out carries over from the zone it keeps. */
 function sortFromStep(step, old, find) {
     const answers = Array.isArray(step.answers) && step.answers.length > 0
@@ -767,6 +845,8 @@ export function flowTerms(definition, previous) {
         }
         if (stage.kind === "task" && stage.planning !== "auto")
             lines.push(stage.planning === "required" ? "Plans first." : "Builds without a plan.");
+        if (stage.kind === "task" && stage.repo !== undefined)
+            lines.push(`Builds in another project: ${stage.repo}`);
         if (stage.kind === "draft")
             lines.push(`Claude writes: ${plain(stage.instructions ?? "")}`, `Then → ${to(stage.next)}`);
         else if (stage.kind === "request" && stage.request !== undefined) {
@@ -783,6 +863,10 @@ export function flowTerms(definition, previous) {
             lines.push(`The AI teammate ${stage.teammate ?? "(none)"} handles it${stage.instructions === null ? "" : `: ${plain(stage.instructions)}`}`, ...(stage.routes === undefined || stage.routes.length === 0 ? [`Then → ${to(stage.next)}`] : stage.routes.map(one => `${one.answer} → ${to(one.to)}`)), `It asks the flow's owner when its rules say to.${stage.reply === true ? " It sends what it writes back to whoever asked." : ""}${stage.onFail === null ? "" : ` If it can't → ${to(stage.onFail)}`}`);
         else if (stage.kind === "notify")
             lines.push(`Posts: ${plain(stage.message ?? "")}`, `Then → ${to(stage.next)}`);
+        else if (stage.kind === "send")
+            lines.push("Sends the card's owner (or the flow's) what the step before produced: its summary, links and any screenshots, in each chat app they use.", `Then → ${to(stage.next)}`);
+        else if (stage.kind === "choose")
+            lines.push("Sends the card's owner (or the flow's) what the step before produced, and asks them to choose:", ...(stage.options ?? []).map(one => `${one.label} → ${one.to === FLOW_END ? "ignores the card." : to(one.to)}`), `Or a reply with what they'd change → ${replyTarget(stage) === null ? "not possible." : to(replyTarget(stage))}`);
         else if (stage.kind === "update")
             lines.push(`Comments on the issue the card came from: ${plain(stage.message ?? "")}${stage.close === true ? " Then closes it (Linear: moves it to done)." : ""}`, `Then → ${to(stage.next)}${stage.onFail === null ? "" : ` If it can't → ${to(stage.onFail)}`}`);
         else if (stage.kind === "sort" && stage.sort !== null) {
@@ -835,6 +919,8 @@ export function flowTerms(definition, previous) {
         terms.push(`Pull request steps push the card's branch to GitHub and open a pull request under this project's pull request setup.${definition.stages.some(one => one.merge !== undefined) ? " A merge happens only after a person approves the card; nothing merges without one." : " Nothing merges on its own."}`);
     if (definition.stages.some(one => one.kind === "draft"))
         terms.push("Draft steps send each card's text to Claude through the lead chat's sign-in. Nothing a draft writes is sent until a later step sends it.");
+    if (definition.stages.some(one => one.kind === "task" && one.repo !== undefined))
+        terms.push("A build step in another project files its task there, only when the flow's owner may file work in that project.");
     if (definition.stages.some(one => one.teammate !== undefined))
         terms.push("AI teammates decide and act within their soul files' rules, reading each card through Claude on this computer's sign-in; they never approve code tasks or merges.");
     return terms;

package/dist/invoke.d.ts

@@ -39,6 +39,9 @@ export type AgentOutcome = {
     sessionId: string | null;
     /** The agent's spoken conclusion — diagnostics, never the handoff. */
     finalMessage: string | null;
+    /** Claude's `structured_output` alone (see ParsedEnvelope) — the only
+     * field a structured handback may be read from. */
+    structuredOutput?: string | null;
     /** The harness's own account of the ending, when its dialect has one. */
     ending?: AgentEnding | null;
     usage: ProviderUsage;

package/dist/invoke.js

@@ -550,6 +550,7 @@ export async function invokeAgent(store, runId, spec, invocation, options) {
             notFound: result.notFound,
             sessionId: envelope.sessionId,
             finalMessage: envelope.finalMessage,
+            structuredOutput: envelope.structuredOutput ?? null,
             ending: envelope.ending ?? null,
             usage: {
                 tokensIn: envelope.tokensIn,