@flow-engineer/flow 0.2.1 → 0.2.2

package/dist/testing/src/chat.js

@@ -4,8 +4,10 @@
 // (agent.simulate). Each line read from stdin is one message; the agent's replies are printed once
 // its turn is over, so it works typed by a person or piped by a coding agent:
 //   printf 'hi\nA latte please\n' | npx @flow-engineer/flow chat
-// --json prints each thing the agent sends as one JSON line. The conversation lives only as long as
-// the command. Exit status: 0 done (stdin ended), 1 usage or the agent could not be built.
+// --json prints each thing the agent sends as one JSON line, and an error as
+// {"error":{"code","message","next"}} (no_model_key, no_agent, not_built, no_test_people,
+// no_channel). The conversation lives only as long as the command. Exit status: 0 done (stdin
+// ended), 1 usage or the agent could not be built.
 var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
     if (typeof path === "string" && /^\.\.?\//.test(path)) {
         return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
@@ -19,6 +21,7 @@ import { join } from "node:path";
 import { createInterface } from "node:readline";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
+import { NO_MODEL_KEY } from "../../src/model.js";
 import { loadEnv } from "./report.js";
 export const CHAT_LINE = `  flow chat [--channel <name>] [--person <phone>] [--json]
                             Talk to the agent in this folder from the terminal: one message per line
@@ -42,11 +45,17 @@ export async function chatCli(args, input = process.stdin) {
         return 0;
     }
     loadEnv(undefined);
-    const file = join(process.cwd(), "src", "agent.ts");
-    if (!existsSync(file)) {
-        console.error(`flow chat: no src/agent.ts here. Run it from your agent's folder (npx @flow-engineer/flow init makes one).`);
+    const json = values.json === true;
+    /** Stops with exit 1: the sentence on stderr, and with --json the error as one JSON line on stdout. */
+    const fail = (code, message, next, nextLine = next ? `Next: ${next}` : undefined) => {
+        console.error(`flow chat: ${message}${nextLine ? `\n${nextLine}` : ""}`);
+        if (json)
+            process.stdout.write(`${JSON.stringify({ error: { code, message, next: next ?? null } })}\n`);
         return 1;
-    }
+    };
+    const file = join(process.cwd(), "src", "agent.ts");
+    if (!existsSync(file))
+        return fail("no_agent", "There is no src/agent.ts here: run it from your agent's folder.", "npx @flow-engineer/flow init", "Next: npx @flow-engineer/flow init makes one in an empty folder.");
     const turns = [];
     let agent;
     try {
@@ -56,24 +65,23 @@ export async function chatCli(args, input = process.stdin) {
         agent = module.buildAgent({ events: [(event) => turns.forEach((listener) => listener(event))] });
     }
     catch (error) {
-        console.error(`flow chat: ${error.message}`);
-        return 1;
+        if (error.code === NO_MODEL_KEY.code)
+            return fail(NO_MODEL_KEY.code, NO_MODEL_KEY.message, NO_MODEL_KEY.next, NO_MODEL_KEY.nextLine);
+        return fail("not_built", error.message);
     }
     const person = values.person ? agent.testPeople().find((p) => p.phone.replace(/\D/g, "") === values.person.replace(/\D/g, "")) : agent.testPeople()[0];
     const channel = values.channel ? agent.channels().find((c) => c.name === values.channel) : agent.channels()[0];
-    if (!person || !channel) {
-        console.error(!person
-            ? `flow chat: ${values.person ? `${values.person} is not one of the agent's testPeople` : "the agent has no testPeople"}; declare them in createAgent({ testPeople: [{ name, phone }] }).`
-            : `flow chat: ${values.channel ? `no channel named ${values.channel}` : "the agent has no channels"}; it has ${agent.channels().map((c) => c.name).join(", ") || "none"}.`);
-        return 1;
-    }
-    agent.attachPlayground(({ outbound }) => print(outbound, channel.name, values.json === true));
+    if (!person)
+        return fail("no_test_people", `${values.person ? `${values.person} is not one of the agent's testPeople` : "the agent has no testPeople"}; declare them in createAgent({ testPeople: [{ name, phone }] }).`);
+    if (!channel)
+        return fail("no_channel", `${values.channel ? `no channel named ${values.channel}` : "the agent has no channels"}; it has ${agent.channels().map((c) => c.name).join(", ") || "none"}.`);
+    agent.attachPlayground(({ outbound }) => print(outbound, channel.name, json));
     turns.push((event) => {
         if (event.type === "model.error")
             console.error(`flow chat: the model failed: ${String(event.error ?? event.message ?? "error")}`);
     });
     const prompt = process.stdin.isTTY && input === process.stdin;
-    if (!values.json)
+    if (!json)
         console.error(`Talking to the agent on ${channel.name} as ${person.name} (${person.phone}). Ctrl-D ends.`);
     const lines = createInterface({ input, terminal: false });
     if (prompt)

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

@@ -0,0 +1,4 @@
+export declare const CHECK_LINE = "  flow check [--json] [--plugin <dir>]    Check the agent's tools, CLI file and skills for MCP and the CLI";
+export declare function checkCli(argv: string[], dir?: string): Promise<number>;
+/** `flow mcp update`: loads the agent with every mcpTools call writing its server's current tools to mcp.lock.json. */
+export declare function mcpUpdateCli(dir?: string): Promise<number>;

package/dist/testing/src/check.js

@@ -0,0 +1,90 @@
+// `flow check`, from an agent's folder: whether its tools can be served over MCP exactly as
+// declared, whether its CLI file (src/cli.ts) still matches them, and whether the skills it would
+// send to MCP hosts name tools only chats have. Rules only, no model: what it reports is
+// objectively wrong (errors, exit 1) or worth a look (warnings).
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync } from "node:fs";
+import { pluginProblems } from "./plugin.js";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { cliProblems } from "../../cli/src/commands.js";
+import { CHAT_ONLY, describe, toolsProblems } from "../../mcp/src/describe.js";
+import { loadSkills, readAgentFolder } from "../../src/skills.js";
+export const CHECK_LINE = `  flow check [--json] [--plugin <dir>]    Check the agent's tools, CLI file and skills for MCP and the CLI`;
+export async function checkCli(argv, dir = process.cwd()) {
+    const json = argv.includes("--json");
+    const errors = [];
+    const warnings = [];
+    const pluginAt = argv.indexOf("--plugin");
+    const pluginDir = pluginAt >= 0 ? argv[pluginAt + 1] : undefined;
+    if (pluginAt >= 0 && (!pluginDir || pluginDir.startsWith("--")))
+        errors.push("--plugin needs its generated folder");
+    if (pluginDir)
+        errors.push(...pluginProblems(dir, resolve(dir, pluginDir)));
+    const agentFile = join(dir, "src/agent.ts");
+    if (!existsSync(agentFile)) {
+        console.error(`No src/agent.ts in ${dir}. Run flow check from the agent's folder.`);
+        return 1;
+    }
+    const agent = await import(__rewriteRelativeImportExtension(pathToFileURL(agentFile).href));
+    const tools = Array.isArray(agent.tools) ? agent.tools : [];
+    if (!Array.isArray(agent.tools))
+        errors.push("src/agent.ts exports no tools array");
+    errors.push(...toolsProblems(tools));
+    if (existsSync(join(dir, "agent"))) {
+        for (const skill of loadSkills(readAgentFolder(join(dir, "agent")))) {
+            const named = CHAT_ONLY.exec(skill.body);
+            if (named)
+                (pluginAt >= 0 ? errors : warnings).push(`skill ${skill.name}: names ${named[1]}, which MCP hosts and the CLI do not have`);
+        }
+    }
+    const cliFile = join(dir, "src/cli.ts");
+    if (existsSync(cliFile)) {
+        const cli = (await import(__rewriteRelativeImportExtension(pathToFileURL(cliFile).href))).cli;
+        if (!cli)
+            errors.push("src/cli.ts exports no cli (export const cli = defineCli({ ... }))");
+        else {
+            const described = tools.flatMap((t) => {
+                try {
+                    return [describe(t)];
+                }
+                catch {
+                    return [];
+                }
+            });
+            const found = cliProblems(cli, described);
+            errors.push(...found.errors.map((e) => `src/cli.ts: ${e}`));
+            warnings.push(...found.warnings.map((w) => `src/cli.ts: ${w}`));
+        }
+    }
+    if (json)
+        console.log(JSON.stringify({ ok: errors.length === 0, errors, warnings }));
+    else {
+        for (const e of errors)
+            console.log(`error  ${e}`);
+        for (const w of warnings)
+            console.log(`warn   ${w}`);
+        console.log(errors.length ? `${errors.length} error${errors.length === 1 ? "" : "s"}.` : `No errors in ${tools.length} tool${tools.length === 1 ? "" : "s"}.`);
+    }
+    return errors.length ? 1 : 0;
+}
+/** `flow mcp update`: loads the agent with every mcpTools call writing its server's current tools to mcp.lock.json. */
+export async function mcpUpdateCli(dir = process.cwd()) {
+    const agentFile = join(dir, "src/agent.ts");
+    if (!existsSync(agentFile)) {
+        console.error(`No src/agent.ts in ${dir}. Run flow mcp update from the agent's folder.`);
+        return 1;
+    }
+    const { UPDATE_ENV } = await import("../../mcp/src/client.js");
+    process.env[UPDATE_ENV] = "1";
+    await import(__rewriteRelativeImportExtension(pathToFileURL(agentFile).href));
+    console.error(`Updated ${join(dir, "mcp.lock.json")}. Run flow check and the tests, then commit it.`);
+    return 0;
+}

package/dist/testing/src/cli.js

@@ -32,25 +32,38 @@ import { request as httpsRequest } from "node:https";
 import { basename, dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
+import { hasModelKey, NO_MODEL_KEY } from "../../src/model.js";
+import { PLUGIN_LINE, pluginCli } from "./plugin.js";
 import { OBSERVE_URL, setting } from "../../src/traces.js";
 import { cloudHeaders, runInCloud, SessionStopped } from "./client.js";
 import { runPrinter } from "./print-run.js";
 import { checkEndpointCli } from "./check-endpoint.js";
+import { CHECK_LINE as TOOLS_CHECK_LINE, checkCli, mcpUpdateCli } from "./check.js";
 import { ACCOUNT_COMMANDS, ACCOUNT_LINES, accountCli } from "./account.js";
 import { CHAT_LINE, chatCli } from "./chat.js";
 import { httpAgent } from "./http-agent.js";
-import { initHere, newStandalone, packageRoot } from "./new.js";
+import { createInterface } from "node:readline/promises";
+import { displayNameOf, folderName, initHere, newStandalone, packageRoot } from "./new.js";
 import { EXIT, finishedOutcome, loadEnv, networkCode, reportError, runVerdict, stoppedOutcome } from "./report.js";
 import { LAST_SESSION, lastSessionIn, SHOW_LINE, showCli } from "./show.js";
 import { loadSuite, parseScenario, parseToolFile, suiteHash } from "./suite.js";
-const NEW_LINE = `  flow new <name>           Make ./<name>/, a new agent started from the café example
-  flow init                 Make that agent in the current folder, named after it`;
+const NEW_LINE = `  flow new <name> [--display-name <name>]
+                            Make ./<name>/, a new agent started from the café example
+  flow init [--display-name <name>]
+                            Make that agent in the current folder, named after it.
+                            --display-name is what people call it, such as "FlatX agent": a
+                            phone reaches it with "Hi FlatX agent (ref <code>)" (asked for when
+                            run in a terminal; else the folder's name in words)`;
 const TEST_LINE = `  flow test [options]       Run the agent's tests in a test cloud, from the agent's folder
                             (src/agent.ts exports buildAgent({ model, events, tools }) and tools;
                             the tests are in tests/scenarios and tests/tools)`;
 const CHECK_LINE = `  flow check-endpoint <url> [--token-env NAME] [--json]
                             Check an agent's HTTP endpoint against the contract, for --agent-url
                             (flow check-endpoint --help)`;
+const MCP_LINE = `  flow mcp update        Write the tools of the MCP servers the agent uses (mcpTools) to
+                            mcp.lock.json, from the agent's folder; commit it after the tests`;
+const CLI_LINE = `  flow cli --server <url> <command>
+                            Any MCP server's tools as commands (flow cli --server <url> --help)`;
 const NEW_USAGE = `Usage:\n${NEW_LINE}\n\n  -h, --help                Show this help`;
 const TEST_OPTIONS = `Options for test:
   --cloud <url>            The test cloud (default: FLOW_FRAMEWORK_CLOUD, else https://flow.engineer/observe)
@@ -102,15 +115,24 @@ the CHINWAG_ names from before the rename still work):
   FLOW_FRAMEWORK_AGENT_TOKEN
                            With --agent-url: sent to it as authorization: Bearer <token>
   OPENROUTER_API_KEY       The agent's model key, or OPENAI_API_KEY, ANTHROPIC_API_KEY or
-                           GEMINI_API_KEY: the first with a value is used`;
+                           GEMINI_API_KEY: the first with a value is used, else FLOW_KEY
+                           (the agent's Flow key, on its trial credit; flow setup writes it)`;
 const TEST_USAGE = `Usage:\n${TEST_LINE}\n\n${TEST_OPTIONS}`;
-const USAGE = `Usage:\n${NEW_LINE}\n${CHAT_LINE}\n${TEST_LINE}\n${SHOW_LINE}\n${CHECK_LINE}\n${ACCOUNT_LINES}\n  flow --version            Show the version\n\n${TEST_OPTIONS}`;
-const NEXT_STEPS = `  2. Add one model key: cp .env.example .env; the file says where to make one
-  3. npx @flow-engineer/flow chat, and type to it (or npm start for the playground)
-  4. npx @flow-engineer/flow link: signs in, writes the other keys, prints the link for your phone;
-     keep npm start running and text it
-  5. Tell your coding agent what to build: its skills are in .claude/skills/`;
+const USAGE = `Usage:\n${NEW_LINE}\n${CHAT_LINE}\n${TEST_LINE}\n${SHOW_LINE}\n${CHECK_LINE}\n${TOOLS_CHECK_LINE}\n${MCP_LINE}\n${CLI_LINE}
+${PLUGIN_LINE}\n${ACCOUNT_LINES}\n  flow --version         Show the version\n\n${TEST_OPTIONS}`;
+/** What to do after new or init, from step 2; a model key comes first when none is set here. */
+function nextSteps() {
+    const steps = [
+        ...(hasModelKey(process.env) ? [] : [`Model key: none yet. ${NO_MODEL_KEY.nextLine.replace(/^Next: r/, "R")} (in .env: cp .env.example .env; the file says where to make one)`]),
+        `npm start, and open the link it prints: try it in the playground as its test people, channels side by side`,
+        `npx @flow-engineer/flow link: signs in, writes the other keys, prints the link for your phone;\n     keep npm start running and text it`,
+        `Tell your coding agent what to build: its skills are in .claude/skills/`,
+    ];
+    return steps.map((step, i) => `  ${i + 2}. ${step}`).join("\n");
+}
 checkNode(process.versions.node);
+if (process.argv[2] === "plugin")
+    process.exit(pluginCli(process.argv.slice(3)));
 if (process.argv[2] === "check-endpoint") {
     // Its token may be in the agent folder's .env; no value is ever printed.
     loadEnv(undefined);
@@ -118,6 +140,20 @@ if (process.argv[2] === "check-endpoint") {
 }
 if (process.argv[2] === "show")
     process.exit(await showCli(process.argv.slice(3)));
+if (process.argv[2] === "check")
+    process.exit(await checkCli(process.argv.slice(3)));
+if (process.argv[2] === "mcp") {
+    if (process.argv[3] !== "update") {
+        console.error(MCP_LINE.trim());
+        process.exit(1);
+    }
+    process.exit(await mcpUpdateCli());
+}
+if (process.argv[2] === "cli") {
+    // Loaded only here: @flow-engineer/flow/cli needs @modelcontextprotocol/client, an optional peer.
+    const { defineCli, runCli } = await import("../../cli/src/index.js");
+    process.exit(await runCli(defineCli({ name: "flow" }), process.argv.slice(3)));
+}
 if (process.argv[2] === "chat")
     process.exit(await chatCli(process.argv.slice(3)));
 if (ACCOUNT_COMMANDS.has(process.argv[2] ?? ""))
@@ -152,34 +188,56 @@ if (values.help || process.argv.length <= 2) {
     console.log(command === "new" || command === "init" ? NEW_USAGE : command === "test" ? TEST_USAGE : USAGE);
     process.exit(0);
 }
+/** --display-name, else asked for in a terminal (Enter takes the folder's name in words), else that default. */
+async function askDisplayName(given, packageName) {
+    if (given !== undefined || !process.stdin.isTTY || !process.stdout.isTTY)
+        return given;
+    const fallback = displayNameOf(undefined, packageName);
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question(`What should people call your agent? Their phone says "Hi <it>" (Enter for "${fallback}"): `)).trim() || undefined;
+    }
+    finally {
+        rl.close();
+    }
+}
+const namedLine = (dir) => {
+    const displayName = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")).displayName;
+    return `People call it "${displayName}" (package.json displayName): a phone reaches it with "Hi ${displayName} (ref <code>)".`;
+};
+const displayNameFlag = values["display-name"];
 if (command === "new") {
     const name = rest.length === 1 ? rest[0] : "";
+    let dir;
     try {
-        newStandalone(name);
+        if (!name)
+            throw new Error("Usage: flow new <name> [--display-name <name>]");
+        dir = newStandalone(name, { displayName: await askDisplayName(displayNameFlag, name) });
     }
     catch (error) {
-        console.error(name ? error.message : "Usage: flow new <name>");
+        console.error(error.message);
         process.exit(1);
     }
-    console.log(`Made ./${name}/ from the café example (Pip). Next:
+    console.log(`Made ./${name}/ from the café example (Pip). ${namedLine(dir)} Next:
   1. cd ${name} && npm install
-${NEXT_STEPS}`);
+${nextSteps()}`);
     process.exit(0);
 }
 if (command === "init") {
     let name;
     try {
         if (rest.length)
-            throw new Error("Usage: flow init (it makes the agent in the current folder; flow new <name> makes a folder for it)");
-        name = initHere();
+            throw new Error("Usage: flow init [--display-name <name>] (it makes the agent in the current folder; flow new <name> makes a folder for it)");
+        name = initHere(process.cwd(), { displayName: await askDisplayName(displayNameFlag, folderName(process.cwd())) });
     }
     catch (error) {
         console.error(error.message);
         process.exit(1);
     }
-    console.log(`Made ${name}, started from the café example (Pip), in this folder. Next:
+    loadEnv(undefined); // a .env already here may hold a model key
+    console.log(`Made ${name}, started from the café example (Pip), in this folder. ${namedLine(process.cwd())} Next:
   1. npm install
-${NEXT_STEPS}`);
+${nextSteps()}`);
     process.exit(0);
 }
 /** Every human line of `flow test`: stdout, or stderr with --json, where stdout is the report. */
@@ -529,7 +587,7 @@ function stoppedReason(error, cloud) {
 /** The command's flags, or exits 1 with what is wrong and that command's usage. */
 function parseCommandLine() {
     const isNew = process.argv[2] === "new" || process.argv[2] === "init";
-    const options = isNew ? { help: TEST_FLAGS.help, version: TEST_FLAGS.version } : TEST_FLAGS;
+    const options = isNew ? { help: TEST_FLAGS.help, version: TEST_FLAGS.version, "display-name": { type: "string" } } : TEST_FLAGS;
     try {
         return parseArgs({ allowPositionals: true, strict: true, options: options });
     }

package/dist/testing/src/flow-login.d.ts

@@ -57,6 +57,18 @@ export interface Account {
     email: string;
     account: string;
 }
+/** setup's flow_key: the agent's one Flow key, for this mode (test or live). */
+export interface FlowKey {
+    env?: string;
+    value?: string;
+    kid?: string;
+    mode?: string;
+    scopes?: string[];
+    agent_id?: string;
+    minted?: boolean;
+    /** When the key it replaced stops working (null: at once, or there was none). */
+    previous_expires_at?: string | null;
+}
 export interface SetupAnswer {
     agent_id: string;
     /** Only the keys minted in this call come back (those the request did not say it has). */
@@ -88,6 +100,15 @@ export interface SetupAnswer {
             used: number;
         };
     }>;
+    /** The agent's one Flow key (FLOW_KEY), only when made in this call: its value is shown once. */
+    flow_key?: FlowKey;
+    /** The account's Flow trial model credit, when the agent has no provider key; absent: none (warnings say why). */
+    model_credit?: {
+        limit_usd?: number;
+        left_usd?: number;
+        base_url?: string;
+        default_model?: string;
+    };
     /** The answer fields of the keys made in this call. */
     minted?: string[];
     next?: string[];
@@ -127,7 +148,19 @@ export declare function setup(url: string, token: string, request: {
     hostname: string;
     channels: string[];
     have: string[];
+    rotate?: true | string[];
+    rotate_now?: true;
 }): Promise<SetupAnswer>;
+/** GET /credit's answer: the account's Flow trial credit in US dollars. */
+export interface ModelCredit {
+    limit_usd?: number;
+    spent_usd?: number;
+    left_usd?: number;
+    default_model?: string;
+    models?: string[];
+}
+/** The credit left on the account of a FLOW_KEY; `baseURL` is Flow's model API (flowModelURL). */
+export declare function modelCredit(baseURL: string, key: string): Promise<ModelCredit>;
 /** The agent's .env names for what setup hands back; only the keys' and the join's names are sent as `have`. */
 export declare const SETUP_ENV: {
     readonly cloud_key: "FLOW_FRAMEWORK_CLOUD_KEY";

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

@@ -6,13 +6,25 @@
 //                                                authorization_pending, slow_down, expired_token, access_denied, invalid_grant
 //   POST /cli/revoke (bearer) {}              ends this token
 //   GET  /cli/whoami (bearer)                 -> {account, email, token}
-//   POST /cli/setup (bearer) {name, hostname, channels, have}
-//        -> {agent_id, cloud_key?, traces_key?, messaging_key?, join_code, account, app_id, dashboard_url, try_url,
-//            <channel>_sender?, <channel>_link? (telegram, whatsapp, imessage: each only while that shared sender
-//            is open), try_urls?, trial?, minted, next}; a 502 carries every field that worked too;
+//   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,
+//            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,
+//        minted: true, previous_expires_at}, only when made in this call (in every answer of that call, errors too;
+//        absent when have names FLOW_KEY and rotate does not); for now only the model uses it;
+//        model_credit is the account's Flow trial model credit, {limit_usd, left_usd, base_url, default_model}, when
+//        have names no provider key and the account has the credit (left_usd 0 when used up), else absent with
+//        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);
 //        429 slow_down with Retry-After; 403 for a trial limit (sandbox_allowance_used, ...), its next prose
 //        Any answer may carry warnings: up to 20 strings to show the owner as they are.
-// Every error is flat: {"error": "<code>", "error_description": "<sentence>", "next": "<command, URL or sentence>"}.
+//   GET  <model URL>/credit (bearer FLOW_KEY) -> {limit_usd, spent_usd, left_usd, default_model, models};
+//        the model URL is src/model.ts's flowModelURL (flow.engineer/llm/framework/v1); 401 invalid_api_key,
+//        403 insufficient_scope (the key lacks model), 402 trial_credit_used or trial_credit_unavailable
+// Every error is flat: {"error": "<code>", "error_description": "<sentence>", "next": "<command, URL or sentence>"}
+// (the model API's are OpenAI's shape, {"error": {message, type, code, next}}).
 // The token is opaque (fcli_...), good only for /cli/*, and sent only to the server that issued it,
 // over https (http only to this machine). Every request gives up after REQUEST_TIMEOUT_MS at most.
 import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
@@ -232,6 +244,19 @@ export async function setup(url, token, request) {
         throw refused("/cli/setup", answer, url);
     return answer.body;
 }
+/** The credit left on the account of a FLOW_KEY; `baseURL` is Flow's model API (flowModelURL). */
+export async function modelCredit(baseURL, key) {
+    let end = baseURL.length;
+    while (end > 0 && baseURL[end - 1] === "/")
+        end--;
+    const answer = await call(baseURL.slice(0, end), "/credit", { token: key, method: "GET" });
+    if (answer.status !== 200) {
+        // OpenAI's error shape: {"error": {message, code, next}}.
+        const inner = answer.body.error && typeof answer.body.error === "object" ? answer.body.error : undefined;
+        throw refused("/credit", inner ? { ...answer, body: { error: inner.code, error_description: inner.message, next: inner.next } } : answer, baseURL);
+    }
+    return answer.body;
+}
 /** The agent's .env names for what setup hands back; only the keys' and the join's names are sent as `have`. */
 export const SETUP_ENV = {
     cloud_key: "FLOW_FRAMEWORK_CLOUD_KEY",

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

@@ -2,12 +2,21 @@
 export declare function checkName(name: string): void;
 /** The @flow-engineer/flow package's folder: the root of a clone, or the installed package. */
 export declare function packageRoot(from?: string): string;
+/** The longest display name: the join message carries it (flow.engineer's /try cuts it there too). */
+export declare const MAX_DISPLAY_NAME = 60;
+/** The name people call the agent, from the package name when none was given: "my-shop" is "my shop". */
+export declare function displayNameOf(given: string | undefined, packageName: string): string;
+interface MakeOptions {
+    root?: string;
+    /** What people call the agent; the package name in words when not given. */
+    displayName?: string;
+}
 /** Makes `<into>/<name>` (the current folder by default) and returns it. */
-export declare function newStandalone(name: string, options?: {
+export declare function newStandalone(name: string, options?: MakeOptions & {
     into?: string;
-    root?: string;
 }): string;
+/** The package name `flow init` gives the agent in `dir`: the folder's name in lowercase and dashes. */
+export declare function folderName(dir: string): string;
 /** Makes the agent in `dir` (the current folder by default), named after the folder; returns its name. */
-export declare function initHere(dir?: string, options?: {
-    root?: string;
-}): string;
+export declare function initHere(dir?: string, options?: MakeOptions): string;
+export {};

package/dist/testing/src/new.js

@@ -3,7 +3,8 @@
 // "@flow-engineer/flow/simulators" and "@flow-engineer/flow/flow-messaging", and the coding-agent
 // skills go in .claude/skills/, with an AGENTS.md (and a CLAUDE.md importing it) pointing at them.
 // `flow init` makes the same agent in the current folder. Inside a clone, `npm run new -- <name>`
-// makes agents/<name>/ instead.
+// makes agents/<name>/ instead. `--display-name` is what people call the agent ("FlatX agent"), kept
+// as package.json's displayName: the message a phone sends to reach it is "Hi <it> (ref <code>)".
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -38,8 +39,10 @@ const TSCONFIG = {
     },
     include: ["src"],
 };
-const ENV_EXAMPLE = `# One model key. The first line with a value is the one used.
-# Make it at the provider, then paste it here. Never commit this file.
+const ENV_EXAMPLE = `# The model key. The first line with a value is the one used. npx @flow-engineer/flow setup writes
+# FLOW_KEY, the agent's one Flow key, which calls models on the account's free trial credit, so no
+# provider key is needed; your own, made at the provider and pasted on its line, wins over it.
+# Never commit this file.
 #   OPENROUTER_API_KEY   https://openrouter.ai/keys
 #   OPENAI_API_KEY       https://platform.openai.com/api-keys
 #   ANTHROPIC_API_KEY    https://console.anthropic.com/settings/keys
@@ -48,6 +51,7 @@ OPENROUTER_API_KEY=
 OPENAI_API_KEY=
 ANTHROPIC_API_KEY=
 GEMINI_API_KEY=
+FLOW_KEY=
 
 # Optional. The model id for that provider; empty is that provider's default.
 # CAFE_MODEL=
@@ -64,39 +68,61 @@ const agentsMd = (name) => `# ${name}
 
 A chat agent on Flow Framework (https://github.com/flow-engineer/flow), started from its café example (Pip).
 
-- Load the skills in \`.claude/skills/\` before changing it: \`flow-framework\` to build the agent, \`flow-framework-tools\`
-  for its tools and their test files, \`flow-framework-tests\` for its test scenarios.
+- Load the skills in \`.claude/skills/\` before changing it: \`flow-framework\` to build the agent (and its MCP
+  server and CLI), \`flow-framework-tools\` for its tools and their test files, \`flow-framework-tests\` for its test
+  scenarios, \`flow-framework-context\` to gather what the tools are written from out of an existing
+  codebase, and \`flow-framework-auth\` for sign-in.
 - \`agent/AGENTS.md\` is the agent's own prompt, not instructions for coding agents.
-- The owner puts one model key in \`.env\` (never read or print it): \`OPENROUTER_API_KEY\`,
-  \`OPENAI_API_KEY\`, \`ANTHROPIC_API_KEY\` or \`GEMINI_API_KEY\`. Then \`npx @flow-engineer/flow chat\`
-  talks to it in the terminal, \`npm start\` runs it in the playground, and \`npx @flow-engineer/flow link\`
-  signs in, puts its other keys in \`.env\` and prints the link that reaches it from a phone while
-  \`npm start\` runs. \`npm run typecheck\` checks the types, \`npm test -- --synthetic\` runs the
-  tests in the test cloud at https://flow.engineer/observe with the owner's \`FLOW_FRAMEWORK_CLOUD_KEY\`
+- The model key goes in \`.env\` (never read or print it): \`npx @flow-engineer/flow link\` (or \`setup\`)
+  writes \`FLOW_KEY\`, the agent's one Flow key, which calls models on Flow's free trial credit, so no provider key is needed; a key the owner types
+  (\`OPENROUTER_API_KEY\`, \`OPENAI_API_KEY\`, \`ANTHROPIC_API_KEY\` or \`GEMINI_API_KEY\`) wins over it. \`npm start\` runs it in the playground,
+  and \`npx @flow-engineer/flow link\` signs in, puts its other keys in \`.env\` and prints the link that
+  reaches it from a phone while \`npm start\` runs.
+- When the owner asks how to test it, recommend first the playground (\`npm start\`, then open the link
+  it prints: the test people and the channels side by side), then their phone (the \`link\`).
+- Your own checks, not the owner's way to test: \`npx @flow-engineer/flow chat\` talks to it in the
+  terminal, \`npm run typecheck\` checks the types, \`npm test -- --synthetic\` runs the tests in the
+  test cloud at https://flow.engineer/observe with the owner's \`FLOW_FRAMEWORK_CLOUD_KEY\`
   (\`npx @flow-engineer/flow --help\`).
 - The guide for coding agents, with exit codes and next steps: https://github.com/flow-engineer/flow/blob/main/docs/agents.md
+- \`npm run mcp\` serves the same tools as an MCP server (src/mcp.ts) and \`npm run cli -- --help\` is
+  its command line (src/cli.ts). \`npx flow check\` checks the tools and the CLI file for both.
 `;
+/** The longest display name: the join message carries it (flow.engineer's /try cuts it there too). */
+export const MAX_DISPLAY_NAME = 60;
+/** The name people call the agent, from the package name when none was given: "my-shop" is "my shop". */
+export function displayNameOf(given, packageName) {
+    const name = (given ?? "").replace(/[()]/g, " ").replace(/\s+/g, " ").trim();
+    if (name.length > MAX_DISPLAY_NAME)
+        throw new Error(`--display-name is at most ${MAX_DISPLAY_NAME} characters, such as "FlatX agent".`);
+    return name || packageName.replace(/-/g, " ");
+}
 /** Makes `<into>/<name>` (the current folder by default) and returns it. */
 export function newStandalone(name, options = {}) {
     checkName(name);
+    const displayName = displayNameOf(options.displayName, name);
     const dir = join(options.into ?? process.cwd(), name);
     if (existsSync(dir))
         throw new Error(`${dir} already exists: pick another name or remove it.`);
-    makeAgent(dir, name, options.root ?? packageRoot());
+    makeAgent(dir, name, displayName, options.root ?? packageRoot());
     return dir;
 }
 /** What `flow init` writes into a folder; it refuses a folder that holds any of them, so nothing is overwritten. */
 const MADE = ["package.json", "tsconfig.json", "src", "agent", "tests", ".env.example", "AGENTS.md", "CLAUDE.md", ".npmrc"];
+/** The package name `flow init` gives the agent in `dir`: the folder's name in lowercase and dashes. */
+export function folderName(dir) {
+    return basename(dir).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "my-agent";
+}
 /** Makes the agent in `dir` (the current folder by default), named after the folder; returns its name. */
 export function initHere(dir = process.cwd(), options = {}) {
     const taken = MADE.filter((f) => existsSync(join(dir, f)));
     if (taken.length)
         throw new Error(`${dir} has ${taken.join(", ")} already: run flow init in an empty folder, or flow new <name> to make one.`);
-    const name = basename(dir).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "my-agent";
-    makeAgent(dir, name, options.root ?? packageRoot());
+    const name = folderName(dir);
+    makeAgent(dir, name, displayNameOf(options.displayName, name), options.root ?? packageRoot());
     return name;
 }
-function makeAgent(dir, name, root) {
+function makeAgent(dir, name, displayName, root) {
     const cafe = join(root, "examples", "cafe");
     for (const part of ["agent", "src", "tests"])
         cpSync(join(cafe, part), join(dir, part), { recursive: true });
@@ -105,21 +131,29 @@ function makeAgent(dir, name, root) {
         const source = readFileSync(path, "utf8")
             .replace(/(["'])(\.\.\/)+src\/index\.ts\1/g, '"@flow-engineer/flow"')
             .replace(/(["'])(\.\.\/)+simulators\/src\/index\.ts\1/g, '"@flow-engineer/flow/simulators"')
-            .replace(/(["'])(\.\.\/)+flow-messaging\/src\/index\.ts\1/g, '"@flow-engineer/flow/flow-messaging"');
-        if (/["']\.\.\/\.\.\//.test(source))
+            .replace(/(["'])(\.\.\/)+flow-messaging\/src\/index\.ts\1/g, '"@flow-engineer/flow/flow-messaging"')
+            .replace(/(["'])(\.\.\/)+mcp\/src\/index\.ts\1/g, '"@flow-engineer/flow/mcp"')
+            .replace(/(["'])(\.\.\/)+cli\/src\/index\.ts\1/g, '"@flow-engineer/flow/cli"');
+        // The CLI is the agent's own command, named after it.
+        const text = file === "cli.ts" ? source.replace(/name: "cafe"/, `name: "${name}"`).replace(/CAFE_SERVER/g, `${name.toUpperCase().replace(/-/g, "_")}_SERVER`) : source;
+        if (/["']\.\.\/\.\.\//.test(text))
             throw new Error(`flow: ${file} imports a file outside the agent; only Flow Framework's public entries can be rewritten.`);
-        writeFileSync(path, source);
+        writeFileSync(path, text);
     }
     const own = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
     const pkg = {
         name,
+        // What people call it: the message a phone sends to reach it is "Hi <displayName> (ref <code>)".
+        displayName,
         version: "0.1.0",
         private: true,
         description: `${name}: a Flow Framework agent, started from the café example.`,
         type: "module",
+        bin: { [name]: "src/cli.ts" },
         engines: own.engines,
-        scripts: { start: "node --env-file-if-exists=.env src/main.ts", test: "flow test", typecheck: "tsc --noEmit" },
-        dependencies: { "@flow-engineer/flow": `^${own.version}` },
+        scripts: { start: "node --env-file-if-exists=.env src/main.ts", mcp: "node src/mcp.ts", cli: "node src/cli.ts", test: "flow test", typecheck: "tsc --noEmit" },
+        // The café serves its tools over MCP (src/mcp.ts) and as a CLI (src/cli.ts): their SDKs, pinned as Flow Framework pins them.
+        dependencies: { "@flow-engineer/flow": `^${own.version}`, ...own.peerDependencies },
         devDependencies: { "@types/node": own.devDependencies["@types/node"], typescript: own.devDependencies.typescript },
     };
     writeFileSync(join(dir, "package.json"), `${JSON.stringify(pkg, null, 2)}\n`);

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

@@ -0,0 +1,4 @@
+export declare const PLUGIN_LINE = "  flow plugin --server <url> --out <dir>  Write Claude Code and Agent Plugins packages";
+export declare function pluginProblems(dir: string, out: string): string[];
+export declare function writePlugins(dir: string, server: string, out: string, name?: string): void;
+export declare function pluginCli(argv: string[], dir?: string): number;