@flow-engineer/flow 0.3.0 → 0.3.2

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,11 @@ 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.
+When the owner names a team's observe workspace, pass `--workspace <name|acc_id>` to `setup` or `link`
+once: its `acc_` id is kept in `.env` (`FLOW_FRAMEWORK_WORKSPACE`) for later runs, and `status` shows it.
 
 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.d.ts

@@ -1,4 +1,4 @@
 export declare const ACCOUNT_COMMANDS: Set<string>;
-export declare const ACCOUNT_LINES = "  flow login [--wait | --no-wait] [--timeout <s>] [--force] [--no-browser] [--json]\n                            Sign in to flow.engineer: opens the browser, prints the link and code,\n                            and waits up to --timeout (default 120) for approval; --wait goes on\n                            waiting for the same code, --no-wait returns at once\n  flow logout [--json]      End this machine's sign-in and delete its token\n  flow whoami [--json]      Show the account you are signed in as\n  flow setup [--replace] [--rotate <keys> [--now]] [--display-name <name>] [--ci] [--json]\n                            Write this agent's keys (its Flow key FLOW_KEY, which also pays for the\n                            model on the account's trial credit when there is no provider key, test\n                            cloud, traces, Flow Messaging) and each open channel's sender into\n                            ./.env (in an agent's folder: package.json); --rotate key,cloud,traces,\n                            messaging or all makes those keys again (the old FLOW_KEY works 24 h\n                            more; --now ends it at once)\n  flow link [--channel telegram|whatsapp|imessage] [--display-name <name>] [--timeout <s>] [--no-browser] [--json]\n                            Print the link that opens a chat with this agent from a phone; signs in\n                            and runs setup first when this folder is not set up yet. --display-name\n                            (here and on setup) renames the agent: package.json's displayName and\n                            its prompt, agent/AGENTS.md; the phone link then says \"Hi <name>\"\n  flow status [--json]      What this folder has and lacks: FLOW_KEY and the model key (never their\n                            values) with the trial credit left, the\n                            sign-in, each channel's sender in .env, and, signed in, which channels\n                            are open now and their free-trial counts";
+export declare const ACCOUNT_LINES = "  flow login [--wait | --no-wait] [--timeout <s>] [--force] [--no-browser] [--json]\n                            Sign in to flow.engineer: opens the browser, prints the link and code,\n                            and waits up to --timeout (default 120) for approval; --wait goes on\n                            waiting for the same code, --no-wait returns at once\n  flow logout [--json]      End this machine's sign-in and delete its token\n  flow whoami [--json]      Show the account you are signed in as\n  flow setup [--replace] [--rotate <keys> [--now]] [--workspace <name|acc_id>] [--display-name <name>] [--ci] [--json]\n                            Write this agent's keys (its Flow key FLOW_KEY, which also pays for the\n                            model on the account's trial credit when there is no provider key, test\n                            cloud, traces, Flow Messaging) and each open channel's sender into\n                            ./.env (in an agent's folder: package.json); --rotate key,cloud,traces,\n                            messaging or all makes those keys again (the old FLOW_KEY works 24 h\n                            more; --now ends it at once). --workspace (here and on link) puts the\n                            agent in that observe workspace of yours, kept in .env as\n                            FLOW_FRAMEWORK_WORKSPACE; a new one makes the cloud and traces keys again\n  flow link [--channel telegram|whatsapp|imessage] [--workspace <name|acc_id>] [--display-name <name>] [--timeout <s>] [--no-browser] [--json]\n                            Print the link that opens a chat with this agent from a phone; signs in\n                            and runs setup first when this folder is not set up yet. --display-name\n                            (here and on setup) renames the agent: package.json's displayName and\n                            its prompt, agent/AGENTS.md; the phone link then says \"Hi <name>\"\n  flow status [--json]      What this folder has and lacks: FLOW_KEY and the model key (never their\n                            values) with the trial credit left, the workspace, the\n                            sign-in, each channel's sender in .env, and, signed in, which channels\n                            are open now and their free-trial counts";
 /** Runs one account command; resolves to the exit status. */
 export declare function accountCli(command: string, args: string[]): Promise<number>;

package/dist/testing/src/account.js

@@ -30,20 +30,22 @@ export const ACCOUNT_LINES = `  flow login [--wait | --no-wait] [--timeout <s>]
                             waiting for the same code, --no-wait returns at once
   flow logout [--json]      End this machine's sign-in and delete its token
   flow whoami [--json]      Show the account you are signed in as
-  flow setup [--replace] [--rotate <keys> [--now]] [--display-name <name>] [--ci] [--json]
+  flow setup [--replace] [--rotate <keys> [--now]] [--workspace <name|acc_id>] [--display-name <name>] [--ci] [--json]
                             Write this agent's keys (its Flow key FLOW_KEY, which also pays for the
                             model on the account's trial credit when there is no provider key, test
                             cloud, traces, Flow Messaging) and each open channel's sender into
                             ./.env (in an agent's folder: package.json); --rotate key,cloud,traces,
                             messaging or all makes those keys again (the old FLOW_KEY works 24 h
-                            more; --now ends it at once)
-  flow link [--channel telegram|whatsapp|imessage] [--display-name <name>] [--timeout <s>] [--no-browser] [--json]
+                            more; --now ends it at once). --workspace (here and on link) puts the
+                            agent in that observe workspace of yours, kept in .env as
+                            FLOW_FRAMEWORK_WORKSPACE; a new one makes the cloud and traces keys again
+  flow link [--channel telegram|whatsapp|imessage] [--workspace <name|acc_id>] [--display-name <name>] [--timeout <s>] [--no-browser] [--json]
                             Print the link that opens a chat with this agent from a phone; signs in
                             and runs setup first when this folder is not set up yet. --display-name
                             (here and on setup) renames the agent: package.json's displayName and
                             its prompt, agent/AGENTS.md; the phone link then says "Hi <name>"
   flow status [--json]      What this folder has and lacks: FLOW_KEY and the model key (never their
-                            values) with the trial credit left, the
+                            values) with the trial credit left, the workspace, the
                             sign-in, each channel's sender in .env, and, signed in, which channels
                             are open now and their free-trial counts`;
 const USAGE = `Usage:\n${ACCOUNT_LINES}
@@ -100,7 +102,7 @@ export async function accountCli(command, args) {
                     : {}),
                 ...(command === "setup" ? { replace: { type: "boolean", default: false }, rotate: { type: "string" }, now: { type: "boolean", default: false }, ci: { type: "boolean", default: false } } : {}),
                 ...(command === "link" ? { channel: { type: "string", default: "telegram" } } : {}),
-                ...(command === "link" || command === "setup" ? { "display-name": { type: "string" } } : {}),
+                ...(command === "link" || command === "setup" ? { "display-name": { type: "string" }, workspace: { type: "string" } } : {}),
             },
         }));
     }
@@ -131,6 +133,12 @@ export async function accountCli(command, args) {
         console.error(`flow setup: --now goes with --rotate key (or all): it ends the old FLOW_KEY at once.\n\n${USAGE}`);
         return EXIT.usage;
     }
+    const workspace = typeof values.workspace === "string" ? values.workspace.trim() : undefined;
+    // flow.engineer takes a workspace's acc_ id or its name: 1 to 100 characters, no control characters.
+    if (workspace !== undefined && (!workspace || workspace.length > 100 || /[\u0000-\u001f\u007f]/.test(workspace))) {
+        console.error(`flow ${command}: --workspace takes a workspace's name or its acc_ id, 1 to 100 characters.\n\n${USAGE}`);
+        return EXIT.usage;
+    }
     const json = values.json === true;
     // Straight to the file descriptors, never buffered: a coding agent's cut-off command keeps every line.
     const out = (report) => writeAll(1, `${JSON.stringify(report)}\n`);
@@ -162,9 +170,9 @@ export async function accountCli(command, args) {
         else if (command === "status")
             await status(json, out, say);
         else if (command === "setup")
-            await setupEnv({ replace: values.replace === true, rotate, now: values.now === true, ci: values.ci === true }, json, out, say);
+            await setupEnv({ replace: values.replace === true, rotate, now: values.now === true, ci: values.ci === true, workspace }, json, out, say);
         else
-            await link({ channel, noBrowser: values["no-browser"] === true, timeoutSeconds, renamed }, json, out, say);
+            await link({ channel, noBrowser: values["no-browser"] === true, timeoutSeconds, renamed, workspace }, json, out, say);
         return EXIT.ok;
     }
     catch (error) {
@@ -499,6 +507,19 @@ const OPEN_HINT = {
     whatsapp: "Open it and send the message it fills in.",
     imessage: "Open it on an iPhone or a Mac and send the message it fills in.",
 };
+/** The observe workspace this folder's agent was put in by --workspace (its acc_ id); unset: the personal one. */
+const WORKSPACE_ENV = "FLOW_FRAMEWORK_WORKSPACE";
+/** The answer's workspace_id, under the name setupEnv gives it only when a workspace was asked for. */
+const WORKSPACE_FIELD = "workspace_kept";
+/** --workspace names another workspace than the one .env's cloud and traces keys are in (none named yet: the personal one). */
+function movesWorkspace(workspace, value) {
+    if (workspace === undefined)
+        return false;
+    const stored = value(WORKSPACE_ENV);
+    if (stored)
+        return workspace.toLowerCase() !== stored.toLowerCase();
+    return Boolean(value(SETUP_ENV.cloud_key) || value(SETUP_ENV.traces_key));
+}
 async function setupEnv(options, json, out, say, forLink) {
     if (options.ci) {
         const steps = [
@@ -511,7 +532,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);
@@ -527,6 +548,14 @@ async function setupEnv(options, json, out, say, forLink) {
     const name = named.replace(/^@[^/]*\//, "").replace(/[^A-Za-z0-9 ._-]/g, "-").slice(0, 64) || "my-agent";
     const all = options.rotate.includes("all");
     const rotated = new Set(all ? Object.values(ROTATE).filter(Boolean) : options.rotate.map((k) => ROTATE[k]));
+    // The workspace asked for: --workspace, else the one an earlier --workspace kept in .env.
+    const workspace = options.workspace ?? (before.get(WORKSPACE_ENV) || undefined);
+    // Another workspace: the cloud and traces keys in .env are the old one's, so they are made again
+    // there (Messaging's key and FLOW_KEY are not bound to a workspace).
+    const moving = movesWorkspace(options.workspace, (n) => before.get(n));
+    if (moving)
+        for (const field of ["cloud_key", "traces_key"])
+            rotated.add(field);
     const rotatedEnv = new Set([...rotated].map((field) => (field === "flow_key" ? FLOW_KEY : SETUP_ENV[field])));
     // An empty value (`cp .env.example .env`) is missing: the server mints it. A model key counts in
     // the shell too (npm start reads both): FLOW_KEY is made only when it is not named as had, and
@@ -542,38 +571,64 @@ async function setupEnv(options, json, out, say, forLink) {
     // FLOW_FRAMEWORK_TRY_URL is one channel's page: link's channel when it is open, else the server's (Telegram's).
     const withTryUrl = (fields) => {
         const code = fields.join_code;
+        // The workspace the answer put the agent in, kept only when one was asked for.
+        if (workspace !== undefined && typeof fields.workspace_id === "string" && fields.workspace_id)
+            fields = { ...fields, [WORKSPACE_FIELD]: fields.workspace_id };
         if (!forLink || typeof fields[`${forLink.channel}_sender`] !== "string" || typeof code !== "string" || !code)
             return fields;
         const pages = fields.try_urls;
         const page = typeof pages?.[forLink.channel] === "string" ? pages[forLink.channel] : tryLink(url, code, forLink.channel);
         return { ...fields, try_url: page };
     };
-    const chosenPage = (n) => forLink !== undefined && n === SETUP_ENV.try_url;
+    const chosenPage = (n) => (forLink !== undefined && n === SETUP_ENV.try_url) || n === WORKSPACE_ENV;
     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 } : {}) });
+        answer = await setup(url, token, { name, hostname: hostname(), channels: [...CHANNELS], have, ...(workspace !== undefined ? { workspace } : {}), ...(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);
     const had = new Map(before);
     // --replace takes every new value but a model key: only --rotate key replaces FLOW_KEY.
     const written = writeEnv(file, lines, before, envEntries(withTryUrl(fields)), (n) => rotatedEnv.has(n) || (options.replace && !MODEL_KEY_NAMES.includes(n)) || chosenPage(n));
+    // An older flow.engineer ignores the field and sets the agent up in the personal workspace.
+    if (workspace !== undefined && !observeFailed && (typeof answer.workspace_id !== "string" || !answer.workspace_id)) {
+        const stop = new Stop("workspace_unsupported", "flow.engineer does not support --workspace yet; the agent was set up in your personal workspace.", undefined, EXIT.refused);
+        stop.warnings = warnings;
+        throw stop;
+    }
     if (typeof answer.join_code !== "string" || !answer.join_code) {
         const kept = written.filter((w) => w.action === "added" || w.action === "replaced").map((w) => w.name);
         const stop = new Stop("no_join_code", `flow.engineer gave no join code${kept.length ? ` (the keys it made are in .env: ${kept.join(", ")})` : ""}, so there is no phone link yet.`, answer.next?.[0] ?? NEXT.setup, EXIT.refused);
         stop.warnings = warnings;
         throw stop;
     }
+    if (observeFailed) {
+        // Moving workspaces, the old workspace's keys still in .env do not count.
+        const missing = [SETUP_ENV.cloud_key, SETUP_ENV.traces_key].filter((n) => !before.get(n) || (moving && before.get(n) === had.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);
@@ -605,6 +660,7 @@ async function setupEnv(options, json, out, say, forLink) {
             whatsapp_link: answer.whatsapp_link ?? null, imessage_link: answer.imessage_link ?? null, try_urls: links,
             direct_links: Object.fromEntries(Object.entries(direct).map(([c, d]) => [c, d.link])), join_message: Object.values(direct)[0]?.message ?? null,
             trial, model_key: model.report,
+            workspace: typeof answer.workspace_id === "string" && answer.workspace_id ? { id: answer.workspace_id, name: answer.workspace_name ?? null } : null,
             // FLOW_KEY's state, never its value: made in this call, with its id, mode and scopes.
             flow_key: { set: Boolean(before.get(FLOW_KEY) || process.env[FLOW_KEY]?.trim()), minted: flowKey?.minted === true,
                 ...(flowKey?.minted ? { kid: flowKey.kid ?? null, mode: flowKey.mode ?? null, scopes: flowKey.scopes ?? [], previous_expires_at: flowKey.previous_expires_at ?? null } : {}) },
@@ -612,11 +668,13 @@ 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)
         say(previous);
+    if (answer.workspace_id)
+        say(`Workspace: ${answer.workspace_name ? `${answer.workspace_name} (${answer.workspace_id})` : answer.workspace_id}`);
     if (answer.dashboard_url)
         say(`Its dashboard: ${answer.dashboard_url}`);
     // Said by link instead, once, with its link.
@@ -634,7 +692,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) {
@@ -653,6 +711,7 @@ function objectField(fields, name) {
  */
 function envEntries(fields) {
     const entries = Object.entries(SETUP_ENV).map(([field, envName]) => [envName, fields[field]]);
+    entries.push([WORKSPACE_ENV, fields[WORKSPACE_FIELD]]);
     const key = objectField(fields, "flow_key");
     if ((key?.env ?? FLOW_KEY) === FLOW_KEY && typeof key?.value === "string")
         entries.push([FLOW_KEY, key.value]);
@@ -729,7 +788,8 @@ async function status(json, out, say) {
                 const named = JSON.parse(readFileSync(join(process.cwd(), "package.json"), "utf8")).name ?? basename(process.cwd());
                 const name = named.replace(/^@[^/]*\//, "").replace(/[^A-Za-z0-9 ._-]/g, "-").slice(0, 64) || "my-agent";
                 const have = [...Object.values(SETUP_ENV).filter((n) => n !== SETUP_ENV.try_url), ...MODEL_KEY_NAMES];
-                server = await setup(url, current.token, { name, hostname: hostname(), channels: [...CHANNELS], have });
+                const workspace = value(WORKSPACE_ENV);
+                server = await setup(url, current.token, { name, hostname: hostname(), channels: [...CHANNELS], have, ...(workspace ? { workspace } : {}) });
             }
         }
         catch {
@@ -748,11 +808,13 @@ async function status(json, out, say) {
         ...(model.report.set && !model.next ? ["npm start"] : []),
         ...(!joinCode || !value(SETUP_ENV.messaging_key) ? [NEXT.link] : CHANNELS.filter((c) => channels[c].open && !channels[c].sender).map((c) => `${NEXT.link} --channel ${c}`)),
     ];
+    const workspace = value(WORKSPACE_ENV) || "personal";
     if (json)
-        out({ model_key: model.report, flow_key: { set: Boolean(value(FLOW_KEY)) }, signed_in: account ? { email: account.email, account: account.account } : false, join_code: joinCode, messaging_key: Boolean(value(SETUP_ENV.messaging_key)), channels, next });
+        out({ model_key: model.report, flow_key: { set: Boolean(value(FLOW_KEY)) }, workspace, signed_in: account ? { email: account.email, account: account.account } : false, join_code: joinCode, messaging_key: Boolean(value(SETUP_ENV.messaging_key)), channels, next });
     if (model.report.env && model.report.env !== FLOW_KEY)
         say(value(FLOW_KEY) ? `${FLOW_KEY} is set.` : `${FLOW_KEY}: not set yet (${RUN} setup writes it).`);
     say(model.line);
+    say(`Workspace: ${workspace}`);
     say(account ? `Signed in as ${account.email}.` : current ? "Not signed in here (or flow.engineer could not be reached)." : "Not signed in.");
     for (const c of CHANNELS) {
         const { sender, open, trial } = channels[c];
@@ -800,7 +862,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,7 +873,9 @@ async function link(options, json, out, say) {
     let credit;
     let trial;
     let had;
-    if (!value(SETUP_ENV.join_code) || !value(SETUP_ENV.messaging_key) || (needsSender && !value(SENDER_ENV[options.channel]))) {
+    let warnings = [];
+    const newWorkspace = options.workspace !== undefined && (movesWorkspace(options.workspace, value) || !value(WORKSPACE_ENV));
+    if (newWorkspace || !value(SETUP_ENV.join_code) || !value(SETUP_ENV.messaging_key) || (needsSender && !value(SENDER_ENV[options.channel]))) {
         agentFolder(process.cwd());
         if (!(await signedInAccount(loginUrl()))) {
             say("Not signed in to flow.engineer yet: signing in first.");
@@ -818,7 +883,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, workspace: options.workspace }, json, out, say, { channel: options.channel }));
         value = dotenvValue();
     }
     const joinCode = value(SETUP_ENV.join_code);
@@ -880,6 +945,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/dist/testing/src/flow-login.d.ts

@@ -71,6 +71,9 @@ export interface FlowKey {
 }
 export interface SetupAnswer {
     agent_id: string;
+    /** The observe workspace (acc_...) the agent and its cloud and traces keys are in; absent from an older server. */
+    workspace_id?: string;
+    workspace_name?: string;
     /** Only the keys minted in this call come back (those the request did not say it has). */
     cloud_key?: string;
     traces_key?: string;
@@ -148,6 +151,7 @@ export declare function setup(url: string, token: string, request: {
     hostname: string;
     channels: string[];
     have: string[];
+    workspace?: string;
     rotate?: true | string[];
     rotate_now?: true;
 }): Promise<SetupAnswer>;

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

@@ -6,8 +6,8 @@
 //                                                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, rotate?, rotate_now?}
-//        -> {agent_id, cloud_key?, traces_key?, messaging_key?, flow_key?, model_credit?, join_code, account, app_id,
+//   POST /cli/setup (bearer) {name, hostname, channels, have, workspace?, rotate?, rotate_now?}
+//        -> {agent_id, workspace_id?, workspace_name?, cloud_key?, traces_key?, messaging_key?, flow_key?, model_credit?, 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;
 //        flow_key is the agent's one Flow key, {env: "FLOW_KEY", value: "flow_test_...", kid, mode, scopes, agent_id,
@@ -18,6 +18,9 @@
 //        the reason in warnings; every folder's setup makes its own key, the credit is the account's;
 //        rotate is true (every key) or the answer fields to make again, such as ["flow_key"]; rotate_now: true
 //        ends the old FLOW_KEY at once instead of 24 h later (previous_expires_at);
+//        workspace is an observe workspace's acc_ id or name (case-insensitive), 1 to 100 characters; absent: the
+//        personal one; workspace_id and workspace_name are the workspace the agent and its cloud and traces keys are in
+//        (whenever observe answered; an older server sends neither); 403 not_a_member, 409 workspace_ambiguous (pass the id);
 //        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.
 //   GET  <model URL>/credit (bearer FLOW_KEY) -> {limit_usd, spent_usd, left_usd, default_model, models};

package/docs/agents.md

@@ -63,9 +63,12 @@ before you hand it back; run them yourself, and do not offer them to the owner a
   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).
+- `setup --workspace <name|acc_id>` (and `link --workspace`) puts the agent, its cloud and traces keys in
+  that observe workspace of yours and keeps its `acc_` id in `.env` as `FLOW_FRAMEWORK_WORKSPACE`, which later
+  runs send; another workspace makes those two keys again (403 `not_a_member`, 409 `workspace_ambiguous`: pass the id).
 - `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`
+  know gets `setup --rotate key`), the workspace (`FLOW_FRAMEWORK_WORKSPACE`, else `personal`), 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.
@@ -80,6 +83,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 +116,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.2",
   "description": "An open-source runtime for chat agents that feel like a person texting back.",
   "license": "Apache-2.0",
   "repository": {