@flow-engineer/flow 0.2.2 → 0.3.0

package/dist/src/http.js

@@ -3,7 +3,7 @@
 // bearer token each.
 //
 // nudgeHandler:
-//   POST {base}        { to: { channel, address }, text | prompt | template, at?, idempotency_key? }
+//   POST {base}        { to: { channel, address }, text (+ link?) | prompt | template, at?, idempotency_key? }
 //                      → 202 { id, status, reason? } as soon as it is recorded, before any send or turn
 //   GET  {base}/:id    → 200 { id, status, reason? }, its state now; 404 for an id the agent never recorded
 //
@@ -68,6 +68,8 @@ const Body = z
     .object({
     to: z.object({ channel: z.string().min(1), address: z.string().min(1) }).strict(),
     text: z.string().min(1).optional(),
+    /** With text: its call to action, as a link button. */
+    link: z.object({ label: z.string().min(1), url: z.url({ protocol: /^https$/ }) }).strict().optional(),
     prompt: z.string().min(1).optional(),
     template: Template.optional(),
     /** Milliseconds since the epoch, as `agent.nudge()` takes it. */
@@ -80,7 +82,8 @@ const Body = z
 })
     .strict()
     .refine((b) => [b.text, b.prompt, b.template].filter((v) => v !== undefined).length === 1, { message: "give exactly one of text, prompt or template" })
-    .refine((b) => !(b.template && b.at !== undefined), { message: "a template nudge cannot be scheduled yet: leave out at" });
+    .refine((b) => !(b.template && b.at !== undefined), { message: "a template nudge cannot be scheduled yet: leave out at" })
+    .refine((b) => !(b.link && (b.text === undefined || b.at !== undefined)), { message: "link goes with text, sent now (no at)" });
 /**
  * Nudges over HTTP, as a request handler for your own server: hand it the requests under `base`.
  * Requests outside `base` get 404 without a token check. A nudge refused or dropped as it is

package/dist/src/index.d.ts

@@ -5,6 +5,7 @@ export { nudgeHandler, peopleHandler, type NudgeHandlerOptions, type PeopleHandl
 export { sqlite, type Database } from "./db.ts";
 export { postgres, type PostgresPool } from "./postgres.ts";
 export { jsonlSink, type EventSink, type FlowEvent, type ChinwagEvent } from "./events.ts";
+export { choosePort, markRunning } from "./local.ts";
 export { flowModel, flowModelURL, openAICompatible, type OpenAICompatibleOptions } from "./model.ts";
 export { Store, type StoreApi } from "./store.ts";
 export type { AgentFiles } from "./skills.ts";

package/dist/src/index.js

@@ -5,6 +5,7 @@ export { nudgeHandler, peopleHandler } from "./http.js";
 export { sqlite } from "./db.js";
 export { postgres } from "./postgres.js";
 export { jsonlSink } from "./events.js";
+export { choosePort, markRunning } from "./local.js";
 export { flowModel, flowModelURL, openAICompatible } from "./model.js";
 export { Store } from "./store.js";
 export { tool, toSpec } from "./tools.js";

package/dist/src/local.d.ts

@@ -0,0 +1,22 @@
+/** True when nothing listens on 127.0.0.1:`port` (the address the playground and the MCP server bind). */
+export declare function portFree(port: number): Promise<boolean>;
+/**
+ * The port to listen on. `env[name]` set: that port, or an error naming a free one when it is taken
+ * (the caller prints its message and exits, so no stack). Not set: `fallback`, else the next free
+ * port above it, with `note` saying so. `command` is how the agent is started, for the error's
+ * "Run: PORT=8798 npm start".
+ */
+export declare function choosePort(name: string, fallback: number, options: {
+    command: string;
+    env?: Record<string, string | undefined>;
+}): Promise<{
+    port: number;
+    note?: string;
+}>;
+/** Writes .flow/running.json in `dir` (this process and its URL) and removes it when the process exits. */
+export declare function markRunning(url: string, dir?: string): void;
+/** The agent running from `dir` (its marker names a live process), or undefined. */
+export declare function runningAgent(dir?: string): {
+    pid: number;
+    url: string;
+} | undefined;

package/dist/src/local.js

@@ -0,0 +1,85 @@
+// An agent run on this machine (`npm start`, `npm run mcp`): the port it listens on, and the marker
+// in .flow/ that says it is running, which `flow link` reads to say whether to start it or restart it.
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createServer } from "node:net";
+import { join } from "node:path";
+import { RESULTS_DIR } from "./names.js";
+/** How many ports above the default are tried before giving up. */
+const SCAN = 50;
+/** True when nothing listens on 127.0.0.1:`port` (the address the playground and the MCP server bind). */
+export function portFree(port) {
+    return new Promise((done) => {
+        const probe = createServer();
+        probe.once("error", () => done(false));
+        probe.listen(port, "127.0.0.1", () => probe.close(() => done(true)));
+    });
+}
+async function firstFree(from, to) {
+    for (let port = from; port <= Math.min(to, 65535); port++)
+        if (await portFree(port))
+            return port;
+    return undefined;
+}
+/**
+ * The port to listen on. `env[name]` set: that port, or an error naming a free one when it is taken
+ * (the caller prints its message and exits, so no stack). Not set: `fallback`, else the next free
+ * port above it, with `note` saying so. `command` is how the agent is started, for the error's
+ * "Run: PORT=8798 npm start".
+ */
+export async function choosePort(name, fallback, options) {
+    const given = (options.env ?? process.env)[name]?.trim();
+    if (given) {
+        const port = Number(given);
+        if (!Number.isInteger(port) || port < 0 || port > 65535)
+            throw new Error(`${name} must be a port number, such as ${name}=${fallback}; it is "${given}".`);
+        if (port === 0 || (await portFree(port)))
+            return { port };
+        const free = await firstFree(port + 1, port + SCAN);
+        throw new Error(`Port ${port} is in use. ${free ? `Run: ${name}=${free} ${options.command}` : `Set ${name} to a free port: ${name}=<port> ${options.command}`}`);
+    }
+    if (await portFree(fallback))
+        return { port: fallback };
+    const free = await firstFree(fallback + 1, fallback + SCAN);
+    if (!free)
+        throw new Error(`Ports ${fallback} to ${fallback + SCAN} are in use. Set ${name} to a free port: ${name}=<port> ${options.command}`);
+    return { port: free, note: `Port ${fallback} is in use, so this runs on ${free} (${name}=<port> picks one).` };
+}
+const RUNNING = "running.json";
+/** Writes .flow/running.json in `dir` (this process and its URL) and removes it when the process exits. */
+export function markRunning(url, dir = process.cwd()) {
+    const file = join(dir, RESULTS_DIR, RUNNING);
+    mkdirSync(join(dir, RESULTS_DIR), { recursive: true });
+    writeFileSync(file, `${JSON.stringify({ pid: process.pid, url })}\n`);
+    process.once("exit", () => {
+        try {
+            if (JSON.parse(readFileSync(file, "utf8")).pid === process.pid)
+                rmSync(file);
+        }
+        catch { }
+    });
+}
+/** The agent running from `dir` (its marker names a live process), or undefined. */
+export function runningAgent(dir = process.cwd()) {
+    const file = join(dir, RESULTS_DIR, RUNNING);
+    if (!existsSync(file))
+        return undefined;
+    let marker;
+    try {
+        marker = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    const { pid, url } = marker;
+    if (typeof pid !== "number" || typeof url !== "string")
+        return undefined;
+    try {
+        process.kill(pid, 0); // signal 0 only asks whether the process is there
+    }
+    catch (error) {
+        // EPERM: it is there, run by another user; ESRCH: it has gone (killed without removing its marker).
+        if (error.code !== "EPERM")
+            return undefined;
+    }
+    return { pid, url };
+}

package/dist/src/types.d.ts

@@ -107,6 +107,14 @@ export type Outbound = {
     };
     /** The channel's own params (see Channel.params), as the agent filled them in. */
     fields?: Record<string, unknown>;
+    /**
+     * false: no link preview. Set on every message the business starts (a nudge, a scheduled
+     * message, a turn the person did not start): on WhatsApp a preview card's title would become
+     * the phone's notification instead of the message's text. Its call to action goes as `link`.
+     */
+    preview?: false;
+    /** The same in every process for one send the business starts (a nudge, a scheduled text), for providers that take one. */
+    idempotencyKey?: string;
 }
 /** The agent has picked these messages up (WhatsApp's blue ticks). */
  | {
@@ -122,6 +130,7 @@ export type Outbound = {
 /** A template the owner set up with the channel (WhatsApp), sent as is, even outside its window. */
  | ({
     type: "template";
+    idempotencyKey?: string;
 } & Template)
 /** A short line of what the agent is doing, shown in the loading indicator; null clears it. */
  | {

package/dist/testing/src/account.d.ts

@@ -1,4 +1,4 @@
 export declare const ACCOUNT_COMMANDS: Set<string>;
-export declare const ACCOUNT_LINES = "  flow login [--wait | --no-wait] [--timeout <s>] [--force] [--no-browser] [--json]\n                            Sign in to flow.engineer: opens the browser, prints the link and code,\n                            and waits up to --timeout (default 120) for approval; --wait goes on\n                            waiting for the same code, --no-wait returns at once\n  flow logout [--json]      End this machine's sign-in and delete its token\n  flow whoami [--json]      Show the account you are signed in as\n  flow setup [--replace] [--rotate <keys> [--now]] [--ci] [--json]\n                            Write this agent's keys (its Flow key FLOW_KEY, which also pays for the\n                            model on the account's trial credit when there is no provider key, test\n                            cloud, traces, Flow Messaging) and each open channel's sender into\n                            ./.env (in an agent's folder: package.json); --rotate key,cloud,traces,\n                            messaging or all makes those keys again (the old FLOW_KEY works 24 h\n                            more; --now ends it at once)\n  flow link [--channel telegram|whatsapp|imessage] [--timeout <s>] [--no-browser] [--json]\n                            Print the link that opens a chat with this agent from a phone; signs in\n                            and runs setup first when this folder is not set up yet\n  flow status [--json]      What this folder has and lacks: FLOW_KEY and the model key (never their\n                            values) with the trial credit left, the\n                            sign-in, each channel's sender in .env, and, signed in, which channels\n                            are open now and their free-trial counts";
+export declare const ACCOUNT_LINES = "  flow login [--wait | --no-wait] [--timeout <s>] [--force] [--no-browser] [--json]\n                            Sign in to flow.engineer: opens the browser, prints the link and code,\n                            and waits up to --timeout (default 120) for approval; --wait goes on\n                            waiting for the same code, --no-wait returns at once\n  flow logout [--json]      End this machine's sign-in and delete its token\n  flow whoami [--json]      Show the account you are signed in as\n  flow setup [--replace] [--rotate <keys> [--now]] [--display-name <name>] [--ci] [--json]\n                            Write this agent's keys (its Flow key FLOW_KEY, which also pays for the\n                            model on the account's trial credit when there is no provider key, test\n                            cloud, traces, Flow Messaging) and each open channel's sender into\n                            ./.env (in an agent's folder: package.json); --rotate key,cloud,traces,\n                            messaging or all makes those keys again (the old FLOW_KEY works 24 h\n                            more; --now ends it at once)\n  flow link [--channel telegram|whatsapp|imessage] [--display-name <name>] [--timeout <s>] [--no-browser] [--json]\n                            Print the link that opens a chat with this agent from a phone; signs in\n                            and runs setup first when this folder is not set up yet. --display-name\n                            (here and on setup) renames the agent: package.json's displayName and\n                            its prompt, agent/AGENTS.md; the phone link then says \"Hi <name>\"\n  flow status [--json]      What this folder has and lacks: FLOW_KEY and the model key (never their\n                            values) with the trial credit left, the\n                            sign-in, each channel's sender in .env, and, signed in, which channels\n                            are open now and their free-trial counts";
 /** Runs one account command; resolves to the exit status. */
 export declare function accountCli(command: string, args: string[]): Promise<number>;

package/dist/testing/src/account.js

@@ -19,9 +19,10 @@ import { basename, join } from "node:path";
 import { parseArgs } from "node:util";
 import { setTimeout as delay } from "node:timers/promises";
 import { currentToken, deleteCredentials, deletePending, LoginRefused, loginUrl, pollToken, readPending, REQUEST_TIMEOUT_MS, revoke, saveCredentials, savePending, modelCredit, SETUP_ENV, setup, startDevice, TimedOut, tryLink, warningsOf, whoami, } from "./flow-login.js";
-import { packageRoot } from "./new.js";
+import { packageRoot, setDisplayName } from "./new.js";
 import { flowModelURL, hasModelKey, MODEL_KEY_NAMES, NO_MODEL_KEY } from "../../src/model.js";
 import { RUN } from "../../src/names.js";
+import { runningAgent } from "../../src/local.js";
 export const ACCOUNT_COMMANDS = new Set(["login", "logout", "whoami", "setup", "link", "status"]);
 export const ACCOUNT_LINES = `  flow login [--wait | --no-wait] [--timeout <s>] [--force] [--no-browser] [--json]
                             Sign in to flow.engineer: opens the browser, prints the link and code,
@@ -29,16 +30,18 @@ export const ACCOUNT_LINES = `  flow login [--wait | --no-wait] [--timeout <s>]
                             waiting for the same code, --no-wait returns at once
   flow logout [--json]      End this machine's sign-in and delete its token
   flow whoami [--json]      Show the account you are signed in as
-  flow setup [--replace] [--rotate <keys> [--now]] [--ci] [--json]
+  flow setup [--replace] [--rotate <keys> [--now]] [--display-name <name>] [--ci] [--json]
                             Write this agent's keys (its Flow key FLOW_KEY, which also pays for the
                             model on the account's trial credit when there is no provider key, test
                             cloud, traces, Flow Messaging) and each open channel's sender into
                             ./.env (in an agent's folder: package.json); --rotate key,cloud,traces,
                             messaging or all makes those keys again (the old FLOW_KEY works 24 h
                             more; --now ends it at once)
-  flow link [--channel telegram|whatsapp|imessage] [--timeout <s>] [--no-browser] [--json]
+  flow link [--channel telegram|whatsapp|imessage] [--display-name <name>] [--timeout <s>] [--no-browser] [--json]
                             Print the link that opens a chat with this agent from a phone; signs in
-                            and runs setup first when this folder is not set up yet
+                            and runs setup first when this folder is not set up yet. --display-name
+                            (here and on setup) renames the agent: package.json's displayName and
+                            its prompt, agent/AGENTS.md; the phone link then says "Hi <name>"
   flow status [--json]      What this folder has and lacks: FLOW_KEY and the model key (never their
                             values) with the trial credit left, the
                             sign-in, each channel's sender in .env, and, signed in, which channels
@@ -97,6 +100,7 @@ export async function accountCli(command, args) {
                     : {}),
                 ...(command === "setup" ? { replace: { type: "boolean", default: false }, rotate: { type: "string" }, now: { type: "boolean", default: false }, ci: { type: "boolean", default: false } } : {}),
                 ...(command === "link" ? { channel: { type: "string", default: "telegram" } } : {}),
+                ...(command === "link" || command === "setup" ? { "display-name": { type: "string" } } : {}),
             },
         }));
     }
@@ -131,7 +135,23 @@ export async function accountCli(command, args) {
     // Straight to the file descriptors, never buffered: a coding agent's cut-off command keeps every line.
     const out = (report) => writeAll(1, `${JSON.stringify(report)}\n`);
     const say = (line) => writeAll(json ? 2 : 1, `${line}\n`);
+    let renamed = false;
     try {
+        if (typeof values["display-name"] === "string" && values.ci !== true) {
+            agentFolder(process.cwd());
+            const before = agentDisplayName();
+            let named;
+            try {
+                named = setDisplayName(process.cwd(), values["display-name"]);
+            }
+            catch (error) {
+                throw new Stop("bad_display_name", error.message, undefined, EXIT.usage);
+            }
+            renamed = named.displayName !== before || named.prompt;
+            if (json)
+                out({ display_name: named.displayName, prompt_renamed: named.prompt });
+            say(`People call it "${named.displayName}" now (package.json displayName${named.prompt ? " and agent/AGENTS.md" : "; agent/AGENTS.md named neither the old name nor Pip, so it is as it was"}).`);
+        }
         if (command === "login") {
             await login({ noBrowser: values["no-browser"] === true, wait: values.wait === true, noWait: values["no-wait"] === true, force: values.force === true, timeoutSeconds }, json, out, say);
         }
@@ -144,7 +164,7 @@ export async function accountCli(command, args) {
         else if (command === "setup")
             await setupEnv({ replace: values.replace === true, rotate, now: values.now === true, ci: values.ci === true }, json, out, say);
         else
-            await link({ channel, noBrowser: values["no-browser"] === true, timeoutSeconds }, json, out, say);
+            await link({ channel, noBrowser: values["no-browser"] === true, timeoutSeconds, renamed }, json, out, say);
         return EXIT.ok;
     }
     catch (error) {
@@ -519,6 +539,16 @@ async function setupEnv(options, json, out, say, forLink) {
     // (and, for FLOW_KEY, ends) the old one rather than adding a second.
     const rotate = all ? true : rotated.size ? [...rotated] : undefined;
     const rotateNow = options.now === true && rotated.has("flow_key");
+    // FLOW_FRAMEWORK_TRY_URL is one channel's page: link's channel when it is open, else the server's (Telegram's).
+    const withTryUrl = (fields) => {
+        const code = fields.join_code;
+        if (!forLink || typeof fields[`${forLink.channel}_sender`] !== "string" || typeof code !== "string" || !code)
+            return fields;
+        const pages = fields.try_urls;
+        const page = typeof pages?.[forLink.channel] === "string" ? pages[forLink.channel] : tryLink(url, code, forLink.channel);
+        return { ...fields, try_url: page };
+    };
+    const chosenPage = (n) => forLink !== undefined && n === SETUP_ENV.try_url;
     let answer;
     try {
         // Every channel: each comes back with its shared sender only while it is open.
@@ -527,7 +557,7 @@ async function setupEnv(options, json, out, say, forLink) {
     catch (error) {
         // The keys minted anyway are not shown again, so whatever the error carries goes into .env first.
         if (error instanceof LoginRefused) {
-            const written = writeEnv(file, lines, before, envEntries(error.fields), (n) => options.replace || rotatedEnv.has(n));
+            const written = writeEnv(file, lines, before, envEntries(withTryUrl(error.fields)), (n) => options.replace || rotatedEnv.has(n) || chosenPage(n));
             if (written.some((w) => w.action === "added" || w.action === "replaced"))
                 say(`Kept in .env before the error: ${written.map((w) => `${w.name} ${w.action}`).join(", ")}.`);
         }
@@ -537,7 +567,7 @@ async function setupEnv(options, json, out, say, forLink) {
     const warnings = warningsOf(fields);
     const had = new Map(before);
     // --replace takes every new value but a model key: only --rotate key replaces FLOW_KEY.
-    const written = writeEnv(file, lines, before, envEntries(fields), (n) => rotatedEnv.has(n) || (options.replace && !MODEL_KEY_NAMES.includes(n)));
+    const written = writeEnv(file, lines, before, envEntries(withTryUrl(fields)), (n) => rotatedEnv.has(n) || (options.replace && !MODEL_KEY_NAMES.includes(n)) || chosenPage(n));
     if (typeof answer.join_code !== "string" || !answer.join_code) {
         const kept = written.filter((w) => w.action === "added" || w.action === "replaced").map((w) => w.name);
         const stop = new Stop("no_join_code", `flow.engineer gave no join code${kept.length ? ` (the keys it made are in .env: ${kept.join(", ")})` : ""}, so there is no phone link yet.`, answer.next?.[0] ?? NEXT.setup, EXIT.refused);
@@ -592,19 +622,25 @@ async function setupEnv(options, json, out, say, forLink) {
     // Said by link instead, once, with its link.
     if (!forLink)
         say(model.line);
-    const people = trial?.imessage?.contacts;
-    if (people && typeof people.used === "number" && typeof people.limit === "number")
-        say(`iMessage: ${people.used} of ${people.limit} people`);
+    // link says its own channel's trial line instead.
     if (!forLink) {
+        const people = peopleLine(trial?.imessage);
+        if (people)
+            say(people);
         for (const c of open)
             say(`On ${CHANNEL_NAME[c]}: ${direct[c] ? `${direct[c].link} (on a computer: ${links[c]})` : links[c]}${trialNote(trial?.[c])}`);
         const added = addedToRunning((n) => had.get(n) || process.env[n]?.trim(), (n) => before.get(n) || process.env[n]?.trim());
         if (added)
-            say(added);
+            say(`If npm start is running, restart it to add ${added}.`);
         say(`Next: ${next.join(", then ")}`);
     }
     return { answer };
 }
+/** iMessage's count of the people it may reach on the trial, as a line; undefined when the answer had none. */
+function peopleLine(t) {
+    const people = t?.contacts;
+    return people && typeof people.used === "number" && typeof people.limit === "number" ? `iMessage: ${people.used} of ${people.limit} people` : undefined;
+}
 const trialNote = (t) => (t && typeof t.limit === "number" ? ` (free trial: ${t.used} of ${t.limit} messages used)` : "");
 /** An answer's field when it is an object (flow_key, model_credit), else undefined (an older server sends none). */
 function objectField(fields, name) {
@@ -658,8 +694,8 @@ function writeEnv(file, lines, before, entries, replace) {
 }
 /**
  * What a running agent (npm start reads .env once, when it starts) lacks after .env changed from
- * `had` to `now`: the channels it is not on yet and a model key, as one sentence; undefined when
- * nothing it uses is new.
+ * `had` to `now`: the channels it is not on yet and a model key, as words ("Telegram and the model
+ * key"); undefined when nothing it uses is new.
  */
 function addedToRunning(had, now) {
     // The starter is on Telegram whenever it has the Flow Messaging key, and on WhatsApp and iMessage
@@ -670,7 +706,7 @@ function addedToRunning(had, now) {
     const what = [...channels, ...model];
     if (!what.length)
         return undefined;
-    return `If npm start is running, restart it to add ${what.length === 1 ? what[0] : `${what.slice(0, -1).join(", ")} and ${what.at(-1)}`}.`;
+    return `${what.length === 1 ? what[0] : `${what.slice(0, -1).join(", ")} and ${what.at(-1)}`}`;
 }
 /**
  * `flow status`: what this folder has and lacks, read from .env and the environment, and, when
@@ -772,6 +808,7 @@ async function link(options, json, out, say) {
     const needsSender = options.channel !== "telegram";
     let value = dotenvValue();
     let credit;
+    let trial;
     let had;
     if (!value(SETUP_ENV.join_code) || !value(SETUP_ENV.messaging_key) || (needsSender && !value(SENDER_ENV[options.channel]))) {
         agentFolder(process.cwd());
@@ -781,7 +818,7 @@ async function link(options, json, out, say) {
         }
         say("Setting up this agent's keys in .env.");
         had = value;
-        ({ answer: { model_credit: credit } } = await setupEnv({ replace: false, rotate: [], ci: false }, json, out, say, { channel: options.channel }));
+        ({ answer: { model_credit: credit, trial } } = await setupEnv({ replace: false, rotate: [], ci: false }, json, out, say, { channel: options.channel }));
         value = dotenvValue();
     }
     const joinCode = value(SETUP_ENV.join_code);
@@ -827,11 +864,22 @@ async function link(options, json, out, say) {
     const replyOnly = REPLY_ONLY[channel];
     const sayToPerson = `${notOpen ? `${what} isn't open yet. ` : ""}Your ${CHANNEL_NAME[channel]} link: ${first.link} ${OPEN_HINT[channel]} `
         + `On a computer without ${CHANNEL_NAME[channel]}, open ${first.page} instead.${replyOnly ? ` ${replyOnly}` : ""}`;
+    const added = had ? addedToRunning(had, value) : undefined;
+    // npm start reads .env and its name once, when it starts. Not running: start it. Running (its
+    // .flow/running.json names a live process): restart it when setup wrote .env, the name changed
+    // just now or a model key is still to come, else it is ready as it is.
+    const running = runningAgent();
+    const runStep = !running
+        ? "npm start, then send the link above"
+        : had || options.renamed || model.next
+            ? `restart npm start (it runs at ${running.url}${added ? ` and lacks ${added}` : " and reads .env and its name only when it starts"}), then send the link above`
+            : `send the link above (npm start is running at ${running.url})`;
+    const next = [...(model.next ? [model.next] : []), runStep];
     if (json) {
         out({
             url: first.link, page: first.page, join_message: first.message, channel, join_code: joinCode, reply_only: Boolean(replyOnly), say_to_person: sayToPerson,
             ...(notOpen ? { not_open: options.channel, message: notOpen, links: Object.fromEntries(links.map(([c, d]) => [c, d.link])) } : {}),
-            model_key: model.report, ...(model.next ? { next: model.next } : {}),
+            model_key: model.report, running: running ? { url: running.url } : false, next: next.join(", then "),
         });
     }
     if (notOpen) {
@@ -843,6 +891,18 @@ async function link(options, json, out, say) {
         say(first.link);
         say(`On a computer without ${CHANNEL_NAME[channel]}: ${first.page}`);
     }
+    // The trial's counts for the channel the link is on, when setup just gave them; no other channel's.
+    const counts = trial?.[channel];
+    if (counts) {
+        const note = trialNote(counts);
+        if (note)
+            say(`${CHANNEL_NAME[channel]} ${note.trim().slice(1, -1)}`); // "WhatsApp free trial: 3 of 300 messages used"
+        if (channel === "imessage") {
+            const people = peopleLine(counts);
+            if (people)
+                say(people);
+        }
+    }
     if (model.report.set)
         say(model.line);
     const one = notOpen && links.length > 1 ? "one" : "it";
@@ -850,13 +910,11 @@ async function link(options, json, out, say) {
     // No model key: the agent cannot answer yet, so the phone does not chat with it until there is one.
     say(model.report.set ? "that phone chats with this agent while it runs (npm start), with no public URL or tunnel." : "that phone reaches this agent while it runs (npm start), but it answers only once .env has a model key:");
     if (model.next)
-        say(`${model.line}\nNext: ${model.next}.`);
+        say(model.line);
     for (const [c] of links)
         if (REPLY_ONLY[c])
             say(REPLY_ONLY[c]);
-    const added = had ? addedToRunning(had, value) : undefined;
-    if (added)
-        say(added);
+    say(`Next: ${next.join(", then ")}.`);
 }
 /**
  * Asks flow.engineer's /try page for its direct link as JSON ({"channel", "message", "link", "page"}):

package/dist/testing/src/business.d.ts

@@ -0,0 +1,42 @@
+import type { Agent, Channel, EventSink, Incoming, Tool } from "../../src/index.ts";
+import type { Command } from "./protocol.ts";
+/** What a business run's agent must do: a Flow Framework Agent. */
+export type BusinessAgent = Pick<Agent, "channels" | "channel" | "message" | "reacted" | "nudge" | "reach" | "runDue" | "conversation" | "fetch">;
+/** What buildAgent is given for a business run, beside its tools and events. */
+export interface BusinessBuild {
+    channels: Channel[];
+    testing: {
+        /** The run's clock. */
+        now: () => number;
+        /** No schedule timer: the clock moves only when the cloud says, and what came due runs then. */
+        scheduleCheckMs: 0;
+        /** The secret the run's events are signed with (Flow-Signature): made for the run, never a real one. */
+        eventsSecret: string;
+    };
+}
+/** One minute: the clock moves this far at a time, and what came due runs at each step. */
+export declare const STEP_MS = 60000;
+export interface BusinessContext {
+    /** The agent the session was opened with: its channels are copied for each run. */
+    sessionAgent: BusinessAgent;
+    build: (options: {
+        tools: Tool[];
+        events: EventSink[];
+    } & BusinessBuild) => BusinessAgent;
+    /** The tunnel's tools (each call asks the cloud), and the agent's own, for tools.real. */
+    tunnelTools: Tool[];
+    realTools: Tool[];
+    /** The session's event uploader. */
+    events: EventSink;
+    /** A POST to the session, sent again under `key` while it may be. */
+    post: (path: string, body: unknown, key: string, what: string) => Promise<unknown>;
+    /** Keeps a failure of fire-and-forget work as the session's (refusals allowed). */
+    watch: (work: Promise<unknown>, context: string, allowRefusal?: boolean) => void;
+    log: (line: string) => void;
+}
+export declare function businessRuns(ctx: BusinessContext): {
+    /** A business run's command, or a message or reaction for one: true when it was one. */
+    handle(command: Command, withFiles: (incoming: Extract<Command, {
+        type: "message";
+    }>["incoming"]) => Incoming): boolean;
+};

package/dist/testing/src/business.js

@@ -0,0 +1,145 @@
+// Business runs on the developer's side of the tunnel: scenarios the business starts (an event its
+// backend sends, a nudge, time passing). Each run gets an agent of its own, built with a clock the
+// cloud's commands move and with copies of the agent's own channels, so its sends go through what
+// the agent wraps around them and come to the cloud with the run's time. The person writes through
+// agent.message(), as a provider's webhook would, so they are a person the agent can nudge.
+import { createHmac, randomBytes } from "node:crypto";
+/** One minute: the clock moves this far at a time, and what came due runs at each step. */
+export const STEP_MS = 60_000;
+export function businessRuns(ctx) {
+    const runs = new Map();
+    const open = async (command) => {
+        const cloudId = command.conversationId;
+        const real = new Set(command.realTools ?? []);
+        const unknown = [...real].filter((name) => !ctx.realTools.some((t) => t.name === name));
+        if (unknown.length)
+            return { conversationId: cloudId, step: 0, at: command.now, error: `the agent has no tool ${unknown.join(", ")} to run for real` };
+        const run = { clock: command.now, secret: `whsec_test_${randomBytes(18).toString("hex")}`, address: command.address, channelName: command.channelName, conversationId: "", deliveries: new Set(), sent: 0 };
+        // The run's events and tool calls are the cloud's conversation, whatever the agent calls it.
+        const events = Object.assign((event) => ctx.events({ ...event, conversationId: cloudId }), { context: true });
+        const tools = ctx.tunnelTools.map((t) => {
+            if (real.has(t.name))
+                return ctx.realTools.find((r) => r.name === t.name);
+            return { ...t, run: (input, context) => t.run(input, { ...context, conversationId: cloudId }) };
+        });
+        const channels = ctx.sessionAgent.channels().map(({ name }) => {
+            const own = ctx.sessionAgent.channel(name);
+            return { ...own, send: (address, outbound) => deliver(run, cloudId, address, outbound) };
+        });
+        run.agent = ctx.build({ tools, events: [events], channels, testing: { now: () => run.clock, scheduleCheckMs: 0, eventsSecret: run.secret } });
+        run.conversationId = (await run.agent.reach({ channel: command.channelName, address: command.address })).conversationId;
+        runs.set(cloudId, run);
+        return { conversationId: cloudId, step: 0, at: run.clock };
+    };
+    const deliver = (run, cloudId, address, outbound) => {
+        if (address !== run.address) {
+            ctx.log(`${cloudId}: the agent sent to ${address}, not the run's person; the cloud does not see it`);
+            return Promise.resolve();
+        }
+        const body = { conversationId: cloudId, outbound, at: run.clock };
+        const delivery = ctx.post("outbound", body, `outbound:${cloudId}:b${++run.sent}`, "outbound delivery").then(() => { });
+        run.deliveries.add(delivery);
+        const done = () => void run.deliveries.delete(delivery);
+        delivery.then(done, done);
+        ctx.watch(delivery, "outbound delivery", true);
+        return delivery;
+    };
+    /** Until nothing more comes due now and everything set off has been sent. */
+    const settle = async (run) => {
+        for (let i = 0; i < 10; i++) {
+            const due = await run.agent.runDue();
+            await run.agent.conversation(run.conversationId)?.whenIdle();
+            await Promise.allSettled([...run.deliveries]);
+            if (!due && !run.agent.conversation(run.conversationId)?.busy)
+                return;
+        }
+    };
+    const event = async (run, command) => {
+        const body = JSON.stringify(command.envelope);
+        const t = Math.floor(run.clock / 1000);
+        const secret = command.signature === "bad" ? `whsec_test_${randomBytes(18).toString("hex")}` : run.secret;
+        const headers = { "content-type": "application/json", "idempotency-key": command.envelope.id };
+        if (command.signature !== "missing")
+            headers["flow-signature"] = `t=${t},v1=${createHmac("sha256", secret).update(`t.${t}.${body}`).digest("hex")}`;
+        const response = await run.agent.fetch(new Request(`http://agent.test${command.path ?? "/v1/events"}`, { method: "POST", headers, body }));
+        const text = await response.text();
+        let parsed = text;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch { /* not JSON: kept as text */ }
+        return { answer: { status: response.status, body: parsed } };
+    };
+    const step = async (run, command) => {
+        const base = { conversationId: command.conversationId, step: command.step };
+        let result = {};
+        try {
+            if (command.type === "event")
+                result = await event(run, command);
+            else if (command.type === "nudge") {
+                const { expiresAt, ...rest } = command.nudge;
+                const nudged = await run.agent.nudge({ to: { channel: run.channelName, address: run.address }, ...rest, ...(expiresAt !== undefined ? { expiresAt } : {}) });
+                result = { nudge: { status: nudged.status, ...(nudged.reason ? { reason: nudged.reason } : {}) } };
+            }
+            else {
+                if (command.to < run.clock)
+                    throw new Error("the clock never moves back");
+                while (run.clock < command.to) {
+                    run.clock = Math.min(command.to, run.clock + STEP_MS);
+                    await settle(run);
+                }
+            }
+            await settle(run);
+        }
+        catch (error) {
+            result = { error: error instanceof Error ? error.message : String(error) };
+        }
+        return { ...base, ...result, at: run.clock };
+    };
+    return {
+        /** A business run's command, or a message or reaction for one: true when it was one. */
+        handle(command, withFiles) {
+            // Steps run beside the stream, so one run's long wait never holds up another's commands; the cloud
+            // sends a run's next command only after this one's answer.
+            if (command.type === "open") {
+                ctx.watch((async () => {
+                    const answer = await open(command).catch((error) => ({ conversationId: command.conversationId, step: 0, at: command.now, error: error instanceof Error ? error.message : String(error) }));
+                    await ctx.post("steps", answer, `step:${command.conversationId}:0`, "step answer");
+                })(), "business step");
+                return true;
+            }
+            if (command.type === "close") {
+                runs.delete(command.conversationId);
+                return true;
+            }
+            if (command.type === "event" || command.type === "nudge" || command.type === "advance") {
+                ctx.watch((async () => {
+                    const run = runs.get(command.conversationId);
+                    const answer = run ? await step(run, command) : { conversationId: command.conversationId, step: command.step, at: 0, error: "no such run open" };
+                    await ctx.post("steps", answer, `step:${command.conversationId}:${command.step}`, "step answer");
+                })(), "business step");
+                return true;
+            }
+            if (command.type !== "message" && command.type !== "reaction")
+                return false;
+            const run = runs.get(command.conversationId);
+            if (!run)
+                return false;
+            if (command.type === "reaction") {
+                run.agent.reacted(run.conversationId, command.emoji, command.toText);
+                return true;
+            }
+            // As a provider's webhook would: the person by their address on the run's channel.
+            const work = (async () => {
+                const taken = await run.agent.message({ channel: run.channelName, from: run.address, message: withFiles(command.incoming), messageId: command.messageId });
+                // An intercepted message's reply is out before its receipt, as on the other runs.
+                if (!taken)
+                    await Promise.allSettled([...run.deliveries]);
+                const receipt = { conversationId: command.conversationId, messageId: command.messageId, status: taken ? "taken" : "intercepted" };
+                await ctx.post("receipts", receipt, `receipt:${receipt.conversationId}:${receipt.messageId}`, "delivery receipt");
+            })();
+            ctx.watch(work, "delivery receipt");
+            return true;
+        },
+    };
+}