@flow-engineer/flow 0.2.2 → 0.3.0

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

package/examples/cafe/src/main.ts

@@ -1,14 +1,19 @@
-// Pip in the playground: `npm start`, then open the printed link and pick a test person. With
-// FLOW_MESSAGING_KEY in .env (`npx @flow-engineer/flow link` puts it there), Pip is on Telegram
+// The agent in the playground: `npm start`, then open the printed link and pick a test person. With
+// FLOW_MESSAGING_KEY in .env (`npx @flow-engineer/flow link` puts it there), it is on Telegram
 // too (and WhatsApp and iMessage when .env names their senders), through Flow Messaging's event
-// stream: an outbound connection, so no public URL or tunnel.
+// stream: an outbound connection, so no public URL or tunnel. It listens on PORT, else 8788 or the
+// next free port above it.
 
+import { readFileSync } from "node:fs";
+import { choosePort, markRunning } from "../../../src/index.ts";
 import { flowMessaging } from "../../../flow-messaging/src/index.ts";
 import { simulators } from "../../../simulators/src/index.ts";
 import { buildAgent } from "./agent.ts";
 import { channelNames, flowChannels } from "./channels.ts";
 
-const play = simulators({ title: "Pip · Bean & Leaf" });
+// What people call it: package.json's displayName (`npx @flow-engineer/flow link --display-name <name>` changes it).
+const { displayName: name = "Pip" } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { displayName?: string };
+const play = simulators({ title: `${name} · Bean & Leaf` });
 const fm = process.env.FLOW_MESSAGING_KEY ? flowMessaging() : undefined;
 const channels = fm ? flowChannels(fm) : [];
 let agent: ReturnType<typeof buildAgent>;
@@ -18,12 +23,22 @@ try {
   console.error((error as Error).message); // such as no model key in .env
   process.exit(1);
 }
-const port = Number(process.env.PORT ?? 8788);
-const { url } = await play.listen(agent, port);
-console.log(`Pip's playground: ${url}/`);
+let url: string;
+try {
+  const { port, note } = await choosePort("PORT", 8788, { command: "npm start" });
+  if (note) console.log(note);
+  ({ url } = await play.listen(agent, port));
+} catch (error) {
+  console.error((error as Error).message); // such as the port PORT names being in use
+  process.exit(1);
+}
+const port = Number(new URL(url).port);
+// `npx @flow-engineer/flow link` reads it (.flow/running.json) to say whether to start or restart this.
+markRunning(url);
+console.log(`${name}'s playground: ${url}/`);
 console.log(`Every channel side by side: ${url}/person`);
 if (fm) {
-  // Events sent while Pip was not running come when it starts again (.flow/ keeps the last one handled).
+  // Events sent while it was not running come when it starts again (.flow/ keeps the last one handled).
   const live = fm.start(agent, { cursorFile: ".flow/flow-messaging-cursor", port: port + 1 });
   console.log(`On ${channelNames(channels)} through Flow Messaging (${live.mode}). The phone link: npx @flow-engineer/flow link`);
   live.stopped.then((why) => console.error(`Flow Messaging stopped: ${why.message} Then: npx @flow-engineer/flow setup`));

package/examples/cafe/src/mcp.ts

@@ -1,9 +1,11 @@
-// Pip's tools and skills as an MCP server, for Claude, ChatGPT or any MCP host: `npm run mcp`.
+// The agent's tools and skills as an MCP server, for Claude, ChatGPT or any MCP host: `npm run mcp`.
 // The same tools the chat agent uses; no model key needed, since the host brings its own model.
 
+import { readFileSync } from "node:fs";
 import { createServer } from "node:http";
 import { fileURLToPath } from "node:url";
 import { mcpServer } from "../../../mcp/src/index.ts";
+import { choosePort } from "../../../src/index.ts";
 import { tools } from "./tools.ts";
 
 export const mcp = mcpServer({
@@ -15,8 +17,24 @@ export const mcp = mcpServer({
   // auth: { issuer, resource, scopes, verify } (the chinwag-auth skill).
 });
 
-const port = Number(process.env.MCP_PORT ?? 8790);
-createServer((req, res) => void mcp.node(req, res)).listen(port, "127.0.0.1", () => {
-  console.log(`Pip's MCP server: http://127.0.0.1:${port}/mcp`);
-  console.log(`Try it in Claude Code: claude mcp add --transport http bean-and-leaf http://127.0.0.1:${port}/mcp`);
-});
+// What people call it: package.json's displayName.
+const { displayName: name = "Pip" } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { displayName?: string };
+// MCP_PORT, else 8790 or the next free port above it.
+let port: number;
+try {
+  const chosen = await choosePort("MCP_PORT", 8790, { command: "npm run mcp" });
+  port = chosen.port;
+  if (chosen.note) console.log(`${chosen.note} The CLI then needs CAFE_SERVER=http://127.0.0.1:${port}/mcp.`);
+} catch (error) {
+  console.error((error as Error).message);
+  process.exit(1);
+}
+createServer((req, res) => void mcp.node(req, res))
+  .once("error", (error) => {
+    console.error(`${error.message}. Run: MCP_PORT=<port> npm run mcp`);
+    process.exit(1);
+  })
+  .listen(port, "127.0.0.1", () => {
+    console.log(`${name}'s MCP server: http://127.0.0.1:${port}/mcp`);
+    console.log(`Try it in Claude Code: claude mcp add --transport http bean-and-leaf http://127.0.0.1:${port}/mcp`);
+  });

package/flow-messaging/README.md

@@ -148,7 +148,9 @@ Each of these can also be passed in code: `flowMessaging({ apiKey, webhookSecret
 ## What it does for you
 
 - Every send carries its own Idempotency-Key. A 429 or 5xx is tried again with the same key after
-  a short Retry-After, so a message never goes out twice.
+  a short Retry-After, so a message never goes out twice. A nudge or a scheduled text keeps one key
+  from its id (`nudge:<id>`, `run:<id>`) in every process, so a restart or a second instance does not
+  send it again.
 - Flow's `409 outside_window` becomes the framework's `outside_window`, so the agent knows to send a
   template.
 - A permanent refusal (opted out, no consent, ...) reaches the agent once, with "don't resend it".

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-engineer/flow",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "An open-source runtime for chat agents that feel like a person texting back.",
   "license": "Apache-2.0",
   "repository": {