@flow-engineer/flow 0.2.3 → 0.3.0

package/dist/testing/src/new.js

@@ -1,10 +1,13 @@
-// `flow new <name>`: makes ./<name>/, an agent of its own started from the café example (Pip),
+// `flow new <name>`: makes ./<name>/, an agent of its own started from the café example,
 // that depends on the @flow-engineer/flow package. Its imports become "@flow-engineer/flow",
 // "@flow-engineer/flow/simulators" and "@flow-engineer/flow/flow-messaging", and the coding-agent
 // skills go in .claude/skills/, with an AGENTS.md (and a CLAUDE.md importing it) pointing at them.
 // `flow init` makes the same agent in the current folder. Inside a clone, `npm run new -- <name>`
 // makes agents/<name>/ instead. `--display-name` is what people call the agent ("FlatX agent"), kept
 // as package.json's displayName: the message a phone sends to reach it is "Hi <it> (ref <code>)".
+// The café's agent is Pip; the display name takes Pip's place in its prompt (agent/AGENTS.md), and
+// its playground and MCP server read the name from package.json. `flow link --display-name` (and
+// `setup`) renames an agent made already, the same way (setDisplayName).
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -66,13 +69,15 @@ FLOW_FRAMEWORK_TRACES_KEY=
 `;
 const agentsMd = (name) => `# ${name}
 
-A chat agent on Flow Framework (https://github.com/flow-engineer/flow), started from its café example (Pip).
+A chat agent on Flow Framework (https://github.com/flow-engineer/flow), started from its café example.
 
 - Load the skills in \`.claude/skills/\` before changing it: \`flow-framework\` to build the agent (and its MCP
   server and CLI), \`flow-framework-tools\` for its tools and their test files, \`flow-framework-tests\` for its test
   scenarios, \`flow-framework-context\` to gather what the tools are written from out of an existing
   codebase, and \`flow-framework-auth\` for sign-in.
-- \`agent/AGENTS.md\` is the agent's own prompt, not instructions for coding agents.
+- \`agent/AGENTS.md\` is the agent's own prompt, not instructions for coding agents. What people call
+  the agent is package.json's \`displayName\`; \`npx @flow-engineer/flow link --display-name <name>\`
+  changes it there and in that prompt.
 - The model key goes in \`.env\` (never read or print it): \`npx @flow-engineer/flow link\` (or \`setup\`)
   writes \`FLOW_KEY\`, the agent's one Flow key, which calls models on Flow's free trial credit, so no provider key is needed; a key the owner types
   (\`OPENROUTER_API_KEY\`, \`OPENAI_API_KEY\`, \`ANTHROPIC_API_KEY\` or \`GEMINI_API_KEY\`) wins over it. \`npm start\` runs it in the playground,
@@ -97,6 +102,39 @@ export function displayNameOf(given, packageName) {
         throw new Error(`--display-name is at most ${MAX_DISPLAY_NAME} characters, such as "FlatX agent".`);
     return name || packageName.replace(/-/g, " ");
 }
+/** The café's name for its agent, in its prompt; a new agent's display name takes its place. */
+const TEMPLATE_NAME = "Pip";
+/** Puts `to` in place of each of `from` (whole words, the longest first, in one pass) in the agent's prompt; true when it changed. */
+function renameInPrompt(dir, from, to) {
+    const file = join(dir, "agent", "AGENTS.md");
+    const names = [...new Set(from.filter((n) => n && n !== to))].sort((a, b) => b.length - a.length);
+    if (!names.length || !existsSync(file))
+        return false;
+    const text = readFileSync(file, "utf8");
+    const word = new RegExp(`(?<![\\p{L}\\p{N}_])(?:${names.map((n) => n.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("|")})(?![\\p{L}\\p{N}_])`, "gu");
+    const renamed = text.replace(word, () => to);
+    if (renamed === text)
+        return false;
+    writeFileSync(file, renamed);
+    return true;
+}
+/**
+ * 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 function setDisplayName(dir, given) {
+    const file = join(dir, "package.json");
+    const pkg = JSON.parse(readFileSync(file, "utf8"));
+    const displayName = displayNameOf(given, pkg.name ?? folderName(dir));
+    const before = typeof pkg.displayName === "string" ? pkg.displayName : "";
+    if (before !== displayName) {
+        // displayName stays right after name, where flow init puts it.
+        const { name, displayName: _, ...rest } = pkg;
+        writeFileSync(file, `${JSON.stringify({ ...(name !== undefined ? { name } : {}), displayName, ...rest }, null, 2)}\n`);
+    }
+    return { displayName, prompt: renameInPrompt(dir, [before, TEMPLATE_NAME], displayName) };
+}
 /** Makes `<into>/<name>` (the current folder by default) and returns it. */
 export function newStandalone(name, options = {}) {
     checkName(name);
@@ -126,6 +164,7 @@ function makeAgent(dir, name, displayName, root) {
     const cafe = join(root, "examples", "cafe");
     for (const part of ["agent", "src", "tests"])
         cpSync(join(cafe, part), join(dir, part), { recursive: true });
+    renameInPrompt(dir, [TEMPLATE_NAME], displayName);
     for (const file of readdirSync(join(dir, "src"), { recursive: true, encoding: "utf8" }).filter((f) => f.endsWith(".ts"))) {
         const path = join(dir, "src", file);
         const source = readFileSync(path, "utf8")
@@ -134,8 +173,8 @@ function makeAgent(dir, name, displayName, root) {
             .replace(/(["'])(\.\.\/)+flow-messaging\/src\/index\.ts\1/g, '"@flow-engineer/flow/flow-messaging"')
             .replace(/(["'])(\.\.\/)+mcp\/src\/index\.ts\1/g, '"@flow-engineer/flow/mcp"')
             .replace(/(["'])(\.\.\/)+cli\/src\/index\.ts\1/g, '"@flow-engineer/flow/cli"');
-        // The CLI is the agent's own command, named after it.
-        const text = file === "cli.ts" ? source.replace(/name: "cafe"/, `name: "${name}"`).replace(/CAFE_SERVER/g, `${name.toUpperCase().replace(/-/g, "_")}_SERVER`) : source;
+        // The CLI is the agent's own command, named after it (and so is its server's setting, which mcp.ts names too).
+        const text = (file === "cli.ts" ? source.replace(/name: "cafe"/, `name: "${name}"`) : source).replace(/CAFE_SERVER/g, `${name.toUpperCase().replace(/-/g, "_")}_SERVER`);
         if (/["']\.\.\/\.\.\//.test(text))
             throw new Error(`flow: ${file} imports a file outside the agent; only Flow Framework's public entries can be rewritten.`);
         writeFileSync(path, text);

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

@@ -1,4 +1,4 @@
-import type { Attachment, ChannelInfo, ChannelSummary, Incoming, ToolSpec } from "../../src/index.ts";
+import type { Attachment, ChannelInfo, ChannelSummary, Incoming, Outbound, Template, ToolSpec } from "../../src/index.ts";
 /** One graded expect item of a run. */
 export interface Check {
     kind: "outcome" | "judge";
@@ -35,6 +35,8 @@ export interface OpenSession {
     resume?: boolean;
     /** The client opens one new session for the unfinished runs when this cloud says session_gone. */
     reopen?: boolean;
+    /** The client plays business runs (open, event, nudge, advance, close). */
+    business?: boolean;
     /** Play only these runs, numbered as given: a re-open after session_gone. Sent only to a cloud whose Opened said reopen,
      * and only when some run finished: the cloud checks it against the suite's files it already stores. */
     only?: RunKey[];
@@ -67,6 +69,8 @@ export interface Opened {
     resume?: boolean;
     /** This cloud answers session_gone for a session it lost, and plays `only` on an open. Absent on an older cloud. */
     reopen?: boolean;
+    /** This cloud plays business runs; the client sent `business`. Absent on an older cloud. */
+    business?: boolean;
 }
 export interface UploadFile {
     hash: string;
@@ -98,7 +102,101 @@ export type Command = {
  | {
     type: "failed";
     error: string;
+} | BusinessCommand;
+/**
+ * A business run's commands. `step` numbers the run's business commands from 1 in the order the
+ * cloud sends them (`open` is 0; a step with `at:` is an `advance` and then its own command); its
+ * StepAnswer carries the same number. The client treats it as opaque.
+ */
+export type BusinessCommand = 
+/** A run starts: build its agent with its clock at `now` (epoch ms). The person is `address` on `channelName`;
+ * `realTools` run the agent's own code in place of the cloud's simulation. */
+{
+    type: "open";
+    conversationId: string;
+    channelName: string;
+    channel: ChannelInfo;
+    address: string;
+    now: number;
+    realTools?: string[];
+}
+/** The business's backend sends an event: POST `path` (default /v1/events) to the agent's own routes with this
+ * envelope as the body, signed with the run's test secret (`signature` bad: with another secret; missing: no header). */
+ | {
+    type: "event";
+    conversationId: string;
+    step: number;
+    envelope: FlowEventEnvelope;
+    path?: string;
+    signature?: "bad" | "missing";
+}
+/** The business nudges the run's person. */
+ | {
+    type: "nudge";
+    conversationId: string;
+    step: number;
+    nudge: BusinessNudge;
+}
+/** Time passes: the clock moves to `to` (epoch ms), a minute at a time, and what came due runs at each step. */
+ | {
+    type: "advance";
+    conversationId: string;
+    step: number;
+    to: number;
+}
+/** The run is over: its agent is dropped. */
+ | {
+    type: "close";
+    conversationId: string;
 };
+/** A Flow event as a business's backend sends it: one envelope for every type. */
+export interface FlowEventEnvelope {
+    /** Unique per event; the agent processes one id once. */
+    id: string;
+    type: string;
+    /** ISO 8601. */
+    occurredAt: string;
+    /** What it is about: "user:<id>", "listing:<slug>". */
+    subject: string;
+    /** How binding a send it asks for, e.g. critical, standard or optional; the agent decides what each means. */
+    delivery?: string;
+    data: Record<string, unknown>;
+}
+/** A nudge as a scenario writes it; `to` is the run's person. */
+export interface BusinessNudge {
+    text?: string;
+    prompt?: string;
+    template?: Template;
+    respectQuietHours?: boolean;
+    /** Epoch ms. */
+    expiresAt?: number;
+    idempotencyKey?: string;
+}
+/** What one business step came to. */
+export interface StepAnswer {
+    conversationId: string;
+    step: number;
+    /** The agent's HTTP answer to an event. */
+    answer?: {
+        status: number;
+        body: unknown;
+    };
+    /** A nudge's result. */
+    nudge?: {
+        status: string;
+        reason?: string;
+    };
+    /** The run's clock when the step settled, epoch ms. */
+    at: number;
+    /** The step could not be played on the agent's side (the agent threw, no such route ...). */
+    error?: string;
+}
+/** A business run's outbound: what the agent sent, and when on the run's clock. */
+export interface BusinessOutbound {
+    conversationId: string;
+    outbound: Outbound;
+    at: number;
+}
 /**
  * A person's message as it travels: a scenario's file goes by its path in the tests folder, and the
  * agent's side reads it there, so the file never leaves the developer's machine.

package/dist/testing/src/protocol.js

@@ -13,6 +13,15 @@
 // says idempotency, a repeat of a key is the stored answer and the client may send it again.
 //   POST /api/sessions/:id/receipts    Receipt → { ok }
 //   POST /api/sessions/:id/drained     {} → { ok }   flush before the terminal command
+//   POST /api/sessions/:id/steps       StepAnswer → { ok }   a business run's step done (below)
+//
+// Business runs (both sides said `business`): a scenario the business starts, with an event its
+// backend sends, a nudge, or time passing on the test's clock. Each such run gets an agent of its
+// own on the agent's side, built with a clock the commands move (its own `now`, no schedule timer),
+// and the agent's own channels, whose sends come to the cloud as an outbound with `at`, the run's
+// clock. The cloud sends `open` first, then any of `message`, `reaction`, `event`, `nudge`,
+// `advance`, and `close` when the run is over. `open`, `event`, `nudge` and `advance` are each
+// answered by one StepAnswer once the agent has settled: everything they set off has been sent.
 //
 // When Opened says resume, every command on the stream carries `id: N` (1, 2, 3, ... per session).
 // A stream that drops, or sits silent past the idle watch, is opened again with Last-Event-ID set

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

@@ -21,6 +21,15 @@ declare const expectedCall: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
     tool: z.ZodString;
     args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, z.core.$strict>]>;
+/** A wait's length in ms, or null when it is not one. */
+export declare function waitMs(text: string): number | null;
+/** One thing the agent sent (`expect.sent`), or must not have (`expect.not_sent`; `{}` is anything at all). */
+declare const sentItem: z.ZodObject<{
+    at: z.ZodOptional<z.ZodString>;
+    template: z.ZodOptional<z.ZodString>;
+    phrased: z.ZodOptional<z.ZodLiteral<true>>;
+    text: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
 declare const scenarioSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
@@ -34,12 +43,13 @@ declare const scenarioSchema: z.ZodObject<{
     timezone: z.ZodOptional<z.ZodString>;
     now: z.ZodOptional<z.ZodPreprocess<z.ZodString, unknown>>;
     person: z.ZodObject<{
+        address: z.ZodOptional<z.ZodString>;
         persona: z.ZodString;
         goal: z.ZodString;
         knows: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>;
-    opening: z.ZodArray<z.ZodObject<{
-        say: z.ZodDefault<z.ZodString>;
+    opening: z.ZodArray<z.ZodPipe<z.ZodObject<{
+        say: z.ZodOptional<z.ZodString>;
         attach: z.ZodOptional<z.ZodObject<{
             kind: z.ZodEnum<{
                 audio: "audio";
@@ -49,7 +59,120 @@ declare const scenarioSchema: z.ZodObject<{
             file: z.ZodString;
         }, z.core.$strip>>;
         after_ms: z.ZodOptional<z.ZodNumber>;
-    }, z.core.$strip>>;
+        event: z.ZodOptional<z.ZodObject<{
+            id: z.ZodOptional<z.ZodString>;
+            type: z.ZodString;
+            occurredAt: z.ZodOptional<z.ZodString>;
+            subject: z.ZodString;
+            delivery: z.ZodOptional<z.ZodString>;
+            data: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strict>>;
+        path: z.ZodOptional<z.ZodString>;
+        signature: z.ZodOptional<z.ZodEnum<{
+            bad: "bad";
+            missing: "missing";
+        }>>;
+        answer: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodObject<{
+            status: z.ZodNumber;
+            field: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>]>>;
+        nudge: z.ZodOptional<z.ZodObject<{
+            text: z.ZodOptional<z.ZodString>;
+            prompt: z.ZodOptional<z.ZodString>;
+            template: z.ZodOptional<z.ZodObject<{
+                name: z.ZodString;
+                language: z.ZodOptional<z.ZodString>;
+                body: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                buttons: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    index: z.ZodNumber;
+                    value: z.ZodString;
+                }, z.core.$strict>>>;
+            }, z.core.$strict>>;
+            respectQuietHours: z.ZodOptional<z.ZodBoolean>;
+            expiresAt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        wait: z.ZodOptional<z.ZodString>;
+        at: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, z.ZodTransform<{
+        say?: string | undefined;
+        attach?: {
+            kind: "audio" | "document" | "image";
+            file: string;
+        } | undefined;
+        after_ms?: number | undefined;
+        event?: {
+            id?: string | undefined;
+            type: string;
+            occurredAt?: string | undefined;
+            subject: string;
+            delivery?: string | undefined;
+            data: Record<string, unknown>;
+        } | undefined;
+        path?: string | undefined;
+        signature?: "bad" | "missing" | undefined;
+        answer?: number | {
+            status: number;
+            field?: string | undefined;
+        } | undefined;
+        nudge?: {
+            text?: string | undefined;
+            prompt?: string | undefined;
+            template?: {
+                name: string;
+                language?: string | undefined;
+                body?: string[] | undefined;
+                buttons?: {
+                    index: number;
+                    value: string;
+                }[] | undefined;
+            } | undefined;
+            respectQuietHours?: boolean | undefined;
+            expiresAt?: string | undefined;
+        } | undefined;
+        wait?: string | undefined;
+        at?: string | undefined;
+    }, {
+        say?: string | undefined;
+        attach?: {
+            kind: "audio" | "document" | "image";
+            file: string;
+        } | undefined;
+        after_ms?: number | undefined;
+        event?: {
+            id?: string | undefined;
+            type: string;
+            occurredAt?: string | undefined;
+            subject: string;
+            delivery?: string | undefined;
+            data: Record<string, unknown>;
+        } | undefined;
+        path?: string | undefined;
+        signature?: "bad" | "missing" | undefined;
+        answer?: number | {
+            status: number;
+            field?: string | undefined;
+        } | undefined;
+        nudge?: {
+            text?: string | undefined;
+            prompt?: string | undefined;
+            template?: {
+                name: string;
+                language?: string | undefined;
+                body?: string[] | undefined;
+                buttons?: {
+                    index: number;
+                    value: string;
+                }[] | undefined;
+            } | undefined;
+            respectQuietHours?: boolean | undefined;
+            expiresAt?: string | undefined;
+        } | undefined;
+        wait?: string | undefined;
+        at?: string | undefined;
+    }>>>;
+    tools: z.ZodOptional<z.ZodObject<{
+        real: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
     world: z.ZodOptional<z.ZodString>;
     max_turns: z.ZodDefault<z.ZodNumber>;
     expect: z.ZodDefault<z.ZodObject<{
@@ -63,6 +186,18 @@ declare const scenarioSchema: z.ZodObject<{
             tool: z.ZodString;
             args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
         }, z.core.$strict>]>>>;
+        sent: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            at: z.ZodOptional<z.ZodString>;
+            template: z.ZodOptional<z.ZodString>;
+            phrased: z.ZodOptional<z.ZodLiteral<true>>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+        not_sent: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            at: z.ZodOptional<z.ZodString>;
+            template: z.ZodOptional<z.ZodString>;
+            phrased: z.ZodOptional<z.ZodLiteral<true>>;
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 declare const toolFileSchema: z.ZodObject<{
@@ -79,6 +214,10 @@ declare const toolFileSchema: z.ZodObject<{
 /** The type of a file a scenario attaches, from its extension. */
 export declare function mimeOf(path: string): string;
 export type Scenario = z.infer<typeof scenarioSchema>;
+export type OpeningStep = Scenario["opening"][number];
+export type SentItem = z.infer<typeof sentItem>;
+/** The business starts something in it (an event, a nudge, time passing), or it checks what was sent: a business run. */
+export declare function isBusiness(scenario: Scenario): boolean;
 export type ToolFile = z.infer<typeof toolFileSchema>;
 export type ExpectedCall = z.infer<typeof expectedCall>;
 /** Parse and check a scenario. The error has one line per problem: `file:line: field: what is wrong`. */

package/dist/testing/src/suite.js

@@ -87,6 +87,87 @@ const expectedCall = z.union([
         args: withClock(z.record(z.string(), z.unknown())).optional(),
     }),
 ], { error: "a tool name, or { tool: <name>, args: { <field>: <value> } }" });
+/** "8h30m", "2d", "45m": how long a `wait` step lets pass. */
+const WAIT = /^(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?$/;
+/** A wait's length in ms, or null when it is not one. */
+export function waitMs(text) {
+    const m = WAIT.exec(text.trim());
+    if (!m || !(m[1] || m[2] || m[3]))
+        return null;
+    const ms = (Number(m[1] ?? 0) * 24 * 60 + Number(m[2] ?? 0) * 60 + Number(m[3] ?? 0)) * 60_000;
+    return ms > 0 ? ms : null;
+}
+/** A moment on the test's clock: a date and time (local to the scenario's timezone unless it has an offset),
+ * HH:MM (the next time the clock shows it), or a `{{now ...}}` placeholder. */
+const moment = z.string().refine((t) => isDateTime(t) || /^([01]\d|2[0-3]):[0-5]\d$/.test(t) || (/^\s*\{\{[\s\S]*\}\}\s*$/.test(t) && placeholderProblem(t) === null), "a time on the test's clock: 2026-10-20T23:30, 2026-10-20T23:30+05:30, 23:30, or {{now + 1d @ 08:00}}");
+const template = z.strictObject({
+    name: z.string().min(1),
+    language: z.string().optional(),
+    body: z.array(z.string()).optional(),
+    buttons: z.array(z.strictObject({ index: z.number().int().min(0), value: z.string() })).optional(),
+});
+/** A Flow event as the business's backend sends it; `id` and `occurredAt` default to one per step and the clock. */
+const flowEvent = withClock(z.strictObject({
+    id: z.string().min(1).optional(),
+    type: z.string().min(1),
+    occurredAt: z.string().optional(),
+    subject: z.string().min(1),
+    delivery: z.string().optional(),
+    data: z.record(z.string(), z.unknown()),
+}));
+const businessNudge = withClock(z
+    .strictObject({
+    text: z.string().min(1).optional(),
+    prompt: z.string().min(1).optional(),
+    template: template.optional(),
+    respectQuietHours: z.boolean().optional(),
+    expiresAt: moment.optional(),
+})
+    .refine((n) => [n.text, n.prompt, n.template].filter((v) => v !== undefined).length === 1, "exactly one of text, prompt or template"));
+/** What the agent's route must answer an event: a status, or a status and the field a 400 names. */
+const answer = z.union([z.number().int().min(100).max(599), z.strictObject({ status: z.number().int().min(100).max(599), field: z.string().min(1).optional() })]);
+/** One thing the agent sent (`expect.sent`), or must not have (`expect.not_sent`; `{}` is anything at all). */
+const sentItem = z.strictObject({
+    /** When, on the test's clock: HH:MM (any day), or a date and time; to the minute. */
+    at: moment.optional(),
+    /** A template by name. */
+    template: z.string().min(1).optional(),
+    /** The agent's own words rather than a template. */
+    phrased: z.literal(true).optional(),
+    /** Text the message (or the template's values) holds. */
+    text: withClock(z.string().min(1)).optional(),
+});
+const openingStep = z
+    .object({
+    say: withClock(z.string()).optional(),
+    /** A file the person sends with it (say is its caption): a path in the tests folder. */
+    attach: z.object({ kind: z.enum(["image", "audio", "document"]), file: z.string().refine(inTests, "a path inside the tests folder, such as fixtures/receipt.jpg") }).optional(),
+    after_ms: z.number().int().min(0).optional(),
+    /** The business's backend sends this event, to the agent's own route. */
+    event: flowEvent.optional(),
+    /** The route the event goes to; /v1/events when left out. */
+    path: z.string().regex(/^\/[^\s?#]*$/, "a path such as /v1/events").optional(),
+    /** bad: signed with another secret; missing: no Flow-Signature header. */
+    signature: z.enum(["bad", "missing"]).optional(),
+    /** What the route must answer; anything 2xx when left out. */
+    answer: answer.optional(),
+    /** The business nudges the person. */
+    nudge: businessNudge.optional(),
+    /** Time passes on the test's clock. */
+    wait: z.string().refine((t) => waitMs(t) !== null, 'a length of time such as 8h30m, 45m or 2d').optional(),
+    /** Move the test's clock to this time before the step. */
+    at: moment.optional(),
+})
+    .superRefine((step, ctx) => {
+    const kinds = [step.say !== undefined || step.attach ? "say" : null, step.event ? "event" : null, step.nudge ? "nudge" : null, step.wait !== undefined ? "wait" : null].filter(Boolean);
+    if (kinds.length !== 1)
+        ctx.addIssue({ code: "custom", message: kinds.length ? `one of say, event, nudge or wait per step, not ${kinds.join(" and ")}` : "say something, attach a file, send an event, nudge, or wait" });
+    if (!step.event && (step.path || step.signature || step.answer !== undefined))
+        ctx.addIssue({ code: "custom", message: "path, signature and answer belong to an event step" });
+    if (kinds[0] === "say" && !step.say && !step.attach)
+        ctx.addIssue({ code: "custom", message: "say something, attach a file, or both" });
+})
+    .transform((step) => (step.event || step.nudge || step.wait !== undefined ? step : { ...step, say: step.say ?? "" }));
 const scenarioSchema = z.object({
     id: z.string().min(1),
     title: z.string().optional(),
@@ -100,20 +181,15 @@ const scenarioSchema = z.object({
         .preprocess((v) => (v instanceof Date ? v.toISOString().replace(/\.\d+Z$/, "Z") : v), z.string().refine(isDateTime, "not a date and time: write YYYY-MM-DDTHH:MM, with :SS, Z or an offset such as -04:00 if needed"))
         .optional(),
     person: z.object({
+        /** Their address on the run's channel (a phone number on phone channels): who a business run's events and nudges are for. */
+        address: z.string().min(1).optional(),
         persona: withClock(z.string()),
         goal: withClock(z.string()),
         knows: z.array(withClock(z.string())).optional(),
     }),
-    opening: z
-        .array(z
-        .object({
-        say: withClock(z.string()).default(""),
-        /** A file the person sends with it (say is its caption): a path in the tests folder. */
-        attach: z.object({ kind: z.enum(["image", "audio", "document"]), file: z.string().refine(inTests, "a path inside the tests folder, such as fixtures/receipt.jpg") }).optional(),
-        after_ms: z.number().int().min(0).optional(),
-    })
-        .refine((step) => step.say || step.attach, "say something, attach a file, or both"))
-        .min(1),
+    opening: z.array(openingStep).min(1),
+    /** Tools whose own code runs in this scenario, in place of the cloud's simulation (state the agent keeps itself). */
+    tools: z.strictObject({ real: z.array(z.string().min(1)).min(1) }).optional(),
     world: withClock(z.string()).optional(),
     max_turns: z.number().int().min(1).max(50).default(8),
     expect: z
@@ -124,6 +200,10 @@ const scenarioSchema = z.object({
         calls: z.array(expectedCall).optional(),
         /** None may be called. */
         never: z.array(expectedCall).optional(),
+        /** What the agent sent, in order (other sends may come between): checked by code, with the test's clock. */
+        sent: z.array(sentItem).optional(),
+        /** None of these was sent; `{}` is anything at all. */
+        not_sent: z.array(sentItem).optional(),
     })
         .default({}),
 });
@@ -149,6 +229,10 @@ export function mimeOf(path) {
     const types = { jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png", webp: "image/webp", gif: "image/gif", pdf: "application/pdf", ogg: "audio/ogg", opus: "audio/ogg", mp3: "audio/mpeg", m4a: "audio/mp4", wav: "audio/wav" };
     return types[extname(path).slice(1).toLowerCase()] ?? "application/octet-stream";
 }
+/** The business starts something in it (an event, a nudge, time passing), or it checks what was sent: a business run. */
+export function isBusiness(scenario) {
+    return scenario.opening.some((s) => s.event || s.nudge || s.wait !== undefined || s.at !== undefined) || !!scenario.expect.sent || !!scenario.expect.not_sent || !!scenario.tools;
+}
 /** Parse and check a scenario. The error has one line per problem: `file:line: field: what is wrong`. */
 export function parseScenario(file) {
     return parseFile(scenarioSchema, file);

package/docs/agents.md

@@ -15,16 +15,24 @@ package.
 ```sh
 npx @flow-engineer/flow init --display-name "FlatX agent"   # the starter in this (empty) folder; ask the owner what to call it first
 npm install
-npx @flow-engineer/flow link --json                 # signs in and sets up if needed (the keys, Flow's trial model key among them), then prints the phone link
-npm start                                           # keep it running: the playground link it prints, and the phone link reaches it
+npx @flow-engineer/flow link --channel telegram --json   # or whatsapp, imessage: signs in and sets up if needed (the keys, Flow's trial model key among them), then prints the phone link
+npm start                                           # after link: keep it running; the playground link it prints, and the phone link reaches it
 npx @flow-engineer/flow status --json               # any time: what the folder has and lacks
 printf 'hi\nA latte please\n' | npx @flow-engineer/flow chat   # your own check: talk to it locally, one message per line
 ```
 
 Before `init` (or `flow new <folder>`), ask the owner what people should call their agent, such as
 "FlatX agent", and pass it as `--display-name`. It is kept as `displayName` in `package.json`, and
-the message their phone sends to reach the agent is `Hi FlatX agent (ref <code>)`; change it there
-any time. Without the flag, `init` asks in a terminal and otherwise uses the folder's name in words.
+the message their phone sends to reach the agent is `Hi FlatX agent (ref <code>)`. The name takes the
+starter's (Pip) place in the agent's prompt, `agent/AGENTS.md`, and the playground and MCP server
+read it from `package.json`. To rename an agent made already, `link --display-name "<name>"` (or
+`setup --display-name`) changes both; restart `npm start` after it. Without the flag, `init` asks in
+a terminal and otherwise uses the folder's name in words.
+
+`npm start` listens on `PORT`, else 8788: with 8788 taken and no `PORT` set it takes the next free
+port and says so, and the playground link it prints has the port it uses. With `PORT` set to a port
+that is taken it prints one line, `Port 8788 is in use. Run: PORT=8798 npm start`, and exits 1.
+`npm run mcp` does the same with `MCP_PORT` (else 8790).
 
 ## How the owner tests it
 
@@ -64,7 +72,8 @@ before you hand it back; run them yourself, and do not offer them to the owner a
 - `link` does the rest when the folder is not set up (no `FLOW_FRAMEWORK_JOIN_CODE` or
   `FLOW_MESSAGING_KEY` in `.env`, or no sender for the WhatsApp or iMessage link asked for): it
   runs `login` (opens the owner's browser itself and prints the link and code at once), then
-  `setup` (writes the keys and each open channel's sender into `.env`), then prints the link.
+  `setup` (writes the keys and each open channel's sender into `.env`, and the chosen channel's
+  page as `FLOW_FRAMEWORK_TRY_URL`), then prints the link and that channel's free-trial line only.
   `--channel telegram|whatsapp|imessage` picks the channel (Telegram by default). Run it in the
   agent's folder: `setup` and `link` refuse a folder with no `package.json` (`not_an_agent_folder`).
 - A channel that is not open yet is said once ("iMessage isn't open yet; here are your Telegram
@@ -75,9 +84,13 @@ before you hand it back; run them yourself, and do not offer them to the owner a
   24 hours of their last message); it cannot message them first. `link --json` says so
   (`reply_only: true`, and in `say_to_person`): tell the owner.
 - The starter's `npm start` is on Telegram, plus WhatsApp and iMessage when `.env` has their senders
-  (`FLOW_MESSAGING_WHATSAPP_SENDER`, `FLOW_MESSAGING_IMESSAGE_SENDER`), and reads `.env` once. When
-  `setup` or `link` adds a channel (or the model key) it says so: "If npm start is running, restart
-  it to add iMessage."
+  (`FLOW_MESSAGING_WHATSAPP_SENDER`, `FLOW_MESSAGING_IMESSAGE_SENDER`), and reads `.env` once.
+  `npm start` marks itself running in `.flow/running.json`, so `link` ends with the step that fits:
+  `Next: npm start, then send the link above` when it is not running; when it is, `Next: restart npm
+  start (it runs at <url> and lacks iMessage), then send the link above` if `link` just wrote `.env`
+  or renamed it, else `Next: send the link above (npm start is running at <url>)` (`link --json`:
+  `running`, `false` or `{"url"}`, and `next`). `setup` alone says "If npm start is running, restart it to add
+  iMessage."
 - Give the owner `say_to_person` from `link --json`, and the sign-in link and code from the
   `pending` line while you wait.
 - `npm start` connects to Flow Messaging by an outbound event stream. Messages sent while it was
@@ -108,7 +121,8 @@ Every error is `{"error":{"code","message","next"}}` on stdout with `--json`, an
 `next` is the exact command or URL to run; when it came from flow.engineer it is the server's.
 A run gives one `next`: `setup --json`'s is a list in order (a model key first when there is
 none, then `npm start` for the playground, then `link` for the phone); inside `link` setup's line
-has none, and an error's `next` replaces it.
+has none, and `link`'s `next` is one string (a model key first when there is none, then starting or
+restarting `npm start`); an error's `next` replaces it.
 Run it, or give it to the owner when it needs them (a browser approval, a page to open). A
 `slow_down` error also has `retry_after` (seconds, or `null` when the server gave none). A
 trial limit's `next` is a sentence, not a command: it is printed on its own line as it came; pass
@@ -140,6 +154,14 @@ reach (`iMessage: 1 of 2 people`; `trial.imessage.contacts` `{limit, used}` in `
   with `FLOW_FRAMEWORK_LOGIN_URL` naming another server, commands stop with `signed_in_elsewhere`.
 - CI never signs in: `npx @flow-engineer/flow setup --ci` says how to give it the test cloud key.
 
+## Messages the business starts
+
+A nudge, a scheduled message or any turn the person did not start goes with link previews off
+(`preview: false` on the message; Flow Messaging's WhatsApp `preview_url: false`): on WhatsApp a
+preview card's title becomes the phone's notification instead of the message's text. For a call to
+action use `link` (`agent.nudge({ to, text, link: { label, url } })`, or the agent's send with
+`link`), not a URL in the text.
+
 ## Shared test numbers and privacy
 
 The free trial runs on Flow's shared Telegram bot, WhatsApp number and iMessage line. Sending an