@flow-engineer/flow 0.2.0 → 0.2.2

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

@@ -0,0 +1,3 @@
+export declare const CHAT_LINE = "  flow chat [--channel <name>] [--person <phone>] [--json]\n                            Talk to the agent in this folder from the terminal: one message per line\n                            of stdin, no account needed (only the model key in .env)";
+/** Runs `flow chat`; resolves to the exit status. */
+export declare function chatCli(args: string[], input?: NodeJS.ReadableStream): Promise<number>;

package/dist/testing/src/chat.js

@@ -0,0 +1,125 @@
+// `flow chat`: talk to the agent in this folder from the terminal, with no account and no channel.
+// It builds the agent from src/agent.ts (buildAgent({ events }), as `flow test` does) with the
+// model key in .env, and writes as the agent's first test person, the way the playground does
+// (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, 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) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync } from "node:fs";
+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
+                            of stdin, no account needed (only the model key in .env)`;
+const USAGE = `Usage:\n${CHAT_LINE}
+
+Writes as the agent's first test person (createAgent({ testPeople })) on its first channel, unless
+--person or --channel says otherwise. Exit status: 0 done, 1 usage or the agent could not be built.`;
+/** Runs `flow chat`; resolves to the exit status. */
+export async function chatCli(args, input = process.stdin) {
+    let values;
+    try {
+        ({ values } = parseArgs({ args, strict: true, options: { channel: { type: "string" }, person: { type: "string" }, json: { type: "boolean", default: false }, help: { type: "boolean", short: "h", default: false } } }));
+    }
+    catch (error) {
+        console.error(`flow chat: ${error.message.split(". ")[0]}\n\n${USAGE}`);
+        return 1;
+    }
+    if (values.help) {
+        console.log(USAGE);
+        return 0;
+    }
+    loadEnv(undefined);
+    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 {
+        const module = await import(__rewriteRelativeImportExtension(pathToFileURL(file).href));
+        if (typeof module.buildAgent !== "function")
+            throw new Error("src/agent.ts must export buildAgent({ events }).");
+        agent = module.buildAgent({ events: [(event) => turns.forEach((listener) => listener(event))] });
+    }
+    catch (error) {
+        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)
+        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 (!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)
+        process.stderr.write("you: ");
+    let conversationId;
+    for await (const line of lines) {
+        const text = line.trim();
+        if (text) {
+            const taken = await agent.simulate({ person: person.phone, channel: channel.name, message: text });
+            if (taken)
+                await agent.conversation((conversationId = taken.conversationId))?.whenIdle();
+        }
+        if (prompt)
+            process.stderr.write("you: ");
+    }
+    // A tool still running in the background answers in a turn of its own: wait for it before leaving.
+    while (conversationId && agent.status().backgroundTasks > 0) {
+        await new Promise((done) => turns.push((event) => event.type === "task.done" && done()));
+        await agent.conversation(conversationId)?.whenIdle();
+    }
+    await agent.flushTraces();
+    return 0;
+}
+/** One thing the agent sent, as a person would read it (or one JSON line). */
+function print(outbound, channel, json) {
+    if (outbound.type === "typing" || outbound.type === "status" || outbound.type === "read")
+        return;
+    if (json)
+        return void process.stdout.write(`${JSON.stringify({ channel, ...outbound })}\n`);
+    if (outbound.type === "reaction")
+        return void process.stdout.write(`agent reacted ${outbound.emoji}\n`);
+    if (outbound.type === "template")
+        return void process.stdout.write(`agent: [template ${outbound.name}]\n`);
+    const extra = [
+        outbound.image && `[photo ${outbound.image.url}]`,
+        outbound.link && `[${outbound.link.label}: ${outbound.link.url}]`,
+        outbound.buttons?.map((b) => `[${b}]`).join(" "),
+        outbound.list && `[${outbound.list.button}: ${outbound.list.rows.map((r) => r.title).join(" | ")}]`,
+    ].filter(Boolean);
+    process.stdout.write(`agent: ${[outbound.text, ...extra].filter(Boolean).join(" ")}\n`);
+}

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/chinwag.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 // The `chinwag` command from before the rename, kept for one release: it says so on stderr (stdout
 // stays the report's, for --json), then runs the flow command (testing/src/cli.ts) as it is.
-console.error("chinwag is now Flow Framework (@flow-engineer/flow): run npx flow, and npm i @flow-engineer/flow.");
+console.error("chinwag is now Flow Framework (@flow-engineer/flow): run npx @flow-engineer/flow, and npm i @flow-engineer/flow.");
 await import("./cli.js");
 export {};

package/dist/testing/src/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-// The flow command. `flow new <name>` makes ./<name>/, an agent started from the café example
-// (testing/src/new.ts). `flow test`, or `flow` with flags, runs an agent's tests in the cloud,
+// The flow command. `flow new <name>` makes ./<name>/, an agent started from the café example, and
+// `flow init` the same agent in the current folder (testing/src/new.ts). `flow chat` talks to the
+// agent in this folder from the terminal (testing/src/chat.ts). `flow test`, or `flow` with flags, runs an agent's tests in the cloud,
 // from the agent's folder:
 //   flow test [--cloud https://flow.engineer/observe] [--runs 3] [--only late-order,refund | --failed] [--json]
 // A hosted cloud (any --cloud off this machine, the default included) needs the
@@ -15,6 +16,8 @@
 // (what each run ended as and the judge's reasons, never the messages), and --failed runs again the
 // scenarios that did not pass. --json prints one report (testing/src/report.ts) on stdout at every exit,
 // and `flow show <run>` prints one run's record from the cloud (testing/src/show.ts).
+// `flow login`, `logout`, `whoami`, `setup` and `link` sign in to flow.engineer and get the agent's
+// keys and its phone link (testing/src/account.ts).
 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) {
@@ -29,22 +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 { 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";
+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)
@@ -91,15 +110,29 @@ with the judge's reasons. Never the messages. The folder is git-ignored and the
 Environment (also read from the agent folder's .env, or --dotenv; variables already set win;
 the CHINWAG_ names from before the rename still work):
   FLOW_FRAMEWORK_CLOUD     The test cloud, when --cloud is not given
-  FLOW_FRAMEWORK_CLOUD_KEY The agent's CI key, for a hosted cloud (oci_...: make one at
-                           https://flow.engineer/observe, your agent, Developers)
+  FLOW_FRAMEWORK_CLOUD_KEY The agent's CI key, for a hosted cloud (oci_...: flow setup
+                           writes it, or make one at https://flow.engineer/observe, your agent, Developers)
   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${TEST_LINE}\n${SHOW_LINE}\n${CHECK_LINE}\n  flow --version            Show the version\n\n${TEST_OPTIONS}`;
+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);
@@ -107,6 +140,24 @@ 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] ?? ""))
+    process.exit(await accountCli(process.argv[2], process.argv.slice(3)));
 const TEST_FLAGS = {
     cloud: { type: "string" },
     runs: { type: "string", default: "1" },
@@ -134,23 +185,59 @@ if (values.version) {
     process.exit(0);
 }
 if (values.help || process.argv.length <= 2) {
-    console.log(command === "new" ? NEW_USAGE : command === "test" ? TEST_USAGE : USAGE);
+    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
-  2. Add one model key: cp .env.example .env; the file says where to make one
-  3. npm start, then open the link it prints
-  4. Tell your coding agent what to build: its skills are in .claude/skills/`);
+${nextSteps()}`);
+    process.exit(0);
+}
+if (command === "init") {
+    let name;
+    try {
+        if (rest.length)
+            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);
+    }
+    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
+${nextSteps()}`);
     process.exit(0);
 }
 /** Every human line of `flow test`: stdout, or stderr with --json, where stdout is the report. */
@@ -183,7 +270,7 @@ try {
     });
 }
 catch (error) {
-    const where = !ciKey && cloud.replace(/\/+$/, "") === OBSERVE_URL ? ` Make a key at ${OBSERVE_URL}: your agent, Developers.` : "";
+    const where = !ciKey && cloud.replace(/\/+$/, "") === OBSERVE_URL ? " Run npx @flow-engineer/flow login, then npx @flow-engineer/flow setup, to get one into .env." : "";
     invalid(`${error.message}${where}`);
 }
 const dir = process.cwd();
@@ -499,8 +586,8 @@ 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";
-    const options = isNew ? { help: TEST_FLAGS.help, version: TEST_FLAGS.version } : TEST_FLAGS;
+    const isNew = process.argv[2] === "new" || process.argv[2] === "init";
+    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/client.d.ts

@@ -34,6 +34,8 @@ export interface ConnectOptions {
     retryBudgetMs?: number;
     /** How long a lost stream keeps trying to resume, on a cloud that resumes (Opened.resume). Default 2 minutes, as long as the cloud holds its commands. */
     resumeWindowMs?: number;
+    /** The clock the resume window is measured on. Default Date.now; a test passes one it moves itself. */
+    now?: () => number;
     /** How often a resumable stream is replaced, before the tunnel's one-hour request cap. Default 50 minutes. */
     streamRefreshMs?: number;
     /** The longest Retry-After a busy cloud's refused open is sent again after, once. Default 60s. */

package/dist/testing/src/client.js

@@ -204,6 +204,7 @@ async function playSession(options, only) {
     const retryBudgetMs = options.retryBudgetMs ?? RETRY_BUDGET_MS;
     const openRetryCapMs = options.openRetryCapMs ?? OPEN_RETRY_CAP_MS;
     const resumeWindowMs = options.resumeWindowMs ?? RESUME_WINDOW_MS;
+    const now = options.now ?? Date.now;
     const streamRefreshMs = options.streamRefreshMs ?? STREAM_REFRESH_MS;
     let idempotent = false;
     const base = options.cloud.replace(/\/$/, "");
@@ -536,13 +537,13 @@ async function playSession(options, only) {
         /** The stream opened again after the last command handled, with backoff, until the resume window closes. */
         const reconnect = async (why) => {
             log(`stream ${why}; resuming after command ${lastId}`);
-            const deadline = Date.now() + resumeWindowMs;
+            const deadline = now() + resumeWindowMs;
             let last;
             for (let attempt = 0;; attempt++) {
                 const backoff = attempt === 0 ? 0 : Math.min(10_000, 250 * 2 ** attempt) * (0.8 + Math.random() * 0.4);
                 const refused = last instanceof Error && last.cause instanceof PostError ? last.cause : undefined;
                 const wait = Math.max(backoff, refused?.retryAfterMs ?? 0);
-                if (Date.now() + wait >= deadline) {
+                if (now() + wait >= deadline) {
                     const detail = last instanceof Error ? `; last try: ${last.message}` : "";
                     throw new StreamLost(`the stream did not resume within ${resumeWindowMs / 1000}s (${why})${detail}`);
                 }
@@ -550,7 +551,7 @@ async function playSession(options, only) {
                 if (failure)
                     throw failure;
                 try {
-                    return await openStream(streamUrl, { ...auth, "last-event-id": String(lastId) }, controller.signal, Math.max(1, Math.min(postTimeoutMs, deadline - Date.now())));
+                    return await openStream(streamUrl, { ...auth, "last-event-id": String(lastId) }, controller.signal, Math.max(1, Math.min(postTimeoutMs, deadline - now())));
                 }
                 catch (error) {
                     if (failure)