toolroll 0.5.0

package/dist/flows-ui.d.ts

@@ -0,0 +1,20 @@
+/** Flows in the console: the list of a person's flows, and one flow's canvas
+ * (the React view's data, plus a plain fallback page the view replaces). */
+import type { BrowserFlowView } from "./browser-workspace.js";
+import type { FlowRow, Store } from "./store.js";
+export declare const FLOWS_CSS = ".flows{max-width:880px;min-width:0}.flows .card{padding:16px 18px;margin:12px 0}.flows .flow-row{display:flex;justify-content:space-between;align-items:baseline;gap:12px;flex-wrap:wrap}.flows .flow-row h2{font-size:1.05rem;margin:0}.flows .flow-counts{font-size:.85rem;color:var(--so-muted)}.flows form{display:grid;gap:10px;margin:0}.flows label{display:grid;gap:6px}.flows input,.flows select{box-sizing:border-box;width:100%;max-width:100%}.flows button{justify-self:start;min-height:44px}.flows .flow-fallback ol{padding-left:20px}.flows summary{cursor:pointer;min-height:44px;display:flex;align-items:center;font-weight:600}.flows .flow-buttons{display:flex;flex-wrap:wrap;gap:8px;margin:10px 0 0}@media(max-width:600px){.flows input,.flows select{font-size:16px}}";
+/** The flows a person can open, with how many cards wait in each, and the new-flow form. */
+export declare function flowsListHtml(store: Store, flows: readonly FlowRow[], projects: readonly string[], csrf: string, canCreate: boolean, problem: string | null): string;
+/** One flow's canvas for one person. */
+export declare function flowView(store: Store, flow: FlowRow, viewer: {
+    name: string;
+    approver: boolean;
+}, selectedCard: number | null, setup?: {
+    dir: string | null;
+    repos: readonly string[];
+    startTrigger?: number | null;
+    sortReady?: boolean;
+    toolHome?: string;
+}): BrowserFlowView;
+/** The page the canvas replaces when scripts can't run: each zone and its cards, in order. */
+export declare function flowFallbackHtml(view: BrowserFlowView): string;

package/dist/flows-ui.js

@@ -0,0 +1,175 @@
+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 { deciderOf, FLOW_COLORS, FLOW_KIND_WORDS, FLOW_STAGE_KINDS, FLOW_TEMPLATES } 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 { googleConnected } from "./google-mail.js";
+import { mailboxReady } from "./mailbox.js";
+import { labelOf, nameOf } from "./teammate-admin.js";
+import { callWords, receiptWords } from "./teammate-tools.js";
+import { undoFor } from "./teammate-week.js";
+const e = (value) => String(value ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+const projectName = (repo) => repo.split(/[\\/]/).filter(Boolean).pop() ?? repo;
+export const FLOWS_CSS = `.flows{max-width:880px;min-width:0}.flows .card{padding:16px 18px;margin:12px 0}.flows .flow-row{display:flex;justify-content:space-between;align-items:baseline;gap:12px;flex-wrap:wrap}.flows .flow-row h2{font-size:1.05rem;margin:0}.flows .flow-counts{font-size:.85rem;color:var(--so-muted)}.flows form{display:grid;gap:10px;margin:0}.flows label{display:grid;gap:6px}.flows input,.flows select{box-sizing:border-box;width:100%;max-width:100%}.flows button{justify-self:start;min-height:44px}.flows .flow-fallback ol{padding-left:20px}.flows summary{cursor:pointer;min-height:44px;display:flex;align-items:center;font-weight:600}.flows .flow-buttons{display:flex;flex-wrap:wrap;gap:8px;margin:10px 0 0}@media(max-width:600px){.flows input,.flows select{font-size:16px}}`;
+/** The flows a person can open, with how many cards wait in each, and the new-flow form. */
+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 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>` +
+            (buttons.length === 0 ? "" : `<p class="flow-buttons">${buttons.map(one => `<a class="button-link" href="/flows/${flow.id}?start=${one.id}">${e(one.label)}</a>`).join(" ")}</p>`) + `</article>`;
+    }).join("");
+    const create = canCreate && projects.length > 0 ? `<details class="card"${flows.length === 0 ? " open" : ""}><summary>New flow</summary><form method="post" action="/flows/new"><input type="hidden" name="csrf" value="${e(csrf)}"><label>Name<input name="name" required maxlength="80" placeholder="for example: Bug fixes"></label><label>Project<select name="repo">${projects.map(repo => `<option value="${e(repo)}">${e(projectName(repo))}</option>`).join("")}</select></label><label>Start from<select name="template">${FLOW_TEMPLATES.map(one => `<option value="${e(one.id)}">${e(one.label)}: ${e(one.about)}</option>`).join("")}</select></label><button>Create flow</button></form></details>` : "";
+    // No flows yet: one click makes a working example with a sample question in it.
+    const example = flows.length === 0 && canCreate && projects.length > 0
+        ? `<form method="post" action="/flows/example" class="card flow-example"><input type="hidden" name="csrf" value="${e(csrf)}"><h2>See a flow work</h2><p class="meta">Claude drafts a reply to a sample customer question; you approve it here or in your chat app.</p>${projects.length === 1 ? `<input type="hidden" name="repo" value="${e(projects[0])}">` : `<label>Project<select name="repo">${projects.map(repo => `<option value="${e(repo)}">${e(projectName(repo))}</option>`).join("")}</select></label>`}<button>Try an example</button></form>`
+        : "";
+    const intro = `<p class="meta">A flow is your process drawn as zones. Cards move through them: agents do the work, people approve, and the team hears about it.</p>` +
+        (canCreate && projects.length > 0 ? `<p class="flow-chat">Describe how work should move and your lead drafts the flow for you to confirm, or start from a template below. <a href="/chat?draft=${encodeURIComponent("Make a flow for ")}">Describe it in chat</a></p>` : "") +
+        `<p class="flow-chat">AI teammates can decide and handle cards for you, within rules you write. <a href="/teammates">Teammates</a> · or set one up with its flow in one click: <a href="/kits">Starter kits</a></p>`;
+    return `<section class="flows">${problem === null ? "" : `<p class="problem" role="alert">${e(problem)}</p>`}${intro}${rows || example || '<p class="meta">No flows yet.</p>'}${create}</section>`;
+}
+const historyText = (event, title, sorts = new Set()) => {
+    const who = event.actor === "flow" ? "" : ` by ${event.actor}`;
+    const note = event.note === null ? "" : `: ${event.note}`;
+    switch (event.outcome) {
+        case "created": return `Added to ${title(event.toStage)}${who}`;
+        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}`;
+        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}`;
+    }
+};
+/** One flow's canvas for one person. */
+export function flowView(store, flow, viewer, selectedCard, setup = { dir: null, repos: [] }) {
+    const definition = flowDefinitionOf(flow);
+    const stages = definition?.stages ?? [];
+    const title = (id) => stages.find(one => one.id === id)?.title ?? id;
+    const sortZones = new Set(stages.filter(one => one.kind === "sort").map(one => one.id));
+    const decisions = sortZones.size === 0 ? new Map() : store.flowSortDecisions(flow.id);
+    const mates = new Map(store.teammates([flow.repo]).map(one => [one.id, one]));
+    const cards = store.flowCards(flow.id, true).filter(card => card.state === "active" || Date.now() - Date.parse(card.updatedAt) < 7 * 86_400_000).map((card) => {
+        const stage = stages.find(one => one.id === card.stage);
+        const task = card.task ?? card.primaryTask;
+        const discussion = store.flowComments(card.id);
+        const watchers = store.flowCardWatchers(card.id);
+        const decider = stage?.kind === "approval" ? deciderOf(stage, flow) : null;
+        // While its teammate is deciding (v92), the card isn't anyone else's to decide yet.
+        const teammateDeciding = stage?.teammate !== undefined && card.waiting !== null && card.waiting.endsWith(" is deciding");
+        const canDecide = viewer.approver && card.state === "active" && stage?.kind === "approval" && (decider === null || decider === viewer.name) && !teammateDeciding;
+        // History reads moves and ownership together, newest first.
+        const owned = discussion.filter(one => one.kind === "owner").map(one => ({ text: one.body === "" ? `${one.author} left it without an owner` : one.body === one.author ? `${one.author} took it on` : `${one.author} made ${one.body} the owner`, at: one.at }));
+        const moves = store.flowEvents(card.id).map(event => ({ text: historyText(event, title, sortZones), at: event.at }));
+        const decision = parseSortDecision(decisions.get(card.id)?.decisionJson ?? null);
+        const shown = stage?.kind === "approval" && definition !== null ? draftFor(definition, stage) : null;
+        // v91: when a Wait zone gives up (or moves on), or a zone's time limit comes.
+        const clock = stage?.wait ?? stage?.limit;
+        const until = card.state !== "active" || stage === undefined || clock === undefined ? null : new Date(Date.parse(store.flowCardEnteredAt(card.id) ?? card.updatedAt) + clock.minutes * 60_000);
+        const deadline = until === null || until.getTime() <= Date.now() ? null : {
+            at: until.toISOString(),
+            label: stage.wait !== undefined ? (stage.wait.for === "reply" ? "No reply by" : "Moves on at") : stage.limit.to !== null ? `Moves to ${title(stage.limit.to)} at` : "Reminder at",
+        };
+        // Its open question: one of its own, or (v94) a tool call waiting for approval.
+        const asked = card.state === "active" ? store.openTeammateQuestionOn(card.id, card.entry) : null;
+        const pending = asked?.toolCall == null ? null : store.teammateCall(asked.toolCall);
+        // A decision its teammate handed over carries what the teammate said (v92).
+        const turn = card.state === "active" && stage?.kind === "approval" && stage.teammate !== undefined ? store.flowStepRun(card.id, card.entry) : null;
+        let handoff = null;
+        if (turn !== null && turn.kind === "teammate" && turn.state === "passed") {
+            try {
+                const said = JSON.parse(turn.decisionJson ?? "{}");
+                const mate = store.teammateByHandle(flow.repo, stage.teammate);
+                if (said.action === "hand_off" && typeof said.note === "string" && said.note !== "" && mate !== null)
+                    handoff = { from: labelOf(mate), note: said.note };
+            }
+            catch {
+                handoff = null;
+            }
+        }
+        const asker = asked === null || asked.state !== "open" ? null : store.getTeammate(asked.teammate);
+        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 })),
+            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,
+            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,
+            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 ?? "" } },
+            calls: store.teammateCallsOn(card.id).slice(-30).map(call => {
+                const mate = mates.get(call.teammate) ?? null;
+                // A person's undo (v97) reads as theirs, and its outcome says what it undid.
+                return { id: call.id, who: call.undoOf !== null ? call.decidedBy ?? "A person" : mate === null ? "A teammate" : nameOf(mate), words: callWords(call.tool, call.action, call.input, 400), state: call.state, outcome: receiptWords(store, call),
+                    why: call.undoOf !== null ? "" : call.why, result: call.state === "asked" ? null : call.result, at: call.createdAt, teammate: call.teammate, undo: viewer.approver ? undoFor(store, call) : null };
+            }),
+        };
+    });
+    const triggers = store.flowTriggers(flow.id).map(trigger => {
+        const config = triggerConfigOf(trigger);
+        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,
+            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),
+            shared: config?.kind === "button" && trigger.hookHash !== null,
+        };
+    });
+    return {
+        kind: "flow",
+        flow: { id: flow.id, name: flow.name, project: projectName(flow.repo), revision: flow.revision, href: `/flows/${flow.id}`, owner: flow.owner },
+        chatHref: `/chat?draft=${encodeURIComponent(`In the ${flow.name} flow, `)}`,
+        triggers,
+        triggerSetup: {
+            kinds: FLOW_TRIGGER_KINDS.map(kind => ({ kind, label: FLOW_TRIGGER_WORDS[kind] })),
+            githubRepo: githubRepoOf(flow.repo), linearKey: readLinearKey(setup.dir) !== null, hooksBase: readHooksBase(setup.dir), hooksPath: HOOK_PATH,
+            mailbox: mailboxReady(setup.dir) ? googleConnected(setup.dir)?.address ?? readEmailSettings(setup.dir)?.from ?? null : null,
+            otherFlows: store.listFlows(setup.repos).filter(one => one.id !== flow.id).map(one => ({ id: one.id, name: one.name, zones: (flowDefinitionOf(one)?.stages ?? []).map(stage => ({ id: stage.id, title: stage.title })) })),
+        },
+        startTrigger: setup.startTrigger ?? null,
+        me: viewer.name,
+        sortReady: setup.sortReady ?? false,
+        teammates: store.teammates([flow.repo]).map(mate => ({ handle: mate.handle, label: labelOf(mate), name: nameOf(mate), working: mate.state === "active", href: `/teammates/${mate.id}` })),
+        emailReady: sendingReady(setup.dir),
+        requestSecrets: flowSecretNames(setup.dir, flow.repo),
+        tools: projectToolsOf(store, flow.repo).map(tool => ({ name: tool.name, about: tool.spec.about, functions: tool.lastTest?.ok === true ? tool.lastTest.tools : [],
+            ready: toolStanding(tool, secretsSetFor(flow.repo, tool.spec, setup.toolHome)).ready })),
+        scripts: store.flowScripts(flow.repo).map(script => ({ name: script.name, about: script.about, body: script.body, timeoutMinutes: script.timeoutMinutes, version: script.version, savedBy: script.savedBy, savedAt: script.savedAt,
+            language: script.language, file: script.file,
+            usedHere: stages.filter(stage => stage.kind === "check" && stage.script === script.name).map(stage => stage.title) })),
+        start: definition?.start ?? stages[0]?.id ?? "",
+        stages,
+        cards,
+        selectedCard,
+        live: flowFingerprint(store, flow.id),
+        canEdit: viewer.approver,
+        approvers: store.listApprovers().map(one => one.name).filter(name => store.accountCanAccess(name, flow.repo)),
+        kinds: FLOW_STAGE_KINDS.map(kind => ({ kind, label: FLOW_KIND_WORDS[kind].label, about: FLOW_KIND_WORDS[kind].about })),
+        colors: [...FLOW_COLORS],
+    };
+}
+/** The page the canvas replaces when scripts can't run: each zone and its cards, in order. */
+export function flowFallbackHtml(view) {
+    return `<section class="flows flow-fallback"><p class="meta">${e(view.flow.project)}</p><ol>${view.stages.map(stage => {
+        const cards = view.cards.filter(card => card.stage === stage.id && card.state === "active");
+        return `<li><strong>${e(stage.title)}</strong> · ${e(FLOW_KIND_WORDS[stage.kind].label)}${cards.length === 0 ? "" : `<ul>${cards.map(card => `<li>${e(card.title)}${card.waiting === null ? "" : ` — ${e(card.waiting)}`}</li>`).join("")}</ul>`}</li>`;
+    }).join("")}</ol></section>`;
+}

package/dist/flows.d.ts

@@ -0,0 +1,229 @@
+export declare const FLOW_STAGE_KINDS: readonly ["inbox", "task", "report", "approval", "check", "update", "notify", "sort", "draft", "request", "email", "tool", "wait", "teammate", "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];
+export type FlowZone = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    color: FlowColor;
+};
+/** One answer a sort zone can pick: its name, what it means (what Jev reads), and the zone it sends the card to. */
+export type FlowSortAnswer = {
+    answer: string;
+    means: string;
+    to: string;
+};
+/** Something else a sort zone notes on the card: a score on a scale of levels, or a yes/no. */
+export type FlowSortNote = {
+    id: string;
+    kind: "score" | "yes-no";
+    question: string;
+    levels: string[] | null;
+};
+/** sort: the question, its answers, how sure Jev must be to act alone (0.5–0.99), and what else it notes. */
+export type FlowSort = {
+    question: string;
+    answers: FlowSortAnswer[];
+    sureAt: number;
+    notes: FlowSortNote[];
+};
+/** request: what is called. The address's scheme and host are fixed; fill-ins go in its path and query (encoded), headers and body. */
+export type FlowRequest = {
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    url: string;
+    headers: Record<string, string>;
+    body: string | null;
+};
+/** email: who it goes to, the subject and the text — all with fill-ins. */
+export type FlowEmail = {
+    to: string;
+    subject: string;
+    body: string;
+};
+/** tool: which of the project's tools (MCP servers), which of its functions, and the arguments as JSON with fill-ins. */
+export type FlowTool = {
+    server: string;
+    name: string;
+    args: string;
+};
+/** wait (v91): for a reply to the card's email (next: replied, onFail: no reply in time), or for a set time (then next). */
+export type FlowWait = {
+    for: "reply" | "time";
+    minutes: number;
+};
+/** 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 = {
+    minutes: number;
+    to: string | null;
+};
+export type FlowStage = {
+    id: string;
+    title: string;
+    kind: FlowStageKind;
+    zone: FlowZone;
+    /** task/report: what the agent is asked to do. `{{card.title}}`,
+     * `{{card.description}}`, `{{note}}` (the latest send-back note) and
+     * `{{stage.<id>}}` (an earlier zone's report) are filled in. */
+    instructions: string | null;
+    /** task: plan first (required), let Toolroll decide (auto), or build directly (skip). */
+    planning: "auto" | "required" | "skip" | null;
+    /** approval: the one person who decides, or null for any approver on the project. */
+    approver: string | null;
+    /** approval: the flow's owner decides (v86), whoever that is when the card arrives; `approver` is then unused. */
+    toOwner?: boolean;
+    /** notify: the message; update: the comment left on the issue. Same fill-ins. */
+    message: string | null;
+    /** update: also close the issue (Linear: move it to the team's done state). */
+    close: boolean | null;
+    /** check: the project script (by name) run with no AI. */
+    script: string | null;
+    /** check (v90): where it runs — a clean folder, or a copy of the card's work (the default for zones made before v90);
+     * the answers a script's "goto:" line may pick, each with the zone it leads to; and the flow secrets it gets as variables. */
+    runIn?: "folder" | "copy";
+    routes?: {
+        answer: string;
+        to: string;
+    }[];
+    secrets?: string[];
+    /** sort: what Jev is asked and where each answer leads. Its onFail is where a card goes when Jev isn't sure. */
+    sort: FlowSort | null;
+    /** request, email, tool (v87): what the step sends, and to where. */
+    request?: FlowRequest;
+    email?: FlowEmail;
+    tool?: FlowTool;
+    /** wait (v91): what it waits for, and how long. */
+    wait?: FlowWait;
+    /** Any zone but Wait and Done (v91): how long a card may sit here before someone is reminded. */
+    limit?: FlowLimit;
+    /** v92: the AI teammate (by handle) who decides a "Person decides" zone (handing hard ones to its person), or handles a "Teammate handles it" zone. */
+    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;
+    /** Where a card goes when this zone's step succeeds, and when it fails or is sent back (sort: when it isn't sure). */
+    next: string | null;
+    onFail: string | null;
+};
+export type FlowDefinition = {
+    version: 1;
+    start: string;
+    stages: FlowStage[];
+};
+/** What each kind is called and does, in the words the canvas uses. */
+export declare const FLOW_KIND_WORDS: Record<FlowStageKind, {
+    label: string;
+    about: string;
+}>;
+/** A project script's name: short, lowercase, dashes — how zones and chat refer to it. */
+export declare const SCRIPT_NAME: RegExp;
+/** The languages a project script is written in (v90). */
+export declare const SCRIPT_LANGUAGES: readonly ["shell", "python", "node"];
+export type ScriptLanguage = (typeof SCRIPT_LANGUAGES)[number];
+export declare const LANGUAGE_WORDS: Record<ScriptLanguage, string>;
+/** How an answer is named to Jev: its words as a short key. */
+export declare const sortKeyOf: (answer: string) => string;
+/** The default for "sure enough to act alone". */
+export declare const SORT_SURE_AT = 0.8;
+/** The longest a zone waits or a limit runs: 30 days. */
+export declare const LONGEST_WAIT_MINUTES: number;
+/** "3 days", "4 hours", "90 minutes", "1 week" (or a number of minutes) as minutes; null when it isn't one. */
+export declare function durationMinutes(value: unknown): number | null;
+/** Minutes in the words people use: "3 days", "1 day 4 hours", "45 minutes". */
+export declare function durationWords(minutes: number): string;
+/** Who decides at an approval zone: its named person, the flow's owner, or null for anyone who approves on the project. */
+export declare function deciderOf(stage: Pick<FlowStage, "approver" | "toOwner">, flow: {
+    owner: string;
+}): string | null;
+/** A flow as drawn on the canvas, checked whole. Throws in plain words. */
+export declare function validateFlowDefinition(input: unknown): FlowDefinition;
+/** 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;
+/** Fill a zone's text from the card: title, description, the latest note and earlier zones' reports. */
+export declare function fillFlowText(template: string, card: {
+    title: string;
+    description: string | null;
+    note: string | null;
+    outputs: Record<string, string>;
+}, encode?: (value: string) => string): string;
+/** The first email address a card mentions, or "" — what {{card.email}} holds. */
+export declare function cardEmailOf(card: {
+    title: string;
+    description: string | null;
+}): string;
+/** A step as the lead describes it, in list order. A step that keeps an
+ * existing zone (by `id`) carries over whatever it leaves out. */
+export type FlowStepInput = {
+    id?: string;
+    title?: string;
+    kind?: FlowStageKind;
+    instructions?: string;
+    planning?: "auto" | "required" | "skip";
+    decider?: string | null;
+    message?: string;
+    script?: string;
+    close?: boolean;
+    /** check (v90): "folder" (a clean folder) or "copy" (a copy of the card's work); the answers a "goto:" line picks, each with the step it goes to; saved secrets it gets. */
+    runIn?: "folder" | "copy";
+    routes?: {
+        answer?: string;
+        goesTo?: string;
+    }[];
+    secrets?: string[];
+    /** sort: the question, each answer with what it means and the step it goes to, how sure Jev must be (a percentage), and up to 3 other things to note. */
+    question?: string;
+    answers?: {
+        answer?: string;
+        means?: string;
+        goesTo?: string;
+    }[];
+    sureAt?: number;
+    alsoNote?: {
+        question?: string;
+        kind?: "score" | "yes-no";
+        levels?: string[];
+    }[];
+    /** request: method, address, headers and body; email: to, subject, body; tool: the tool (server), its function (tool) and arguments. */
+    method?: FlowRequest["method"];
+    url?: string;
+    headers?: Record<string, string>;
+    body?: string;
+    to?: string;
+    subject?: string;
+    server?: string;
+    tool?: string;
+    args?: Record<string, unknown> | string;
+    /** wait (v91): for a reply (the default) or a set time, and how long ("3 days"); where a card goes when no reply comes. */
+    waitFor?: "reply" | "time";
+    wait?: string | number;
+    ifNoReply?: string;
+    /** Any step but wait and done (v91): remind after this long ("2 days"; "none" removes it), and on holding and approval steps, move the card to this step then. */
+    remindAfter?: string | number;
+    thenMoveTo?: string;
+    /** v92: the AI teammate (by name) who decides an approval step (handing hard ones to its decider) or handles a teammate step. */
+    teammate?: string;
+    /** v96: a teammate step sends what it writes back to whoever asked. */
+    reply?: boolean;
+    next?: string;
+    ifFails?: string;
+    ifNotSure?: string;
+};
+/** What a draft zone asks for when the steps leave it out. */
+export declare const DRAFT_DEFAULT = "Write a short, friendly reply to the person who sent this card, in plain words.";
+/**
+ * A flow from an ordered list of steps: ids from names, each step leading
+ * to the next, a Done zone at the end when none is listed, and a decision
+ * sending work back to the nearest earlier step that does work. New zones
+ * are laid out in rows; zones kept from `previous` keep their place.
+ */
+export declare function flowFromSteps(input: unknown, previous?: FlowDefinition | null): FlowDefinition;
+/** What confirming a new or changed flow means, in the canvas's words: each step's job and path, what changed, and that the usual approvals still apply. */
+export declare function flowTerms(definition: FlowDefinition, previous: FlowDefinition | null): string[];
+/** Ready-made flows: the coding flow is the whole business process around a change. */
+export declare const FLOW_TEMPLATES: readonly {
+    id: string;
+    label: string;
+    about: string;
+    definition: FlowDefinition;
+}[];