toolroll 0.9.20 → 0.9.21

package/dist/flow-gallery-ui.js

@@ -3,7 +3,8 @@
  * its promise, a small drawing of its zones, what it needs and "Use this". A template's page asks only what it
  * needs, previews in plain words what it will do and never do, and creates it — the same answers it previewed.
  */
-import { BLANK, GALLERY, GALLERY_GROUPS, galleryDiagram, OUTDATED_COMMANDS } from "./flow-gallery.js";
+import { BLANK, GALLERY, GALLERY_GROUPS, galleryDiagram, OUTDATED_COMMANDS, SEND_RESULT } from "./flow-gallery.js";
+import { choiceTargets } from "./flows.js";
 const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
 export const GALLERY_CSS = `.gallery{max-width:1120px;min-width:0}.gallery h2{margin:28px 0 10px;font-size:.9375rem}.gallery h2:first-of-type{margin-top:8px}` +
     `.gallery-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(250px,1fr));gap:12px}` +
@@ -16,7 +17,7 @@ export const GALLERY_CSS = `.gallery{max-width:1120px;min-width:0}.gallery h2{ma
     `.gallery .gallery-card a.button-link{align-self:flex-start;min-height:36px;background:var(--so-paper);color:var(--so-ink);border:1px solid var(--so-input-line)}` +
     `.gallery-blank{margin-top:20px}` +
     `.gallery-use{max-width:720px;min-width:0}.gallery-use .gallery-zones{height:88px;margin:4px 0 12px}.gallery-use form{display:grid;gap:12px;margin:0}.gallery-use label{display:grid;gap:4px;font-weight:500}` +
-    `.gallery-use label small{font-weight:400;color:var(--so-muted)}` +
+    `.gallery-use label small{font-weight:400;color:var(--so-muted)}.gallery-use label.gallery-check{display:flex;align-items:flex-start;gap:8px;font-weight:500}.gallery-use label.gallery-check input{margin-top:3px;width:16px;height:16px;min-height:0;flex:none}.gallery-use label.gallery-check small{display:block}` +
     `.gallery-use input:not([type=hidden]),.gallery-use select{box-sizing:border-box;width:100%;max-width:100%;min-height:32px;padding:0 10px;border:1px solid var(--so-input-line);border-radius:8px;background:var(--so-paper);color:var(--so-ink);font:inherit}` +
     `.gallery-preview{display:grid;gap:8px;padding:16px;border:1px solid var(--so-line);border-radius:10px;background:var(--so-paper);min-width:0}.gallery-preview h2{margin:0;font-size:.9375rem}` +
     `.gallery-preview ul{margin:0;padding-left:18px;line-height:1.55}.gallery-preview p{margin:0;overflow-wrap:anywhere}.gallery-preview .gallery-never{font-weight:600}` +
@@ -34,11 +35,11 @@ export function zonesDiagram(definition, label) {
     const pad = 40;
     const box = `${minX - pad} ${minY - pad} ${maxX - minX + pad * 2} ${maxY - minY + pad * 2}`;
     const centre = (id) => { const at = definition.stages.find(one => one.id === id)?.zone; return at === undefined ? null : { x: at.x + at.w / 2, y: at.y + at.h / 2 }; };
-    const lines = definition.stages.flatMap(stage => [stage.next, ...(stage.sort?.answers.map(one => one.to) ?? []), ...(stage.routes?.map(one => one.to) ?? [])].map(to => {
+    const lines = definition.stages.flatMap(stage => [stage.next, ...(stage.sort?.answers.map(one => one.to) ?? []), ...(stage.routes?.map(one => one.to) ?? []), ...choiceTargets(stage)].map(to => {
         const from = centre(stage.id), end = centre(to);
         return from === null || end === null ? "" : `<line x1="${from.x}" y1="${from.y}" x2="${end.x}" y2="${end.y}" vector-effect="non-scaling-stroke"/>`;
     })).join("");
-    const rects = definition.stages.map(one => `<rect x="${one.zone.x}" y="${one.zone.y}" width="${one.zone.w}" height="${one.zone.h}" rx="36" data-person="${one.kind === "approval"}" vector-effect="non-scaling-stroke"/>`).join("");
+    const rects = definition.stages.map(one => `<rect x="${one.zone.x}" y="${one.zone.y}" width="${one.zone.w}" height="${one.zone.h}" rx="36" data-person="${one.kind === "approval" || one.kind === "choose"}" vector-effect="non-scaling-stroke"/>`).join("");
     return `<svg class="gallery-zones" viewBox="${box}" preserveAspectRatio="xMidYMid meet" role="img" aria-label="${e(label)}">${lines}${rects}</svg>`;
 }
 const needsList = (template) => template.needs.length === 0 ? `<ul class="gallery-needs"><li>Nothing to connect</li></ul>`
@@ -73,13 +74,13 @@ export function galleryUseHtml(input) {
         `<p class="gallery-never">${e(input.preview.built.never)}</p>` +
         (input.preview.startsFrom.length === 0 ? `<p class="meta">Cards start when you add them.</p>` : input.preview.startsFrom.map(one => `<p class="meta">Starts from: ${e(one)}</p>`).join("")) +
         `<details><summary>Every step</summary><ol>${input.preview.steps.map(one => `<li>${e(one.replace(/^\d+\.\s/, ""))}</li>`).join("")}</ol></details></section>`;
-    const asks = template.asks.length > 0 || input.projects.length > 1;
     return `<section class="gallery-use" data-gallery-template="${e(template.id)}">` +
         (input.problem === null ? "" : `<p class="problem" role="alert">${e(input.problem)}</p>`) +
         `<p>${e(template.promise)}</p>${input.diagram === null ? "" : zonesDiagram(input.diagram, `Zones: ${input.diagram.stages.map(one => one.title).join(", ")}`)}${needsList(template)}` +
         `<form method="post" action="/flows/new/${e(template.id)}" data-gallery-use><input type="hidden" name="csrf" value="${e(input.csrf)}">` +
         `<input type="hidden" name="previewed" value="${e(input.preview?.digest ?? "")}">${project}${template.asks.map(field).join("")}` +
-        `<label>Name<input name="name" value="${e(input.name)}" maxlength="80"></label>${preview}` +
-        `<p class="gallery-actions">${input.preview === null ? "" : `<button type="submit" name="intent" value="create">Create flow</button>`}${asks || input.preview === null ? `<button type="submit" name="intent" value="preview" class="secondary">${input.preview === null ? "Preview" : "Update preview"}</button>` : ""}</p>` +
+        `<label>Name<input name="name" value="${e(input.name)}" maxlength="80"></label>` +
+        `<label class="gallery-check"><input type="checkbox" name="${SEND_RESULT.key}" value="yes"${input.answers[SEND_RESULT.key] === "yes" ? " checked" : ""} data-send-result><span>${e(SEND_RESULT.title)}<small>When a card finishes, what was done comes to you in your chat apps.</small></span></label>${preview}` +
+        `<p class="gallery-actions">${input.preview === null ? "" : `<button type="submit" name="intent" value="create">Create flow</button>`}<button type="submit" name="intent" value="preview" class="secondary">${input.preview === null ? "Preview" : "Update preview"}</button></p>` +
         `</form><p class="meta"><a href="/flows/new">All templates</a></p></section>`;
 }

package/dist/flow-gallery.d.ts

@@ -62,6 +62,14 @@ export declare const galleryTemplateOf: (id: string) => GalleryTemplate | null;
 export type GalleryAnswers = Record<string, string>;
 /** Each question's default for a project: the branch pull requests go to, when that's set up. */
 export declare function galleryDefaults(store: Store, template: GalleryTemplate, repo: string | null): GalleryAnswers;
+/** The optional last step every template offers, and the answer that turns it on. */
+export declare const SEND_RESULT: {
+    readonly key: "send-result";
+    readonly title: "Send me the result";
+    readonly does: "When a card finishes, sends you what was done (its summary, links and screenshots) in your chat apps.";
+};
+/** A flow with "Send me the result" before its end: every path into its main Done zone passes through it first. */
+export declare function withSendResult(definition: FlowDefinition): FlowDefinition;
 /** The answers, checked in plain words, with what they fill in. Throws. */
 export declare function checkAnswers(template: GalleryTemplate, given: GalleryAnswers): GalleryAnswers;
 export type GalleryBuilt = {

package/dist/flow-gallery.js

@@ -8,6 +8,9 @@
  * where an answer goes and `{{script.<name>}}` where its script's name goes — so it can be written out as a
  * shared flow file later. Every one is built only from existing zone and trigger kinds, and none merges:
  * a pull request it opens waits for a person.
+ *
+ * Every template can end with "Send me the result" (a "Send to me" zone before its end), off unless asked for
+ * (`send-result: yes`): what the flow did reaches the person in their chat apps.
  */
 import { createHash } from "node:crypto";
 import { scanForSecrets } from "./evidence.js";
@@ -15,7 +18,7 @@ import { flowDefinitionOf } from "./flow-engine.js";
 import { saveScript, validateScript } from "./flow-scripts.js";
 import { isToolrollRepo, planeReviewSteps } from "./flow-starters.js";
 import { addFlowTriggerTo, describeTrigger, githubRepoOf, scheduleFromWords, validateTriggerConfig } from "./flow-triggers.js";
-import { clockTime, flowFromSteps, flowTerms, FLOW_TEMPLATES, ISSUE_LABEL } from "./flows.js";
+import { choiceTargets, clockTime, flowFromSteps, flowTerms, FLOW_TEMPLATES, ISSUE_LABEL } from "./flows.js";
 import { publishingOf } from "./pull-request-flow.js";
 export const GALLERY_GROUPS = [
     { id: "ship", label: "Ship code" },
@@ -291,9 +294,38 @@ const oneLine = (value, cap, what) => {
         throw new Error(`That ${what} looks like it holds a key or password. Keep secrets out of it.`);
     return said;
 };
+/** The optional last step every template offers, and the answer that turns it on. */
+export const SEND_RESULT = { key: "send-result", title: "Send me the result", does: "When a card finishes, sends you what was done (its summary, links and screenshots) in your chat apps." };
+/** A flow with "Send me the result" before its end: every path into its main Done zone passes through it first. */
+export function withSendResult(definition) {
+    // Its main end: Done, else an end that isn't a filtered-out one (drawn in rose), else any end.
+    const ends = definition.stages.filter(one => one.kind === "done");
+    const end = ends.find(one => one.id === "done") ?? ends.find(one => one.zone.color !== "rose") ?? ends[0];
+    if (end === undefined || definition.stages.some(one => one.kind === "send" && one.next === end.id))
+        return definition;
+    let id = "send-result";
+    for (let n = 2; definition.stages.some(one => one.id === id); n++)
+        id = `send-result-${n}`;
+    const into = (to) => to === end.id ? id : to;
+    const stages = definition.stages.map(one => ({
+        ...one, next: one.next === null ? null : into(one.next), onFail: one.onFail === null ? null : into(one.onFail),
+        ...(one.limit === undefined ? {} : { limit: { ...one.limit, to: one.limit.to === null ? null : into(one.limit.to) } }),
+        sort: one.sort === null ? null : { ...one.sort, answers: one.sort.answers.map(answer => ({ ...answer, to: into(answer.to) })) },
+        ...(one.routes === undefined ? {} : { routes: one.routes.map(route => ({ ...route, to: into(route.to) })) }),
+        ...(one.options === undefined || choiceTargets(one).length === 0 ? {} : { options: one.options.map(option => ({ ...option, to: into(option.to) })) }),
+    }));
+    // Where the end was, and the end moves along to make room.
+    const send = { id, title: SEND_RESULT.title, kind: "send", zone: { ...end.zone, color: "green", h: 220 }, instructions: null, planning: null, approver: null,
+        message: null, close: null, script: null, sort: null, next: end.id, onFail: null };
+    const moved = stages.map(one => one.id === end.id ? { ...one, zone: { ...one.zone, x: one.zone.x + Math.max(300, one.zone.w + 40) } } : one);
+    return { ...definition, ...(definition.start === end.id ? { start: id } : {}), stages: [...moved.filter(one => one.id !== end.id), send, moved.find(one => one.id === end.id)] };
+}
 /** The answers, checked in plain words, with what they fill in. Throws. */
 export function checkAnswers(template, given) {
     const answers = {};
+    // Off unless asked for; only said when on, so a template's answers read as before.
+    if (given[SEND_RESULT.key] === "yes")
+        answers[SEND_RESULT.key] = "yes";
     for (const ask of template.asks) {
         const value = String(given[ask.key] ?? ask.default).trim();
         if (ask.key === "label")
@@ -386,10 +418,12 @@ export function buildFromGallery(store, template, repo, given) {
         return { name, about: draft.about, body: draft.body, timeoutMinutes: draft.timeoutMinutes, existing };
     });
     const github = githubRepoOf(repo);
-    const definition = template.definition !== undefined ? structuredClone(template.definition)
+    const drawn = template.definition !== undefined ? structuredClone(template.definition)
         : flowFromSteps(fill(template.ownSteps !== undefined && isToolrollRepo(repo) ? template.ownSteps : template.steps, answers, names, github), null);
+    const sends = answers[SEND_RESULT.key] === "yes";
+    const definition = sends ? withSendResult(drawn) : drawn;
     return { template, repo, answers, definition, triggers: fill(template.triggers, answers, names, github), scripts,
-        does: fill(template.does, answers, names, github), never: template.never };
+        does: [...fill(template.does, answers, names, github), ...(sends && definition !== drawn ? [SEND_RESULT.does] : [])], never: template.never };
 }
 /** A template's zones as its defaults draw them, for the gallery's small drawing; no project needed. */
 export function galleryDiagram(template) {

package/dist/flow-send.d.ts

@@ -0,0 +1,80 @@
+import { type FlowDecision } from "./flow-engine.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>`. */
+export declare const FLOW_SEND_KEY: RegExp;
+/** The notice a "Person chooses" visit sends: `flow-choose:<card>:<entry>`, a "flow-decision" like an approval's. */
+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;
+    /** choose: the options as they were offered, and whether a reply is taken. */
+    options?: {
+        choice: number;
+        label: string;
+    }[];
+    reply?: boolean;
+};
+/** 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. */
+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;
+/** The links a sent visit's message carries as buttons: Toolroll's own pages, the first one first. */
+export declare function flowSendPaths(content: FlowSendContent): {
+    label: string;
+    path: string;
+}[];
+/** A "Send to me" visit: what the step before produced, to the person once; the card moves on after. */
+export declare function sendStep(store: Store, flow: FlowRow, definition: FlowDefinition, stage: FlowStage, card: FlowCardRow, now: Date, evidenceRoot?: string): void;
+/** A "Person chooses" visit: the same content with the zone's options, to the person once; the card waits for their choice. */
+export declare function chooseStep(store: Store, flow: FlowRow, definition: FlowDefinition, stage: FlowStage, card: FlowCardRow, now: Date, evidenceRoot?: string): void;
+/** The words above a choice's buttons: what was done, then what to do. */
+export declare function flowChooseBody(content: FlowSendContent): string;
+export type FlowChoiceVisit = {
+    card: FlowCardRow;
+    flow: FlowRow;
+    stage: FlowStage;
+    definition: FlowDefinition;
+    person: string;
+};
+/** The card, if it is still at that visit, waiting for its person's choice. */
+export declare function flowChoiceAt(store: Store, cardId: number, entry: number): FlowChoiceVisit | null;
+/**
+ * A person's choice on a card waiting at a "Person chooses" zone: an option (by its place, and the words and zone they saw), or a
+ * 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;
+    actor: string;
+    where: string;
+    repos: readonly string[];
+    evidenceRoot?: string;
+}, now: Date): FlowDecision;

package/dist/flow-send.js

@@ -0,0 +1,249 @@
+/**
+ * "Send to me" and "Person chooses" zones (flows.ts): what a card's step before produced, sent to the card's person.
+ *
+ * - The person is the card's owner, else the flow's.
+ * - What is sent: the card's title and the step it comes from, a summary (the build's own report, a research report,
+ *   or what the step before wrote), its links (the result, its pull request, the report, the card) and the build's
+ *   screenshots. It is worked out once per visit and kept (flow_send), so every chat app and the card show the same.
+ * - It goes as one notification to that person, which each chat app they paired delivers (Telegram: the screenshots as
+ *   one album; Slack and Discord: uploads in its thread; Teams: a link to them), and the card shows it in the console.
+ * - A choose visit carries the zone's options as buttons (telegram-flow.ts, chat-flow.ts, and the card). Each leads to
+ *   a zone, or ends the card as Ignored; a reply instead is the {{note}} for where replies go. Every choice is made
+ *   here (chooseFlowCard), for exactly the visit the person saw, by that person alone, and ledgered with where.
+ *
+ * Deterministic and model-free, in the worker's flow pass.
+ */
+import { assignmentOf } from "./assignment.js";
+import { withActor } from "./actor.js";
+import { flowCardHref, flowDefinitionOf, revisionWithNote } from "./flow-engine.js";
+import { notifyPeople } from "./flow-people.js";
+import { FLOW_END, replyTarget } from "./flows.js";
+import { FLOW_SHOTS_KIND } from "./store.js";
+/** The notice a "Send to me" visit sends: `flow-send:<card>:<entry>`. */
+export const FLOW_SEND_KEY = /^flow-send:([1-9][0-9]{0,14}):([1-9][0-9]{0,9})$/;
+/** The notice a "Person chooses" visit sends: `flow-choose:<card>:<entry>`, a "flow-decision" like an approval's. */
+export const FLOW_CHOOSE_KEY = /^flow-choose:([1-9][0-9]{0,14}):([1-9][0-9]{0,9})$/;
+/** What the person is asked under the buttons. */
+export const REPLY_ASK = "Or reply with what you'd change.";
+const SUMMARY_CHARS = 1500;
+const STEP_CHARS = 500;
+/** Who a card's "Send to me" and "Person chooses" zones are for: its owner, else the flow's. */
+export function flowPersonOf(card, flow) {
+    return card.owner ?? flow.owner;
+}
+const cut = (text, cap) => text.length <= cap ? text : `${text.slice(0, cap - 1).trimEnd()}…`;
+const plain = (text) => text.replace(/\r\n?/g, "\n").replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, "").replace(/\n{3,}/g, "\n\n").trim();
+/** The zone the card came from into this visit: its latest move, else a zone that leads here. */
+function stepBefore(store, definition, card) {
+    const events = store.flowEvents(card.id);
+    const last = events[events.length - 1];
+    const from = last !== undefined && last.toStage === card.stage && last.fromStage !== card.stage ? last.fromStage : null;
+    return definition.stages.find(one => one.id === from)
+        ?? definition.stages.find(one => one.next === card.stage || one.onFail === card.stage || (one.options ?? []).some(option => option.to === card.stage)) ?? null;
+}
+/** A result's facts for the person, read as the operator would: its report, its pull request and screenshots. */
+function resultOf(store, taskId, now, evidenceRoot) {
+    const repo = store.lookupRef(taskId)?.repo ?? null;
+    if (repo === null)
+        return null;
+    const snapshot = assignmentOf(store, taskId, now, { principal: "operator", repos: [repo] }, evidenceRoot);
+    const receipt = snapshot?.receipt ?? null;
+    const url = snapshot?.publication?.prUrl ?? null;
+    return {
+        taskId: receipt?.taskId ?? snapshot?.activeTaskId ?? taskId, report: receipt?.agentReport ?? null,
+        pullRequest: url !== null && /^https:\/\/[^\s<>"]+$/.test(url) ? url : null,
+        shots: receipt !== null && store.artifactsFor(receipt.runId).some(one => one.kind === "screenshot") ? { taskId: receipt.taskId, run: receipt.runId } : null,
+    };
+}
+/** What a visit sends its person, worked out from the card as it is now. */
+export function flowSendContent(store, flow, definition, stage, card, now, evidenceRoot) {
+    const before = stepBefore(store, definition, card);
+    const output = before === null ? undefined : card.outputs[before.id]?.trim() || undefined;
+    // The task the step before produced (a build or research zone hands it over), and the card's main build.
+    const handed = card.task !== null && before !== null && (before.kind === "task" || before.kind === "report") ? card.task : null;
+    const report = handed !== null && before?.kind === "report" ? handed : null;
+    const build = before?.kind === "task" && handed !== null ? handed : card.primaryTask;
+    const result = build === null ? null : resultOf(store, build, now, evidenceRoot);
+    const lines = [];
+    if (before?.kind === "report" && output !== undefined)
+        lines.push(cut(output, SUMMARY_CHARS));
+    else if (result?.report != null && result.report.trim() !== "") {
+        lines.push(cut(result.report.trim(), SUMMARY_CHARS));
+        if (output !== undefined && before?.kind !== "task")
+            lines.push(`${before.title}: ${cut(output, STEP_CHARS)}`);
+    }
+    else if (output !== undefined)
+        lines.push(cut(output, SUMMARY_CHARS));
+    else {
+        // Nothing from the step before: the latest thing any zone wrote, else the card's own details.
+        const latest = [...definition.stages].reverse().find(one => one.id !== stage.id && card.outputs[one.id]?.trim());
+        lines.push(latest !== undefined ? `${latest.title}: ${cut(card.outputs[latest.id].trim(), SUMMARY_CHARS)}` : card.description === null ? "Nothing was written down for this step." : cut(card.description, SUMMARY_CHARS));
+    }
+    const links = [];
+    if (result !== null)
+        links.push({ label: "Result", path: `/t/${encodeURIComponent(result.taskId)}` });
+    if (result?.pullRequest != null)
+        links.push({ label: "Pull request", url: result.pullRequest });
+    if (report !== null)
+        links.push({ label: "Report", path: `/t/${encodeURIComponent(report)}` });
+    links.push({ label: "Card", path: flowCardHref(flow.id, card.id) });
+    const options = stage.kind === "choose" ? (stage.options ?? []).map((one, choice) => ({ choice, label: one.label })) : undefined;
+    return {
+        title: cut(plain(before === null ? card.title : `${card.title} · ${before.title}`), 200), ...(before === null ? {} : { from: before.title }),
+        summary: plain(lines.join("\n\n")), links, shots: result?.shots ?? null,
+        ...(options === undefined ? {} : { options, reply: replyTarget(stage) !== null }),
+    };
+}
+/** A kept content, read back; null when it can't be. */
+export function readFlowSend(json) {
+    try {
+        const raw = JSON.parse(json);
+        return typeof raw.title === "string" && typeof raw.summary === "string" && Array.isArray(raw.links) ? raw : null;
+    }
+    catch {
+        return 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) {
+    const pull = content.links.find((one) => "url" in one);
+    return [content.title, content.summary, ...(pull === undefined ? [] : [`${pull.label}: ${pull.url}`])].filter(one => one !== "").join("\n\n");
+}
+/** The links a sent visit's message carries as buttons: Toolroll's own pages, the first one first. */
+export function flowSendPaths(content) {
+    return content.links.filter((one) => "path" in one);
+}
+/** A visit's content, kept the first time; later passes (and every chat app) read the same one. */
+function keep(store, flow, definition, stage, card, now, evidenceRoot) {
+    const person = flowPersonOf(card, flow);
+    const kept = store.flowSend(card.id, card.entry);
+    const read = kept === null ? null : readFlowSend(kept.contentJson);
+    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);
+    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. */
+function enqueue(store, flow, card, person, content, notice, now) {
+    if (!store.accountCanAccess(person, flow.repo))
+        return;
+    withActor(null, () => {
+        store.enqueueNotification({ dedupeKey: notice.key, kind: notice.kind, recipient: person, ...(notice.attention ? { pushClass: "attention" } : {}),
+            subject: notice.subject.slice(0, 200), body: notice.body.slice(0, 4000), link: flowSendPaths(content)[0]?.path ?? flowCardHref(flow.id, card.id), source: { project: flow.repo } }, now);
+        if (content.shots !== null && store.lookupRef(content.shots.taskId)?.repo != null && store.accountCanAccess(person, store.lookupRef(content.shots.taskId).repo)) {
+            store.enqueueNotification({ dedupeKey: `flow-shots:${card.id}:${card.entry}`, kind: FLOW_SHOTS_KIND, recipient: person, subject: "Screenshots with this result", body: "",
+                link: `/t/${encodeURIComponent(content.shots.taskId)}`, source: { run: content.shots.run } }, now);
+        }
+    });
+}
+/** A "Send to me" visit: what the step before produced, to the person once; the card moves on after. */
+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);
+    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);
+}
+/** A "Person chooses" visit: the same content with the zone's options, to the person once; the card waits for their choice. */
+export function chooseStep(store, flow, definition, stage, card, now, evidenceRoot) {
+    const { content, person, fresh } = keep(store, flow, definition, stage, card, now, evidenceRoot);
+    const waiting = `Waiting for ${person} to choose`;
+    if (card.waiting !== waiting)
+        store.updateFlowCard(card.id, { waiting }, now);
+    if (!fresh)
+        return;
+    enqueue(store, flow, card, person, content, { key: `flow-choose:${card.id}:${card.entry}`, kind: "flow-decision", attention: true,
+        subject: `${flow.name}: ${content.title}`, body: flowChooseBody(content) }, now);
+}
+/** The words above a choice's buttons: what was done, then what to do. */
+export function flowChooseBody(content) {
+    const pull = content.links.find((one) => "url" in one);
+    return [content.summary, ...(pull === undefined ? [] : [`${pull.label}: ${pull.url}`]), content.reply === true ? `Choose one. ${REPLY_ASK}` : "Choose one."].join("\n\n");
+}
+/** The card, if it is still at that visit, waiting for its person's choice. */
+export function flowChoiceAt(store, cardId, entry) {
+    const card = store.getFlowCard(cardId);
+    const flow = card === null ? null : store.getFlow(card.flow);
+    const definition = flow === null ? null : flowDefinitionOf(flow);
+    if (card === null || flow === null || definition === null || card.state !== "active" || card.entry !== entry)
+        return null;
+    const stage = definition.stages.find(one => one.id === card.stage);
+    if (stage === undefined || stage.kind !== "choose")
+        return null;
+    return { card, flow, stage, definition, person: flowPersonOf(card, flow) };
+}
+const via = (where) => where === "" ? "" : ` in ${where}`;
+/**
+ * A person's choice on a card waiting at a "Person chooses" zone: an option (by its place, and the words and zone they saw), or a
+ * 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 function chooseFlowCard(store, input, now) {
+    const card = store.getFlowCard(input.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);
+    if (visit === null)
+        return { ok: false, message: "That card has moved on since; nothing was changed." };
+    const { stage, definition, person } = visit;
+    if (person !== input.actor)
+        return { ok: false, message: `Only ${person} chooses here.` };
+    const titleOf = (id) => definition.stages.find(one => one.id === id)?.title ?? id;
+    const ledger = (outcome, said) => store.recordAction({ at: now.toISOString(), actor: input.actor, repo: flow.repo, taskId: card.primaryTask, runId: null,
+        action: "flow choice", outcome, source: "request", detail: `${flow.name} · card ${card.id} · ${stage.title}: ${said} · via ${input.where || "Toolroll"}` });
+    if (input.choice !== null) {
+        const option = (stage.options ?? [])[input.choice];
+        if (option === undefined || (input.label !== undefined && option.label !== input.label) || (input.to !== undefined && option.to !== input.to))
+            return { ok: false, message: "Those options changed since; nothing was changed." };
+        if (option.to === FLOW_END) {
+            const closed = store.transact(() => {
+                if (!store.moveFlowCard(card.id, { to: card.stage, outcome: "cancelled", actor: input.actor, historyNote: `Ignored: chose “${option.label}”${via(input.where)}`, expectEntry: card.entry }, now))
+                    return false;
+                store.updateFlowCard(card.id, { state: "cancelled", waiting: "Ignored" }, now);
+                store.retireFlowChoices(card.id, card.entry, now);
+                ledger("ignored", `“${option.label}”`);
+                return true;
+            });
+            return closed ? { ok: true, said: "Ignored. The card is closed." } : { ok: false, message: "That card has moved on since; nothing was changed." };
+        }
+        const moved = store.transact(() => {
+            if (!store.moveFlowCard(card.id, { to: option.to, outcome: "moved", actor: input.actor, historyNote: `Chose “${option.label}”${via(input.where)}`, expectEntry: card.entry }, now))
+                return false;
+            store.retireFlowChoices(card.id, card.entry, now);
+            ledger("chosen", `“${option.label}”`);
+            return true;
+        });
+        if (!moved)
+            return { ok: false, message: "That card has moved on since; nothing was changed." };
+        if (card.owner !== null && card.owner !== input.actor)
+            notifyPeople(store, card, [card.owner], input.actor, { key: `chose:${card.entry}`, subject: `${input.actor} chose “${option.label}” for “${card.title}”`, body: `It moves to ${titleOf(option.to)}.` }, now);
+        const title = titleOf(option.to);
+        return { ok: true, said: `${option.label}. Moved to ${title}${/[.?!]$/.test(title) ? "" : "."}` };
+    }
+    const note = (input.note ?? "").trim();
+    const target = replyTarget(stage);
+    if (target === null)
+        return { ok: false, message: "Choose one of the options; this step doesn't take a reply." };
+    if (input.to !== undefined && target !== input.to)
+        return { ok: false, message: "Where replies go changed since; nothing was changed." };
+    if (note === "")
+        return { ok: false, message: "Say what you'd change." };
+    if (note.length > 2000)
+        return { ok: false, message: "Keep it under 2,000 characters." };
+    const revision = revisionWithNote(store, card, definition.stages.find(one => one.id === target), note, input.actor, input.repos, input.evidenceRoot, now);
+    const moved = store.transact(() => {
+        if (!store.moveFlowCard(card.id, { to: target, outcome: "sent-back", actor: input.actor, note, ...(revision === null ? {} : { task: revision }), expectEntry: card.entry }, now))
+            return false;
+        store.retireFlowChoices(card.id, card.entry, now);
+        ledger("replied", `a reply to ${titleOf(target)}`);
+        return true;
+    });
+    if (!moved)
+        return { ok: false, message: "That card has moved on since; nothing was changed." };
+    if (card.owner !== null && card.owner !== input.actor)
+        notifyPeople(store, card, [card.owner], input.actor, { key: `replied:${card.entry}`, subject: `${input.actor} replied on “${card.title}”`, body: `Sent to ${titleOf(target)}:\n\n${note}`, attention: true }, now);
+    return { ok: true, said: revision === null ? `Sent to ${titleOf(target)} with your note.` : `Sent to ${titleOf(target)}: a revision was made with your note.` };
+}

package/dist/flow-share.js

@@ -81,12 +81,15 @@ function stepOf(stage, ask) {
         step["teammate"] = stage.teammate;
     if (stage.reply === true)
         step["reply"] = true;
+    // A choice's buttons; "end" ignores the card. A build in another project names a path on this computer, so it stays here.
+    if (stage.options !== undefined)
+        step["options"] = stage.options.map(one => ({ label: one.label, goesTo: one.to }));
     if (stage.limit !== undefined)
         Object.assign(step, { remindAfter: words(stage.limit.minutes), ...(stage.limit.to === null ? {} : { thenMoveTo: stage.limit.to }) });
     if (stage.next !== null)
         step["next"] = stage.next;
     if (stage.onFail !== null)
-        step[stage.kind === "sort" ? "ifNotSure" : stage.kind === "wait" ? "ifNoReply" : "ifFails"] = stage.onFail;
+        step[stage.kind === "sort" ? "ifNotSure" : stage.kind === "wait" ? "ifNoReply" : stage.kind === "choose" ? "ifReplied" : "ifFails"] = stage.onFail;
     step["at"] = { x: stage.zone.x, y: stage.zone.y, w: stage.zone.w, h: stage.zone.h, color: stage.zone.color };
     return step;
 }
@@ -181,7 +184,7 @@ function scrubber(values, names) {
     };
 }
 /** Structural fields: ids and references, never prose. Scrubbing them would break the flow's paths. */
-const STRUCTURAL = new Set(["format", "id", "kind", "goesTo", "next", "ifFails", "ifNotSure", "ifNoReply", "thenMoveTo", "zone", "script", "language", "planning", "runIn", "waitFor", "method", "watch", "from", "delivery", "color", "merge"]);
+const STRUCTURAL = new Set(["format", "id", "kind", "goesTo", "next", "ifFails", "ifNotSure", "ifNoReply", "ifReplied", "thenMoveTo", "zone", "script", "language", "planning", "runIn", "waitFor", "method", "watch", "from", "delivery", "color", "merge"]);
 function scrubDeep(value, scrub, key, inScripts) {
     if (typeof value === "string")
         return key !== null && (STRUCTURAL.has(key) || (inScripts && key === "name")) ? value : scrub(value);
@@ -272,7 +275,7 @@ function stageInputOf(step, index, find) {
     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["ifFails"];
+    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 sureAt = step["sureAt"];
     return {
@@ -290,6 +293,7 @@ function stageInputOf(step, index, find) {
         ...(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") } } : {}),
         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),
     };

package/dist/flow-steps.js

@@ -350,7 +350,7 @@ async function runCheck(store, flow, stage, script, card, now, io) {
                 return { state: "failed", said: `The project's setup failed before ${script.name} ran (exit ${prepared.code}).\n${tail(`${prepared.stdout}\n${prepared.stderr}`)}`, log, exitCode: prepared.code };
         }
         const definition = flowDefinitionOf(flow);
-        const titleOf = (id) => definition?.stages.find(one => one.id === id)?.title ?? id;
+        const titleOf = (id) => definition?.stages.find(one => one.id === id.split(".")[0])?.title ?? id;
         // The card as data: never part of a command.
         const input = {
             card: { id: card.id, title: card.title, description: card.description, email: cardEmailOf(card) || null, note: card.note, owner: card.owner, source: card.source === null ? null : { kind: card.source.kind, label: card.source.label, url: card.source.url } },

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}`}`)),