@flow-engineer/flow 0.2.3 → 0.3.0

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;
+        },
+    };
+}

package/dist/testing/src/cli.js

@@ -32,7 +32,7 @@ import { request as httpsRequest } from "node:https";
 import { basename, dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
-import { hasModelKey, NO_MODEL_KEY } from "../../src/model.js";
+import { hasModelKey } from "../../src/model.js";
 import { PLUGIN_LINE, pluginCli } from "./plugin.js";
 import { OBSERVE_URL, setting } from "../../src/traces.js";
 import { cloudHeaders, runInCloud, SessionStopped } from "./client.js";
@@ -122,10 +122,11 @@ const USAGE = `Usage:\n${NEW_LINE}\n${CHAT_LINE}\n${TEST_LINE}\n${SHOW_LINE}\n${
 ${PLUGIN_LINE}\n${ACCOUNT_LINES}\n  flow --version         Show the version\n\n${TEST_OPTIONS}`;
 /** What to do after new or init, from step 2; a model key comes first when none is set here. */
 function nextSteps() {
+    // link signs in and writes the keys first, FLOW_KEY (the model, on Flow's free trial credit) among
+    // them, so npm start comes after it and has the model key and the channels from its first start.
     const steps = [
-        ...(hasModelKey(process.env) ? [] : [`Model key: none yet. ${NO_MODEL_KEY.nextLine.replace(/^Next: r/, "R")} (in .env: cp .env.example .env; the file says where to make one)`]),
-        `npm start, and open the link it prints: try it in the playground as its test people, channels side by side`,
-        `npx @flow-engineer/flow link: signs in, writes the other keys, prints the link for your phone;\n     keep npm start running and text it`,
+        `npx @flow-engineer/flow link --channel telegram (or whatsapp, imessage): signs in, writes the keys\n     into .env (FLOW_KEY pays for the model on Flow's free trial credit; ${hasModelKey(process.env) ? "your own model key in .env still wins" : "or put your own model key in .env"}) and prints the link for your phone`,
+        `npm start, and open the link it prints: try it in the playground as its test people, channels side by side;\n     keep it running and text it from your phone`,
         `Tell your coding agent what to build: its skills are in .claude/skills/`,
     ];
     return steps.map((step, i) => `  ${i + 2}. ${step}`).join("\n");
@@ -203,7 +204,7 @@ async function askDisplayName(given, packageName) {
 }
 const namedLine = (dir) => {
     const displayName = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).displayName;
-    return `People call it "${displayName}" (package.json displayName): a phone reaches it with "Hi ${displayName} (ref <code>)".`;
+    return `People call it "${displayName}" (package.json displayName, and its prompt agent/AGENTS.md): a phone reaches it with "Hi ${displayName} (ref <code>)".`;
 };
 const displayNameFlag = values["display-name"];
 if (command === "new") {
@@ -218,7 +219,7 @@ if (command === "new") {
         console.error(error.message);
         process.exit(1);
     }
-    console.log(`Made ./${name}/ from the café example (Pip). ${namedLine(dir)} Next:
+    console.log(`Made ./${name}/ from the café example. ${namedLine(dir)} Next:
   1. cd ${name} && npm install
 ${nextSteps()}`);
     process.exit(0);
@@ -235,7 +236,7 @@ if (command === "init") {
         process.exit(1);
     }
     loadEnv(undefined); // a .env already here may hold a model key
-    console.log(`Made ${name}, started from the café example (Pip), in this folder. ${namedLine(process.cwd())} Next:
+    console.log(`Made ${name}, started from the café example, in this folder. ${namedLine(process.cwd())} Next:
   1. npm install
 ${nextSteps()}`);
     process.exit(0);
@@ -303,7 +304,8 @@ else {
     if (typeof module.buildAgent !== "function" || !Array.isArray(module.tools)) {
         invalid("src/agent.ts must export buildAgent({ model, events, tools }) and tools, or pass --agent-url to test an agent by its HTTP endpoint.");
     }
-    agent = { tools: module.tools, build: ({ tools, events }) => module.buildAgent({ tools, events }) };
+    // A business run's agent also gets its channels and clock (testing/src/business.ts); buildAgent passes them on to createAgent.
+    agent = { tools: module.tools, build: ({ tools, events, channels, testing }) => module.buildAgent({ tools, events, ...(channels ? { channels, testing } : {}) }) };
 }
 /** With --agent-url the agent's own tools run for real: the suite's tool simulators do not apply. */
 function forUrl(files) {

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

@@ -1,6 +1,7 @@
 import { type Agent, type EventSink, type Tool } from "../../src/index.ts";
 import type { Opened, RunSummary, SessionSummary } from "./protocol.ts";
 import { type SuiteFile } from "./suite.ts";
+import { type BusinessBuild } from "./business.ts";
 export interface ConnectOptions {
     /** The cloud's address, such as http://127.0.0.1:8900. */
     cloud: string;
@@ -10,11 +11,12 @@ export interface ConnectOptions {
     title?: string;
     /** The agent's real tools: only their names, descriptions and inputs are used. */
     tools: Tool[];
-    /** Builds the agent with the tools and events it is given: a Flow Framework Agent, or anything that answers like one (http-agent.ts). */
+    /** Builds the agent with the tools and events it is given: a Flow Framework Agent, or anything that answers like one (http-agent.ts).
+     * A business run (protocol.ts) builds one more per run, with its own channels and clock (`BusinessBuild`); that needs a Flow Framework Agent. */
     build: (options: {
         tools: Tool[];
         events: EventSink[];
-    }) => AgentUnderTest;
+    } & Partial<BusinessBuild>) => AgentUnderTest;
     files: SuiteFile[];
     /** The tests folder: files a scenario attaches are read from here, and never leave this machine. */
     testsDir?: string;

package/dist/testing/src/client.js

@@ -10,6 +10,7 @@ import { toSpec } from "../../src/index.js";
 import { PROFILE_TOOL, profileTool } from "../../src/conversation.js";
 import { STAND_IN } from "../../src/tools.js";
 import { mimeOf, parseScenario, parseToolFile, suiteHash } from "./suite.js";
+import { businessRuns } from "./business.js";
 /** The session opened, then the cloud ended it with a `failed` command. `code` is the reason's leading
  * code (`capacity: ...` gives capacity), when it starts with one. */
 export class CloudEnded extends Error {
@@ -351,6 +352,8 @@ async function playSession(options, only) {
     events.context = true;
     try {
         const agent = options.build({ tools, events: [events] });
+        // Business runs need an agent of this framework: its own channels, routes, clock and nudges.
+        const canBusiness = typeof agent.reach === "function" && typeof agent.fetch === "function";
         const open = {
             agent: { name: options.name, title: options.title, tools: [...options.tools, ...(agent.hasProfile?.() ? standIn : [])].map(toSpec), channels: agent.channels() },
             files: options.files.map(({ path, hash }) => ({ path, hash })),
@@ -359,6 +362,7 @@ async function playSession(options, only) {
             retries: true,
             resume: true,
             reopen: true,
+            ...(canBusiness ? { business: true } : {}),
             ...(only ? { only } : {}),
         };
         const opened = await openOnce(`${base}/api/sessions`, open, options.openHeaders, controller.signal, postTimeoutMs, openRetryCapMs, log);
@@ -382,6 +386,20 @@ async function playSession(options, only) {
         options.onDashboard?.(dashboard, opened.sessionId, typeof opened.agent === "string" && opened.agent ? opened.agent : undefined);
         log(`Watch it: ${opened.dashboard}`);
         session = `${tunnel}/api/sessions/${opened.sessionId}`;
+        const business = canBusiness && opened.business === true
+            ? businessRuns({
+                sessionAgent: agent,
+                build: (built) => options.build(built),
+                tunnelTools: tools,
+                realTools: options.tools,
+                events,
+                post: (path, body, key, what) => postRetry(`${session}/${path}`, body, auth, controller.signal, log, postTimeoutMs, {
+                    mode: idempotent ? "idempotent" : path === "outbound" ? "outbound" : "never", key, budgetMs: retryBudgetMs, what,
+                }),
+                watch,
+                log,
+            })
+            : null;
         if (failure)
             throw failure;
         startFlush();
@@ -447,6 +465,8 @@ async function playSession(options, only) {
         const handle = async (command) => {
             if (draining && (command.type === "message" || command.type === "reaction"))
                 throw new Error("the cloud sent a command after drain");
+            if (business && (business.handle(command, (incoming) => withFiles(incoming, options.testsDir, log))))
+                return;
             if (command.type === "message") {
                 const deliveries = [];
                 // Not async: register the promise during receive(), before its fire-and-forget

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

@@ -1,3 +1,3 @@
 export { runInCloud, type CloudSummary, type ConnectOptions } from "./client.ts";
-export { hashOf, loadSuite, parseScenario, parseToolFile, suiteHash, type Scenario, type SuiteFile, type ToolFile } from "./suite.ts";
-export type { Check, Command, OpenSession, Opened, RunKey, RunSummary, SessionSummary, ToolCallRequest, ToolCallResult, UploadFile, Usage, WireIncoming } from "./protocol.ts";
+export { hashOf, isBusiness, loadSuite, parseScenario, parseToolFile, suiteHash, waitMs, type OpeningStep, type Scenario, type SentItem, type SuiteFile, type ToolFile } from "./suite.ts";
+export type { BusinessCommand, BusinessNudge, BusinessOutbound, Check, Command, FlowEventEnvelope, StepAnswer, OpenSession, Opened, RunKey, RunSummary, SessionSummary, ToolCallRequest, ToolCallResult, UploadFile, Usage, WireIncoming } from "./protocol.ts";

package/dist/testing/src/index.js

@@ -1,2 +1,2 @@
 export { runInCloud } from "./client.js";
-export { hashOf, loadSuite, parseScenario, parseToolFile, suiteHash } from "./suite.js";
+export { hashOf, isBusiness, loadSuite, parseScenario, parseToolFile, suiteHash, waitMs } from "./suite.js";

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

@@ -6,6 +6,15 @@ export declare function packageRoot(from?: string): string;
 export declare const MAX_DISPLAY_NAME = 60;
 /** The name people call the agent, from the package name when none was given: "my-shop" is "my shop". */
 export declare function displayNameOf(given: string | undefined, packageName: string): string;
+/**
+ * Renames the agent in `dir`: package.json's displayName, and in its prompt the old display name
+ * (and the café's Pip) become the new one. Returns the name and whether the prompt changed (a prompt
+ * rewritten by hand may name neither).
+ */
+export declare function setDisplayName(dir: string, given: string): {
+    displayName: string;
+    prompt: boolean;
+};
 interface MakeOptions {
     root?: string;
     /** What people call the agent; the package name in words when not given. */