toolroll 0.5.0

package/dist/flow-insights.js

@@ -0,0 +1,149 @@
+/**
+ * Flow insights (v84): how work moves through a flow and where it breaks,
+ * read from what the flow already records — every card's moves (flow_event)
+ * and every script or update step's run (flow_step_run, with its log). No
+ * model, no sampling: counts over a window, per zone and per script.
+ */
+import { flowDefinitionOf } from "./flow-engine.js";
+import { parseSortDecision } from "./flow-sort.js";
+const median = (values) => {
+    if (values.length === 0)
+        return null;
+    const sorted = [...values].sort((a, b) => a - b);
+    const middle = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 1 ? sorted[middle] : (sorted[middle - 1] + sorted[middle]) / 2;
+};
+/** One flow's insights over the last `days` days. */
+export function flowInsights(store, flow, now, days = 30) {
+    const since = new Date(now.getTime() - days * 86_400_000);
+    const definition = flowDefinitionOf(flow);
+    const stages = definition?.stages ?? [];
+    const titleOf = (id) => stages.find(one => one.id === id)?.title ?? id;
+    const cards = store.flowCards(flow.id, true);
+    const cardTitle = (id) => cards.find(one => one.id === id)?.title ?? `card ${id}`;
+    const zones = new Map(stages.map(stage => [stage.id, {
+            zone: stage.id, title: stage.title, kind: stage.kind, entered: 0, movedOn: 0, failed: 0, sentBack: 0,
+            here: cards.filter(card => card.state === "active" && card.stage === stage.id).length, typicalMinutes: null, lastProblem: null, stays: [],
+        }]));
+    const moves = store.flowMoves(flow.id, since);
+    const byCard = new Map();
+    for (const move of moves)
+        byCard.set(move.card, [...byCard.get(move.card) ?? [], move]);
+    for (const [card, list] of byCard)
+        list.forEach((move, index) => {
+            const arrived = zones.get(move.toStage);
+            if (arrived !== undefined) {
+                arrived.entered++;
+                const next = list[index + 1];
+                if (next !== undefined)
+                    arrived.stays.push((Date.parse(next.at) - Date.parse(move.at)) / 60_000);
+            }
+            const left = move.fromStage === null ? undefined : zones.get(move.fromStage);
+            if (left === undefined)
+                return;
+            if (move.outcome === "fail" || move.outcome === "sent-back") {
+                if (move.outcome === "fail")
+                    left.failed++;
+                else
+                    left.sentBack++;
+                left.lastProblem = { card, cardTitle: cardTitle(card), note: move.note, at: move.at };
+            }
+            else if (move.outcome !== "cancelled")
+                left.movedOn++;
+        });
+    const zoneList = [...zones.values()].map(({ stays, ...zone }) => ({ ...zone, typicalMinutes: median(stays) === null ? null : Math.round(median(stays) * 10) / 10 }));
+    const doneZones = new Set(stages.filter(one => one.kind === "done").map(one => one.id));
+    const runs = store.flowStepRuns(flow.id, since, 200);
+    const scripts = new Map();
+    for (const run of runs) {
+        if (run.script === null || (run.state !== "passed" && run.state !== "failed"))
+            continue;
+        const entry = scripts.get(run.script) ?? { runs: 0, passed: 0, failed: 0, durations: [], lastFailure: null };
+        entry.runs++;
+        if (run.state === "passed")
+            entry.passed++;
+        else {
+            entry.failed++;
+            entry.lastFailure ??= run.result;
+        }
+        if (run.durationMs !== null)
+            entry.durations.push(run.durationMs / 1000);
+        scripts.set(run.script, entry);
+    }
+    const sorts = stages.filter(one => one.kind === "sort" && one.sort !== null).map(stage => sortInsight(stage, runs, byCard));
+    return {
+        flow: flow.id, name: flow.name, days,
+        cards: {
+            started: moves.filter(one => one.outcome === "created").length,
+            finished: new Set(moves.filter(one => doneZones.has(one.toStage)).map(one => one.card)).size,
+            active: cards.filter(one => one.state === "active").length,
+        },
+        zones: zoneList,
+        breaks: zoneList.filter(one => one.failed + one.sentBack > 0).sort((a, b) => (b.failed + b.sentBack) - (a.failed + a.sentBack)).slice(0, 3)
+            .map(one => ({ zone: one.zone, title: one.title, problems: one.failed + one.sentBack, of: Math.max(one.entered, one.failed + one.sentBack) })),
+        scripts: [...scripts].map(([script, one]) => ({ script, runs: one.runs, passed: one.passed, failed: one.failed, typicalSeconds: median(one.durations) === null ? null : Math.round(median(one.durations)), lastFailure: one.lastFailure })),
+        sorts,
+        runs: runs.slice(0, 40).map(run => ({
+            card: run.card, cardTitle: run.cardTitle, entry: run.entry, zone: run.stage, zoneTitle: titleOf(run.stage), kind: run.kind, script: run.script, version: run.scriptVersion,
+            state: run.state, result: run.result, exitCode: run.exitCode, durationMs: run.durationMs, at: run.finishedAt ?? run.startedAt, hasLog: run.log !== null && run.log !== "",
+        })),
+    };
+}
+const BANDS = [[90, 101], [80, 90], [70, 80], [50, 70]];
+function sortInsight(stage, runs, byCard) {
+    const sort = stage.sort;
+    const targets = new Set(sort.answers.map(one => one.to));
+    const bands = BANDS.map(([from, to]) => ({ from, to: Math.min(to, 100), right: 0, of: 0 }));
+    const insight = { zone: stage.id, title: stage.title, sureAt: sort.sureAt, sorted: 0, alone: 0, notSure: 0, corrected: 0, bands, costUsd: 0, suggestion: null };
+    for (const run of runs) {
+        if (run.kind !== "sort" || run.stage !== stage.id || run.state !== "passed")
+            continue;
+        const decision = parseSortDecision(run.decisionJson);
+        if (decision === null)
+            continue;
+        insight.sorted++;
+        if (decision.confident)
+            insight.alone++;
+        else
+            insight.notSure++;
+        insight.costUsd += decision.cost ?? 0;
+        // Where the sort sent the card, and what happened to it next.
+        const moves = byCard.get(run.card) ?? [];
+        const sent = moves.findIndex(one => one.fromStage === stage.id && one.actor === "flow" && one.at >= run.startedAt);
+        const after = sent === -1 ? undefined : moves[sent + 1];
+        const picked = sort.answers.find(one => one.answer === decision.answer)?.to ?? null;
+        let right = null;
+        if (after !== undefined && after.actor !== "flow" && after.outcome === "moved" && targets.has(after.toStage)) {
+            // A person placed it where an answer leads: that is what the answer should have been.
+            right = after.toStage === picked;
+            if (decision.confident && !right)
+                insight.corrected++;
+        }
+        else if (decision.confident && after !== undefined)
+            right = true;
+        if (right === null)
+            continue;
+        const band = bands.find(one => decision.sure * 100 >= one.from && decision.sure * 100 < (one.to === 100 ? 101 : one.to));
+        if (band !== undefined) {
+            band.of++;
+            if (right)
+                band.right++;
+        }
+    }
+    insight.costUsd = Math.round(insight.costUsd * 1_000_000) / 1_000_000;
+    // Say so only with enough cards behind it.
+    const at = Math.round(sort.sureAt * 100);
+    const below = bands.find(one => one.to <= at && one.to > at - 15 && one.of >= 5);
+    const above = bands.filter(one => one.from >= at && one.of >= 5);
+    const shaky = above.find(one => one.right / one.of < 0.8);
+    if (shaky !== undefined)
+        insight.suggestion = `Jev was wrong on ${shaky.of - shaky.right} of ${shaky.of} cards it sent on alone at ${shaky.from}–${shaky.to}% sure. Consider asking for ${Math.min(95, shaky.to)}%.`;
+    else if (below !== undefined && below.right / below.of >= 0.9)
+        insight.suggestion = `Cards Jev was ${below.from}–${below.to}% sure about were right ${below.right} of ${below.of} times. You could let it act alone from ${below.from}%.`;
+    return insight;
+}
+/** One line for a flow's list entry: where it has had the most trouble lately. */
+export function troubleWords(insights) {
+    const worst = insights.breaks[0];
+    return worst === undefined ? null : `most trouble in ${worst.title} (${worst.problems} of ${worst.of} in the last ${insights.days} days)`;
+}

package/dist/flow-live.d.ts

@@ -0,0 +1,24 @@
+import type { ServerResponse } from "node:http";
+import type { Store } from "./store.js";
+export type FlowPresence = {
+    name: string;
+    cards: number[];
+    editing: boolean;
+};
+export type FlowViewer = {
+    name: string;
+    card: number | null;
+    editing: boolean;
+    response: ServerResponse;
+    valid: () => boolean;
+};
+/** What changes when anything on the canvas changes: one row, one read, kept short and opaque. */
+export declare function flowFingerprint(store: Store, flow: number): string | null;
+export type FlowRooms = {
+    /** Keep this page's stream on the flow until it closes; the first event says where the flow stands. */
+    join: (flow: number, viewer: FlowViewer) => void;
+    /** Every stream, ended (the server is closing). */
+    close: () => void;
+    size: () => number;
+};
+export declare function createFlowRooms(fingerprint: (flow: number) => string | null, tickMs?: number): FlowRooms;

package/dist/flow-live.js

@@ -0,0 +1,150 @@
+/**
+ * The live canvas (v88): a flow open in several browsers stays the same in
+ * all of them, and each shows who else has it open.
+ *
+ * - A change nudge. While anyone has a flow open, one cheap query a second
+ *   reads the flow's fingerprint (its revision, cards, moves, comments,
+ *   watchers, step runs and triggers); when it changes, every open page
+ *   hears "change" and reads the flow again the usual way. The nudge
+ *   carries no card data: what a page shows is always what its own read
+ *   returned, under its own checks.
+ * - Who's here. Each open page says which card it has open and whether it
+ *   is changing the flow; everyone else on the flow hears the list, by
+ *   name. It lives in memory only and goes when the page closes or hides.
+ *
+ * Streams are refresh hints only: nothing here writes, and a page that
+ * can't keep one open falls back to reading every few seconds.
+ */
+import { createHash } from "node:crypto";
+const TICK_MS = 1_000;
+const CHECK_EVERY = 15;
+const HEARTBEAT_EVERY = 15;
+const PRESENCE_SETTLE_MS = 150;
+/** What changes when anything on the canvas changes: one row, one read, kept short and opaque. */
+export function flowFingerprint(store, flow) {
+    const row = store.handle.prepare(`SELECT f.state || '|' || f.revision || '|' || f.updated_at || '|' || coalesce(f.owner, '') AS head,
+    (SELECT count(*) || ':' || coalesce(max(updated_at), '') FROM flow_card WHERE flow = f.id) AS cards,
+    (SELECT coalesce(max(e.id), 0) FROM flow_event e JOIN flow_card c ON c.id = e.card WHERE c.flow = f.id) AS moves,
+    (SELECT coalesce(max(m.id), 0) FROM flow_comment m JOIN flow_card c ON c.id = m.card WHERE c.flow = f.id) AS comments,
+    (SELECT count(*) || ':' || coalesce(max(w.added_at), '') FROM flow_card_watcher w JOIN flow_card c ON c.id = w.card WHERE c.flow = f.id) AS watchers,
+    (SELECT count(*) || ':' || coalesce(sum(r.attempts), 0) || ':' || coalesce(max(coalesce(r.finished_at, r.started_at)), '') || ':' || coalesce(sum(r.state = 'running'), 0)
+       FROM flow_step_run r JOIN flow_card c ON c.id = r.card WHERE c.flow = f.id) AS runs,
+    (SELECT count(*) || ':' || coalesce(max(updated_at), '') || ':' || coalesce(max(last_at), '') || ':' || coalesce(sum(failures), 0) FROM flow_trigger WHERE flow = f.id) AS triggers
+    FROM flow f WHERE f.id = ?`).get(flow);
+    return row === undefined ? null : createHash("sha256").update(Object.values(row).map(String).join("|")).digest("hex").slice(0, 16);
+}
+export function createFlowRooms(fingerprint, tickMs = TICK_MS) {
+    const rooms = new Map();
+    const write = (viewer, event, data) => {
+        if (viewer.response.writableEnded || viewer.response.destroyed)
+            return;
+        viewer.response.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+    };
+    /** Everyone on the flow but you, one line per person however many pages they have open. */
+    const others = (room, me) => {
+        const people = new Map();
+        for (const one of room.viewers) {
+            if (one.name === me)
+                continue;
+            const seen = people.get(one.name) ?? { name: one.name, cards: [], editing: false };
+            if (one.card !== null && !seen.cards.includes(one.card))
+                seen.cards.push(one.card);
+            seen.editing ||= one.editing;
+            people.set(one.name, seen);
+        }
+        return [...people.values()].sort((a, b) => a.name.localeCompare(b.name));
+    };
+    const announce = (room) => {
+        // A page that moves from one card to the next leaves and joins at once: say it once, after it settles.
+        if (room.settling !== null)
+            clearTimeout(room.settling);
+        room.settling = setTimeout(() => {
+            room.settling = null;
+            for (const viewer of room.viewers)
+                write(viewer, "here", { people: others(room, viewer.name) });
+        }, PRESENCE_SETTLE_MS);
+        room.settling.unref();
+    };
+    const leave = (flow, viewer) => {
+        const room = rooms.get(flow);
+        if (room === undefined || !room.viewers.delete(viewer))
+            return;
+        if (!viewer.response.writableEnded)
+            viewer.response.end();
+        if (room.viewers.size > 0) {
+            announce(room);
+            return;
+        }
+        if (room.timer !== null)
+            clearInterval(room.timer);
+        if (room.settling !== null)
+            clearTimeout(room.settling);
+        rooms.delete(flow);
+    };
+    const tick = (flow, room) => {
+        room.ticks += 1;
+        if (room.ticks % CHECK_EVERY === 0) {
+            // A signed-out or narrowed account stops hearing about the flow.
+            for (const viewer of [...room.viewers])
+                if (!viewer.valid()) {
+                    write(viewer, "gone", {});
+                    leave(flow, viewer);
+                }
+            if (!rooms.has(flow))
+                return;
+        }
+        let now;
+        try {
+            now = fingerprint(flow);
+        }
+        catch {
+            return; /* a busy database: the next tick reads again */
+        }
+        if (now === null) {
+            for (const viewer of [...room.viewers]) {
+                write(viewer, "gone", {});
+                leave(flow, viewer);
+            }
+            return;
+        }
+        if (now !== room.last) {
+            room.last = now;
+            for (const viewer of room.viewers)
+                write(viewer, "change", { at: now });
+        }
+        else if (room.ticks % HEARTBEAT_EVERY === 0) {
+            for (const viewer of room.viewers)
+                if (!viewer.response.writableEnded)
+                    viewer.response.write(": keep-alive\n\n");
+        }
+    };
+    return {
+        join(flow, viewer) {
+            let room = rooms.get(flow);
+            if (room === undefined) {
+                let last = null;
+                try {
+                    last = fingerprint(flow);
+                }
+                catch { /* the first tick reads it */ }
+                room = { viewers: new Set(), last, timer: null, ticks: 0, settling: null };
+                const created = room;
+                room.timer = setInterval(() => tick(flow, created), tickMs);
+                room.timer.unref();
+                rooms.set(flow, room);
+            }
+            room.viewers.add(viewer);
+            write(viewer, "change", { at: room.last });
+            write(viewer, "here", { people: others(room, viewer.name) });
+            announce(room);
+            const gone = () => leave(flow, viewer);
+            viewer.response.once("close", gone);
+        },
+        close() {
+            for (const [flow, room] of [...rooms])
+                for (const viewer of [...room.viewers])
+                    leave(flow, viewer);
+        },
+        size: () => [...rooms.values()].reduce((sum, room) => sum + room.viewers.size, 0),
+    };
+}

package/dist/flow-people.d.ts

@@ -0,0 +1,24 @@
+import { type FlowAct } from "./flow-engine.js";
+import type { FlowCardRow, Store } from "./store.js";
+/** Everyone who may take part in a project's flows: approvers who can reach the project. */
+export declare function flowPeople(store: Store, repo: string): string[];
+/** The people a comment @mentions: known names only, each once, in the order written. */
+export declare function mentionsIn(body: string, people: readonly string[]): string[];
+type CardEvent = {
+    key: string;
+    subject: string;
+    body: string;
+    attention?: boolean;
+};
+/** One notification per person, to that person only. The actor never notifies themself. */
+export declare function notifyPeople(store: Store, card: FlowCardRow, people: Iterable<string>, actor: string | null, event: CardEvent, now: Date): string[];
+/** Who follows a card: its owner and its watchers. */
+export declare function cardFollowers(store: Store, card: FlowCardRow): string[];
+/** Make someone (or no one) a card's owner. The new owner follows it and hears so. */
+export declare function assignFlowCard(store: Store, card: FlowCardRow, owner: string | null, actor: string, now: Date): FlowAct;
+export declare function watchFlowCard(store: Store, card: FlowCardRow, name: string, watching: boolean, now: Date): FlowAct;
+/** A comment on a card: keys refused; the people it @mentions, the owner and watchers hear about it; the author and anyone mentioned follow it from now on. */
+export declare function commentOnFlowCard(store: Store, card: FlowCardRow, author: string, text: unknown, now: Date): FlowAct & {
+    mentions?: string[];
+};
+export {};

package/dist/flow-people.js

@@ -0,0 +1,91 @@
+/**
+ * People on flow cards (v83): who owns a card, who follows it, what was said
+ * on it, and who hears about what. A notification about a card goes to the
+ * people it concerns — the one who decides, its owner, its watchers, whoever
+ * was @mentioned — on their own paired phone or chat, never to everyone.
+ * A "Tell the team" zone still posts to everyone; that is what it is for.
+ */
+import { scanForSecrets } from "./evidence.js";
+import { flowCardHref } from "./flow-engine.js";
+/** Everyone who may take part in a project's flows: approvers who can reach the project. */
+export function flowPeople(store, repo) {
+    return store.listApprovers().map(one => one.name).filter(name => store.accountCanAccess(name, repo));
+}
+/** The people a comment @mentions: known names only, each once, in the order written. */
+export function mentionsIn(body, people) {
+    const found = [];
+    for (const match of body.matchAll(/(^|[^A-Za-z0-9_.@-])@([A-Za-z0-9][A-Za-z0-9_.-]{0,63})/g)) {
+        const name = people.find(one => one.toLowerCase() === match[2].replace(/[.-]+$/, "").toLowerCase());
+        if (name !== undefined && !found.includes(name))
+            found.push(name);
+    }
+    return found;
+}
+/** One notification per person, to that person only. The actor never notifies themself. */
+export function notifyPeople(store, card, people, actor, event, now) {
+    const flow = store.getFlow(card.flow);
+    if (flow === null)
+        return [];
+    const sent = [];
+    for (const person of new Set(people)) {
+        if (person === actor || !store.accountCanAccess(person, flow.repo))
+            continue;
+        const queued = store.enqueueNotification({
+            dedupeKey: `flow-card:${card.id}:${event.key}:${person}`, kind: "flow-card", recipient: person,
+            ...(event.attention === true ? { pushClass: "attention" } : {}),
+            subject: `${flow.name}: ${event.subject}`.slice(0, 200), body: event.body.slice(0, 2000), link: flowCardHref(flow.id, card.id), source: { project: flow.repo },
+        }, now);
+        if (queued)
+            sent.push(person);
+    }
+    return sent;
+}
+/** Who follows a card: its owner and its watchers. */
+export function cardFollowers(store, card) {
+    return [...new Set([...(card.owner === null ? [] : [card.owner]), ...store.flowCardWatchers(card.id)])];
+}
+/** Make someone (or no one) a card's owner. The new owner follows it and hears so. */
+export function assignFlowCard(store, card, owner, actor, now) {
+    const flow = store.getFlow(card.flow);
+    if (flow === null || card.state !== "active")
+        return { ok: false, message: "That card is finished." };
+    if (owner !== null && !flowPeople(store, flow.repo).includes(owner))
+        return { ok: false, message: `${owner} can't work on this project.` };
+    if (owner === card.owner)
+        return { ok: true, said: owner === null ? "It has no owner." : `${owner === actor ? "You already own" : `${owner} already owns`} it.`, card: card.id };
+    store.setFlowCardOwner(card.id, owner, actor, now);
+    if (owner !== null) {
+        store.setFlowCardWatcher(card.id, owner, true, now);
+        notifyPeople(store, card, [owner], actor, { key: `owner:${now.getTime()}`, subject: `You now own “${card.title}”`, body: `${actor} made you the owner of “${card.title}”. You'll hear when it needs you or finishes.` }, now);
+    }
+    return { ok: true, said: owner === null ? "It has no owner now." : owner === actor ? "You own it now." : `${owner} owns it now.`, card: card.id };
+}
+export function watchFlowCard(store, card, name, watching, now) {
+    store.setFlowCardWatcher(card.id, name, watching, now);
+    return { ok: true, said: watching ? "You'll hear about this card." : "You won't hear about this card unless someone mentions you.", card: card.id };
+}
+/** A comment on a card: keys refused; the people it @mentions, the owner and watchers hear about it; the author and anyone mentioned follow it from now on. */
+export function commentOnFlowCard(store, card, author, text, now) {
+    const flow = store.getFlow(card.flow);
+    if (flow === null)
+        return { ok: false, message: "That card is gone." };
+    const body = (typeof text === "string" ? text : "").replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "").trim();
+    if (body === "")
+        return { ok: false, message: "Write something first." };
+    if (body.length > 4000)
+        return { ok: false, message: "Keep a comment under 4000 characters." };
+    if (scanForSecrets(body).length > 0)
+        return { ok: false, message: "That looks like a key or password. Keep secrets out of comments." };
+    const mentions = mentionsIn(body, flowPeople(store, flow.repo));
+    const followers = cardFollowers(store, card);
+    const id = store.transact(() => {
+        const made = store.addFlowComment({ card: card.id, author, body, mentions }, now);
+        for (const person of [author, ...mentions])
+            store.setFlowCardWatcher(card.id, person, true, now);
+        return made;
+    });
+    const quote = body.length > 280 ? `${body.slice(0, 277)}…` : body;
+    notifyPeople(store, card, mentions, author, { key: `mention:${id}`, subject: `${author} mentioned you on “${card.title}”`, body: quote, attention: true }, now);
+    notifyPeople(store, card, followers.filter(one => !mentions.includes(one)), author, { key: `comment:${id}`, subject: `${author} commented on “${card.title}”`, body: quote }, now);
+    return { ok: true, said: mentions.length === 0 ? "Comment added." : `Comment added. ${mentions.join(" and ")} will hear about it.`, card: card.id, mentions };
+}

package/dist/flow-replies.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Replies to a card's email (v91).
+ *
+ * A Send email step keeps the Message-ID of what it sent and whom it went
+ * to. An email that names one of those (In-Reply-To or References) and comes
+ * from someone the card wrote to is a reply to that card: it joins the card's
+ * discussion, and a card waiting for it in a Wait zone moves on, the reply
+ * kept as that zone's output ({{stage.<wait zone>}}). Anyone can copy a
+ * Message-ID into a header, so a message from anyone else is never taken as a
+ * reply; neither is a machine's (out of office, bounces).
+ *
+ * The mailbox is read for replies only while some card is in an email
+ * conversation, about once a minute, read-only like Inbox triggers. An Inbox
+ * trigger reading the same mailbox hands replies here instead of making a new
+ * card, and a reply both see is taken once.
+ */
+import type { FlowCardRow, Store } from "./store.js";
+import { type InboundMail, type MailReader } from "./mailbox.js";
+/** Where the next email to this card's conversation goes in the thread: its latest message, and the chain before it. */
+export declare function threadOf(store: Store, card: FlowCardRow): {
+    inReplyTo: string;
+    references: string[];
+    people: Set<string>;
+} | null;
+/** What a Send email step sent, kept so a reply can find the card (and the email the card came from, which a reply may name). */
+export declare function recordSent(store: Store, card: FlowCardRow, sent: {
+    id: string;
+    to: string[];
+}, now: Date): void;
+export type Replied = {
+    card: FlowCardRow;
+    moved: boolean;
+    again: boolean;
+};
+/** Take one email as a reply to the card whose conversation it answers; null when it answers none that is active. */
+export declare function takeReply(store: Store, mail: InboundMail, own: string, now: Date): Replied | null;
+export type ReplyWatchIo = {
+    dir: string | null;
+    fetch: typeof fetch;
+    mail?: MailReader;
+};
+export type ReplyWatch = {
+    read: number;
+    taken: number;
+    problem: string | null;
+};
+/** Read the mailbox for replies to cards in an email conversation, when it is due. */
+export declare function watchFlowReplies(store: Store, now: Date, io: ReplyWatchIo): Promise<ReplyWatch>;

package/dist/flow-replies.js

@@ -0,0 +1,113 @@
+import { validateFlowDefinition } from "./flows.js";
+import { mailboxAccess, mailCursorOf, mailCursorText, readThroughImap } from "./mailbox.js";
+import { cardFollowers, notifyPeople } from "./flow-people.js";
+const WATCH_EVERY_MS = 60_000;
+const BACKOFF_MS = [60_000, 5 * 60_000, 15 * 60_000];
+/** A first read (or one after a long pause) looks this many messages back, so a reply that came just before isn't missed. */
+const LOOK_BACK = 50;
+const PER_READ = 50;
+const REPLY_CHARS = 4000;
+const definitionOf = (store, flow) => {
+    const row = store.getFlow(flow);
+    try {
+        return row === null ? null : validateFlowDefinition(JSON.parse(row.definitionJson));
+    }
+    catch {
+        return null;
+    }
+};
+/** Everyone a card's conversation is with: whom it wrote to, who wrote back, and who sent the email it came from. */
+function peopleOf(store, card) {
+    const people = new Set(store.flowMailOf(card.id).flatMap(one => one.address.split(",")).filter(one => one !== ""));
+    if (card.source?.mail?.from)
+        people.add(card.source.mail.from.toLowerCase());
+    return people;
+}
+/** Where the next email to this card's conversation goes in the thread: its latest message, and the chain before it. */
+export function threadOf(store, card) {
+    const source = card.source?.mail;
+    const ids = [...(source?.references ?? []), ...(source?.id ? [source.id] : []), ...store.flowMailOf(card.id).map(one => one.messageId)];
+    const chain = [...new Set(ids)];
+    const latest = chain.at(-1);
+    return latest === undefined ? null : { inReplyTo: latest, references: chain.slice(-20), people: peopleOf(store, card) };
+}
+/** What a Send email step sent, kept so a reply can find the card (and the email the card came from, which a reply may name). */
+export function recordSent(store, card, sent, now) {
+    if (!/^<[^<>\s]{3,250}>$/.test(sent.id))
+        return;
+    store.recordFlowMail({ messageId: sent.id, card: card.id, direction: "sent", address: sent.to.map(one => one.toLowerCase()).join(",") }, now);
+    const source = card.source?.mail;
+    if (source?.id)
+        store.recordFlowMail({ messageId: source.id, card: card.id, direction: "received", address: source.from }, now);
+}
+/** Take one email as a reply to the card whose conversation it answers; null when it answers none that is active. */
+export function takeReply(store, mail, own, now) {
+    if (mail.automatic || mail.messageId === null || mail.from === "" || mail.from === own.toLowerCase())
+        return null;
+    const named = [...new Set([mail.inReplyTo, ...[...mail.references].reverse()].filter((one) => one !== null))];
+    const seen = new Set();
+    for (const known of store.flowMailAmong(named)) {
+        if (seen.has(known.card))
+            continue;
+        seen.add(known.card);
+        const card = store.getFlowCard(known.card);
+        if (card === null || card.state !== "active" || !peopleOf(store, card).has(mail.from))
+            continue;
+        // A trigger and the watcher can both read it: it is taken once.
+        if (!store.recordFlowMail({ messageId: mail.messageId, card: card.id, direction: "received", address: mail.from }, now))
+            return { card, moved: false, again: true };
+        const text = mail.text.length > REPLY_CHARS ? `${mail.text.slice(0, REPLY_CHARS).trimEnd()}…` : mail.text;
+        const who = mail.fromName === null ? mail.from : `${mail.fromName} <${mail.from}>`;
+        store.addFlowComment({ card: card.id, author: mail.from, body: `Replied by email${mail.subject === "" ? "" : ` (“${mail.subject}”)`}:\n\n${text || "(no text)"}`, mentions: [] }, now);
+        const definition = definitionOf(store, card.flow);
+        const stage = definition?.stages.find(one => one.id === card.stage);
+        const waiting = stage?.kind === "wait" && stage.wait?.for === "reply" && stage.next !== null;
+        // The people on the card hear about it; it needs them only when the flow wasn't waiting for it.
+        const people = card.owner === null ? cardFollowers(store, card) : [card.owner];
+        notifyPeople(store, card, people, null, { key: `reply:${mail.messageId}`, subject: `${mail.fromName ?? mail.from} replied to “${card.title}”`, body: text || "(no text)", attention: !waiting }, now);
+        if (waiting) {
+            store.updateFlowCard(card.id, { outputs: { ...card.outputs, [stage.id]: `From: ${who}\n\n${text}` } }, now);
+            const moved = store.moveFlowCard(card.id, { to: stage.next, outcome: "ok", actor: "flow", historyNote: `${mail.from} replied`, expectEntry: card.entry }, now);
+            return { card, moved, again: false };
+        }
+        return { card, moved: false, again: false };
+    }
+    return null;
+}
+/** Read the mailbox for replies to cards in an email conversation, when it is due. */
+export async function watchFlowReplies(store, now, io) {
+    const quiet = { read: 0, taken: 0, problem: null };
+    const watch = store.flowMailWatch();
+    if (watch.nextAt !== null && Date.parse(watch.nextAt) > now.getTime())
+        return quiet;
+    if (!store.flowConversationsOpen())
+        return quiet;
+    const failed = (said) => {
+        const failures = watch.failures + 1;
+        store.setFlowMailWatch({ cursor: watch.cursor, nextAt: new Date(now.getTime() + BACKOFF_MS[Math.min(failures, BACKOFF_MS.length) - 1]).toISOString(), failures, lastOutcome: said }, now);
+        return { read: 0, taken: 0, problem: said };
+    };
+    const signed = await mailboxAccess(io.dir, io.fetch);
+    if (!signed.ok)
+        return failed(signed.said);
+    const reader = io.mail ?? readThroughImap;
+    // After a long pause the mailbox may hold a lot: start again from now, looking a little way back.
+    const stale = watch.nextAt === null || now.getTime() - Date.parse(watch.nextAt) > 24 * 60 * 60_000;
+    let after = stale ? null : mailCursorOf(watch.cursor);
+    if (after === null) {
+        const where = await reader(signed.access, "INBOX", null, 0);
+        if (!where.ok)
+            return failed(where.said);
+        after = { validity: where.at.validity, uid: Math.max(0, where.at.uid - LOOK_BACK) };
+    }
+    const read = await reader(signed.access, "INBOX", after, PER_READ);
+    if (!read.ok)
+        return failed(read.said);
+    let taken = 0;
+    for (const mail of read.mails)
+        if (takeReply(store, mail, signed.address, now)?.again === false)
+            taken++;
+    store.setFlowMailWatch({ cursor: mailCursorText(read.at), nextAt: new Date(now.getTime() + (read.more ? 0 : WATCH_EVERY_MS)).toISOString(), failures: 0,
+        lastOutcome: taken === 0 ? "No new replies." : `${taken} ${taken === 1 ? "reply" : "replies"} taken.` }, now);
+    return { read: read.mails.length, taken, problem: null };
+}

package/dist/flow-scripts.d.ts

@@ -0,0 +1,38 @@
+import { type ScriptLanguage } from "./flows.js";
+import type { FlowScriptRow, Store } from "./store.js";
+export type ScriptDraft = {
+    name: string;
+    about: string;
+    body: string;
+    timeoutMinutes: number;
+    language: ScriptLanguage;
+    file: string | null;
+};
+/** A script as it would be saved, checked in plain words. Throws. */
+export declare function validateScript(input: {
+    name?: unknown;
+    about?: unknown;
+    body?: unknown;
+    timeoutMinutes?: unknown;
+    language?: unknown;
+    file?: unknown;
+}): ScriptDraft;
+/** What a run is held to. A shell script written here keeps its v84 digest. */
+export declare const scriptDigest: (draft: Pick<ScriptDraft, "body" | "timeoutMinutes"> & Partial<Pick<ScriptDraft, "language" | "file">>) => string;
+export type ScriptSaved = {
+    ok: true;
+    said: string;
+    version: number;
+} | {
+    ok: false;
+    message: string;
+};
+/** Save a script (a new version when it exists). */
+export declare function saveScript(store: Store, repo: string, input: Parameters<typeof validateScript>[0], actor: string, now: Date): ScriptSaved;
+/** The flows and zones in a project that run each script. */
+export declare function scriptUses(store: Store, repo: string): Map<string, {
+    flow: number;
+    flowName: string;
+    zone: string;
+}[]>;
+export declare function scriptWords(script: FlowScriptRow): string;