@flow-engineer/flow 0.0.0-stage → 0.2.0

package/dist/testing/src/suite.js

@@ -0,0 +1,198 @@
+// A test suite on disk: tests/scenarios/*.yaml and tests/tools/*.yaml, each file hashed by its
+// content so the cloud stores it once and a run records exactly which tests it ran.
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { extname, isAbsolute, join } from "node:path";
+import { isMap, isSeq, LineCounter, parseDocument } from "yaml";
+import { z } from "../../src/index.js";
+export function hashOf(content) {
+    return createHash("sha256").update(content).digest("hex");
+}
+/** Every scenario and tool file under `testsDir`, in a stable order. */
+export function loadSuite(testsDir) {
+    const files = [];
+    for (const folder of ["scenarios", "tools"]) {
+        const dir = join(testsDir, folder);
+        if (!existsSync(dir))
+            continue;
+        for (const name of readdirSync(dir).filter((n) => n.endsWith(".yaml")).sort()) {
+            const content = readFileSync(join(dir, name), "utf8");
+            files.push({ path: `${folder}/${name}`, hash: hashOf(content), content });
+        }
+    }
+    return files;
+}
+/** One hash for the whole suite: runs are compared only when it matches. */
+export function suiteHash(files) {
+    return hashOf(files.map((f) => `${f.path}:${f.hash}`).sort().join("\n"));
+}
+/** `{{ now [±<n>m|h|d|w]* [@ HH:MM] [| iso|date|time|weekday] }}`, spaces optional between the parts. */
+const CLOCK = /^\s*now(?:\s*[+-]\s*\d+[mhdw])*(?:\s*@\s*(?:[01]\d|2[0-3]):[0-5]\d)?(?:\s*\|\s*(?:iso|date|time|weekday))?\s*$/;
+/** What is wrong with the `{{ now ... }}` placeholders in `text`, or null. A placeholder is the test's clock
+ * (`{{now}}`, `{{now + 7d | date}}`, `{{now + 6d @ 10:00}}`), filled by the cloud per run; any other `{{...}}` is left alone. */
+export function placeholderProblem(text) {
+    for (const [whole, inner] of text.matchAll(/\{\{([\s\S]*?)\}\}/g)) {
+        if (/^\s*now\b/.test(inner) && !CLOCK.test(inner)) {
+            return `unknown placeholder ${whole}: write it like {{now + 3d}}, {{now - 2h | time}} or {{now + 1w @ 10:00 | date}}`;
+        }
+    }
+    return null;
+}
+/** Every string in `value` whose placeholders are wrong, with where it is under `value`. */
+function* placeholderProblems(value, path = []) {
+    if (typeof value === "string") {
+        const problem = placeholderProblem(value);
+        if (problem)
+            yield { path, problem };
+    }
+    else if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++)
+            yield* placeholderProblems(value[i], [...path, i]);
+    }
+    else if (value && typeof value === "object") {
+        for (const [key, item] of Object.entries(value))
+            yield* placeholderProblems(item, [...path, key]);
+    }
+}
+/** A value whose strings may hold placeholders, each checked. */
+const withClock = (schema) => schema.superRefine((value, ctx) => {
+    for (const { path, problem } of placeholderProblems(value))
+        ctx.addIssue({ code: "custom", message: problem, path });
+});
+/** A time zone Intl knows. */
+function isTimeZone(zone) {
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: zone });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** YYYY-MM-DDTHH:MM[:SS], optionally Z or ±HH:MM, naming a real moment. */
+function isDateTime(text) {
+    const m = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?(?:Z|[+-](\d{2}):(\d{2}))?$/.exec(text);
+    if (!m)
+        return false;
+    const [y, mo, d, h, mi, s = 0, oh = 0, om = 0] = m.slice(1).map((part) => (part === undefined ? undefined : Number(part)));
+    const day = new Date(Date.UTC(y, mo - 1, d));
+    return day.getUTCFullYear() === y && day.getUTCMonth() === mo - 1 && day.getUTCDate() === d && h < 24 && mi < 60 && s < 60 && oh < 24 && om < 60;
+}
+/** A tool call the run must (`calls`) or must not (`never`) make: a tool name, or the tool with input fields it must have. */
+const expectedCall = z.union([
+    z.string().min(1),
+    z.strictObject({
+        tool: z.string().min(1),
+        /** Each field must equal the call's input field: nested objects in part, arrays and strings exactly. */
+        args: withClock(z.record(z.string(), z.unknown())).optional(),
+    }),
+], { error: "a tool name, or { tool: <name>, args: { <field>: <value> } }" });
+const scenarioSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().optional(),
+    /** Every platform it runs on; each is a run of its own, with its own result. */
+    channels: z.array(z.enum(["sms", "whatsapp", "imessage", "telegram", "web"])).min(1),
+    /** The IANA time zone of the test's clock; UTC when left out. */
+    timezone: z.string().refine(isTimeZone, "not a time zone: use an IANA name such as America/New_York or UTC").optional(),
+    /** The test's clock when each run starts, local to `timezone` unless it has an offset; the real time when left out.
+     * YAML's default schema reads it as a string; a Date from another schema is taken as its UTC time. */
+    now: z
+        .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({
+        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),
+    world: withClock(z.string()).optional(),
+    max_turns: z.number().int().min(1).max(50).default(8),
+    expect: z
+        .object({
+        outcome: z.array(withClock(z.string())).optional(),
+        judge: z.array(withClock(z.string())).optional(),
+        /** Each must be called at least once in the run; checked by code from the recorded calls. */
+        calls: z.array(expectedCall).optional(),
+        /** None may be called. */
+        never: z.array(expectedCall).optional(),
+    })
+        .default({}),
+});
+const toolFileSchema = z.object({
+    tool: z.string().min(1),
+    behaviour: z.string().optional(),
+    responses: z
+        .array(z.object({
+        when: z.string(),
+        latency_ms: z.number().int().min(0),
+        input: withClock(z.unknown()).optional(),
+        output: withClock(z.unknown()).optional(),
+        error: withClock(z.string()).optional(),
+    }))
+        .min(1),
+});
+/** A relative path that stays inside the tests folder. */
+function inTests(path) {
+    return !!path && !isAbsolute(path) && !path.split(/[\\/]/).includes("..");
+}
+/** The type of a file a scenario attaches, from its extension. */
+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";
+}
+/** 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);
+}
+export function parseToolFile(file) {
+    return parseFile(toolFileSchema, file);
+}
+function parseFile(schema, file) {
+    const lines = new LineCounter();
+    const doc = parseDocument(file.content, { lineCounter: lines });
+    const at = (offset) => `${file.path}:${offset === undefined ? 1 : lines.linePos(offset).line}`;
+    if (doc.errors.length) {
+        // The YAML parser's own message ends with where it is and a drawing of the line; the prefix says where.
+        throw new Error(doc.errors.map((e) => `${at(e.pos[0])}: ${e.message.split("\n")[0].replace(/ at line \d+, column \d+:?$/, "")}`).join("\n"));
+    }
+    const result = schema.safeParse(doc.toJS());
+    if (result.success)
+        return result.data;
+    throw new Error(result.error.issues.map((issue) => {
+        const field = issue.path.map((key, i) => (typeof key === "number" ? `[${key}]` : `${i ? "." : ""}${String(key)}`)).join("");
+        const what = /received undefined$/.test(issue.message) ? "missing" : issue.message;
+        return `${at(offsetOf(doc.contents, issue.path))}: ${field ? `${field}: ` : ""}${what}`;
+    }).join("\n"));
+}
+/** Where the deepest part of `path` that the file has starts: the value, or for a missing key the key that holds it. */
+function offsetOf(root, path) {
+    let node = root;
+    let offset = root?.range?.[0];
+    let holder;
+    for (const key of path) {
+        if (isMap(node)) {
+            const pair = node.items.find((p) => p.key?.value === key);
+            if (!pair)
+                return holder ?? offset;
+            holder = pair.key.range?.[0];
+            node = pair.value;
+        }
+        else if (isSeq(node) && typeof key === "number" && node.items[key]) {
+            holder = undefined;
+            node = node.items[key];
+        }
+        else
+            break;
+        offset = node?.range?.[0] ?? offset;
+    }
+    return offset;
+}

package/examples/cafe/agent/AGENTS.md

@@ -0,0 +1,10 @@
+# Pip
+
+You are Pip, the ordering assistant for Bean & Leaf, a small café. People text you to order drinks and food for pickup, ask what's on the menu, and check on their order.
+
+- Use get_menu for anything about items, sizes, milks or prices; never guess a price.
+- Before placing an order, read it back once with the total and ask them to confirm. Place it with place_order only after they say yes.
+- When the order is placed, tell them the order number and when it will be ready.
+- Keep messages short and friendly, like a barista texting.
+- Anything about allergies or dietary needs: load the allergens skill first.
+- You can't take payment by text; they pay at pickup.

package/examples/cafe/agent/skills/allergens/SKILL.md

@@ -0,0 +1,7 @@
+---
+name: allergens
+description: questions about allergies, dairy, nuts, gluten or other dietary needs
+---
+- Answer only from the allergens listed for each item in get_menu; if an item lists none, say you're not sure and suggest asking the barista at pickup.
+- Oat and almond milk are made in the same area as dairy: say so to anyone with a severe dairy allergy.
+- Never say an item is "safe" for an allergy; say what it contains and what it's made near.

package/examples/cafe/src/agent.ts

@@ -0,0 +1,39 @@
+// Builds Pip. The playground (main.ts) and the tests build it the same way; tests pass their own
+// model, events and (simulated) tools.
+
+import { fileURLToPath } from "node:url";
+import { createAgent, customUI, openAICompatible, sms, whatsapp, type AgentOptions, type EventSink, type Model, type Tool } from "../../../src/index.ts";
+import { tools as cafeTools } from "./tools.ts";
+
+export interface BuildOptions {
+  model?: Model;
+  events?: EventSink[];
+  tools?: Tool[];
+  /** Where Pip runs, for a host with no file system (Cloudflare): its files as text, its database, no schedule timer. */
+  host?: Pick<AgentOptions, "files" | "database" | "scheduleCheckMs">;
+}
+
+export const tools = cafeTools;
+
+// The café's numbers and web chat are not connected yet, so every provider refuses to send. Test
+// people write from the playground, and replies to them go back there, never through these.
+const notConnected = async () => {
+  throw new Error("not connected yet: only test people in the playground reach Pip for now");
+};
+const provider = { sendMessage: notConnected, react: notConnected, typing: notConnected, markRead: notConnected, status: notConnected };
+
+export function buildAgent(options: BuildOptions = {}) {
+  return createAgent({
+    ...(options.host ?? { dir: fileURLToPath(new URL("../agent", import.meta.url)) }),
+    model: options.model ?? openAICompatible({ model: process.env.CAFE_MODEL }),
+    tools: options.tools ?? cafeTools,
+    events: options.events ?? [],
+    channels: [whatsapp(provider), sms(provider), customUI("web", provider)],
+    testPeople: [
+      { name: "Maria", phone: "+15555550101" },
+      { name: "Sam", phone: "+15555550102" },
+      { name: "Priya", phone: "+15555550103" },
+    ],
+    timeZone: "America/New_York",
+  });
+}

package/examples/cafe/src/main.ts

@@ -0,0 +1,16 @@
+// Pip in the playground: `npm start`, then open the printed link and pick a test person.
+
+import { simulators } from "../../../simulators/src/index.ts";
+import { buildAgent } from "./agent.ts";
+
+const play = simulators({ title: "Pip · Bean & Leaf" });
+let agent: ReturnType<typeof buildAgent>;
+try {
+  agent = buildAgent({ events: [play.events] });
+} catch (error) {
+  console.error((error as Error).message); // such as no model key in .env
+  process.exit(1);
+}
+const { url } = await play.listen(agent, Number(process.env.PORT ?? 8788));
+console.log(`Pip's playground: ${url}/`);
+console.log(`Every channel side by side: ${url}/person`);

package/examples/cafe/src/tools.ts

@@ -0,0 +1,62 @@
+// Pip's tools, over a tiny in-memory café. Placing an order is slow on purpose (a real point-of-sale
+// takes seconds), so it shows a tool moving to the background.
+
+import { tool, z } from "../../../src/index.ts";
+
+const MENU = [
+  { item: "Latte", sizes: { small: 4.0, large: 4.8 }, milks: ["whole", "oat", "almond"], allergens: ["dairy (unless plant milk)"] },
+  { item: "Flat white", sizes: { small: 4.2 }, milks: ["whole", "oat"], allergens: ["dairy (unless oat)"] },
+  { item: "Cold brew", sizes: { small: 4.5, large: 5.2 }, milks: [], allergens: [] },
+  { item: "Chai", sizes: { small: 4.0, large: 4.6 }, milks: ["whole", "oat"], allergens: ["dairy (unless oat)"] },
+  { item: "Almond croissant", sizes: { one: 4.25 }, milks: [], allergens: ["gluten", "nuts", "dairy", "egg"] },
+  { item: "Banana bread", sizes: { slice: 3.75 }, milks: [], allergens: ["gluten", "egg", "walnuts"] },
+];
+
+let nextOrder = 1040;
+const orders = new Map<string, { items: unknown; readyBy: string }>();
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export const tools = [
+  tool({
+    name: "get_menu",
+    description: "The full menu: items, sizes with prices in USD, milk options and allergens.",
+    input: z.object({}),
+    run: async () => {
+      await wait(150);
+      return { menu: MENU, note: "This is the whole menu." };
+    },
+  }),
+  tool({
+    name: "place_order",
+    description: "Place a confirmed pickup order. Returns the order number and when it will be ready.",
+    input: z.object({
+      name: z.string().describe("The name for the order"),
+      items: z.array(
+        z.object({
+          item: z.string(),
+          size: z.string(),
+          milk: z.string().optional(),
+          quantity: z.number().int().min(1).max(20).default(1),
+        }),
+      ),
+    }),
+    run: async ({ items }) => {
+      await wait(5_000);
+      const id = `BL-${nextOrder++}`;
+      const readyBy = new Date(Date.now() + 10 * 60_000).toISOString();
+      orders.set(id, { items, readyBy });
+      return { order_id: id, ready_by: readyBy, pay_at_pickup: true };
+    },
+  }),
+  tool({
+    name: "order_status",
+    description: "Where an order is: received, being made, or ready.",
+    input: z.object({ order_id: z.string() }),
+    run: async ({ order_id }) => {
+      await wait(200);
+      const order = orders.get(order_id);
+      if (!order) return { found: false };
+      return { found: true, status: Date.now() > Date.parse(order.readyBy) ? "ready" : "being made", ready_by: order.readyBy };
+    },
+  }),
+];

package/examples/cafe/tests/scenarios/latte-correction.yaml

@@ -0,0 +1,30 @@
+# A spec: one situation to put the agent in, and what has to be true at the end.
+id: latte-correction
+title: Orders a latte, corrects the milk mid-thought, confirms
+channels: [whatsapp]         # each platform it runs on, with that simulator's rules
+
+person:                      # played by a model that sees only what a person would see
+  persona: Sam, in a hurry on the way to work; types in short bursts, no capitals.
+  goal: Get a large oat latte for pickup, under the name Sam.
+  knows:                     # told only if the agent asks
+    - Their name is Sam.
+
+opening:                     # the first messages, sent exactly like this; then the person plays on
+  - say: "can i get a large latte"
+  - say: "oat milk actually"
+    after_ms: 1200
+
+world: |                     # what is true in this test; the tool simulator plays the tools from it
+  The menu is as in tests/tools/get_menu.yaml. Oat milk is in stock. The café is busy this
+  morning, so the point of sale is slow to take orders, but they go through.
+
+max_turns: 8
+
+expect:
+  outcome:                   # judged against what the tools did (the simulator's log)
+    - Exactly one order is placed, for one large latte with oat milk, under the name Sam.
+  judge:                     # read by the judge from the transcript, each pass or fail with a reason
+    - The order read back to Sam uses oat milk, not whole milk.
+    - The agent asks Sam to confirm before placing the order.
+    - Sam is told the order number and when it will be ready.
+    - Prices match the menu.

package/examples/cafe/tests/scenarios/order-fails.yaml

@@ -0,0 +1,26 @@
+id: order-fails
+title: The point of sale is down when the order is placed
+channels: [sms]
+
+person:
+  persona: Jo, polite, a regular; writes full sentences.
+  goal: Order a small cold brew for pickup under the name Jo.
+  knows:
+    - Their name is Jo.
+
+opening:
+  - say: "Hi, could I order a small cold brew for pickup please? Name's Jo."
+
+world: |
+  The menu is as in tests/tools/get_menu.yaml. The café's point of sale is down this morning and
+  stays down for the whole conversation.
+
+max_turns: 6
+
+expect:
+  outcome:
+    - No order is placed.
+  judge:
+    - Jo is told plainly that the order could not go through, without technical detail.
+    - The agent does not claim the order was placed.
+    - Jo is offered a way forward (try again shortly, or order at the counter).

package/examples/cafe/tests/tools/get_menu.yaml

@@ -0,0 +1,14 @@
+tool: get_menu
+behaviour: |
+  Returns the whole menu every time. If the scenario's world says what is on the menu, answer
+  with that; otherwise use the menu below.
+responses:
+  - when: Always
+    latency_ms: 150
+    input: {}
+    output:
+      menu:
+        - { item: Latte, sizes: { small: 4.0, large: 4.8 }, milks: [whole, oat, almond], allergens: ["dairy (unless plant milk)"] }
+        - { item: Cold brew, sizes: { small: 4.5, large: 5.2 }, milks: [], allergens: [] }
+        - { item: Almond croissant, sizes: { one: 4.25 }, milks: [], allergens: [gluten, nuts, dairy, egg] }
+      note: This is the whole menu.

package/examples/cafe/tests/tools/place_order.yaml

@@ -0,0 +1,29 @@
+# Everything place_order can do, for the tool simulator. During a test no real tool runs: a model
+# plays the tool. On each call it reads the scenario's world and picks the response (and how long
+# the call takes) that fits, from the kinds below. Scenarios never set responses or latencies;
+# they describe the situation ("the point of sale is slow this morning") and the simulator plays
+# it, possibly differently on each call, as a real system would.
+#
+#   behaviour    what the tool does, in plain words, beyond its description
+#   responses    the kinds of response it gives, each with an example and how long it takes
+#                (recorded from real calls once observability records them; by hand until then)
+tool: place_order
+behaviour: |
+  Order numbers are BL- followed by four digits and go up by one per order. ready_by is about
+  ten minutes after the order is placed. Fails if an item, size or milk is not on the menu.
+responses:
+  - when: The order goes through (usual)
+    latency_ms: 4800
+    input:
+      name: Sam
+      items: [{ item: Latte, size: large, milk: oat, quantity: 1 }]
+    output: { order_id: BL-1040, ready_by: "{{now + 10m}}", pay_at_pickup: true }
+  - when: The point of sale is busy; the order still goes through
+    latency_ms: 11000
+    output: { order_id: BL-1041, ready_by: "{{now + 15m}}", pay_at_pickup: true }
+  - when: The point of sale is down
+    latency_ms: 3000
+    error: Point of sale unavailable
+  - when: Something in the order is not on the menu
+    latency_ms: 600
+    error: "Unknown item: Matcha latte"

package/examples/http-agent/server.mjs

@@ -0,0 +1,32 @@
+// An agent you already have, wrapped for `flow test --agent-url`: one POST per message from the
+// person, answered with the replies to send. No dependencies. Put your own agent where reply() is.
+//
+//   node server.mjs                 listens on http://localhost:3000/flow (PORT to change it)
+//   npx @flow-engineer/flow test --agent-url http://localhost:3000/flow      from this folder, in another terminal
+
+import { createServer } from "node:http";
+
+/** Each conversation's messages, as your agent keeps them per phone number. */
+const histories = new Map();
+
+/** Your agent's turn: the person's message in, the replies out. Its tools run here, for real. */
+async function reply(conversationId, channel, message) {
+  const history = histories.get(conversationId) ?? [];
+  histories.set(conversationId, history);
+  history.push({ from: "person", text: message.text });
+  const text = history.length === 1 ? "Hi! We're open 8am to 6pm every day. Can I help with anything else?" : "Happy to help. Have a good day!";
+  history.push({ from: "agent", text });
+  return [{ type: "message", text }];
+}
+
+createServer(async (req, res) => {
+  if (req.method !== "POST" || req.url !== "/flow") return res.writeHead(404).end();
+  // Set FLOW_FRAMEWORK_AGENT_TOKEN on both sides to require it.
+  const token = process.env.FLOW_FRAMEWORK_AGENT_TOKEN ?? process.env.CHINWAG_AGENT_TOKEN;
+  if (token && req.headers.authorization !== `Bearer ${token}`) return res.writeHead(401).end();
+  let body = "";
+  for await (const chunk of req) body += chunk;
+  const { conversationId, channel, message } = JSON.parse(body);
+  const replies = await reply(conversationId, channel, message);
+  res.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ replies }));
+}).listen(Number(process.env.PORT ?? 3000), () => console.log(`Listening on http://localhost:${process.env.PORT ?? 3000}/flow`));

package/examples/http-agent/tests/scenarios/opening-hours.yaml

@@ -0,0 +1,16 @@
+id: opening-hours
+title: Asks when the shop is open
+channels: [whatsapp]
+
+person:
+  persona: Alex, friendly, writes short messages.
+  goal: Find out when the shop is open today.
+
+opening:
+  - say: "hi, what time are you open today?"
+
+max_turns: 4
+
+expect:
+  judge:
+    - Alex is told the opening hours.

package/flow-messaging/README.md

@@ -0,0 +1,152 @@
+# Flow Messaging channels
+
+Put a Flow Framework (`npm i @flow-engineer/flow`) agent on real WhatsApp, Telegram and US SMS
+through [Flow Messaging](https://api.flow.engineer) (API version 2026-11-01). `@flow-engineer/flow/flow-messaging` gives you
+channels that send through Flow's senders, and a webhook that checks Flow's signed events and hands
+them to the agent. It needs nothing beyond the framework (it uses `fetch` and `node:crypto`).
+
+```sh
+npm install @flow-engineer/flow
+```
+
+Node 22.18 or later. The adapter ships inside `@flow-engineer/flow`; import it from `@flow-engineer/flow/flow-messaging`.
+
+## Quick start
+
+### 1. Get a key
+
+Ask the API for a test key. You don't need an account:
+
+```sh
+curl -X POST https://api.flow.engineer/v1/sandbox/keys
+```
+
+The answer holds your test key (`key`, `fk_test_...`, shown once) and the sandbox senders (`senders`).
+Each sender has an ID (`snd_...`), a link to open on your phone, and a join code to send it.
+
+The sandbox has Telegram today. WhatsApp and iMessage come as they open. A sandbox key lasts 7 days
+and covers one contact. Live keys (`fk_live_...`) and your own WhatsApp, Telegram or
+SMS senders are set up from the dashboard at https://api.flow.engineer.
+
+Open the Telegram sandbox sender's link on your phone and send its join code. You are now the
+sandbox contact your agent can talk to.
+
+### 2. Run the agent
+
+```ts
+// main.ts
+import { createServer } from "node:http";
+import { createAgent } from "@flow-engineer/flow";
+import { flowMessaging } from "@flow-engineer/flow/flow-messaging";
+
+const fm = flowMessaging(); // reads FLOW_MESSAGING_KEY and FLOW_MESSAGING_WEBHOOK_SECRET
+
+const agent = createAgent({
+  dir: "./agent", // your agent's folder (AGENTS.md, ...)
+  model: yourModel,
+  // only the channels you have senders for
+  channels: [fm.telegram(), fm.whatsapp(), fm.sms()],
+});
+await agent.resume();
+
+createServer(fm.webhook(agent)).listen(Number(process.env.PORT ?? 8080));
+```
+
+Already have an HTTP server? Hand the raw body and headers to `fm.receive` instead:
+
+```ts
+const { status, body } = await fm.receive(agent, { body: rawBody, headers: req.headers });
+```
+
+### 3. Point Flow's webhook at it
+
+Flow posts events to a public HTTPS URL. Create a webhook endpoint for it:
+
+```sh
+curl https://api.flow.engineer/v1/webhook_endpoints \
+  -H "Authorization: Bearer $FLOW_MESSAGING_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://your-agent.example.com/", "events": ["message.received", "message.failed", "reaction.added", "contact.deleted"]}'
+```
+
+The answer holds the signing secret (`secret`, `whsec_...`), shown once. Save it as
+`FLOW_MESSAGING_WEBHOOK_SECRET`.
+
+On a laptop there is no public URL. Run a tunnel to the port (for example
+`cloudflared tunnel --url http://localhost:8080`) and register that URL.
+
+## Environment
+
+| Variable | What it is |
+|---|---|
+| `FLOW_MESSAGING_KEY` | Your app's API key, `fk_test_...` or `fk_live_...`. Keep it on your server. |
+| `FLOW_MESSAGING_WEBHOOK_SECRET` | The webhook endpoint's signing secret, `whsec_...`. While you rotate it, give both, comma-separated. |
+| `FLOW_MESSAGING_TELEGRAM_SENDER`, `FLOW_MESSAGING_WHATSAPP_SENDER`, `FLOW_MESSAGING_SMS_SENDER` | Each channel's sender, `snd_...`. Needed to start conversations (nudges, templates) and to tell senders apart. Replies to people who wrote first work without it. |
+| `FLOW_MESSAGING_BASE_URL` | Optional. Default `https://api.flow.engineer`. |
+
+Each of these can also be passed in code: `flowMessaging({ apiKey, webhookSecret, baseUrl })`, and
+`fm.telegram({ sender, name, instructions })` (the same for `whatsapp` and `sms`).
+
+## What it maps
+
+**Out (agent to person):**
+
+- Text: Markdown on Telegram, plain text on WhatsApp and SMS.
+- Reply buttons and lists, sent as Flow `buttons`. WhatsApp shows up to 3 reply buttons, or a list
+  for 4 to 10. Telegram shows an inline keyboard.
+- A link: one URL button (WhatsApp's call-to-action button).
+- A photo: a media message with the text as its caption. Flow's button messages have no image
+  header, so a photo with buttons or a link goes just before them.
+- Quotes (`reply_to`), reactions, typing, and read receipts (WhatsApp).
+- WhatsApp templates, by name or `tpl_` ID, with their header (text, or media by URL or file ID),
+  body values (`{{1}}`, `{{2}}`, ...) and button values (URL suffixes, quick-reply payloads).
+
+**In (person to agent):**
+
+- Text.
+- Taps on buttons, list rows and template quick replies, as a choice. A quick reply's payload is
+  its ID.
+- Quotes, read from Flow.
+- Reactions to the agent's messages.
+- Late failures (`message.failed`), told to the agent as "Not delivered".
+- Photos, voice notes, audio and documents, as attachments. Their bytes are fetched from
+  `GET /v1/files/{id}` only when the agent can use them. A voice note Flow already transcribed
+  arrives as its transcript.
+- A video, a file Flow did not keep, a location or a contact card arrives as a note in the text.
+
+## 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.
+- 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".
+- Signatures are checked: HMAC-SHA256, five minutes' tolerance, and any of the secrets you gave.
+- An event Flow delivers twice reaches the agent once. A failure answers 500, so Flow delivers the
+  event again.
+- `contact.deleted` makes it forget the contact.
+- Keys and message text are never logged.
+
+What it remembers (conversations, contacts, event IDs) is kept in memory. After a restart, the
+first send to someone starts from the channel's sender, and Flow puts it into the open conversation
+if there is one.
+
+The framework has no Telegram channel kind yet, so Telegram is a custom channel. iMessage is not in this
+package yet.
+
+## Also exported
+
+- `verifySignature(body, header, secrets)`: checks a `Flow-Signature` header yourself.
+- `FlowMessagingError`: the API's typed error (`status`, `type`, `channelCode`, `retryAfter`).
+- `API_VERSION`: the API version every request asks for, `2026-11-01`.
+- `TELEGRAM`: the Telegram channel's limits, as a framework `ChannelInfo`.
+
+## Links
+
+- Flow Messaging: https://api.flow.engineer
+- API reference: https://api.flow.engineer/openapi.yaml
+- Flow Framework: https://www.npmjs.com/package/flow
+
+## License
+
+MIT, as the rest of this repository.