@flow-engineer/flow 0.2.0 → 0.2.1

package/dist/testing/src/flow-login.js

@@ -0,0 +1,249 @@
+// The flow.engineer side of `flow login`, `logout`, `whoami` and `setup`: every call to it, and
+// where the Flow CLI token is kept. Only this file knows the server's routes and field names
+// (flow.engineer's CLI sign-in contract).
+//   POST /cli/device {client_name, hostname}  -> {device_code, user_code, verification_uri, verification_uri_complete, interval, expires_in}
+//   POST /cli/token {device_code}             -> {access_token, expires_at, account}, or 400 {error} as RFC 8628 has it:
+//                                                authorization_pending, slow_down, expired_token, access_denied, invalid_grant
+//   POST /cli/revoke (bearer) {}              ends this token
+//   GET  /cli/whoami (bearer)                 -> {account, email, token}
+//   POST /cli/setup (bearer) {name, hostname, channels, have}
+//        -> {agent_id, cloud_key?, traces_key?, messaging_key?, join_code, account, app_id, dashboard_url, try_url,
+//            <channel>_sender?, <channel>_link? (telegram, whatsapp, imessage: each only while that shared sender
+//            is open), try_urls?, trial?, minted, next}; a 502 carries every field that worked too;
+//        429 slow_down with Retry-After; 403 for a trial limit (sandbox_allowance_used, ...), its next prose
+//        Any answer may carry warnings: up to 20 strings to show the owner as they are.
+// Every error is flat: {"error": "<code>", "error_description": "<sentence>", "next": "<command, URL or sentence>"}.
+// The token is opaque (fcli_...), good only for /cli/*, and sent only to the server that issued it,
+// over https (http only to this machine). Every request gives up after REQUEST_TIMEOUT_MS at most.
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configDir, configFile, RUN, setting } from "../../src/names.js";
+export const LOGIN_URL = "https://flow.engineer";
+/** The longest one request to flow.engineer may take; login's polls are cut shorter by what is left of --timeout. */
+export const REQUEST_TIMEOUT_MS = 30_000;
+/** A login URL a token may go to: https, or http to this machine only (a local flow.engineer). */
+export function safeLoginUrl(url) {
+    const parsed = URL.parse(url);
+    if (!parsed)
+        return false;
+    if (parsed.protocol === "https:")
+        return true;
+    return parsed.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname);
+}
+/** flow.engineer, or FLOW_FRAMEWORK_LOGIN_URL, without trailing slashes (trimmed from the end, in linear time). */
+export function loginUrl(env = process.env) {
+    const url = setting("LOGIN_URL", env) || LOGIN_URL;
+    let end = url.length;
+    while (end > 0 && url[end - 1] === "/")
+        end--;
+    return url.slice(0, end);
+}
+/** ~/.config/flow-framework/credentials.json (XDG_CONFIG_HOME when set), written at mode 0600. */
+export function credentialsPath(env = process.env) {
+    return join(configDir(env), "credentials.json");
+}
+/** The credentials file to read or delete: credentialsPath, else ~/.config/chinwag/credentials.json while only it exists. */
+const savedCredentialsPath = (env) => configFile("credentials.json", env);
+/**
+ * The token to use: FLOW_FRAMEWORK_TOKEN, else the credentials file's (with `url`, the server that
+ * issued it, the only one it is sent to); undefined when signed out.
+ */
+export function currentToken(env = process.env) {
+    const fromEnv = setting("TOKEN", env)?.trim();
+    if (fromEnv)
+        return { token: fromEnv, from: "env" };
+    const saved = readCredentials(env);
+    return saved ? { token: saved.token, from: "file", url: saved.url || LOGIN_URL } : undefined;
+}
+export function readCredentials(env = process.env) {
+    const path = savedCredentialsPath(env);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const saved = JSON.parse(readFileSync(path, "utf8"));
+        return typeof saved.token === "string" && saved.token ? saved : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function saveCredentials(credentials, env = process.env) {
+    const path = credentialsPath(env);
+    mkdirSync(join(path, ".."), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600); // a file that was already there keeps its mode on write
+    return path;
+}
+export function deleteCredentials(env = process.env) {
+    const path = savedCredentialsPath(env);
+    if (!existsSync(path))
+        return false;
+    rmSync(path);
+    return true;
+}
+/** ~/.config/flow-framework/pending.json, written at mode 0600 and deleted once the code is used or expired. */
+export function pendingPath(env = process.env) {
+    return join(configDir(env), "pending.json");
+}
+export function readPending(env = process.env) {
+    try {
+        const saved = JSON.parse(readFileSync(pendingPath(env), "utf8"));
+        return typeof saved.device_code === "string" && typeof saved.expires_at === "number" ? saved : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function savePending(pending, env = process.env) {
+    const path = pendingPath(env);
+    mkdirSync(join(path, ".."), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify(pending, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+export function deletePending(env = process.env) {
+    rmSync(pendingPath(env), { force: true });
+}
+/** The answer's warnings: its strings only, at most 20. */
+export function warningsOf(body) {
+    return Array.isArray(body.warnings) ? body.warnings.filter((w) => typeof w === "string" && w !== "").slice(0, 20) : [];
+}
+/** Retry-After as seconds from now (delta-seconds or an HTTP date); undefined when absent or unreadable. */
+export function retryAfterSeconds(header, now = Date.now()) {
+    if (!header)
+        return undefined;
+    const value = header.trim();
+    if (/^\d+$/.test(value))
+        return Number(value);
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? undefined : Math.max(0, Math.ceil((at - now) / 1000));
+}
+/**
+ * The server answered with an error status; `code` is its `error` field when it gave one, `next` its
+ * next step, and `fields` the whole answer (a failed setup carries the keys it minted anyway).
+ */
+export class LoginRefused extends Error {
+    status;
+    code;
+    next;
+    fields;
+    /** Seconds the server asked to wait (Retry-After), for a 429. */
+    retryAfter;
+    constructor(status, code, message, next, fields = {}, retryAfter) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.next = next;
+        this.fields = fields;
+        this.retryAfter = retryAfter;
+    }
+}
+/** The server answered nothing in time: `ms` is how long this request was given. */
+export class TimedOut extends Error {
+    ms;
+    constructor(url, ms) {
+        super(`${url} did not answer within ${Math.ceil(ms / 1000)} s.`);
+        this.ms = ms;
+    }
+}
+async function call(url, path, options = {}) {
+    if (!safeLoginUrl(url)) {
+        throw new LoginRefused(0, "insecure_login_url", `${url} is not https: the sign-in and its token go only over https (http only to localhost).`, `set FLOW_FRAMEWORK_LOGIN_URL to an https address, or unset it to use ${LOGIN_URL}`);
+    }
+    const timeoutMs = Math.max(0, Math.min(options.timeoutMs ?? REQUEST_TIMEOUT_MS, REQUEST_TIMEOUT_MS));
+    const headers = { accept: "application/json" };
+    if (options.token)
+        headers.authorization = `Bearer ${options.token}`;
+    if (options.body !== undefined)
+        headers["content-type"] = "application/json";
+    let response;
+    let text;
+    try {
+        response = await fetch(`${url}${path}`, {
+            method: options.method ?? "POST",
+            headers,
+            body: options.body === undefined ? undefined : JSON.stringify(options.body),
+            redirect: options.token ? "error" : "follow", // a redirect would carry the token to another address
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        text = await response.text();
+    }
+    catch (error) {
+        if (error.name === "TimeoutError")
+            throw new TimedOut(url, timeoutMs);
+        throw error;
+    }
+    let body = {};
+    try {
+        body = text ? JSON.parse(text) : {};
+    }
+    catch {
+        if (response.ok)
+            throw new LoginRefused(response.status, "bad_answer", `${url}${path} answered ${response.status} with no JSON.`);
+    }
+    return { status: response.status, body, retryAfter: retryAfterSeconds(response.headers.get("retry-after")) };
+}
+function refused(path, answer, url) {
+    // A bare 404: this server has no CLI sign-in (an older one, or not flow.engineer at all).
+    if (answer.status === 404 && typeof answer.body.error !== "string") {
+        return new LoginRefused(404, "server_unsupported", `${url} has no ${path}, so it cannot sign in the Flow CLI: it is an older server, or not flow.engineer.`, url === LOGIN_URL ? `${RUN}@latest login` : `unset FLOW_FRAMEWORK_LOGIN_URL to use ${LOGIN_URL}, or point it at a server that has /cli/`, answer.body);
+    }
+    const code = typeof answer.body.error === "string" ? answer.body.error : answer.status === 401 ? "not_signed_in" : `http_${answer.status}`;
+    const detail = typeof answer.body.error_description === "string" ? answer.body.error_description : typeof answer.body.message === "string" ? answer.body.message : "";
+    const next = typeof answer.body.next === "string" && answer.body.next ? answer.body.next : undefined;
+    const sentence = detail.endsWith(".") ? detail.slice(0, -1) : detail;
+    return new LoginRefused(answer.status, code, `${path} answered ${answer.status} ${code}${sentence ? `: ${sentence}` : ""}.`, next, answer.body, answer.retryAfter);
+}
+/** `clientName` and `hostname` are shown on the approval page. */
+export async function startDevice(url, clientName, hostname) {
+    const answer = await call(url, "/cli/device", { body: { client_name: clientName, hostname } });
+    if (answer.status !== 200 || typeof answer.body.device_code !== "string")
+        throw refused("/cli/device", answer, url);
+    return answer.body;
+}
+const WAITING = new Set(["authorization_pending", "slow_down", "expired_token", "access_denied"]);
+/** `timeoutMs` cuts this one poll short (login gives it what is left of --timeout). */
+export async function pollToken(url, deviceCode, timeoutMs) {
+    const answer = await call(url, "/cli/token", { body: { device_code: deviceCode }, timeoutMs });
+    const token = answer.body.access_token;
+    if (answer.status === 200 && typeof token === "string") {
+        return { status: "signed_in", token, expires_at: answer.body.expires_at, account: answer.body.account };
+    }
+    const error = answer.body.error;
+    if (typeof error === "string" && WAITING.has(error))
+        return { status: error };
+    throw refused("/cli/token", answer, url);
+}
+export async function revoke(url, token) {
+    const answer = await call(url, "/cli/revoke", { token, body: {} });
+    // 401: the token had already ended, which is what logout wants.
+    if (answer.status >= 300 && answer.status !== 401)
+        throw refused("/cli/revoke", answer, url);
+}
+export async function whoami(url, token) {
+    const answer = await call(url, "/cli/whoami", { token, method: "GET" });
+    if (answer.status !== 200)
+        throw refused("/cli/whoami", answer, url);
+    return answer.body;
+}
+export async function setup(url, token, request) {
+    const answer = await call(url, "/cli/setup", { token, body: request });
+    // A 200 is returned whole even without a join code: the keys it minted are shown only now.
+    if (answer.status !== 200)
+        throw refused("/cli/setup", answer, url);
+    return answer.body;
+}
+/** The agent's .env names for what setup hands back; only the keys' and the join's names are sent as `have`. */
+export const SETUP_ENV = {
+    cloud_key: "FLOW_FRAMEWORK_CLOUD_KEY",
+    traces_key: "FLOW_FRAMEWORK_TRACES_KEY",
+    messaging_key: "FLOW_MESSAGING_KEY",
+    telegram_sender: "FLOW_MESSAGING_TELEGRAM_SENDER",
+    whatsapp_sender: "FLOW_MESSAGING_WHATSAPP_SENDER",
+    imessage_sender: "FLOW_MESSAGING_IMESSAGE_SENDER",
+    join_code: "FLOW_FRAMEWORK_JOIN_CODE",
+    try_url: "FLOW_FRAMEWORK_TRY_URL",
+};
+/** The phone link for a join code, built as the server builds its try_url, for a .env from before setup kept it. */
+export function tryLink(url, joinCode, channel) {
+    return `${url}/try/${encodeURIComponent(joinCode)}?c=${encodeURIComponent(channel)}`;
+}

package/dist/testing/src/new.d.ts

@@ -7,3 +7,7 @@ export declare function newStandalone(name: string, options?: {
     into?: string;
     root?: string;
 }): string;
+/** Makes the agent in `dir` (the current folder by default), named after the folder; returns its name. */
+export declare function initHere(dir?: string, options?: {
+    root?: string;
+}): string;

package/dist/testing/src/new.js

@@ -1,9 +1,11 @@
 // `flow new <name>`: makes ./<name>/, an agent of its own started from the café example (Pip),
-// that depends on the @flow-engineer/flow package. Its imports become "@flow-engineer/flow" and "@flow-engineer/flow/simulators", and
-// the coding-agent skills go in .claude/skills/, with an AGENTS.md (and a CLAUDE.md importing it)
-// pointing at them. Inside a clone, `npm run new -- <name>` makes agents/<name>/ instead.
+// that depends on the @flow-engineer/flow package. Its imports become "@flow-engineer/flow",
+// "@flow-engineer/flow/simulators" and "@flow-engineer/flow/flow-messaging", and the coding-agent
+// skills go in .claude/skills/, with an AGENTS.md (and a CLAUDE.md importing it) pointing at them.
+// `flow init` makes the same agent in the current folder. Inside a clone, `npm run new -- <name>`
+// makes agents/<name>/ instead.
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 /** Throws unless `name` can be an agent's folder and package name. */
@@ -50,7 +52,7 @@ GEMINI_API_KEY=
 # Optional. The model id for that provider; empty is that provider's default.
 # CAFE_MODEL=
 
-# The test cloud (npx flow test --synthetic) and traces. Sign in at https://flow.engineer/observe,
+# The test cloud (npx @flow-engineer/flow test --synthetic) and traces. Sign in at https://flow.engineer/observe,
 # add the agent, and on its Developers page make a CI key (oci_..., shown once); the trace key is
 # from the same site.
 FLOW_FRAMEWORK_CLOUD=https://flow.engineer/observe
@@ -65,18 +67,36 @@ A chat agent on Flow Framework (https://github.com/flow-engineer/flow), started
 - Load the skills in \`.claude/skills/\` before changing it: \`flow-framework\` to build the agent, \`flow-framework-tools\`
   for its tools and their test files, \`flow-framework-tests\` for its test scenarios.
 - \`agent/AGENTS.md\` is the agent's own prompt, not instructions for coding agents.
-- \`npm start\` runs it in the playground. The owner puts one model key in \`.env\` (never read or
-  print it): \`OPENROUTER_API_KEY\`, \`OPENAI_API_KEY\`, \`ANTHROPIC_API_KEY\` or \`GEMINI_API_KEY\`.
-  \`npm run typecheck\` checks the types, \`npm test -- --synthetic\` runs the tests in the test
-  cloud at https://flow.engineer/observe with the owner's \`FLOW_FRAMEWORK_CLOUD_KEY\` (\`npx flow --help\`).
+- The owner puts one model key in \`.env\` (never read or print it): \`OPENROUTER_API_KEY\`,
+  \`OPENAI_API_KEY\`, \`ANTHROPIC_API_KEY\` or \`GEMINI_API_KEY\`. Then \`npx @flow-engineer/flow chat\`
+  talks to it in the terminal, \`npm start\` runs it in the playground, and \`npx @flow-engineer/flow link\`
+  signs in, puts its other keys in \`.env\` and prints the link that reaches it from a phone while
+  \`npm start\` runs. \`npm run typecheck\` checks the types, \`npm test -- --synthetic\` runs the
+  tests in the test cloud at https://flow.engineer/observe with the owner's \`FLOW_FRAMEWORK_CLOUD_KEY\`
+  (\`npx @flow-engineer/flow --help\`).
+- The guide for coding agents, with exit codes and next steps: https://github.com/flow-engineer/flow/blob/main/docs/agents.md
 `;
 /** Makes `<into>/<name>` (the current folder by default) and returns it. */
 export function newStandalone(name, options = {}) {
     checkName(name);
-    const root = options.root ?? packageRoot();
     const dir = join(options.into ?? process.cwd(), name);
     if (existsSync(dir))
         throw new Error(`${dir} already exists: pick another name or remove it.`);
+    makeAgent(dir, name, options.root ?? packageRoot());
+    return dir;
+}
+/** What `flow init` writes into a folder; it refuses a folder that holds any of them, so nothing is overwritten. */
+const MADE = ["package.json", "tsconfig.json", "src", "agent", "tests", ".env.example", "AGENTS.md", "CLAUDE.md", ".npmrc"];
+/** Makes the agent in `dir` (the current folder by default), named after the folder; returns its name. */
+export function initHere(dir = process.cwd(), options = {}) {
+    const taken = MADE.filter((f) => existsSync(join(dir, f)));
+    if (taken.length)
+        throw new Error(`${dir} has ${taken.join(", ")} already: run flow init in an empty folder, or flow new <name> to make one.`);
+    const name = basename(dir).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "my-agent";
+    makeAgent(dir, name, options.root ?? packageRoot());
+    return name;
+}
+function makeAgent(dir, name, root) {
     const cafe = join(root, "examples", "cafe");
     for (const part of ["agent", "src", "tests"])
         cpSync(join(cafe, part), join(dir, part), { recursive: true });
@@ -84,7 +104,8 @@ export function newStandalone(name, options = {}) {
         const path = join(dir, "src", file);
         const source = readFileSync(path, "utf8")
             .replace(/(["'])(\.\.\/)+src\/index\.ts\1/g, '"@flow-engineer/flow"')
-            .replace(/(["'])(\.\.\/)+simulators\/src\/index\.ts\1/g, '"@flow-engineer/flow/simulators"');
+            .replace(/(["'])(\.\.\/)+simulators\/src\/index\.ts\1/g, '"@flow-engineer/flow/simulators"')
+            .replace(/(["'])(\.\.\/)+flow-messaging\/src\/index\.ts\1/g, '"@flow-engineer/flow/flow-messaging"');
         if (/["']\.\.\/\.\.\//.test(source))
             throw new Error(`flow: ${file} imports a file outside the agent; only Flow Framework's public entries can be rewritten.`);
         writeFileSync(path, source);
@@ -103,7 +124,12 @@ export function newStandalone(name, options = {}) {
     };
     writeFileSync(join(dir, "package.json"), `${JSON.stringify(pkg, null, 2)}\n`);
     writeFileSync(join(dir, "tsconfig.json"), `${JSON.stringify(TSCONFIG, null, 2)}\n`);
-    writeFileSync(join(dir, ".gitignore"), "node_modules/\n.env\n.flow/\n");
+    // An existing .gitignore (flow init in a fresh repository) keeps its lines and gets the missing ones.
+    const ignore = join(dir, ".gitignore");
+    const ignored = existsSync(ignore) ? readFileSync(ignore, "utf8") : "";
+    const missing = ["node_modules/", ".env", ".flow/"].filter((line) => !ignored.split("\n").includes(line));
+    if (missing.length)
+        writeFileSync(ignore, `${ignored}${ignored && !ignored.endsWith("\n") ? "\n" : ""}${missing.join("\n")}\n`);
     // npm install then refuses a Node older than the engines field says, before .ts files fail to load.
     writeFileSync(join(dir, ".npmrc"), "engine-strict=true\n");
     writeFileSync(join(dir, ".env.example"), ENV_EXAMPLE);
@@ -118,5 +144,4 @@ export function newStandalone(name, options = {}) {
     }
     writeFileSync(join(dir, "AGENTS.md"), agentsMd(name));
     writeFileSync(join(dir, "CLAUDE.md"), "@AGENTS.md\n");
-    return dir;
 }

package/docs/agents.md

@@ -0,0 +1,85 @@
+# Flow Framework for coding agents
+
+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
+except their model key. 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                        # the starter agent in this (empty) folder; flow new <name> makes a folder
+npm install
+# the owner puts one model key in .env (OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY or GEMINI_API_KEY)
+printf 'hi\nA latte please\n' | npx @flow-engineer/flow chat   # talk to it locally: no account, one message per line
+npx @flow-engineer/flow link --json                 # signs in and sets up if needed, then prints the phone link
+npm start                                           # keep it running; the owner texts it from the phone
+```
+
+- `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`).
+- 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`). If it was running when
+  `link` added one, restart it.
+- 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)
+
+| 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, a channel not open yet, 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.
+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`).
+
+## 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 is the owner's: they type it into `.env` themselves.
+- `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.

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/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`));
+}