@flow-engineer/flow 0.2.1 → 0.2.2

package/dist/testing/src/account.js

@@ -18,22 +18,31 @@ import { hostname } from "node:os";
 import { basename, join } from "node:path";
 import { parseArgs } from "node:util";
 import { setTimeout as delay } from "node:timers/promises";
-import { currentToken, deleteCredentials, deletePending, LoginRefused, loginUrl, pollToken, readPending, REQUEST_TIMEOUT_MS, revoke, saveCredentials, savePending, SETUP_ENV, setup, startDevice, TimedOut, tryLink, warningsOf, whoami, } from "./flow-login.js";
+import { currentToken, deleteCredentials, deletePending, LoginRefused, loginUrl, pollToken, readPending, REQUEST_TIMEOUT_MS, revoke, saveCredentials, savePending, modelCredit, SETUP_ENV, setup, startDevice, TimedOut, tryLink, warningsOf, whoami, } from "./flow-login.js";
 import { packageRoot } from "./new.js";
+import { flowModelURL, hasModelKey, MODEL_KEY_NAMES, NO_MODEL_KEY } from "../../src/model.js";
 import { RUN } from "../../src/names.js";
-export const ACCOUNT_COMMANDS = new Set(["login", "logout", "whoami", "setup", "link"]);
+export const ACCOUNT_COMMANDS = new Set(["login", "logout", "whoami", "setup", "link", "status"]);
 export const ACCOUNT_LINES = `  flow login [--wait | --no-wait] [--timeout <s>] [--force] [--no-browser] [--json]
                             Sign in to flow.engineer: opens the browser, prints the link and code,
                             and waits up to --timeout (default 120) for approval; --wait goes on
                             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] [--ci] [--json]
-                            Write this agent's keys (test cloud, traces, Flow Messaging) and each
-                            open channel's sender into ./.env (in an agent's folder: package.json)
+  flow setup [--replace] [--rotate <keys> [--now]] [--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] [--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`;
+                            and runs setup first when this folder is not set up yet
+  flow status [--json]      What this folder has and lacks: FLOW_KEY and the model key (never their
+                            values) with the trial credit left, 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}
 
 The token is kept in ~/.config/flow-framework/credentials.json (mode 0600); FLOW_FRAMEWORK_TOKEN, when
@@ -86,7 +95,7 @@ export async function accountCli(command, args) {
                         force: { type: "boolean", default: false },
                     }
                     : {}),
-                ...(command === "setup" ? { replace: { type: "boolean", default: false }, ci: { type: "boolean", default: false } } : {}),
+                ...(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" } } : {}),
             },
         }));
@@ -109,6 +118,15 @@ export async function accountCli(command, args) {
         console.error(`flow link: --channel takes ${CHANNELS.join(", ")}.\n\n${USAGE}`);
         return EXIT.usage;
     }
+    const rotate = values.rotate === undefined ? [] : String(values.rotate).split(",").map((k) => k.trim());
+    if (rotate.some((k) => !(k in ROTATE)) || (rotate.includes("all") && rotate.length > 1)) {
+        console.error(`flow setup: --rotate takes ${Object.keys(ROTATE).filter((k) => k !== "all").join(", ")} (comma-separated), or all.\n\n${USAGE}`);
+        return EXIT.usage;
+    }
+    if (values.now === true && !rotate.includes("key") && !rotate.includes("all")) {
+        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 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`);
@@ -121,8 +139,10 @@ export async function accountCli(command, args) {
             await logout(json, out, say);
         else if (command === "whoami")
             await showAccount(json, out, say);
+        else if (command === "status")
+            await status(json, out, say);
         else if (command === "setup")
-            await setupEnv(values.replace === true, values.ci === true, json, out, say);
+            await setupEnv({ replace: values.replace === true, rotate, now: values.now === true, ci: values.ci === true }, json, out, say);
         else
             await link({ channel, noBrowser: values["no-browser"] === true, timeoutSeconds }, json, out, say);
         return EXIT.ok;
@@ -362,9 +382,11 @@ async function showAccount(json, out, say) {
         out(account);
     say(`Signed in to flow.engineer as ${account.email} (account ${account.account}).`);
 }
-const SECRET = new Set([SETUP_ENV.cloud_key, SETUP_ENV.traces_key, SETUP_ENV.messaging_key]);
+const SECRET = new Set([SETUP_ENV.cloud_key, SETUP_ENV.traces_key, SETUP_ENV.messaging_key, ...MODEL_KEY_NAMES]);
 const masked = (name, value) => (SECRET.has(name) ? `${/^[a-z]+_(?:test_|live_)?/.exec(value)?.[0] ?? ""}…${value.slice(-4)}` : value);
 const ENV_LINE = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/;
+/** `--rotate`'s names and the answer field each makes again; `all` is every key. */
+const ROTATE = { key: "flow_key", cloud: "cloud_key", traces: "traces_key", messaging: "messaging_key", all: "" };
 /** The names set in a .env's lines, with their values unquoted. */
 function envValues(lines) {
     const values = new Map();
@@ -389,8 +411,76 @@ function agentFolder(dir) {
         return;
     throw new Stop("not_an_agent_folder", `${dir} has no package.json, so it is not an agent's folder; its keys would land in the wrong .env.`, `cd into your agent's folder, or make an agent here first: ${RUN} init`, EXIT.usage);
 }
-async function setupEnv(replace, ci, json, out, say, forLink) {
-    if (ci) {
+/** The agent's one Flow key; for the model it is last in the model keys' order, so a provider key the owner sets wins. */
+const FLOW_KEY = MODEL_KEY_NAMES.at(-1);
+const USED_UP = "This account's Flow trial credit is used up.";
+const NO_CREDIT = `Flow has no trial model credit for this account, so ${FLOW_KEY} cannot pay for the model.`;
+const OWN_KEY = "add your own model key to .env";
+/** setup's model_credit or GET /credit's answer as FlowCredit: its numbers only. */
+function creditOf(from) {
+    if (!from)
+        return null;
+    const credit = {};
+    for (const field of ["limit_usd", "left_usd", "spent_usd"]) {
+        const n = from[field];
+        if (typeof n === "number" && Number.isFinite(n))
+            credit[field] = n;
+    }
+    return credit;
+}
+const dollars = (n) => `$${n.toFixed(2)}`;
+/**
+ * The model key's state: `line` to print, and with no key the step that gets one, which goes first
+ * in the run's one `next`. `credit`: Flow's credit from setup's answer or GET /credit. `afterSetup`:
+ * setup ran just now, so its answer says why there is none.
+ */
+function modelKeyReport(value, credit, afterSetup) {
+    const env = MODEL_KEY_NAMES.find((name) => value(name)) ?? null;
+    const flowCredit = creditOf(credit);
+    const usedUp = flowCredit?.left_usd !== undefined && flowCredit.left_usd <= 0;
+    if (env && env !== FLOW_KEY)
+        return { report: { set: true, env, flow_credit: null }, line: `Model: ${env} is set` };
+    if (env) {
+        if (usedUp)
+            return { report: { set: true, env, flow_credit: flowCredit, message: USED_UP }, line: USED_UP, next: OWN_KEY };
+        // Setup just ran and gave no credit (warnings say why): FLOW_KEY is there, but cannot pay for the model.
+        if (afterSetup && !flowCredit)
+            return { report: { set: true, env, flow_credit: null, message: NO_CREDIT }, line: NO_CREDIT, next: OWN_KEY };
+        const left = flowCredit?.left_usd !== undefined ? ` (${dollars(flowCredit.left_usd)} left)` : "";
+        return { report: { set: true, env, flow_credit: flowCredit }, line: `Model: Flow trial credit${left}` };
+    }
+    // No key, and the account's credit is used up: setup made none.
+    if (usedUp)
+        return { report: { set: false, env: null, flow_credit: flowCredit, message: USED_UP }, line: USED_UP, next: OWN_KEY };
+    const report = { set: false, env: null, flow_credit: null, message: NO_MODEL_KEY.message };
+    // Setup ran and flow.engineer gave no FLOW_KEY (an older server, or none for this account now).
+    if (afterSetup)
+        return { report, line: NO_MODEL_KEY.message, next: `${OWN_KEY} (flow.engineer gave no trial credit)` };
+    return { report, line: NO_MODEL_KEY.message, next: NO_MODEL_KEY.nextLine.replace(/^Next: /, "").replace(/\.$/, "") };
+}
+/** What people call this folder's agent (package.json displayName, from `flow init`), else its package name in words. */
+function agentDisplayName(dir = process.cwd()) {
+    const file = join(dir, "package.json");
+    const pkg = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+    const named = typeof pkg.displayName === "string" ? pkg.displayName.trim() : "";
+    return named || (pkg.name ?? basename(dir)).replace(/^@[^/]+\//, "").replace(/-/g, " ");
+}
+/** The /try page with the agent's name (`n`), so it fills in "Hi <name> (ref <code>)". */
+function namedPage(url, name) {
+    const parsed = URL.parse(url);
+    if (!parsed)
+        return url;
+    parsed.searchParams.set("n", name);
+    return parsed.toString();
+}
+/** How to use each channel's direct link. */
+const OPEN_HINT = {
+    telegram: "Open it and press Start.",
+    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.",
+};
+async function setupEnv(options, json, out, say, forLink) {
+    if (options.ci) {
         const steps = [
             `CI never signs in. It runs the tests with the agent's test cloud key, ${SETUP_ENV.cloud_key}, as a secret.`,
             `Run ${NEXT.setup} on your machine first, then copy the key from .env into your CI without printing it, for GitHub:`,
@@ -401,7 +491,7 @@ async function setupEnv(replace, ci, json, out, say, forLink) {
             out({ ci: { secret: SETUP_ENV.cloud_key, steps } });
         for (const line of steps)
             say(line);
-        return;
+        return { answer: {} };
     }
     const dir = process.cwd();
     agentFolder(dir);
@@ -415,24 +505,39 @@ async function setupEnv(replace, ci, json, out, say, forLink) {
     const named = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).name ?? basename(dir);
     // The server takes 1 to 64 letters, digits, spaces, -, _ and .: a package's scope and other characters go.
     const name = named.replace(/^@[^/]*\//, "").replace(/[^A-Za-z0-9 ._-]/g, "-").slice(0, 64) || "my-agent";
-    // An empty value (`cp .env.example .env`) is missing: the server mints it.
-    const have = Object.values(SETUP_ENV).filter((n) => n !== SETUP_ENV.try_url && before.get(n));
+    const all = options.rotate.includes("all");
+    const rotated = new Set(all ? Object.values(ROTATE).filter(Boolean) : options.rotate.map((k) => ROTATE[k]));
+    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
+    // the trial model credit is given only when no provider key is.
+    const have = [
+        ...Object.values(SETUP_ENV).filter((n) => n !== SETUP_ENV.try_url && before.get(n)),
+        ...MODEL_KEY_NAMES.filter((n) => before.get(n) || process.env[n]?.trim()),
+    ].filter((n) => !rotatedEnv.has(n));
+    // Dropping a key's name from `have` makes it again; `rotate` names them too, so the server replaces
+    // (and, for FLOW_KEY, ends) the old one rather than adding a second.
+    const rotate = all ? true : rotated.size ? [...rotated] : undefined;
+    const rotateNow = options.now === true && rotated.has("flow_key");
     let answer;
     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 });
+        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, error.fields, replace);
+            const written = writeEnv(file, lines, before, envEntries(error.fields), (n) => options.replace || rotatedEnv.has(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;
     }
-    const warnings = warningsOf(answer);
-    const written = writeEnv(file, lines, before, answer, replace);
+    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(fields), (n) => rotatedEnv.has(n) || (options.replace && !MODEL_KEY_NAMES.includes(n)));
     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);
@@ -440,36 +545,87 @@ async function setupEnv(replace, ci, json, out, say, forLink) {
         throw stop;
     }
     printWarnings(warnings);
-    const open = CHANNELS.filter((c) => typeof answer[`${c}_sender`] === "string");
-    const links = Object.fromEntries(open.map((c) => [c, answer.try_urls?.[c] ?? (c === "telegram" && answer.try_url ? answer.try_url : tryLink(url, answer.join_code, c))]));
-    const next = [`${RUN} test --synthetic`, "npm start", ...(answer.next?.length ? answer.next : [NEXT.link])];
+    const open = CHANNELS.filter((c) => typeof fields[`${c}_sender`] === "string");
+    const displayName = agentDisplayName(dir);
+    const links = Object.fromEntries(open.map((c) => [c, namedPage(answer.try_urls?.[c] ?? (c === "telegram" && answer.try_url ? answer.try_url : tryLink(url, answer.join_code, c)), displayName)]));
+    // Said by link instead, which asks for its own; a page that does not answer leaves only the page.
+    const direct = {};
+    if (!forLink) {
+        for (const c of open) {
+            const found = await directLink(links[c]).catch((error) => (error instanceof Stop ? undefined : Promise.reject(error)));
+            if (found)
+                direct[c] = found;
+        }
+    }
+    // A closed channel's trial counts are not shown: only the open ones'.
+    const trial = answer.trial ? Object.fromEntries(Object.entries(answer.trial).filter(([c]) => open.includes(c))) : null;
+    const model = modelKeyReport((n) => before.get(n) || process.env[n]?.trim() || undefined, objectField(fields, "model_credit"), true);
+    const flowKey = objectField(fields, "flow_key");
+    // A rotated FLOW_KEY: when the one it replaced stops working.
+    const previous = rotated.has("flow_key") && flowKey?.minted
+        ? flowKey.previous_expires_at ? `The old ${FLOW_KEY} works until ${flowKey.previous_expires_at}.` : rotateNow ? `The old ${FLOW_KEY} stopped working now.` : undefined
+        : undefined;
+    // A first run's order: a model key if there is none, the playground (npm start), then the phone.
+    // chat and test --synthetic are the coding agent's own checks, not the owner's way to test.
+    const next = [...(model.next ? [model.next] : []), "npm start", ...(answer.next?.length ? answer.next : [NEXT.link])];
     if (json) {
         out({
             agent: answer.agent_id, join_code: answer.join_code, env_written: { ".env": written }, minted: answer.minted ?? [],
             dashboard_url: answer.dashboard_url ?? null, try_url: answer.try_url ?? null, telegram_link: answer.telegram_link ?? null,
-            whatsapp_link: answer.whatsapp_link ?? null, imessage_link: answer.imessage_link ?? null, try_urls: links, trial: answer.trial ?? null, next, warnings,
+            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,
+            // 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 } : {}) },
+            // link's own line (or its error) has the run's next steps: one list per run.
+            ...(forLink ? {} : { next }), warnings,
         });
     }
     say(`Agent ${answer.agent_id}. In .env:`);
     for (const w of written)
-        say(`  ${w.name}=${w.value}  ${w.action}${w.action === "kept" ? " (yours differs; --replace takes the new one)" : ""}`);
+        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.dashboard_url)
         say(`Its dashboard: ${answer.dashboard_url}`);
-    const people = answer.trial?.imessage?.contacts;
+    // Said by link instead, once, with its link.
+    if (!forLink)
+        say(model.line);
+    const people = trial?.imessage?.contacts;
     if (people && typeof people.used === "number" && typeof people.limit === "number")
         say(`iMessage: ${people.used} of ${people.limit} people`);
     if (!forLink) {
         for (const c of open)
-            say(`On ${CHANNEL_NAME[c]}: ${links[c]}${trialNote(answer.trial?.[c])}`);
+            say(`On ${CHANNEL_NAME[c]}: ${direct[c] ? `${direct[c].link} (on a computer: ${links[c]})` : links[c]}${trialNote(trial?.[c])}`);
+        const added = addedToRunning((n) => had.get(n) || process.env[n]?.trim(), (n) => before.get(n) || process.env[n]?.trim());
+        if (added)
+            say(added);
         say(`Next: ${next.join(", then ")}`);
     }
+    return { answer };
 }
 const trialNote = (t) => (t && typeof t.limit === "number" ? ` (free trial: ${t.used} of ${t.limit} messages used)` : "");
-/** Merges setup's fields into .env's lines and writes the file (mode 0600) when anything changed. */
-function writeEnv(file, lines, before, fields, replace) {
+/** An answer's field when it is an object (flow_key, model_credit), else undefined (an older server sends none). */
+function objectField(fields, name) {
+    const value = fields[name];
+    return value && typeof value === "object" && !Array.isArray(value) ? value : undefined;
+}
+/**
+ * The .env lines an answer gives: SETUP_ENV's fields, then the agent's Flow key as FLOW_KEY (no
+ * other name: a provider key the owner typed is never written over, and wins for the model).
+ */
+function envEntries(fields) {
+    const entries = Object.entries(SETUP_ENV).map(([field, envName]) => [envName, fields[field]]);
+    const key = objectField(fields, "flow_key");
+    if ((key?.env ?? FLOW_KEY) === FLOW_KEY && typeof key?.value === "string")
+        entries.push([FLOW_KEY, key.value]);
+    return entries;
+}
+/** Merges the entries into .env's lines and writes the file (mode 0600) when anything changed; `replace(name)` says when a value there gives way. */
+function writeEnv(file, lines, before, entries, replace) {
     const written = [];
-    for (const [field, envName] of Object.entries(SETUP_ENV)) {
-        const value = fields[field];
+    for (const [envName, value] of entries) {
         if (typeof value !== "string" || !value)
             continue;
         const old = before.get(envName);
@@ -485,7 +641,7 @@ function writeEnv(file, lines, before, fields, replace) {
         }
         else if (old === value)
             action = "unchanged";
-        else if (!replace)
+        else if (!replace(envName))
             action = "kept";
         else {
             lines[at] = `${envName}=${value}`;
@@ -500,25 +656,123 @@ function writeEnv(file, lines, before, fields, replace) {
         chmodSync(file, 0o600); // a .env that was there keeps its old mode on write
     return written;
 }
+/**
+ * What a running agent (npm start reads .env once, when it starts) lacks after .env changed from
+ * `had` to `now`: the channels it is not on yet and a model key, as one sentence; undefined when
+ * nothing it uses is new.
+ */
+function addedToRunning(had, now) {
+    // The starter is on Telegram whenever it has the Flow Messaging key, and on WhatsApp and iMessage
+    // when .env names their senders; without the key it was on no channel at all.
+    const on = (env, c) => Boolean(env(SETUP_ENV.messaging_key) && (c === "telegram" || env(SENDER_ENV[c])));
+    const channels = CHANNELS.filter((c) => on(now, c) && !on(had, c)).map((c) => CHANNEL_NAME[c]);
+    const model = !MODEL_KEY_NAMES.some((n) => had(n)) && MODEL_KEY_NAMES.some((n) => now(n)) ? ["the model key"] : [];
+    const what = [...channels, ...model];
+    if (!what.length)
+        return undefined;
+    return `If npm start is running, restart it to add ${what.length === 1 ? what[0] : `${what.slice(0, -1).join(", ")} and ${what.at(-1)}`}.`;
+}
+/**
+ * `flow status`: what this folder has and lacks, read from .env and the environment, and, when
+ * signed in and set up, flow.engineer's answer for which channels are open now and their trial
+ * counts. It changes nothing: setup is asked with every key named as had, so nothing is made, and
+ * its answer is not written. Not signed in, or flow.engineer unreachable: that part is left out.
+ */
+async function status(json, out, say) {
+    const value = dotenvValue();
+    const model = await flowModelStatus(value);
+    const joinCode = value(SETUP_ENV.join_code) ?? null;
+    let account = null;
+    let server = null;
+    const current = currentToken();
+    const url = loginUrl();
+    if (current && (!current.url || current.url === url)) {
+        try {
+            account = await whoami(url, current.token);
+            if (joinCode && existsSync(join(process.cwd(), "package.json"))) {
+                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 });
+            }
+        }
+        catch {
+            // Signed out on the server, or not reachable: status says what it can from here.
+        }
+    }
+    const fields = (server ?? {});
+    const channels = Object.fromEntries(CHANNELS.map((c) => [c, {
+            sender: Boolean(c === "telegram" ? value(SETUP_ENV.messaging_key) : value(SENDER_ENV[c])),
+            open: server ? typeof fields[`${c}_sender`] === "string" : null,
+            trial: server && typeof fields[`${c}_sender`] === "string" ? server.trial?.[c] ?? null : null,
+        }]));
+    // The playground (npm start) before the phone, as setup's next.
+    const next = [
+        ...(model.next ? [model.next] : []),
+        ...(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}`)),
+    ];
+    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 });
+    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(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];
+        const where = sender ? "in .env" : "not in .env";
+        const now = open === null ? "" : open ? "; open now" : "; not open yet";
+        say(`${CHANNEL_NAME[c]}: ${c === "telegram" ? `Flow Messaging key ${where}` : `sender ${where}`}${now}${trialNote(trial ?? undefined)}`);
+    }
+    if (next.length)
+        say(`Next: ${next.join(", then ")}`);
+}
+/**
+ * status's model line. Flow's key the active one: its credit from GET /credit. A key Flow does not
+ * know says so with the step that makes a new one; Flow not reachable leaves the credit unknown.
+ */
+async function flowModelStatus(value) {
+    const local = modelKeyReport(value, undefined, false);
+    if (local.report.env !== FLOW_KEY)
+        return local;
+    const key = value(FLOW_KEY);
+    try {
+        return modelKeyReport(value, await modelCredit(flowModelURL({ ...process.env, FLOW_MODEL_URL: value("FLOW_MODEL_URL") }), key), false);
+    }
+    catch (error) {
+        if (error instanceof LoginRefused && (error.status === 401 || error.status === 403)) {
+            const message = error.status === 401
+                ? `${FLOW_KEY} is not a key Flow knows (revoked, or from another server).`
+                : `${FLOW_KEY} may not call Flow's models (its scopes lack model).`;
+            return { report: { ...local.report, message }, line: message, next: `${RUN} setup --rotate key` };
+        }
+        if (error instanceof LoginRefused && error.status === 402) {
+            const message = error.code === "trial_credit_used" ? USED_UP : NO_CREDIT;
+            return { report: { ...local.report, flow_credit: error.code === "trial_credit_used" ? { left_usd: 0 } : null, message }, line: message, next: OWN_KEY };
+        }
+        return { ...local, line: `${local.line} (credit left unknown: Flow could not be reached)` };
+    }
+}
 /** The names set in ./.env, with what the environment sets winning. */
 function dotenvValue() {
     const file = join(process.cwd(), ".env");
     const saved = existsSync(file) ? envValues(readFileSync(file, "utf8").split("\n")) : new Map();
-    return (name) => process.env[name] || saved.get(name);
+    return (name) => process.env[name]?.trim() || saved.get(name);
 }
 /**
  * The phone link for this folder's join code. Not set up yet (no join code or no Flow Messaging key
  * 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, so a channel that is not open yet answers with the server's next step instead of a link
- * that does not work.
+ * 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.
  */
 async function link(options, json, out, say) {
     const again = `${NEXT.link}${options.channel === "telegram" ? "" : ` --channel ${options.channel}`}`;
     const what = CHANNEL_NAME[options.channel];
     const needsSender = options.channel !== "telegram";
     let value = dotenvValue();
-    let restart = false;
+    let credit;
+    let had;
     if (!value(SETUP_ENV.join_code) || !value(SETUP_ENV.messaging_key) || (needsSender && !value(SENDER_ENV[options.channel]))) {
         agentFolder(process.cwd());
         if (!(await signedInAccount(loginUrl()))) {
@@ -526,37 +780,90 @@ async function link(options, json, out, say) {
             await login({ noBrowser: options.noBrowser, wait: false, noWait: false, force: true, timeoutSeconds: options.timeoutSeconds, resume: { then: again } }, json, out, say);
         }
         say("Setting up this agent's keys in .env.");
-        await setupEnv(false, false, json, out, say, { channel: options.channel });
+        had = value;
+        ({ answer: { model_credit: credit } } = await setupEnv({ replace: false, rotate: [], ci: false }, json, out, say, { channel: options.channel }));
         value = dotenvValue();
-        restart = true;
     }
     const joinCode = value(SETUP_ENV.join_code);
     if (!joinCode)
         throw new Stop("no_join_code", `Setup wrote no ${SETUP_ENV.join_code} into .env.`, NEXT.setup, EXIT.refused);
-    if (needsSender && !value(SENDER_ENV[options.channel])) {
-        throw new Stop("channel_not_open", `${what} is not open on Flow's shared senders yet, so setup got no ${SENDER_ENV[options.channel]}.`, NEXT.link, EXIT.refused);
-    }
     // The server's own try_url when setup kept one for this join code and channel, else the same page built here.
     const fromServer = value(SETUP_ENV.try_url);
-    const url = fromServer?.includes(`/try/${encodeURIComponent(joinCode)}?`) && URL.parse(fromServer)?.searchParams.get("c") === options.channel ? fromServer : tryLink(loginUrl(), joinCode, options.channel);
-    await checkTryPage(url);
-    const replyOnly = REPLY_ONLY[options.channel];
-    const sayToPerson = `Open this on your phone and send the message ${what} fills in: ${url}${replyOnly ? ` ${replyOnly}` : ""}`;
-    if (json)
-        out({ url, channel: options.channel, join_code: joinCode, reply_only: Boolean(replyOnly), say_to_person: sayToPerson });
-    say(url);
-    say(`Open it on a phone with ${what} and send the message it fills in, with your join code. From then on`);
-    say("that phone chats with this agent while it runs (npm start), with no public URL or tunnel.");
-    if (replyOnly)
-        say(replyOnly);
-    if (restart)
-        say("If the agent is running already, restart it (npm start) so it picks up the new .env.");
+    const name = agentDisplayName();
+    const pageFor = (channel) => namedPage(fromServer?.includes(`/try/${encodeURIComponent(joinCode)}?`) && URL.parse(fromServer)?.searchParams.get("c") === channel ? fromServer : tryLink(loginUrl(), joinCode, channel), name);
+    /** The channel's direct link, or the Stop that says it is not open (no sender in .env, or the try page says channel_not_open). */
+    const open = async (channel) => {
+        if (channel !== "telegram" && !value(SENDER_ENV[channel])) {
+            return new Stop("channel_not_open", `${CHANNEL_NAME[channel]} is not open on Flow's shared senders yet, so setup got no ${SENDER_ENV[channel]}.`, NEXT.link, EXIT.refused);
+        }
+        try {
+            return await directLink(pageFor(channel));
+        }
+        catch (error) {
+            if (error instanceof Stop && error.code === "channel_not_open")
+                return error;
+            throw error;
+        }
+    };
+    const model = modelKeyReport(value, credit, had !== undefined);
+    const asked = await open(options.channel);
+    let links;
+    let notOpen;
+    if (!(asked instanceof Stop))
+        links = [[options.channel, asked]];
+    else {
+        // The asked-for channel is closed: the others' links instead, each checked the same way.
+        links = [];
+        for (const c of CHANNELS.filter((c) => c !== options.channel)) {
+            const other = await open(c);
+            if (!(other instanceof Stop))
+                links.push([c, other]);
+        }
+        if (!links.length)
+            throw asked;
+        notOpen = `${what} isn't open yet; here ${links.length === 1 ? "is your" : "are your"} ${links.map(([c]) => CHANNEL_NAME[c]).join(" and ")} link${links.length === 1 ? "" : "s"}.`;
+    }
+    const [channel, first] = links[0];
+    const replyOnly = REPLY_ONLY[channel];
+    const sayToPerson = `${notOpen ? `${what} isn't open yet. ` : ""}Your ${CHANNEL_NAME[channel]} link: ${first.link} ${OPEN_HINT[channel]} `
+        + `On a computer without ${CHANNEL_NAME[channel]}, open ${first.page} instead.${replyOnly ? ` ${replyOnly}` : ""}`;
+    if (json) {
+        out({
+            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, ...(model.next ? { next: model.next } : {}),
+        });
+    }
+    if (notOpen) {
+        say(notOpen);
+        for (const [c, d] of links)
+            say(`On ${CHANNEL_NAME[c]}: ${d.link} (on a computer: ${d.page})`);
+    }
+    else {
+        say(first.link);
+        say(`On a computer without ${CHANNEL_NAME[channel]}: ${first.page}`);
+    }
+    if (model.report.set)
+        say(model.line);
+    const one = notOpen && links.length > 1 ? "one" : "it";
+    say(`${channel === "telegram" ? `Open ${one} on a phone and press Start` : `Open ${one} on a phone and send the message it fills in, "${first.message}"`}. From then on`);
+    // No model key: the agent cannot answer yet, so the phone does not chat with it until there is one.
+    say(model.report.set ? "that phone chats with this agent while it runs (npm start), with no public URL or tunnel." : "that phone reaches this agent while it runs (npm start), but it answers only once .env has a model key:");
+    if (model.next)
+        say(`${model.line}\nNext: ${model.next}.`);
+    for (const [c] of links)
+        if (REPLY_ONLY[c])
+            say(REPLY_ONLY[c]);
+    const added = had ? addedToRunning(had, value) : undefined;
+    if (added)
+        say(added);
 }
 /**
- * Asks flow.engineer for the try page as JSON: a channel it cannot open yet (or a join code it does
- * not know) answers {"error", "error_description", "next"}, which stops here with that next step.
+ * Asks flow.engineer's /try page for its direct link as JSON ({"channel", "message", "link", "page"}):
+ * a channel it cannot open yet (or a join code it does not know) answers {"error",
+ * "error_description", "next"}, which stops here with that next step.
  */
-async function checkTryPage(url) {
+async function directLink(url) {
     let response;
     try {
         response = await fetch(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
@@ -566,14 +873,18 @@ async function checkTryPage(url) {
             throw new TimedOut(url, REQUEST_TIMEOUT_MS);
         throw error;
     }
-    if (response.ok)
-        return void (await response.body?.cancel());
     const text = await response.text();
     let body = {};
     try {
         body = JSON.parse(text);
     }
     catch { }
+    if (response.ok) {
+        const { link, message, page } = body;
+        if (typeof link === "string" && link && typeof message === "string" && message)
+            return { link, message, page: typeof page === "string" && page ? page : url };
+        throw new Stop("bad_answer", `${url} answered without a link.`, undefined, EXIT.refused);
+    }
     const code = typeof body.error === "string" ? body.error : `http_${response.status}`;
     const detail = typeof body.error_description === "string" ? body.error_description : `${url} answered ${response.status}.`;
     throw new Stop(code, detail, typeof body.next === "string" && body.next ? body.next : undefined, EXIT.refused);