@flow-engineer/flow 0.2.2 → 0.3.0

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

@@ -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

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/client.d.ts

@@ -28,8 +28,8 @@ export declare class Client {
     get<T>(path: string): Promise<T>;
     /** A file's bytes: GET /v1/files/{id} answers them or redirects to a signed URL, which fetch follows without the key. */
     download(fileId: string): Promise<Uint8Array>;
-    /** A POST with its own Idempotency-Key, kept across the retries of this one call; `tries: 1` for courtesies. */
-    post<T>(path: string, body: unknown, tries?: number): Promise<T>;
+    /** A POST with its own Idempotency-Key (the caller's, else a new one), kept across the retries of this one call; `tries: 1` for courtesies. */
+    post<T>(path: string, body: unknown, tries?: number, idempotencyKey?: string): Promise<T>;
     private request;
 }
 /**

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

@@ -66,9 +66,9 @@ export class Client {
             throw await errorOf(response);
         return new Uint8Array(await response.arrayBuffer());
     }
-    /** A POST with its own Idempotency-Key, kept across the retries of this one call; `tries: 1` for courtesies. */
-    post(path, body, tries = TRIES) {
-        return this.request("POST", path, body, randomUUID(), tries);
+    /** A POST with its own Idempotency-Key (the caller's, else a new one), kept across the retries of this one call; `tries: 1` for courtesies. */
+    post(path, body, tries = TRIES, idempotencyKey = randomUUID()) {
+        return this.request("POST", path, body, idempotencyKey, tries);
     }
     async request(method, path, body, idempotencyKey, tries = TRIES) {
         if (!this.apiKey)

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) {
+    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 } : {}) });
+                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 });
+                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,20 +176,23 @@ 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);
-                await send(route, to, first, message.replyTo);
-                for (const next of rest)
-                    await send(route, to, next);
+                const key = message.idempotencyKey;
+                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}`, 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" }),
             markRead: (to, messageIds) => courtesy(route, to, "read", { up_to: messageIds.at(-1) }, messageIds.at(-1)),
-            sendTemplate: async (to, wanted) => {
+            sendTemplate: async (to, wanted, idempotencyKey) => {
                 if (!route.sender)
                     throw new Error(`a template needs the channel's sender (set FLOW_MESSAGING_${route.kind.toUpperCase()}_SENDER)`);
                 const found = await template(route.sender, wanted);
                 const params = templateParams(wanted);
-                await send(route, to, { type: "template", template_id: found.id, language: wanted.language ?? found.language, ...(Object.keys(params).length ? { params } : {}) });
+                await send(route, to, { type: "template", template_id: found.id, language: wanted.language ?? found.language, ...(Object.keys(params).length ? { params } : {}) }, undefined, undefined, idempotencyKey);
             },
         };
     }
@@ -232,6 +236,7 @@ export function flowMessaging(options = {}) {
                             ...(outbound.buttons && info.buttons ? { buttons: outbound.buttons } : {}),
                             ...(outbound.link && info.linkButton ? { link: outbound.link } : {}),
                             ...(outbound.image && info.images ? { image: outbound.image } : {}),
+                            ...(outbound.idempotencyKey ? { idempotencyKey: outbound.idempotencyKey } : {}),
                         });
                     case "reaction":
                         return p.react(to, outbound.messageId, outbound.emoji);

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,10 @@ 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;
 }
 export interface WhatsAppProvider {
     sendMessage(to: string, message: Message): Promise<void>;
@@ -90,12 +94,10 @@ export interface WhatsAppProvider {
     react?(to: string, messageId: string, emoji: string): Promise<void>;
     typing?(to: string, on: boolean): Promise<void>;
     markRead?(to: string, messageIds: string[]): Promise<void>;
-    sendTemplate?(to: string, template: Template): Promise<void>;
+    sendTemplate?(to: string, template: Template, idempotencyKey?: string): Promise<void>;
 }
 export interface SmsProvider {
-    sendMessage(to: string, message: {
-        text: string;
-    }): Promise<void>;
+    sendMessage(to: string, message: Pick<Message, "text" | "idempotencyKey">): Promise<void>;
 }
 /** Your own UI. `message` carries the text, any buttons, and your params by name. */
 export interface CustomUIProvider {

package/dist/src/channels.js

@@ -93,8 +93,8 @@ export function whatsapp(provider, options = {}) {
                 case "template": {
                     if (!provider.sendTemplate || off.has("templates"))
                         throw new Error("this WhatsApp provider sends no templates");
-                    const { type: _type, ...template } = outbound;
-                    return provider.sendTemplate(to, template);
+                    const { type: _type, idempotencyKey, ...template } = outbound;
+                    return provider.sendTemplate(to, template, idempotencyKey);
                 }
                 case "status":
                     return;
@@ -112,7 +112,7 @@ export function sms(provider, options = {}) {
         phone: true,
         send: (to, outbound) => {
             if (outbound.type === "message")
-                return provider.sendMessage(to, { text: outbound.text });
+                return provider.sendMessage(to, { text: outbound.text, ...(outbound.idempotencyKey ? { idempotencyKey: outbound.idempotencyKey } : {}) });
             if (outbound.type === "template")
                 throw new Error("SMS has no templates");
             // Reactions, typing, read receipts and status do not exist on SMS.
@@ -159,6 +159,8 @@ 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;
@@ -268,6 +270,7 @@ export declare class Conversation {
     private send;
     /** A fixed-text scheduled message or a text or template nudge, sent with no model turn. */
     private sendDirect;
+    private directSettled;
     /**
      * The history the model is sent: all of it while it fits the budget, else the latest entries
      * that do, from the start of one (never between a call and its result), after a line that says

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();
@@ -443,7 +445,7 @@ export class Conversation {
         }
         else if (row.kind === "schedule") {
             if (p.fixed)
-                this.direct.push({ inbox: row.id, channel: p.channel, text: p.text, run: p.run });
+                this.direct.push({ inbox: row.id, channel: p.channel, text: p.text, run: p.run, schedule: p.schedule });
             else
                 this.notes.push({ text: p.text, inbox: row.id, owed: { run: p.run, mode: p.mode, channel: p.channel } });
         }
@@ -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);
@@ -573,8 +575,14 @@ export class Conversation {
             this.note(`[Chinwag] ${task.tool} (${task.taskId}) was still running in the background when the agent restarted. It may or may not have finished; check before telling them it is done.`);
             this.persist(() => store.removeTask(this.id, task.taskId));
         }
-        for (const row of await store.openInbox(this.id))
-            this.enqueue(row);
+        for (const row of await store.openInbox(this.id)) {
+            // Already in the history (its row was not marked done): answered, so not answered again.
+            const p = row.payload;
+            if (row.kind === "message" && this.messageIds.get(p.id) === p.channel)
+                this.persist(() => store.doneInbox([row.id]));
+            else
+                this.enqueue(row);
+        }
         const row = await store.conversation(this.id);
         this.resumeTurn = row?.turnOpen === true;
         if ((this.resumeTurn || this.hasWork()) && !this.running)
@@ -797,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))
@@ -1043,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) {
@@ -1136,6 +1147,12 @@ export class Conversation {
     }
     /** A fixed-text scheduled message or a text or template nudge, sent with no model turn. */
     async sendDirect(d) {
+        // Settled already (by an earlier process, or another one running beside this): never sent twice.
+        if (await this.directSettled(d)) {
+            if (d.inbox !== undefined)
+                this.persist(() => this.settings.store.doneInbox([d.inbox]));
+            return;
+        }
         const settle = (status, reason) => {
             this.settle(d, status, reason);
             this.flush([d]);
@@ -1163,7 +1180,10 @@ export class Conversation {
         }
         if (covered)
             return settle("dropped", `no-contact rule ${covered.id}: ${covered.rule}`);
-        const outbound = d.template ? { type: "template", ...d.template } : { type: "message", text: d.text ?? "" };
+        // 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 } : 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");
@@ -1195,6 +1215,18 @@ export class Conversation {
         this.settings.emit(this.id, "message.out", { text: d.text ?? d.template?.name, channel: d.channel, direct: true });
         settle("sent");
     }
+    async directSettled(d) {
+        const { store } = this.settings;
+        if (d.nudge) {
+            const status = (await store.nudge(d.nudge))?.status;
+            return status !== undefined && !["queued", "held", "scheduled"].includes(status);
+        }
+        if (d.run && d.schedule) {
+            const outcome = (await store.runs(d.schedule)).find((r) => r.id === d.run)?.outcome;
+            return outcome !== undefined && outcome !== "queued" && outcome !== "held";
+        }
+        return false;
+    }
     /**
      * The history the model is sent: all of it while it fits the budget, else the latest entries
      * that do, from the start of one (never between a call and its result), after a line that says