@flow-engineer/flow 0.2.0 → 0.2.2

package/dist/testing/src/plugin.js

@@ -0,0 +1,116 @@
+// Plugin packages generated from an agent's skills. The two native formats deliver skills once:
+// both point at the tools-only MCP endpoint. Teams can edit manifests and add files alongside them.
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { CHAT_ONLY } from "../../mcp/src/describe.js";
+import { loadSkills, readAgentFolder } from "../../src/skills.js";
+export const PLUGIN_LINE = "  flow plugin --server <url> --out <dir>  Write Claude Code and Agent Plugins packages";
+const STAMP = ".chinwag-skills.json";
+function skillFiles(dir) {
+    const files = {};
+    const root = join(dir, "agent");
+    function visit(path) {
+        for (const entry of readdirSync(join(root, path), { withFileTypes: true })) {
+            const child = `${path}/${entry.name}`;
+            if (entry.isSymbolicLink())
+                throw new Error(`Plugin skills cannot copy a symlink: ${child}`);
+            if (entry.isDirectory())
+                visit(child);
+            else if (entry.isFile())
+                files[child] = readFileSync(join(root, child));
+        }
+    }
+    if (existsSync(join(root, "skills")))
+        visit("skills");
+    return files;
+}
+/** Hashes source bytes, rather than mtimes: a checkout cannot make an old plugin look current. */
+function hashes(files) {
+    return Object.fromEntries(Object.entries(files).sort(([a], [b]) => a.localeCompare(b)).map(([p, body]) => [p, createHash("sha256").update(body).digest("hex")]));
+}
+export function pluginProblems(dir, out) {
+    const expected = hashes(skillFiles(dir));
+    try {
+        const recorded = JSON.parse(readFileSync(join(out, STAMP), "utf8"));
+        if (JSON.stringify(recorded) !== JSON.stringify(expected))
+            return ["plugin skills are stale; run flow plugin again"];
+        for (const format of ["claude", "agent-plugins"]) {
+            if (JSON.stringify(hashes(Object.fromEntries(Object.keys(expected).map((p) => [p, readFileSync(join(out, format, p))])))) !== JSON.stringify(expected)) {
+                return [`${format} plugin skills differ from agent/skills; run flow plugin again`];
+            }
+        }
+        return [];
+    }
+    catch {
+        return ["plugin skills are missing or unreadable; run flow plugin again"];
+    }
+}
+export function writePlugins(dir, server, out, name) {
+    const pkg = existsSync(join(dir, "package.json")) ? JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) : {};
+    const pluginName = name ?? String(pkg.name ?? "agent").replace(/^@[^/]+\//, "");
+    if (!/^(?!.*(?:--|\.\.))[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/.test(pluginName) || pluginName.length > 64)
+        throw new Error("Give --name a plugin name: lowercase letters, numbers, dots and hyphens, up to 64 characters.");
+    const url = new URL(server);
+    if (url.username || url.password || url.search || url.hash)
+        throw new Error("The server URL must not contain credentials, a query or a fragment.");
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)))
+        throw new Error("Use https for remote servers, or http on localhost.");
+    url.pathname = `${url.pathname.replace(/\/+$/, "")}${url.pathname.replace(/\/+$/, "").endsWith("/plugin") ? "" : "/plugin"}`;
+    const files = skillFiles(dir);
+    for (const skill of loadSkills(readAgentFolder(join(dir, "agent")))) {
+        const named = CHAT_ONLY.exec(skill.body);
+        if (named)
+            throw new Error(`skill ${skill.name}: names ${named[1]}, which the plugin's MCP server does not have`);
+    }
+    const manifest = { name: pluginName, ...(pkg.version ? { version: pkg.version } : {}), ...(pkg.description ? { description: pkg.description } : {}) };
+    const json = (path, value) => write(path, `${JSON.stringify(value, null, 2)}\n`);
+    function write(path, body) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, body);
+    }
+    // Remove only files this generator previously owned, so deleted source skills do not linger.
+    let previous = {};
+    if (existsSync(join(out, STAMP)))
+        previous = JSON.parse(readFileSync(join(out, STAMP), "utf8"));
+    for (const path of Object.keys(previous)) {
+        if (!path.startsWith("skills/") || path.split("/").includes(".."))
+            throw new Error("Invalid plugin skills stamp");
+        if (!(path in files))
+            for (const format of ["claude", "agent-plugins"])
+                rmSync(join(out, format, path), { force: true });
+    }
+    for (const format of ["claude", "agent-plugins"]) {
+        const root = join(out, format);
+        for (const [path, body] of Object.entries(files))
+            write(join(root, path), body);
+        if (format === "claude") {
+            json(join(root, ".claude-plugin/plugin.json"), manifest);
+            json(join(root, ".mcp.json"), { mcpServers: { [pluginName]: { type: "http", url: url.href } } });
+        }
+        else {
+            json(join(root, "plugin.json"), { $schema: "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", ...manifest });
+            json(join(root, "mcp.json"), { $schema: "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", mcpServers: { [pluginName]: { type: "streamable-http", url: url.href } } });
+        }
+    }
+    json(join(out, STAMP), hashes(files));
+}
+export function pluginCli(argv, dir = process.cwd()) {
+    try {
+        const { values } = parseArgs({ args: argv, options: { server: { type: "string" }, out: { type: "string" }, name: { type: "string" }, help: { type: "boolean", short: "h" } } });
+        if (values.help) {
+            console.log(PLUGIN_LINE.trim());
+            return 0;
+        }
+        if (!values.server || !values.out)
+            throw new Error(PLUGIN_LINE.trim());
+        writePlugins(dir, values.server, resolve(dir, values.out), values.name);
+        console.log(`Wrote ${values.out}/claude and ${values.out}/agent-plugins. Check: flow check --plugin ${values.out}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(error.message);
+        return 1;
+    }
+}

package/docs/agents.md

@@ -0,0 +1,160 @@
+# Flow Framework for coding agents
+
+This guide is at https://flow.engineer/flow-framework/agents.md: that is the link to give.
+
+You are building or changing a chat agent for a person (the owner) so they can text it from their
+phone while it runs on their laptop. No tunnel, no public URL, and no key the owner copies by hand.
+Every command here runs without a terminal and never reads stdin, except `chat`, which reads the
+messages you pipe to it.
+
+Always name the package: `npx @flow-engineer/flow ...`. `npx flow` on its own fetches another npm
+package.
+
+## The flow
+
+```sh
+npx @flow-engineer/flow init --display-name "FlatX agent"   # the starter in this (empty) folder; ask the owner what to call it first
+npm install
+npx @flow-engineer/flow link --json                 # signs in and sets up if needed (the keys, Flow's trial model key among them), then prints the phone link
+npm start                                           # keep it running: the playground link it prints, and the phone link reaches it
+npx @flow-engineer/flow status --json               # any time: what the folder has and lacks
+printf 'hi\nA latte please\n' | npx @flow-engineer/flow chat   # your own check: talk to it locally, one message per line
+```
+
+Before `init` (or `flow new <folder>`), ask the owner what people should call their agent, such as
+"FlatX agent", and pass it as `--display-name`. It is kept as `displayName` in `package.json`, and
+the message their phone sends to reach the agent is `Hi FlatX agent (ref <code>)`; change it there
+any time. Without the flag, `init` asks in a terminal and otherwise uses the folder's name in words.
+
+## How the owner tests it
+
+When the owner asks how to test the agent, recommend these, in this order:
+
+1. **The playground in the browser**: `npm start`, then open the link it prints. The test people
+   (`testPeople`; Maria, Sam and Priya in the starter) and the channels are side by side, and
+   **Debug** shows each tool call and how fast each message was answered.
+2. **Their phone**: the link from `link` (`say_to_person` in `link --json`), while `npm start` runs.
+   It is the channel's own link (`url`): `https://t.me/<bot>?start=<code>` (press Start),
+   `https://wa.me/<number>?text=...` or, for iMessage, `sms:<number>?&body=...` (an iPhone or a Mac),
+   each with `Hi <displayName> (ref <code>)` filled in (`join_message`). `page` is the same on
+   flow.engineer, for a computer without that app.
+
+`flow chat` and `npm test -- --synthetic` (the test cloud) are for you, to check your own work
+before you hand it back; run them yourself, and do not offer them to the owner as ways to test.
+
+- The model key: a provider key is optional. `setup` (which `link` runs; alone it needs `login`
+  first) writes `FLOW_KEY`, the agent's one Flow key, into `.env` (printed only as its prefix and
+  last 4, `FLOW_KEY=flow_test_…abcd  added`; never read or print its value): with no provider key
+  the agent calls models through Flow with it, on the account's $2 of Flow trial credit (printed as
+  `Model: Flow trial credit ($1.87 left)`). The owner may add their own: one of `OPENROUTER_API_KEY`,
+  `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` or `GEMINI_API_KEY` in `.env` wins over `FLOW_KEY` for the model
+  (to switch back, empty that line), and a key they set is never written over. When the credit is
+  used up, a model call fails with code `trial_credit_used` (`trial_credit_unavailable` when the account gets none) and the next step: add your own key. With no key, `chat` and `npm start` stop with one sentence and
+  `Next: run npx @flow-engineer/flow setup to get Flow's free trial credit, or add your own key.`
+  (`chat --json`: `{"error":{"code":"no_model_key","message":...,"next":"npx @flow-engineer/flow setup"}}`),
+  and `init`, `setup`, `link` and `status` say so too, with the way to get one first in `next`.
+  Each folder's `setup` makes its own `FLOW_KEY` (the credit is the account's);
+  `setup --rotate key` replaces a leaked one (the old one works 24 h more; `--now` ends it at once).
+- `status` reports `FLOW_KEY` and the model key (never their values; `flow_key.set` in `--json`; with
+  `FLOW_KEY` the model's key, the credit left from Flow, `model_key.flow_credit`; a key Flow does not
+  know gets `setup --rotate key`), the sign-in, each channel's sender in `.env`
+  and, signed in, which channels are open now with their trial counts. It writes nothing.
+- `chat` builds the agent from `src/agent.ts` and writes as its first test person. Each reply is
+  printed (`agent: ...`) once the turn is over; `--json` gives one JSON line per thing it sends.
+- `link` does the rest when the folder is not set up (no `FLOW_FRAMEWORK_JOIN_CODE` or
+  `FLOW_MESSAGING_KEY` in `.env`, or no sender for the WhatsApp or iMessage link asked for): it
+  runs `login` (opens the owner's browser itself and prints the link and code at once), then
+  `setup` (writes the keys and each open channel's sender into `.env`), then prints the link.
+  `--channel telegram|whatsapp|imessage` picks the channel (Telegram by default). Run it in the
+  agent's folder: `setup` and `link` refuse a folder with no `package.json` (`not_an_agent_folder`).
+- A channel that is not open yet is said once ("iMessage isn't open yet; here are your Telegram
+  and WhatsApp links"), with the open channels' links, and exits 0: `link --json` then has
+  `not_open` (the channel asked for), `links` (each open channel's) and `url`/`channel` for the
+  first of them. Only when no channel is open does it exit 3 (`channel_not_open`).
+- On WhatsApp and iMessage the agent can only reply after the owner writes first (WhatsApp: within
+  24 hours of their last message); it cannot message them first. `link --json` says so
+  (`reply_only: true`, and in `say_to_person`): tell the owner.
+- The starter's `npm start` is on Telegram, plus WhatsApp and iMessage when `.env` has their senders
+  (`FLOW_MESSAGING_WHATSAPP_SENDER`, `FLOW_MESSAGING_IMESSAGE_SENDER`), and reads `.env` once. When
+  `setup` or `link` adds a channel (or the model key) it says so: "If npm start is running, restart
+  it to add iMessage."
+- Give the owner `say_to_person` from `link --json`, and the sign-in link and code from the
+  `pending` line while you wait.
+- `npm start` connects to Flow Messaging by an outbound event stream. Messages sent while it was
+  stopped arrive when it starts again (for as long as Flow keeps events, 30 days by default).
+
+## Exit codes (login, setup, link)
+
+`status` exits 0 whatever it finds (1 for a wrong flag): read its fields.
+
+| Code | Meaning | What to do |
+|---|---|---|
+| 0 | Done | Go on |
+| 1 | Usage, not signed in, not an agent's folder, or a login URL that is not https | Fix the command, or run `next` |
+| 2 | flow.engineer could not be reached, or did not answer in time (`timeout`) | Try again |
+| 3 | Refused: denied, expired, a product failed, no channel open yet (one closed while others are open is exit 0 with their links), a server with no CLI sign-in (`server_unsupported`), or a free-trial limit (`sandbox_allowance_used`, the iMessage people cap; HTTP 403) | Run `next`; for a trial limit `next` is a sentence: give it to the owner as it is |
+| 4 | Sign-in still waiting for the owner's approval, or flow.engineer asked to wait (`slow_down`, HTTP 429) | Approval: ask the owner to approve, then run `next` (the same code is kept). `slow_down`: wait `retry_after` seconds (printed as `Wait <n> s`), then run `next` |
+
+`login` and `link` wait at most `--timeout` seconds (120 by default) before exit 4, and no single
+request waits longer than 30 s. `login --wait` (or `link` again) goes on with the same code: no new
+code and no new browser tab. flow.engineer decides when a code has expired (an approved one can be
+collected a while after its `expires_in`); a waiting code that has expired is replaced by one new
+sign-in, and so is a code from another login URL.
+
+## The `next` lines
+
+Every error is `{"error":{"code","message","next"}}` on stdout with `--json`, and
+`<message> Next: <next>` on stderr. A waiting sign-in is `{"status":"pending",...,"next":...}`.
+`next` is the exact command or URL to run; when it came from flow.engineer it is the server's.
+A run gives one `next`: `setup --json`'s is a list in order (a model key first when there is
+none, then `npm start` for the playground, then `link` for the phone); inside `link` setup's line
+has none, and an error's `next` replaces it.
+Run it, or give it to the owner when it needs them (a browser approval, a page to open). A
+`slow_down` error also has `retry_after` (seconds, or `null` when the server gave none). A
+trial limit's `next` is a sentence, not a command: it is printed on its own line as it came; pass
+it on to the owner unchanged.
+
+flow.engineer may add `warnings` (up to 20 lines) to any setup answer. Each is printed on its own
+line on stderr; with `--json` setup's line has `warnings` (an empty list when there are none), and
+an error line has it when there were any. Pass them on to the owner.
+
+`setup` also shows the free trial: messages used per channel, and on iMessage the people it may
+reach (`iMessage: 1 of 2 people`; `trial.imessage.contacts` `{limit, used}` in `--json`).
+
+`chat` exits 1 for anything that stops it before the first message: `no_model_key`, `no_agent`
+(no `src/agent.ts`), `not_built`, `no_test_people`, `no_channel`; with `--json` as
+`{"error":{"code","message","next"}}` on stdout.
+
+## Keys
+
+- Never ask the owner to paste a key into the chat, and never print, read aloud or commit `.env`.
+  `setup` writes the keys itself and prints only their last 4 characters.
+- The model key: Flow's trial key from `setup`, or the owner's own, typed into `.env` themselves.
+- `setup --rotate cloud,traces,messaging,model` (or `all`) makes those keys again and replaces
+  their lines in `.env`.
+- `setup` keeps every value already in `.env` (`--replace` takes the new ones), but a name there
+  with no value (`cp .env.example .env`) counts as missing and is filled on its own line. Keys
+  flow.engineer made are written even when the rest of setup fails, since they are shown only once.
+  `.env` is set to mode 0600.
+- The sign-in token goes only to the server that issued it, over https (http only to localhost):
+  with `FLOW_FRAMEWORK_LOGIN_URL` naming another server, commands stop with `signed_in_elsewhere`.
+- CI never signs in: `npx @flow-engineer/flow setup --ci` says how to give it the test cloud key.
+
+## Shared test numbers and privacy
+
+The free trial runs on Flow's shared Telegram bot, WhatsApp number and iMessage line. Sending an
+agent's join message (`Hi <name> (ref <code>)`, what the link fills in) binds that phone to that
+agent's app on the shared sender, so the person's messages go only to that app; sending another
+app's join message moves them there. Trial chats are
+test data, kept for the account's retention (30 days by default). Do not use the trial for real
+customers' data: connect your own number for that.
+
+## Stability
+
+Flow Framework is 0.x. The commands, `--json` fields and exit codes in this guide stay compatible
+within 0.2.x; a breaking change comes with a minor version bump and a note in the release. Pin the
+version in `package.json` for production.
+
+## Host it
+
+Coming soon: `npx @flow-engineer/flow deploy`, to keep the agent answering while the laptop sleeps.

package/examples/cafe/src/agent.ts

@@ -2,13 +2,15 @@
 // 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 { 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">;
 }
@@ -23,12 +25,14 @@ const notConnected = async () => {
 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: [whatsapp(provider), sms(provider), customUI("web", provider)],
+    channels: [...unconnected, ...connected],
     testPeople: [
       { name: "Maria", phone: "+15555550101" },
       { name: "Sam", phone: "+15555550102" },

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/cli.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+// The café's command line, over its MCP server (npm run mcp in another terminal):
+//   npm run cli -- order -h
+//   npm run cli -- order place --name Sam --items '[{"item":"Latte","size":"large","milk":"oat"}]'
+//   npm run cli -- order status BL-1040 --json
+// (npm reads flags before `--` as its own: keep the `--`.) Installed, it is the `cafe` command.
+// Every tool is already a command under its own name; this file adds the words and arguments.
+
+import { fileURLToPath } from "node:url";
+import { defineCli, runCli } from "../../../cli/src/index.ts";
+
+export const cli = defineCli({
+  name: "cafe",
+  server: process.env.CAFE_SERVER ?? "http://127.0.0.1:8790/mcp",
+  description: "Bean & Leaf's menu and pickup orders",
+  groups: { order: "Place and track pickup orders" },
+  commands: {
+    menu: { tool: "get_menu", columns: ["item", "milks", "allergens"] },
+    "order place": { tool: "place_order", examples: [`cafe order place --name Sam --items '[{"item":"Latte","size":"large","milk":"oat"}]'`] },
+    "order status": { tool: "order_status", args: ["order_id"], view: ["found", "status", "ready_by"], examples: ["cafe order status BL-1040"] },
+  },
+});
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) process.exit(await runCli(cli, process.argv.slice(2)));

package/examples/cafe/src/main.ts

@@ -1,16 +1,30 @@
-// Pip in the playground: `npm start`, then open the printed link and pick a test person.
+// 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] });
+  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 { url } = await play.listen(agent, Number(process.env.PORT ?? 8788));
+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/mcp.ts

@@ -0,0 +1,22 @@
+// Pip's tools and skills as an MCP server, for Claude, ChatGPT or any MCP host: `npm run mcp`.
+// The same tools the chat agent uses; no model key needed, since the host brings its own model.
+
+import { createServer } from "node:http";
+import { fileURLToPath } from "node:url";
+import { mcpServer } from "../../../mcp/src/index.ts";
+import { tools } from "./tools.ts";
+
+export const mcp = mcpServer({
+  name: "bean-and-leaf",
+  version: "1.0.0",
+  tools,
+  dir: fileURLToPath(new URL("../agent", import.meta.url)),
+  // The café has no accounts yet, so every tool answers without sign-in. With accounts, add
+  // auth: { issuer, resource, scopes, verify } (the chinwag-auth skill).
+});
+
+const port = Number(process.env.MCP_PORT ?? 8790);
+createServer((req, res) => void mcp.node(req, res)).listen(port, "127.0.0.1", () => {
+  console.log(`Pip's MCP server: http://127.0.0.1:${port}/mcp`);
+  console.log(`Try it in Claude Code: claude mcp add --transport http bean-and-leaf http://127.0.0.1:${port}/mcp`);
+});

package/examples/cafe/src/tools.ts

@@ -19,8 +19,15 @@ const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
 export const tools = [
   tool({
     name: "get_menu",
+    title: "Menu",
     description: "The full menu: items, sizes with prices in USD, milk options and allergens.",
     input: z.object({}),
+    output: z.object({
+      menu: z.array(z.object({ item: z.string(), sizes: z.record(z.string(), z.number()), milks: z.array(z.string()), allergens: z.array(z.string()) })),
+      note: z.string(),
+    }),
+    signIn: "none",
+    hints: { readOnly: true, openWorld: false },
     run: async () => {
       await wait(150);
       return { menu: MENU, note: "This is the whole menu." };
@@ -28,6 +35,7 @@ export const tools = [
   }),
   tool({
     name: "place_order",
+    title: "Place an 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"),
@@ -40,6 +48,9 @@ export const tools = [
         }),
       ),
     }),
+    output: z.object({ order_id: z.string(), ready_by: z.string(), pay_at_pickup: z.boolean() }),
+    status: { running: "Placing your order…", done: "Order placed" },
+    hints: { destructive: false, openWorld: false },
     run: async ({ items }) => {
       await wait(5_000);
       const id = `BL-${nextOrder++}`;
@@ -52,6 +63,8 @@ export const tools = [
     name: "order_status",
     description: "Where an order is: received, being made, or ready.",
     input: z.object({ order_id: z.string() }),
+    output: z.object({ found: z.boolean(), status: z.enum(["being made", "ready"]).optional(), ready_by: z.string().optional() }),
+    hints: { readOnly: true, openWorld: false },
     run: async ({ order_id }) => {
       await wait(200);
       const order = orders.get(order_id);

package/flow-messaging/README.md

@@ -1,9 +1,13 @@
 # Flow Messaging channels
 
-Put a Flow Framework (`npm i @flow-engineer/flow`) agent on real WhatsApp, Telegram and US SMS
+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 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`).
+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
@@ -26,7 +30,8 @@ Each sender has an ID (`snd_...`), a link to open on your phone, and a join code
 
 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.
+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.
@@ -35,31 +40,58 @@ sandbox contact your agent can talk to.
 
 ```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 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.sms()],
+  channels: [fm.telegram(), fm.whatsapp(), fm.imessage(), fm.sms()],
 });
 await agent.resume();
 
-createServer(fm.webhook(agent)).listen(Number(process.env.PORT ?? 8080));
+const live = fm.start(agent, { cursorFile: ".flow/flow-messaging-cursor" });
+live.stopped.then((why) => console.error(`Flow Messaging refused the stream: ${why.message}`));
 ```
 
-Already have an HTTP server? Hand the raw body and headers to `fm.receive` instead:
+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 });
 ```
 
-### 3. Point Flow's webhook at it
-
 Flow posts events to a public HTTPS URL. Create a webhook endpoint for it:
 
 ```sh
@@ -72,32 +104,31 @@ curl https://api.flow.engineer/v1/webhook_endpoints \
 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.
+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. |
-| `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_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` and `sms`).
+`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 and SMS.
+- 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.
-- A link: one URL button (WhatsApp's call-to-action button).
+  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, typing, and read receipts (WhatsApp).
+- 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).
 
@@ -122,24 +153,32 @@ Each of these can also be passed in code: `flowMessaging({ apiKey, webhookSecret
   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.
+- 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. After a restart, the
+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 channel kind yet, so Telegram is a custom channel. iMessage is not in this
-package yet.
+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`: the Telegram channel's limits, as a framework `ChannelInfo`.
+- `TELEGRAM`, `IMESSAGE`: the Telegram and iMessage channels' limits, as framework `ChannelInfo`s.
 
 ## Links
 
@@ -149,4 +188,4 @@ package yet.
 
 ## License
 
-MIT, as the rest of this repository.
+Apache-2.0, as the rest of this repository.