@flow-engineer/flow 0.0.1 → 0.2.1

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,43 @@
+// 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 Channel, 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[];
+  /** Channels that are connected, such as Telegram through Flow Messaging (main.ts adds them when .env has its key); one named whatsapp replaces the unconnected one. */
+  channels?: Channel[];
+  /** 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 = {}) {
+  const connected = options.channels ?? [];
+  const unconnected = [whatsapp(provider), sms(provider), customUI("web", provider)].filter((c) => !connected.some((k) => k.name === c.name));
+  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: [...unconnected, ...connected],
+    testPeople: [
+      { name: "Maria", phone: "+15555550101" },
+      { name: "Sam", phone: "+15555550102" },
+      { name: "Priya", phone: "+15555550103" },
+    ],
+    timeZone: "America/New_York",
+  });
+}

package/examples/cafe/src/channels.ts

@@ -0,0 +1,20 @@
+// Which Flow Messaging channels Pip is on: Telegram always, WhatsApp and iMessage when .env names
+// their sender (FLOW_MESSAGING_WHATSAPP_SENDER, FLOW_MESSAGING_IMESSAGE_SENDER).
+
+import type { flowMessaging } from "../../../flow-messaging/src/index.ts";
+
+type FlowMessaging = Pick<ReturnType<typeof flowMessaging>, "telegram" | "whatsapp" | "imessage">;
+
+export function flowChannels(fm: FlowMessaging, env: Record<string, string | undefined> = process.env) {
+  return [
+    fm.telegram(),
+    ...(env.FLOW_MESSAGING_WHATSAPP_SENDER ? [fm.whatsapp()] : []),
+    ...(env.FLOW_MESSAGING_IMESSAGE_SENDER ? [fm.imessage()] : []),
+  ];
+}
+
+/** The channels as the log line names them: "Telegram, WhatsApp, iMessage". */
+export function channelNames(channels: Array<{ name: string }>): string {
+  const label: Record<string, string> = { telegram: "Telegram", whatsapp: "WhatsApp", imessage: "iMessage" };
+  return channels.map((c) => label[c.name] ?? c.name).join(", ");
+}

package/examples/cafe/src/main.ts

@@ -0,0 +1,30 @@
+// Pip in the playground: `npm start`, then open the printed link and pick a test person. With
+// FLOW_MESSAGING_KEY in .env (`npx @flow-engineer/flow link` puts it there), Pip is on Telegram
+// too (and WhatsApp and iMessage when .env names their senders), through Flow Messaging's event
+// stream: an outbound connection, so no public URL or tunnel.
+
+import { flowMessaging } from "../../../flow-messaging/src/index.ts";
+import { simulators } from "../../../simulators/src/index.ts";
+import { buildAgent } from "./agent.ts";
+import { channelNames, flowChannels } from "./channels.ts";
+
+const play = simulators({ title: "Pip · Bean & Leaf" });
+const fm = process.env.FLOW_MESSAGING_KEY ? flowMessaging() : undefined;
+const channels = fm ? flowChannels(fm) : [];
+let agent: ReturnType<typeof buildAgent>;
+try {
+  agent = buildAgent({ events: [play.events], channels });
+} catch (error) {
+  console.error((error as Error).message); // such as no model key in .env
+  process.exit(1);
+}
+const port = Number(process.env.PORT ?? 8788);
+const { url } = await play.listen(agent, port);
+console.log(`Pip's playground: ${url}/`);
+console.log(`Every channel side by side: ${url}/person`);
+if (fm) {
+  // Events sent while Pip was not running come when it starts again (.flow/ keeps the last one handled).
+  const live = fm.start(agent, { cursorFile: ".flow/flow-messaging-cursor", port: port + 1 });
+  console.log(`On ${channelNames(channels)} through Flow Messaging (${live.mode}). The phone link: npx @flow-engineer/flow link`);
+  live.stopped.then((why) => console.error(`Flow Messaging stopped: ${why.message} Then: npx @flow-engineer/flow setup`));
+}

package/examples/cafe/src/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,191 @@
+# Flow Messaging channels
+
+Put a Flow Framework (`npm i @flow-engineer/flow`) agent on real WhatsApp, Telegram, iMessage 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 two ways to receive Flow's events: the live event
+stream, an outbound WebSocket that needs no public URL, and a webhook that checks Flow's
+signatures. It needs nothing beyond the framework (it uses `fetch`, Node's `WebSocket` and `node:crypto`).
+
+On a laptop, `npx @flow-engineer/flow link` signs in, writes `FLOW_MESSAGING_KEY` and the Telegram
+sender into `.env` and prints the link for your phone, so you can skip step 1 below.
+
+```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. iMessage lines, Flow's
+shared one included, are arranged with the Flow team.
+
+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 { 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 for a webhook)
+
+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.imessage(), fm.sms()],
+});
+await agent.resume();
+
+const live = fm.start(agent, { cursorFile: ".flow/flow-messaging-cursor" });
+live.stopped.then((why) => console.error(`Flow Messaging refused the stream: ${why.message}`));
+```
+
+That's it on a laptop: with no webhook secret, `fm.start` opens the event stream (`fm.stream(agent)`
+does only that).
+
+### The event stream
+
+`GET /v1/stream` is a WebSocket the agent opens to Flow, with the key offered as a subprotocol
+(Node's `WebSocket` cannot set headers). It asks only for the events the adapter handles and hands
+each, in log order, to the same handler as the webhook.
+
+- **Acknowledged once handled.** The stream has no ack frame for events; it resumes from `after`.
+  The adapter moves its cursor past an event only once the agent has taken it, so an event that
+  fails, or arrives as the socket drops, comes again.
+- **Reconnects.** A dropped socket, Flow's `reconnect` frame (it restarts, or a connection reaches
+  24 hours) and a failed event reconnect with `after` set to the last handled event: at once the
+  first time, then backing off to 30 s, or after Flow's `retry_after` (too many streams for the
+  key, Flow busy). An event that fails 5 times in a row is passed over, so it cannot hold up every
+  later one; it stays in Flow's log (`GET /v1/events`).
+- **Offline messages.** With `cursorFile`, the last handled event's ID is kept on disk, so after a
+  restart Flow replays everything that came while the agent was stopped, for as long as your plan
+  keeps events (30 days by default). Without it, a dropped stream still resumes, but a restart
+  starts from now. A cursor older than Flow's log starts again from now, and says so.
+- **Stops for good** on a refused key or request (close codes 4401, 4403, 4400): `stopped`
+  resolves with the code, type and Flow's message. `close()` ends the stream.
+- **Replies go over HTTP**, with their Idempotency-Keys, so they never wait for the stream.
+- The stream cannot send `Flow-Version`, so its events come in the version your app was pinned to.
+
+### Or a webhook
+
+Already have an HTTP server? Hand the raw body and headers to `fm.receive`, or serve `fm.webhook(agent)`
+(with a webhook secret set, `fm.start` serves it on `port`, default `PORT` else 8080):
+
+```ts
+const { status, body } = await fm.receive(agent, { body: rawBody, headers: req.headers });
+```
+
+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: use the event stream instead.
+
+## 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. Without it, `fm.start` uses the event stream. |
+| `FLOW_MESSAGING_TELEGRAM_SENDER`, `FLOW_MESSAGING_WHATSAPP_SENDER`, `FLOW_MESSAGING_IMESSAGE_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`, `imessage` and `sms`).
+
+## What it maps
+
+**Out (agent to person):**
+
+- Text: Markdown on Telegram, plain text on WhatsApp, iMessage 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. iMessage has none, so the agent is not offered them.
+- A link: one URL button (WhatsApp's call-to-action button); on iMessage, the URL on its own line.
+- 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 (tapbacks on iMessage), typing, and read receipts (WhatsApp, iMessage).
+- 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 (or by both the stream and a webhook) reaches the agent once. On the
+  webhook a failure answers 500, so Flow delivers the event again; on the stream it comes again on
+  the next connection.
+- `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, except the stream's
+`cursorFile`. 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 or iMessage channel kind yet, so both are custom channels. On iMessage
+a person is their phone number, or their email address when that is their handle; they are not joined
+with the same number on WhatsApp or SMS.
+
+**iMessage replies only.** On Flow's shared iMessage sender (as on WhatsApp after 24 hours) the agent
+can only answer someone who wrote first. A nudge or scheduled message to anyone else fails, and
+reaches the agent as "Not delivered" (`outside_window`). Ask people to write first with the line's
+opt-in link. Text takes up to 9999 characters; there are no buttons, lists or templates.
+
+## 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`, `IMESSAGE`: the Telegram and iMessage channels' limits, as framework `ChannelInfo`s.
+
+## Links
+
+- Flow Messaging: https://api.flow.engineer
+- API reference: https://api.flow.engineer/openapi.yaml
+- Flow Framework: https://www.npmjs.com/package/flow
+
+## License
+
+Apache-2.0, as the rest of this repository.

package/package.json

@@ -1,13 +1,68 @@
 {
   "name": "@flow-engineer/flow",
-  "version": "0.0.1",
-  "description": "Flow Framework (coming soon)",
-  "main": "index.js",
+  "version": "0.2.1",
+  "description": "An open-source runtime for chat agents that feel like a person texting back.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flow-engineer/flow.git"
+  },
+  "homepage": "https://github.com/flow-engineer/flow",
+  "type": "module",
+  "engines": {
+    "node": ">=22.18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./simulators": {
+      "types": "./dist/simulators/src/index.d.ts",
+      "default": "./dist/simulators/src/index.js"
+    },
+    "./flow-messaging": {
+      "types": "./dist/flow-messaging/src/index.d.ts",
+      "default": "./dist/flow-messaging/src/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/src/index.d.ts",
+      "default": "./dist/testing/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "flow": "dist/testing/src/cli.js",
+    "chinwag": "dist/testing/src/chinwag.js"
+  },
+  "files": [
+    "dist",
+    "examples/cafe/agent",
+    "examples/cafe/src",
+    "examples/cafe/tests",
+    "examples/http-agent",
+    "flow-messaging/README.md",
+    "docs/agents.md",
+    "coding-agents",
+    "spec",
+    "README.md",
+    "LICENSE"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json && node -e \"for (const f of ['page.html', 'person.html']) fs.copyFileSync('simulators/src/' + f, 'dist/simulators/src/' + f)\"",
+    "prepack": "npm run build",
+    "test": "node --test --test-timeout=30000 \"test/**/*.test.ts\"",
+    "test:changed": "node scripts/test-changed.ts",
+    "new": "node scripts/new-agent.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "openai": "^7.32.0",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5"
   },
-  "keywords": [],
-  "author": "",
-  "license": "ISC",
-  "type": "commonjs"
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "typescript": "^7.0.2"
+  }
 }