@flow-engineer/flow 0.3.0 → 0.3.1

package/coding-agents/skill.md

@@ -20,7 +20,7 @@ and `flow-framework-auth` (`auth-skill.md`) when tools need to know who the pers
 `npx @flow-engineer/flow new <name>` (lowercase letters, digits and dashes) makes `./<name>/` from the café
 example: a complete agent with tools and tests that depends on the `@flow-engineer/flow` package and imports
 `@flow-engineer/flow` and `@flow-engineer/flow/simulators`, with these skills in `.claude/skills/`. Run `npm install` there.
-Build in it, changing Pip's prompt, skills, tools and tests into yours. A provider key is optional:
+Build in it, changing the café agent's prompt, skills, tools and tests into yours. A provider key is optional:
 `npx @flow-engineer/flow link` (or `setup`) writes `FLOW_KEY`, the agent's one Flow key, into `.env` (never
 read or print it), and the agent calls models through Flow with it on $2 of Flow trial credit. A key of the owner's own wins over it, made
 at the provider: `OPENROUTER_API_KEY` at https://openrouter.ai/keys,
@@ -349,7 +349,9 @@ kept: give the owner the link and code, and run `link` again (it polls the same
 `setup`, which writes the test cloud, traces and Flow Messaging keys into `.env`, prints names and
 last 4 characters only, keeps values already there (`--replace` takes the new ones), and is safe to
 run again. `--channel telegram|whatsapp|imessage` picks the channel; a channel flow.engineer cannot
-open yet exits 3 with its `next`. `login`, `setup` and `link` also run on their own.
+open yet exits 3 with its `next`. When only observe's part of setup fails (traces and the test cloud),
+`link` still prints the link and exits 0, with one warning saying what is missing and the server's
+fix (`warnings` in `--json`): pass it on to the owner. `login`, `setup` and `link` also run on their own.
 
 In `src/main.ts`, put `fm.telegram()` from `@flow-engineer/flow/flow-messaging` in the agent's
 channels and call `fm.start(agent, { cursorFile: ".flow/flow-messaging-cursor" })`: with no webhook

package/dist/testing/src/account.js

@@ -511,7 +511,7 @@ async function setupEnv(options, json, out, say, forLink) {
             out({ ci: { secret: SETUP_ENV.cloud_key, steps } });
         for (const line of steps)
             say(line);
-        return { answer: {} };
+        return { answer: {}, warnings: [] };
     }
     const dir = process.cwd();
     agentFolder(dir);
@@ -550,18 +550,29 @@ async function setupEnv(options, json, out, say, forLink) {
     };
     const chosenPage = (n) => forLink !== undefined && n === SETUP_ENV.try_url;
     let answer;
+    // For link: the server's refusal when Messaging's part came (a join code) and only observe's failed.
+    let observeFailed;
     try {
         // Every channel: each comes back with its shared sender only while it is open.
         answer = await setup(url, token, { name, hostname: hostname(), channels: [...CHANNELS], have, ...(rotate ? { rotate } : {}), ...(rotateNow ? { rotate_now: true } : {}) });
     }
     catch (error) {
-        // The keys minted anyway are not shown again, so whatever the error carries goes into .env first.
-        if (error instanceof LoginRefused) {
-            const written = writeEnv(file, lines, before, envEntries(withTryUrl(error.fields)), (n) => options.replace || rotatedEnv.has(n) || chosenPage(n));
-            if (written.some((w) => w.action === "added" || w.action === "replaced"))
-                say(`Kept in .env before the error: ${written.map((w) => `${w.name} ${w.action}`).join(", ")}.`);
+        // Texting needs only Messaging's part, so link goes on without observe's (traces and the test
+        // cloud) and says what is missing; setup alone, whose job is both, still stops.
+        if (forLink && error instanceof LoginRefused && typeof error.fields.join_code === "string" && error.fields.join_code) {
+            const { error: _code, error_description: why, next: fix, ...rest } = error.fields;
+            answer = rest;
+            observeFailed = { why: typeof why === "string" && why ? why : error.message, fix: typeof fix === "string" && fix ? fix : error.next };
+        }
+        else {
+            // The keys minted anyway are not shown again, so whatever the error carries goes into .env first.
+            if (error instanceof LoginRefused) {
+                const written = writeEnv(file, lines, before, envEntries(withTryUrl(error.fields)), (n) => options.replace || rotatedEnv.has(n) || chosenPage(n));
+                if (written.some((w) => w.action === "added" || w.action === "replaced"))
+                    say(`Kept in .env before the error: ${written.map((w) => `${w.name} ${w.action}`).join(", ")}.`);
+            }
+            throw error;
         }
-        throw error;
     }
     const fields = answer;
     const warnings = warningsOf(fields);
@@ -574,6 +585,11 @@ async function setupEnv(options, json, out, say, forLink) {
         stop.warnings = warnings;
         throw stop;
     }
+    if (observeFailed) {
+        const missing = [SETUP_ENV.cloud_key, SETUP_ENV.traces_key].filter((n) => !before.get(n));
+        const why = observeFailed.why.replace(/\.$/, "");
+        warnings.push(`Traces and tests won't work${missing.length ? ` until .env has ${missing.join(" and ")}` : ""}: ${why}.${observeFailed.fix ? ` Then: ${observeFailed.fix}` : ""}`);
+    }
     printWarnings(warnings);
     const open = CHANNELS.filter((c) => typeof fields[`${c}_sender`] === "string");
     const displayName = agentDisplayName(dir);
@@ -612,7 +628,7 @@ async function setupEnv(options, json, out, say, forLink) {
             ...(forLink ? {} : { next }), warnings,
         });
     }
-    say(`Agent ${answer.agent_id}. In .env:`);
+    say(answer.agent_id ? `Agent ${answer.agent_id}. In .env:` : "In .env:");
     for (const w of written)
         say(`  ${w.name}=${w.value}  ${w.action}${w.action === "kept" ? (w.name === FLOW_KEY ? " (--rotate key makes a new one)" : " (yours differs; --replace takes the new one)") : ""}`);
     if (previous)
@@ -634,7 +650,7 @@ async function setupEnv(options, json, out, say, forLink) {
             say(`If npm start is running, restart it to add ${added}.`);
         say(`Next: ${next.join(", then ")}`);
     }
-    return { answer };
+    return { answer, warnings };
 }
 /** iMessage's count of the people it may reach on the trial, as a line; undefined when the answer had none. */
 function peopleLine(t) {
@@ -800,7 +816,8 @@ function dotenvValue() {
  * in .env, or no sender for a WhatsApp or iMessage link): it signs in first when it has to (the same
  * login, resuming a code already waiting) and runs setup, then asks flow.engineer for the channel's
  * page. A channel that is not open yet is said once, with the links of the channels that are (exit
- * 0); with none open, it stops with the server's next step.
+ * 0); with none open, it stops with the server's next step. A setup whose observe part failed but
+ * whose Messaging part came goes on the same way, with one warning (setupEnv).
  */
 async function link(options, json, out, say) {
     const again = `${NEXT.link}${options.channel === "telegram" ? "" : ` --channel ${options.channel}`}`;
@@ -810,6 +827,7 @@ async function link(options, json, out, say) {
     let credit;
     let trial;
     let had;
+    let warnings = [];
     if (!value(SETUP_ENV.join_code) || !value(SETUP_ENV.messaging_key) || (needsSender && !value(SENDER_ENV[options.channel]))) {
         agentFolder(process.cwd());
         if (!(await signedInAccount(loginUrl()))) {
@@ -818,7 +836,7 @@ async function link(options, json, out, say) {
         }
         say("Setting up this agent's keys in .env.");
         had = value;
-        ({ answer: { model_credit: credit, trial } } = await setupEnv({ replace: false, rotate: [], ci: false }, json, out, say, { channel: options.channel }));
+        ({ answer: { model_credit: credit, trial }, warnings } = await setupEnv({ replace: false, rotate: [], ci: false }, json, out, say, { channel: options.channel }));
         value = dotenvValue();
     }
     const joinCode = value(SETUP_ENV.join_code);
@@ -880,6 +898,8 @@ async function link(options, json, out, say) {
             url: first.link, page: first.page, join_message: first.message, channel, join_code: joinCode, reply_only: Boolean(replyOnly), say_to_person: sayToPerson,
             ...(notOpen ? { not_open: options.channel, message: notOpen, links: Object.fromEntries(links.map(([c, d]) => [c, d.link])) } : {}),
             model_key: model.report, running: running ? { url: running.url } : false, next: next.join(", then "),
+            // Setup's warnings when it ran just now (also on its own line above), such as observe's part failing.
+            ...(warnings.length ? { warnings } : {}),
         });
     }
     if (notOpen) {

package/docs/agents.md

@@ -80,6 +80,14 @@ before you hand it back; run them yourself, and do not offer them to the owner a
   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`).
+- Texting needs only Flow Messaging's part of setup (and a model key). When setup's answer has it
+  (the join code, the Messaging key and senders) but observe's part failed (traces and the test
+  cloud: `observe_failed`, or observe's own limit), `link` prints one warning line on stderr,
+  `Traces and tests won't work until .env has FLOW_FRAMEWORK_CLOUD_KEY and FLOW_FRAMEWORK_TRACES_KEY:
+  <the server's reason>. Then: <its next>`, then the link, the channel's trial line and its `Next:`
+  as usual, and exits 0; `link --json` has the line in `warnings`, on setup's line and on its own.
+  Give it to the owner; `setup` makes the missing keys once it is fixed. Run again, `link` finds
+  Messaging's part in `.env` and does not run setup. `setup` on its own still exits 3 for it.
 - 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.
@@ -105,7 +113,7 @@ before you hand it back; run them yourself, and do not offer them to the owner a
 | 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 |
+| 3 | Refused: denied, expired, a product failed (for `link`, only when Messaging's part did: observe's alone is exit 0 with a warning), 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

package/examples/cafe/src/agent.ts

@@ -1,4 +1,4 @@
-// Builds Pip. The playground (main.ts) and the tests build it the same way; tests pass their own
+// Builds the agent. 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";
@@ -11,7 +11,7 @@ export interface BuildOptions {
   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. */
+  /** Where the agent runs, for a host with no file system (Cloudflare): its files as text, its database, no schedule timer. */
   host?: Pick<AgentOptions, "files" | "database" | "scheduleCheckMs">;
 }
 
@@ -20,7 +20,7 @@ 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");
+  throw new Error("not connected yet: only test people in the playground reach the agent for now");
 };
 const provider = { sendMessage: notConnected, react: notConnected, typing: notConnected, markRead: notConnected, status: notConnected };
 

package/examples/cafe/src/channels.ts

@@ -1,4 +1,4 @@
-// Which Flow Messaging channels Pip is on: Telegram always, WhatsApp and iMessage when .env names
+// Which Flow Messaging channels the agent 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";

package/examples/cafe/src/main.ts

@@ -12,7 +12,7 @@ import { buildAgent } from "./agent.ts";
 import { channelNames, flowChannels } from "./channels.ts";
 
 // What people call it: package.json's displayName (`npx @flow-engineer/flow link --display-name <name>` changes it).
-const { displayName: name = "Pip" } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { displayName?: string };
+const { displayName: name = "your agent" } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { displayName?: string };
 const play = simulators({ title: `${name} · Bean & Leaf` });
 const fm = process.env.FLOW_MESSAGING_KEY ? flowMessaging() : undefined;
 const channels = fm ? flowChannels(fm) : [];

package/examples/cafe/src/mcp.ts

@@ -18,7 +18,7 @@ export const mcp = mcpServer({
 });
 
 // What people call it: package.json's displayName.
-const { displayName: name = "Pip" } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { displayName?: string };
+const { displayName: name = "your agent" } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { displayName?: string };
 // MCP_PORT, else 8790 or the next free port above it.
 let port: number;
 try {

package/examples/cafe/src/tools.ts

@@ -1,4 +1,4 @@
-// Pip's tools, over a tiny in-memory café. Placing an order is slow on purpose (a real point-of-sale
+// The agent'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";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-engineer/flow",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "An open-source runtime for chat agents that feel like a person texting back.",
   "license": "Apache-2.0",
   "repository": {