@flow-engineer/flow 0.2.3 → 0.3.1

package/README.md

@@ -27,17 +27,17 @@ Node 22.18 or later. Your agent is TypeScript that Node runs as it is, with no b
 
 ```bash
 npx @flow-engineer/flow new my-agent --display-name "My agent" && cd my-agent && npm install
-npx @flow-engineer/flow link   # signs in; writes Flow's free trial model key and a phone link (or put your own key in .env)
+npx @flow-engineer/flow link --channel telegram   # or whatsapp, imessage: signs in; writes Flow's free trial model key and a phone link (or put your own key in .env)
 npm start
 ```
 
-`flow new <name>` makes `./<name>/` from the café example (lowercase letters, digits and dashes); `--display-name` is what people call it, kept as `displayName` in its `package.json`, and a phone reaches it by sending `Hi <that name> (ref <code>)`. Open the link `npm start` prints and text Pip, a café ordering assistant: your starting point. Pick a platform at the top (SMS, WhatsApp, iMessage, Telegram, web), and turn on **Debug** to see every tool call and how fast each message was answered. A model call that fails (a wrong or expired key, say) shows in the chat, in Debug and on the terminal. The café's `src/agent.ts` reads its model id from `CAFE_MODEL` (default: the model for the key you set, see [Models](#models)). The new folder has the coding-agent skills in `.claude/skills/` and an `AGENTS.md` pointing at them, so you can tell Claude Code, Codex or any coding agent what to build.
+`flow new <name>` makes `./<name>/` from the café example (lowercase letters, digits and dashes); `--display-name` is what people call it, kept as `displayName` in its `package.json`, and a phone reaches it by sending `Hi <that name> (ref <code>)`. Open the link `npm start` prints (it uses `PORT`, else 8788 or the next free port) and text your agent, the café's ordering assistant under the name you gave it (Pip in the example): your starting point; `flow link --display-name <name>` renames it later. Pick a platform at the top (SMS, WhatsApp, iMessage, Telegram, web), and turn on **Debug** to see every tool call and how fast each message was answered. A model call that fails (a wrong or expired key, say) shows in the chat, in Debug and on the terminal. The café's `src/agent.ts` reads its model id from `CAFE_MODEL` (default: the model for the key you set, see [Models](#models)). The new folder has the coding-agent skills in `.claude/skills/` and an `AGENTS.md` pointing at them, so you can tell Claude Code, Codex or any coding agent what to build.
 
 ### On your phone, from your laptop
 
 ```bash
 npx @flow-engineer/flow init                 # the same starter in the current folder; then npm install
-npx @flow-engineer/flow link                 # signs in (opens the browser), writes its keys and Flow's trial model key into .env, prints a link
+npx @flow-engineer/flow link --channel telegram   # signs in (opens the browser), writes its keys and Flow's trial model key into .env, prints a link
 npm start                                    # try it in the playground link it prints, then open the phone link and text the agent
 npx @flow-engineer/flow status               # what the folder has and lacks
 ```

package/coding-agents/skill.md

@@ -20,7 +20,7 @@ and `flow-framework-auth` (`auth-skill.md`) when tools need to know who the pers
 `npx @flow-engineer/flow new <name>` (lowercase letters, digits and dashes) makes `./<name>/` from the café
 example: a complete agent with tools and tests that depends on the `@flow-engineer/flow` package and imports
 `@flow-engineer/flow` and `@flow-engineer/flow/simulators`, with these skills in `.claude/skills/`. Run `npm install` there.
-Build in it, changing Pip's prompt, skills, tools and tests into yours. A provider key is optional:
+Build in it, changing the café agent's prompt, skills, tools and tests into yours. A provider key is optional:
 `npx @flow-engineer/flow link` (or `setup`) writes `FLOW_KEY`, the agent's one Flow key, into `.env` (never
 read or print it), and the agent calls models through Flow with it on $2 of Flow trial credit. A key of the owner's own wins over it, made
 at the provider: `OPENROUTER_API_KEY` at https://openrouter.ai/keys,
@@ -63,21 +63,25 @@ skill, not in AGENTS.md.
 ## buildAgent
 
 Build the agent in one function that the playground and the tests both call, so they never
-drift apart. Tests pass their own model, events and simulated tools:
+drift apart. Tests pass their own model, events and simulated tools; a test the business starts
+also passes `channels` and `testing` (the run's clock), which go on to `createAgent` as they are
+(the `flow-framework-tests` skill):
 
 ```ts
 import { fileURLToPath } from "node:url";
-import { createAgent, openAICompatible, type EventSink, type Model, type Tool } from "@flow-engineer/flow";
+import { createAgent, openAICompatible, type AgentOptions, type Channel, type EventSink, type Model, type Tool } from "@flow-engineer/flow";
 import { tools as myTools } from "./tools.ts";
 
 export const tools = myTools;
 
-export function buildAgent(options: { model?: Model; events?: EventSink[]; tools?: Tool[] } = {}) {
+export function buildAgent(options: { model?: Model; events?: EventSink[]; tools?: Tool[]; channels?: Channel[]; testing?: Partial<AgentOptions> } = {}) {
   return createAgent({
     dir: fileURLToPath(new URL("../agent", import.meta.url)),
     model: options.model ?? openAICompatible({ model: "anthropic/claude-haiku-5.5" }),
     tools: options.tools ?? myTools,
     events: options.events ?? [],
+    ...(options.channels ? { channels: options.channels } : {}),
+    ...options.testing,
   });
 }
 ```
@@ -93,7 +97,12 @@ and are `message.in`/`message.out` events marked `answered: true`);
 `deadlineMs` (default 60,000) is the longest a reply waits for a tool before it moves to the
 background (set a tool's own `deadlineMs` for a known-slow one); `partialAfterMs` (default 5,000)
 is how long a finished tool's result waits for the others of its response; `shareUpdates` turns live status lines on web and app UIs off, or replaces their
-guidance with a string.
+guidance with a string; `routes` (`{ "/v1/events": (request) => Response }`) are HTTP routes the
+agent serves beside its chat, such as a business's event push, answered by `agent.fetch(request)`
+(and by the test cloud with a test's events); `onTick(now)` is work of your own on the agent's clock
+(held sends, reminders timed from your data), run with each check for due scheduled messages.
+`agent.reach({ channel, address })` makes the conversation of someone the business may message
+before they have written; until they write, only a template reaches them on WhatsApp.
 
 Models are reached through any OpenAI-compatible API. `openAICompatible()` with no key reads the
 first of `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` and
@@ -205,6 +214,9 @@ to send later. Prefer `prompt`; use `text` only when the wording must be exact.
 see it.", no values) so a nudge is held until they reply instead of refused (`outside_window`); the
 agent may send a fitting template itself (`send_template`), and `template.missing` events say which
 messages want one. Held nudges (quiet hours, a closed window) settle as `held`, then `sent` or `expired`.
+For a call to action use `link` (`text` with `link: { label, url }`, or the agent's send with
+`link`), never a URL in the text: what the business starts goes with link previews off, since on
+WhatsApp a preview card's title becomes the phone's notification instead of the message.
 
 When the owner's backend is a separate service, mount `nudgeHandler(agent, { token })` (from
 `@flow-engineer/flow`; a token of at least 32 characters, from a secret; `base` is `/nudges` by default) in the
@@ -313,12 +325,13 @@ and every simulated message is logged with the person, channel, time and address
 To chat with the agent from the owner's phone, with no tunnel and no key made by hand, run these
 from the agent's folder (`npx @flow-engineer/flow init --display-name "<name>"` makes a starter in
 an empty one: first ask the owner what people should call their agent, such as "FlatX agent"; the
-phone's first message is `Hi FlatX agent (ref <code>)`, and `package.json`'s `displayName` keeps it).
+phone's first message is `Hi FlatX agent (ref <code>)`, and `package.json`'s `displayName` keeps it;
+`link --display-name "<name>"` renames it later, in `package.json` and `agent/AGENTS.md`).
 Only `chat` reads stdin; `init` asks for the name only in a terminal, and nothing else asks for input.
 
 ```sh
-npx @flow-engineer/flow link --json          # signs in and runs setup when needed (Flow's trial model key too), then the channel's own link (t.me, wa.me, sms:); give its say_to_person to the owner
-npm start                                    # the agent: its playground link, and the owner texts it while it runs
+npx @flow-engineer/flow link --channel telegram --json   # or whatsapp, imessage: signs in and runs setup when needed (Flow's trial model key too), then the channel's own link (t.me, wa.me, sms:); give its say_to_person to the owner, and run its next
+npm start                                    # after link: its playground link, and the owner texts it while it runs (PORT, else 8788 or the next free port)
 npx @flow-engineer/flow status --json        # what the folder has and lacks, at any time
 printf 'hi\nA latte please\n' | npx @flow-engineer/flow chat   # your own check: one message per line, replies printed
 npx @flow-engineer/flow test --synthetic     # your own check: the tests, on the key setup wrote
@@ -336,7 +349,9 @@ kept: give the owner the link and code, and run `link` again (it polls the same
 `setup`, which writes the test cloud, traces and Flow Messaging keys into `.env`, prints names and
 last 4 characters only, keeps values already there (`--replace` takes the new ones), and is safe to
 run again. `--channel telegram|whatsapp|imessage` picks the channel; a channel flow.engineer cannot
-open yet exits 3 with its `next`. `login`, `setup` and `link` also run on their own.
+open yet exits 3 with its `next`. When only observe's part of setup fails (traces and the test cloud),
+`link` still prints the link and exits 0, with one warning saying what is missing and the server's
+fix (`warnings` in `--json`): pass it on to the owner. `login`, `setup` and `link` also run on their own.
 
 In `src/main.ts`, put `fm.telegram()` from `@flow-engineer/flow/flow-messaging` in the agent's
 channels and call `fm.start(agent, { cursorFile: ".flow/flow-messaging-cursor" })`: with no webhook

package/coding-agents/test-skill.md

@@ -74,7 +74,7 @@ expect:
 - `timezone` (default UTC) and `now`: the test's clock. `now` is when each run starts,
   `YYYY-MM-DDTHH:MM[:SS]`, local to `timezone` unless it ends in `Z` or an offset (`-04:00`); left
   out, it is the real time. Placeholders are filled from it, and the simulated tools and the judge
-  are told it; your agent's clock is not changed: the agent still reads the real time. So set `now` only when the agent takes
+  are told it; outside a business run (below) your agent's clock is not changed: the agent still reads the real time. So set `now` only when the agent takes
   its dates from its tools or its context; otherwise leave it out and placeholders follow the real
   date.
 
@@ -98,6 +98,55 @@ time of day, then `| iso` (the default, with its offset), `| date` (2026-10-16),
 `person`, `opening`, `expect` and the tool files' `responses`; the cloud fills them on each run. Any other
 `{{...}}` is plain text.
 
+### Scenarios the business starts
+
+A scenario can start with the business instead of the person: an event its backend sends, a nudge,
+or time passing. Such a run (a business run) gets an agent of its own, built by `buildAgent` with
+the run's clock and the agent's own channels (pass `options.channels` and `options.testing` on to
+`createAgent`, `testing` spread as it is: `now` and `scheduleCheckMs: 0`), so the agent runs on
+the test's clock: quiet hours, held sends, `expiresAt` and caps over days follow it.
+
+```yaml
+timezone: Asia/Kolkata
+now: 2026-10-20T23:30
+person:
+  address: "+15550100001"        # who the events and nudges are for (a made-up number)
+  persona: ...
+  goal: ...
+opening:
+  - event: { type: buying.bid.outbid, delivery: critical, subject: "user:u1", data: { user: { phone: "+15550100001" } } }
+  - wait: 8h30m                  # time passes; what came due runs, a minute at a time
+  - say: "ok thanks"             # the person can still write
+  - event: { id: evt_dup, type: ..., subject: ..., data: {...} }
+    signature: bad               # or missing; answer: 401
+    answer: 401                  # what the route must answer (default: any 2xx); { status: 400, field: data.user }
+  - nudge: { prompt: "Tell them the listing ends soon." }   # or text, or template: { name, body: [...] }
+    at: 2026-10-21T15:00         # moves the clock first: a date and time, HH:MM (the next one), or {{now ...}}
+max_turns: 1                     # 1: no turns played after the opening
+tools: { real: [keep_me_posted] }  # their own code runs, for state the agent keeps itself
+expect:
+  sent:                          # what went out, in order (other sends may come between)
+    - { at: "23:30", template: outbid }
+    - { at: "08:00", phrased: true, text: "₹53,000" }
+  not_sent:
+    - { template: outbid_reminder }   # {} is anything at all
+```
+
+- An `event` is sent exactly as a business's backend sends a Flow event: one envelope
+  `{ id, type, occurredAt, subject, delivery?, data }` (`id` and `occurredAt` default to one per
+  step and the clock), as `POST /v1/events` (or the step's `path`) to the agent's `routes`, with
+  `Content-Type: application/json`, `Idempotency-Key: <id>` and
+  `Flow-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.{t}.{body}">`, signed with the
+  run's own test secret (`options.testing.eventsSecret`: check signatures with it in a business run).
+  The same `id` twice is a duplicate, as it would be live.
+- A `nudge` is `agent.nudge` to the run's person; `wait` and `at` move the clock (never back).
+- `expect.sent` items: `at` (HH:MM on any day, or a date and time; to the minute), `template`
+  (its name), `phrased: true` (the agent's own words, not a template), `text` (in the message, or in
+  the template's values). Checked by code, like `calls`.
+- A business run where the agent sent nothing is not a failure by itself: `expect` decides.
+- Timers of your own (held sends, reminders timed from your data) go in `createAgent`'s `onTick`,
+  which runs on the agent's clock, never in a `setInterval` of your own.
+
 How fast the agent first replies to each message is measured on every run from timestamps, not
 written in scenarios: the dashboard shows it for the whole run (average, p95, min and max).
 

package/dist/flow-messaging/src/index.js

@@ -97,16 +97,17 @@ export function flowMessaging(options = {}) {
         return { phone: to.startsWith("+") ? to : `+${to}` };
     }
     /** One message: into the person's conversation, or a new one from the channel's sender. */
-    async function send(route, to, content, replyTo, about = replyTo, idempotencyKey) {
+    async function send(route, to, content, replyTo, about = replyTo, idempotencyKey, channelOptions) {
         try {
             const conversation = await conversationFor(route.name, to, about);
+            const options = channelOptions ? { channel_options: channelOptions } : {};
             let sent;
             if (conversation)
-                sent = await client.post(`/v1/conversations/${idSegment("conv", conversation)}/messages`, { content, ...(replyTo ? { reply_to: replyTo } : {}) }, undefined, idempotencyKey);
+                sent = await client.post(`/v1/conversations/${idSegment("conv", conversation)}/messages`, { content, ...(replyTo ? { reply_to: replyTo } : {}), ...options }, undefined, idempotencyKey);
             else {
                 if (!route.sender)
                     throw new Error(`no conversation with them on ${route.name} yet, and no sender to start one (set FLOW_MESSAGING_${route.kind.toUpperCase()}_SENDER)`);
-                sent = await client.post("/v1/messages", { sender: route.sender, to: recipient(route.kind, to), content }, undefined, idempotencyKey);
+                sent = await client.post("/v1/messages", { sender: route.sender, to: recipient(route.kind, to), content, ...options }, undefined, idempotencyKey);
             }
             flowConversation.set(key(route.name, to), sent.conversation);
         }
@@ -175,11 +176,13 @@ export function flowMessaging(options = {}) {
     function provider(route) {
         return {
             sendMessage: async (to, message) => {
+                // A message the business started: on WhatsApp, no link preview (its card's title would be the phone's notification).
+                const options = (content) => (message.preview === false && route.kind === "whatsapp" && content.type === "text" ? { preview_url: false } : undefined);
                 const [first, ...rest] = contents(route.kind, message);
                 const key = message.idempotencyKey;
-                await send(route, to, first, message.replyTo, message.replyTo, key);
+                await send(route, to, first, message.replyTo, message.replyTo, key, options(first));
                 for (const [i, next] of rest.entries())
-                    await send(route, to, next, undefined, undefined, key && `${key}:${i + 1}`);
+                    await send(route, to, next, undefined, undefined, key && `${key}:${i + 1}`, options(next));
             },
             react: (to, messageId, emoji) => send(route, to, { type: "reaction", message_id: messageId, emoji }, undefined, messageId),
             typing: (to, on) => courtesy(route, to, "typing", { state: on ? "on" : "off" }),

package/dist/simulators/src/server.d.ts

@@ -136,6 +136,8 @@ export interface Playground {
 }
 export interface TestCloudSimulators {
     events: EventSink;
+    /** Where the agent's sends to one person's thread go, before they have written (a run the business starts). */
+    deliverer(platform: string, person: string): Deliver;
     listen(agent: AgentConnection, port: number): Promise<Listening>;
     handler(agent: AgentConnection, base?: string): Handler;
 }

package/dist/simulators/src/server.js

@@ -393,7 +393,9 @@ export function simulators(options = {}) {
     }
     function serve(handle, port) {
         const server = createServer(handle);
-        return new Promise((resolve) => {
+        return new Promise((resolve, reject) => {
+            // A port taken since it was chosen rejects, as an error the caller can print, never an unhandled 'error' event.
+            server.once("error", reject);
             server.listen(port, "127.0.0.1", () => resolve({
                 // The bound port, so port 0 (any free port) works too.
                 url: `http://127.0.0.1:${server.address().port}`,
@@ -537,6 +539,10 @@ export function simulators(options = {}) {
         }
         const testCloud = {
             events: cloudEvents,
+            deliverer: (platform, person) => {
+                const p = platformOf(platform);
+                return deliverer(p, key(p.id, person));
+            },
             listen: (agent, port) => serve(guarded((req, res) => handle(agent, req, res, "")), port),
             handler: (agent, base = "") => guarded((req, res) => handle(agent, req, res, base)),
         };

package/dist/src/agent.d.ts

@@ -140,6 +140,18 @@ export interface AgentOptions {
     keepMessageIdsDays?: number;
     /** The clock (tests move it). */
     now?: () => number;
+    /**
+     * Work of your own that runs on the agent's clock: called (and awaited) each time due scheduled
+     * messages are looked for (every `scheduleCheckMs`, and each `runDue()`), with the time now. A
+     * test that moves the clock runs it at each step, so your own timers (held sends, reminders
+     * timed from your data) follow the test's clock. An error is logged, never thrown.
+     */
+    onTick?: (now: number) => Promise<void> | void;
+    /**
+     * HTTP routes the agent serves beside its chat, by path ("/v1/events": a business's event push),
+     * answered by `agent.fetch(request)`. The test cloud calls them in-process with a test's events.
+     */
+    routes?: Record<string, (request: Request) => Response | Promise<Response>>;
     /**
      * The people who may write from the test playground (`simulate`), and no one else. Each is a
      * real person to the agent, by their phone number: the same conversation whether they write from
@@ -197,6 +209,11 @@ export interface NudgeInput {
     };
     /** Sent as written, with no model call. */
     text?: string;
+    /** With `text`: its call to action, sent as a link button (on channels without one, the URL after the text). Never a URL in the text. */
+    link?: {
+        label: string;
+        url: string;
+    };
     /** The agent gets a turn with this note and writes the message itself, or sends nothing. */
     prompt?: string;
     /** A template the owner already set up with the channel, sent as is (also outside WhatsApp's window). */
@@ -515,6 +532,21 @@ export declare class Agent {
     }>;
     /** Whether the agent has a profile (get_user_profile), so the test cloud knows to play it. */
     hasProfile(): boolean;
+    /**
+     * A person the business may message before they have written (they gave it their number): their
+     * conversation, made the first time, with no message in it. Until they write, their WhatsApp
+     * window is closed, so only a template reaches them there.
+     */
+    reach(to: {
+        channel: string;
+        address: string;
+    }): Promise<{
+        conversationId: string;
+    }>;
+    /** A channel the agent was given, by name, as it was given (the test cloud plays a copy of it). */
+    channel(name: string): Channel | undefined;
+    /** Answers a request to one of `routes` by its path; 404 for any other. */
+    fetch(request: Request): Promise<Response>;
     nudge(input: NudgeInput): Promise<NudgeResult>;
     /**
      * Records a nudge and resolves at once, without waiting for its send or turn: `queued`, or what

package/dist/src/agent.js

@@ -63,6 +63,9 @@ export class Agent {
             if (this.channelsByName.has(name))
                 throw new Error(`flow: "${name}" is reserved; give the channel another name`);
         this.now = options.now ?? Date.now;
+        for (const path of Object.keys(options.routes ?? {}))
+            if (!path.startsWith("/"))
+                throw new Error(`flow: a route is a path starting with /, not "${path}"`);
         if (options.fallbackTemplate) {
             const declared = declaredTemplate(options.templates, options.fallbackTemplate);
             if (!declared)
@@ -313,7 +316,7 @@ export class Agent {
             // Released because they just wrote: their window is open, though their message may not have landed yet.
             const inbox = await this.store.releaseNudge(writer ? { ...n, body: { ...n.body, theyWrote: true } } : n);
             if (inbox !== null)
-                this.wake(n.conversationId, inbox);
+                await this.wake(n.conversationId, inbox);
         }
     }
     /** Sends the traces of finished turns still waiting for the traces endpoint; call it before the process exits. */
@@ -701,6 +704,30 @@ export class Agent {
     hasProfile() {
         return this.options.profile !== undefined;
     }
+    /**
+     * A person the business may message before they have written (they gave it their number): their
+     * conversation, made the first time, with no message in it. Until they write, their WhatsApp
+     * window is closed, so only a template reaches them there.
+     */
+    async reach(to) {
+        await this.settings.ready;
+        const adapter = this.channelOf(to.channel);
+        const identity = await this.conversationFor(adapter, to.channel, to.address);
+        const conversation = this.open(identity.conversationId);
+        conversation.link({ name: to.channel, info: adapter.info, params: adapter.params, instructions: adapter.instructions, address: to.address, deliver: this.deliverer(adapter, to.address, identity.conversationId), lastMessageAt: identity.lastMessageAt });
+        return { conversationId: identity.conversationId };
+    }
+    /** A channel the agent was given, by name, as it was given (the test cloud plays a copy of it). */
+    channel(name) {
+        return this.channelsByName.get(name);
+    }
+    /** Answers a request to one of `routes` by its path; 404 for any other. */
+    async fetch(request) {
+        const route = this.options.routes?.[new URL(request.url).pathname];
+        if (!route)
+            return Response.json({ error: "no such route" }, { status: 404 });
+        return route(request);
+    }
     async nudge(input) {
         // outcome() waits while it is queued, so what it resolves is settled.
         return (await this.outcome(await this.recordNudge(input)));
@@ -715,6 +742,8 @@ export class Agent {
         const kinds = [input.text, input.prompt, input.template].filter((v) => v !== undefined).length;
         if (kinds !== 1)
             throw new Error("flow: a nudge has exactly one of text, prompt or template");
+        if (input.link && (input.text === undefined || input.at !== undefined))
+            throw new Error("flow: a nudge's link goes with text, sent now (not with `at`)");
         // A declared template whose values don't fit it never goes: Meta would refuse it, the playground would show nonsense.
         const declared = input.template && declaredTemplate(this.options.templates, input.template);
         if (declared)
@@ -755,7 +784,7 @@ export class Agent {
             const added = await add({ ...record, body: { text: input.text, prompt: input.prompt, at: input.at }, status: "scheduled" }, schedule);
             return typeof added === "number" ? { id, status: "scheduled" } : added;
         }
-        const body = { address: input.to.address, ...(input.template ? { template: input.template } : input.text !== undefined ? { text: input.text } : { prompt: input.prompt }) };
+        const body = { address: input.to.address, ...(input.template ? { template: input.template } : input.text !== undefined ? { text: input.text, ...(input.link ? { link: input.link } : {}) } : { prompt: input.prompt }) };
         const now = this.now();
         const quietEnds = input.respectQuietHours === false ? null : await this.quietEnd(conversationId, now);
         if (quietEnds !== null) {
@@ -780,7 +809,7 @@ export class Agent {
         const added = await add({ ...record, body, status: "queued" });
         if (typeof added !== "number")
             return added;
-        this.wake(conversationId, added);
+        void this.wake(conversationId, added);
         return { id, status: "queued" };
     }
     /** A nudge's state now, or null for an id the store does not hold. */
@@ -826,9 +855,11 @@ export class Agent {
                 return `no way to reach them on ${s.channel}`;
             return windowClosed({ info: this.infoOf(s.channel, s.conversationId), lastMessageAt: identity.lastMessageAt }, now) ? "outside_window" : null;
         });
-        for (const q of queued)
-            this.wake(q.conversationId, q.inbox);
+        // Awaited, so a caller that then waits for the conversation (a test moving the clock) sees the turn.
+        await Promise.all(queued.map((q) => this.wake(q.conversationId, q.inbox)));
         await this.releaseHeld(now);
+        if (this.options.onTick)
+            await Promise.resolve().then(() => this.options.onTick(now)).catch((error) => console.warn("flow: onTick:", error));
         await this.pruneMessageIds(now).catch((error) => console.warn("flow: pruning message ids:", error));
         return queued.length;
     }
@@ -872,14 +903,13 @@ export class Agent {
     wake(conversationId, inbox) {
         const resident = this.conversations.get(conversationId);
         if (!resident) {
-            void this.store.conversation(conversationId).then((row) => {
+            return this.store.conversation(conversationId).then((row) => {
                 if (row)
                     this.rows.set(conversationId, row);
                 this.open(conversationId);
             });
-            return;
         }
-        void this.store.openInbox(conversationId).then((rows) => {
+        return this.store.openInbox(conversationId).then((rows) => {
             const row = rows.find((r) => r.id === inbox);
             if (row)
                 resident.enqueue(row);

package/dist/src/channels.d.ts

@@ -76,6 +76,8 @@ export interface Message {
     image?: {
         url: string;
     };
+    /** false: send it with link previews off (a message the business started). */
+    preview?: false;
     /** Given for a send the business starts (a nudge, a scheduled text): the same in every process, so a provider that takes one sends it once. */
     idempotencyKey?: string;
 }

package/dist/src/channels.js

@@ -159,6 +159,7 @@ function message(outbound) {
         ...(outbound.list ? { list: outbound.list } : {}),
         ...(outbound.link ? { link: outbound.link } : {}),
         ...(outbound.image ? { image: outbound.image } : {}),
+        ...(outbound.preview === false ? { preview: false } : {}),
         ...(outbound.idempotencyKey ? { idempotencyKey: outbound.idempotencyKey } : {}),
     };
 }

package/dist/src/conversation.d.ts

@@ -117,6 +117,8 @@ export declare class Conversation {
     private readonly tasks;
     private taskCount;
     private idleSince;
+    /** The turn running now was not started by the person (a nudge, a scheduled message, a background result). */
+    private businessTurn;
     private settled;
     /** Channels where nothing has reached the person since their latest message there. */
     private readonly unanswered;

package/dist/src/conversation.js

@@ -101,6 +101,8 @@ export class Conversation {
     tasks = new Map();
     taskCount = 0;
     idleSince = Date.now();
+    /** The turn running now was not started by the person (a nudge, a scheduled message, a background result). */
+    businessTurn = false;
     settled = [];
     /** Channels where nothing has reached the person since their latest message there. */
     unanswered = new Set();
@@ -463,7 +465,7 @@ export class Conversation {
                 this.notes.push({ text, inbox: row.id, owed: { nudge: p.nudge, mode: "prompt", channel: p.channel, address: p.address } });
             }
             else
-                this.direct.push({ inbox: row.id, channel: p.channel, address: p.address, text: p.text, template: p.template, nudge: p.nudge, ...(p.theyWrote ? { theyWrote: true } : {}) });
+                this.direct.push({ inbox: row.id, channel: p.channel, address: p.address, text: p.text, ...(p.link ? { link: p.link } : {}), template: p.template, nudge: p.nudge, ...(p.theyWrote ? { theyWrote: true } : {}) });
         }
         if (!this.running && this.hasWork())
             this.schedule(0);
@@ -803,6 +805,7 @@ export class Conversation {
         this.absorb();
         // A turn the person started (as against a background result, a scheduled message or a nudge).
         const theirs = this.unanswered.size > 0;
+        this.businessTurn = !theirs;
         if (!this.channels.size) {
             // No way to reach them right now (a channel with no adapter, after a restart).
             for (const o of this.owed.splice(0))
@@ -1049,6 +1052,8 @@ export class Conversation {
                 ...(input.link ? { link: input.link } : {}),
                 ...(input.image ? { image: input.image } : {}),
                 ...(hasFields ? { fields } : {}),
+                // A turn the person did not start: no link preview leads the notification (types.ts, `preview`).
+                ...(this.businessTurn ? { preview: false } : {}),
             });
             const failure = await this.send(channel, outbound);
             if (failure) {
@@ -1175,9 +1180,10 @@ export class Conversation {
         }
         if (covered)
             return settle("dropped", `no-contact rule ${covered.id}: ${covered.rule}`);
+        // The business started it: its link goes as a button, and no preview leads the notification.
         // The same key in every process, so the channel's provider sends it once.
         const idempotencyKey = d.nudge ? `nudge:${d.nudge}` : d.run ? `run:${d.run}` : `inbox:${this.id}:${d.inbox}`;
-        const outbound = d.template ? { type: "template", ...d.template, idempotencyKey } : { type: "message", text: d.text ?? "", idempotencyKey };
+        const outbound = d.template ? { type: "template", ...d.template, idempotencyKey } : fitMessage(link.info, { type: "message", text: d.text ?? "", ...(d.link ? { link: d.link } : {}), preview: false, idempotencyKey });
         let failure = null;
         if (this.closed)
             return settle("failed", "this person was forgotten");

package/dist/src/http.js

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

package/dist/src/index.d.ts

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

package/dist/src/index.js

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

package/dist/src/local.d.ts

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