@flow-engineer/flow 0.3.2 → 0.3.4

package/README.md

@@ -50,7 +50,7 @@ Test it first in the playground (the link `npm start` prints: the test people an
 
 **Stability.** 0.x: the CLI's commands, `--json` fields and exit codes in [docs/agents.md](docs/agents.md) stay compatible within 0.2.x; a breaking change comes with a minor version bump and a release note. Pin the version in `package.json` for production.
 
-**Host it.** Coming soon: `npx @flow-engineer/flow deploy`, to keep the agent answering while the laptop sleeps.
+**Host it.** `npx @flow-engineer/flow deploy` puts the agent on Flow's hosting, so it keeps answering while the laptop sleeps: staging first, then `deploy promote` to production; `deploy secrets --from-env .env` sends its keys as secrets. `deploy status` shows what is live and its URL, `flow logs` its log lines. It needs the agent's CI key (`FLOW_FRAMEWORK_CLOUD_KEY`, which `flow setup` writes) and a `buildAgent` that passes `options.host` on to `createAgent` ([docs/agents.md](docs/agents.md), "Host it").
 
 ### In a folder of your own
 
@@ -408,13 +408,18 @@ Each run's line carries its id (`FAIL  latte-correction #1 (whatsapp) trn_…: 6
   "runs": [
     { "runId": "trn_…", "scenario": "latte-correction", "channel": "whatsapp", "run": 1, "verdict": "failed",
       "error": null, "ended": "goal_met", "turns": 6, "watch": "https://…",
-      "failedChecks": [{ "kind": "judge", "text": "The agent asks Sam to confirm before placing the order.", "reason": "…" }] }
-  ]
+      "failedChecks": [{ "kind": "judge", "text": "The agent asks Sam to confirm before placing the order.", "reason": "…" }],
+      "invalid": null }
+  ],
+  "invalid": [],
+  "sessionInvalid": null
 }
 ```
 
 `outcome` is `passed` (exit 0), `failed` or `invalid` (1), `errored` or `transport` (2), `refused` (3) or `interrupted` (130). A run's `verdict` is `errored` whenever the cloud names an `error` for it (such as `judge_failed`, `simulator_failed` or `spend_cap`), whatever it `ended` as: the cloud could not play or judge it, so it says nothing about the agent. Its line reads `ERROR` instead of `PASS` or `FAIL`, and the run's `error` is that code (else `null`). `error` is `{ "message", "status", "type", "retryAfterSeconds" }` when the session did not finish (`type` is the cloud's code, such as `spend_cap`; the others are `null` when it did not say).
 
+A scenario the cloud cannot play (a key it does not know, a value it cannot read) does not stop the others: its runs are `errored` with `error` `scenario_invalid` and `invalid` `{ "path", "reason" }` (the reason starts `unsupported:` when the cloud does not know a key), its line reads `INVALID` with the file and what is wrong, and the top-level `invalid` lists each such scenario once as `{ "scenario", "path", "reason" }`. When the cloud ends the whole session `scenario_invalid` (a tools or checks file it cannot read, or an older cloud), `sessionInvalid` is `{ "reason", "olderCloud", "sent" }`: what the cloud said after the code (else `null`), whether that suggests a cloud older than this client, and the scenarios sent as `{ "scenario", "path" }`; the same lines are printed.
+
 `--only latte-correction,order-fails` runs only those scenarios (file names without `.yaml`); every tool file still goes. Once the session has opened, every exit (0, 1, 2, 3 or 130) writes `.flow/last-session.json` in the agent's folder and prints its path; `flow new` git-ignores `.flow/`. It holds what each run ended as and the judge's reasons, never the messages (a reason can quote one, which is why the file stays on your machine; the suite is synthetic by `--synthetic`):
 
 ```json
@@ -429,6 +434,8 @@ Each run's line carries its id (`FAIL  latte-correction #1 (whatsapp) trn_…: 6
 }
 ```
 
+A run of a scenario the cloud could not play also has `invalid` (`{ "path", "reason" }`), and a session the cloud ended `scenario_invalid` has `sessionInvalid`, as in `--json`.
+
 `ended` is `finished`, `stopped` (the session broke off or the cloud stopped it) or `interrupted`. `agent` is the cloud's id for the agent (a hosted cloud names it), which `flow show` reads. `only` is the scenarios the session was limited to, `null` for the whole suite. `verdict` is `passed`, `failed`, `errored` (the cloud could not play or judge the run) or `not_played` (the session ended first; its `runId` is `null`).
 
 `flow show <run-id>` prints one run's record from the cloud, read with `FLOW_FRAMEWORK_CLOUD_KEY`: the verdict, every check with the judge's reason, then the conversation in time order with each tool call the simulator played (its input, output and what it changed). `flow show last` picks the first run in `.flow/last-session.json` that did not pass (its first run when all passed) and names the others. `--json` prints the record exactly as the cloud answered it. It exits 0 when it printed; 1 for a wrong flag, no key or last session, no such run (404) or one past the 30 days runs are kept (410); 2 when the cloud did not answer or answered 5xx; 3 when it refused the key (401, 403) or is busy (429).
@@ -641,7 +648,7 @@ cd agents/my-agent && npm start
 
 **Which channels are real?** WhatsApp, SMS and your own UI (`customUI`) have production definitions today; you plug in any provider by writing `sendMessage`. Telegram and iMessage are real through Flow Messaging (`fm.telegram()`, `fm.imessage()`, [flow-messaging/README.md](flow-messaging/README.md)); in core they are in the playground for now.
 
-**Does it host my agent?** No. It runs in your Node process, on your machine or servers. You pay your model and messaging providers directly.
+**Does it host my agent?** The framework runs in your Node process, on your machine or servers, and you pay your model and messaging providers directly. Flow's hosting can run it instead, from the same `buildAgent` that `flow test` loads: `npx @flow-engineer/flow deploy`.
 
 **Is the data mine?** Yes. State lives in your database, and events go wherever you send them.
 

package/coding-agents/skill.md

@@ -335,6 +335,7 @@ npm start                                    # after link: its playground link,
 npx @flow-engineer/flow status --json        # what the folder has and lacks, at any time
 printf 'hi\nA latte please\n' | npx @flow-engineer/flow chat   # your own check: one message per line, replies printed
 npx @flow-engineer/flow test --synthetic     # your own check: the tests, on the key setup wrote
+npx @flow-engineer/flow deploy --json        # when the owner wants it hosted: staging on Flow's cloud (see "Deploy it")
 ```
 
 When the owner asks how to test it, recommend first the playground (`npm start`, then open the
@@ -365,6 +366,38 @@ starter does this when `.env` has `FLOW_MESSAGING_KEY`. Each error is
 name the package (`npx @flow-engineer/flow ...`): `npx flow` on its own fetches another npm package.
 CI never logs in: `setup --ci` says how to give it the cloud key.
 
+## Deploy it
+
+Flow hosts Flow Framework agents: `npx @flow-engineer/flow deploy` runs the agent's folder on Flow's
+cloud, with its state kept for it, Flow Messaging's stream held, and its secrets kept apart from
+every other agent's. Do not pick a VPS, Fly or Render on the owner's behalf: ask the owner whether
+the agent goes on Flow's cloud or their own servers.
+
+On Flow's cloud the agent needs only what `flow test` already loads: `src/agent.ts` exports
+`buildAgent({ events, tools, host })` and passes `host` on to `createAgent` (`{ ...host }`), which
+brings the store and, when the agent has `FLOW_MESSAGING_KEY`, `host.messaging`. An agent that drops
+`host`, or brings a database of its own, is refused in production (a warning in staging). The CI
+key is `FLOW_FRAMEWORK_CLOUD_KEY` (`flow setup` writes it into `.env`).
+
+```sh
+npx @flow-engineer/flow deploy secrets --from-env .env --json   # the agent's keys as secrets (names printed, never values)
+npx @flow-engineer/flow deploy --json                           # staging: packs, builds, follows it to live; run its next
+npx @flow-engineer/flow deploy promote --json                   # staging's live version to production, once the owner has tried it
+npx @flow-engineer/flow deploy status --json                    # what is live in each environment: version, when, URL
+npx @flow-engineer/flow logs --since 15m                        # the hosted agent's log lines (--follow for new ones)
+printf '%s' "$VALUE" | npx @flow-engineer/flow deploy secret NAME --env production   # one secret, from stdin
+```
+
+Promote, or `deploy --env production`, only when the owner says so. A refused deploy lists the
+hosting lint's findings (`deploy.findings`): fix the errors and deploy again. Secrets take effect on
+the next deploy. Stop the laptop's `npm start` once the deployed one is live: two copies on one key
+both answer every message.
+
+On the owner's own servers: one instance, kept warm, CPU always on, a durable `database`
+(`postgres(pool)`), `await agent.resume()` at start, the secrets from the platform's secret store
+(never the `.env`), and Flow Messaging's stream (`fm.start`) with its cursor file on a disk that
+survives a restart, or its webhook (`FLOW_MESSAGING_WEBHOOK_SECRET`) on a public https address.
+
 ## Send traces to a dashboard
 
 Every turn can go to a traces endpoint as an OTLP/JSON trace, posted to `<url>/v1/traces`, so
@@ -534,7 +567,7 @@ An operation already accepted by the agent may still complete after its client s
 Enable this only in local startup code. The runner is off by default, rejects non-loopback or
 forwarded connections, and is not part of the hosted test cloud. It calls the actual CLI runner
 only locally. Hosted CLI support is deferred pending security review; do not add it to cloud startup
-or deployment wiring. See the hosted CLI TODO in the README. The runner invokes the CLI
+or deployment wiring (that is `flow deploy`). See the hosted CLI TODO in the README. The runner invokes the CLI
 without a shell: quoting works, pipelines/expansion do not. The browser cannot override server
 or token flags, or use `skill --write` to write onto the developer's computer.
 For other embedded clients, `CliConfig.directory` overrides credential/conversation storage;

package/coding-agents/test-skill.md

@@ -183,13 +183,18 @@ connects out to the cloud, which plays the person and the tools and judges.
    `runId`, `scenario`, `channel`, `run`, `verdict`, `error` (the cloud's code when it could not play
    or judge the run, such as `judge_failed`; the run is then `errored` and its line reads `ERROR`,
    whatever it ended as), `ended`, `turns`, `watch` and `failedChecks` (`kind`, `text` and the judge's
-   `reason`). Each session that opened also leaves
+   `reason`), and `invalid` (`{ path, reason }` for a scenario the cloud could not play, its error
+   `scenario_invalid` and its line `INVALID`; else `null`); top-level `invalid` lists those scenarios
+   once each (`scenario`, `path`, `reason`: fix the file; `unsupported: ...` means the cloud does not
+   know that key), and `sessionInvalid` (`reason`, `olderCloud`, `sent`) is set when the cloud ended
+   the whole session `scenario_invalid`. Each session that opened also leaves
    `.flow/last-session.json` in the agent's folder (its path is printed on every exit): `sessionId`,
    `agent`, `dashboard`, `suiteHash`, `endedAt`, `ended` (`finished`, `stopped` or `interrupted`),
    `only` (the scenarios it was limited to, else `null`) and per run `scenario` (file name without
    `.yaml`), `channel`, `run`, `runId`, `verdict` (`passed`, `failed`, `errored`: the cloud could not
    play or judge it, such as a failed tool simulator or person model, which is not a failure of your
-   agent, or `not_played`: the session ended first) and `failedChecks` (with reasons).
+   agent, or `not_played`: the session ended first), `failedChecks` (with reasons) and `invalid`
+   when the cloud could not play the scenario, plus `sessionInvalid` as in `--json`.
    Read these instead of parsing the printed lines.
    Exit status: 0 all passed; 1 a run failed, or nothing was sent (a wrong flag, a test file that does
    not parse, no key); 2 the connection or the cloud failed, or runs errored and none failed; 3 the

package/dist/testing/src/account.js

@@ -61,6 +61,8 @@ Exit status: 0 done, 1 usage or not signed in, 2 network, 3 refused, denied or e
 4 still waiting for approval (run ${RUN} login --wait), or flow.engineer asked to wait (try again after the time it gives).`;
 const NEXT = { login: `${RUN} login`, wait: `${RUN} login --wait`, setup: `${RUN} setup`, link: `${RUN} link` };
 const CHANNELS = ["telegram", "whatsapp", "imessage"];
+/** After link and status: the step that keeps the agent answering once this machine sleeps. */
+const DEPLOY_HINT = `To keep it answering while this machine sleeps: ${RUN} deploy (Flow's hosting, staging first).`;
 const EXIT = { ok: 0, usage: 1, network: 2, refused: 3, pending: 4 };
 class Stop extends Error {
     code;
@@ -824,6 +826,7 @@ async function status(json, out, say) {
     }
     if (next.length)
         say(`Next: ${next.join(", then ")}`);
+    say(DEPLOY_HINT);
 }
 /**
  * status's model line. Flow's key the active one: its credit from GET /credit. A key Flow does not
@@ -982,6 +985,7 @@ async function link(options, json, out, say) {
         if (REPLY_ONLY[c])
             say(REPLY_ONLY[c]);
     say(`Next: ${next.join(", then ")}.`);
+    say(DEPLOY_HINT);
 }
 /**
  * Asks flow.engineer's /try page for its direct link as JSON ({"channel", "message", "link", "page"}):

package/dist/testing/src/cli.js

@@ -17,7 +17,8 @@
 // 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).
+// keys and its phone link (testing/src/account.ts). `flow deploy` puts the agent on Flow's hosting
+// (testing/src/deploy.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) {
@@ -41,10 +42,11 @@ 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 { DEPLOY_LINE, deployCli, logsCli } from "./deploy.js";
 import { httpAgent } from "./http-agent.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 { EXIT, finishedOutcome, invalidLines, invalidScenarios, loadEnv, networkCode, reportError, runVerdict, sessionInvalid, sessionInvalidLines, 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> [--display-name <name>]
@@ -105,7 +107,7 @@ Exit status:
 Results: once the session has opened, every exit writes .flow/last-session.json in the agent's
 folder: the session id, the cloud's agent id, dashboard link, suite hash and time, and per run its
 scenario, channel, number, run id, verdict (passed, failed, errored or not_played) and failed checks
-with the judge's reasons. Never the messages. The folder is git-ignored and the suite synthetic.
+with the judge's reasons (and, for a scenario the cloud could not play, its file and what is wrong). Never the messages. The folder is git-ignored and the suite synthetic.
 
 Environment (also read from the agent folder's .env, or --dotenv; variables already set win;
 the CHINWAG_ names from before the rename still work):
@@ -119,7 +121,7 @@ the CHINWAG_ names from before the rename still work):
                            (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${TOOLS_CHECK_LINE}\n${MCP_LINE}\n${CLI_LINE}
-${PLUGIN_LINE}\n${ACCOUNT_LINES}\n  flow --version         Show the version\n\n${TEST_OPTIONS}`;
+${PLUGIN_LINE}\n${ACCOUNT_LINES}\n${DEPLOY_LINE}\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() {
     // link signs in and writes the keys first, FLOW_KEY (the model, on Flow's free trial credit) among
@@ -155,6 +157,10 @@ if (process.argv[2] === "cli") {
     const { defineCli, runCli } = await import("../../cli/src/index.js");
     process.exit(await runCli(defineCli({ name: "flow" }), process.argv.slice(3)));
 }
+if (process.argv[2] === "deploy")
+    process.exit(await deployCli(process.argv.slice(3)));
+if (process.argv[2] === "logs")
+    process.exit(await logsCli(process.argv.slice(3)));
 if (process.argv[2] === "chat")
     process.exit(await chatCli(process.argv.slice(3)));
 if (ACCOUNT_COMMANDS.has(process.argv[2] ?? ""))
@@ -251,6 +257,8 @@ let sessionId = "";
 let dashboard = "";
 let agentId = "";
 const seen = [];
+/** Set when the cloud ended the whole session scenario_invalid. */
+let endedInvalid = null;
 if (command !== undefined && (command !== "test" || rest.length))
     invalid(`flow: unknown command "${positionals.join(" ")}".\n\n${USAGE}`);
 const envProblem = loadEnv(values.dotenv);
@@ -381,6 +389,10 @@ catch (error) {
         end("transport", { received: error.runs, error: reportError(error, reason) });
     }
     console.error(reason);
+    endedInvalid = sessionInvalid(error, files.filter((f) => f.path.startsWith("scenarios/")).map((f) => ({ scenario: f.path.slice("scenarios/".length, -".yaml".length), path: f.path })));
+    if (endedInvalid)
+        for (const line of sessionInvalidLines(endedInvalid))
+            console.error(line);
     // The cloud stopped a session that had opened: what finished is kept, the rest is not_played.
     saveSession("stopped", seen, dashboard, console.error);
     end(stoppedOutcome(error, sessionId !== ""), { received: seen, error: reportError(error, reason) });
@@ -402,6 +414,8 @@ for (const channel of [...new Set(summary.runs.map((r) => r.channel))]) {
     const runs = summary.runs.filter((r) => r.channel === channel);
     say(`  ${channel}: ${runs.filter((r) => runVerdict(r) === "passed").length} of ${runs.length} passed`);
 }
+for (const line of invalidLines(invalidScenarios(mergedRuns(summary.runs).map((m) => ({ scenario: m.scenario, invalid: m.summary?.invalid })))))
+    say(line);
 if (summary.lost)
     say(`The cloud lost session ${summary.lost.sessionId} part way; a second session played its unfinished runs. The first: ${summary.lost.dashboard}`);
 say(`Cost: ${usd(total((r) => r.agentUsage.costUsd))} agent (${tokens(total((r) => r.agentUsage.input))} in, ${tokens(total((r) => r.agentUsage.output))} out) + ${usd(total((r) => r.testUsage.costUsd))} test models.\n${summary.dashboard}`);
@@ -432,8 +446,11 @@ function mergedRuns(received) {
         fileOf.set(scenario.id, id);
         for (let run = 1; run <= perScenario; run++) {
             for (const channel of scenario.channels) {
-                const r = byRun.get(key(scenario.id, channel, run));
+                // A scenario the cloud could not read is named by its file, not its id.
+                const r = byRun.get(key(scenario.id, channel, run)) ?? byRun.get(key(id, channel, run));
                 byRun.delete(key(scenario.id, channel, run));
+                if (r)
+                    byRun.delete(key(r.scenario, channel, run));
                 out.push(r ? merged(id, r) : { scenario: id, channel, run, verdict: "not_played" });
             }
         }
@@ -466,7 +483,9 @@ function saveSession(ended, received, link, print) {
             runId: m.summary?.runId ?? null,
             verdict: m.verdict,
             failedChecks: failedChecks(m.summary),
+            ...(m.summary?.invalid ? { invalid: m.summary.invalid } : {}),
         })),
+        ...(endedInvalid ? { sessionInvalid: endedInvalid } : {}),
     };
     const path = join(dir, LAST_SESSION);
     try {
@@ -496,6 +515,7 @@ function end(outcome, options = {}) {
             turns: m.summary?.turns ?? null,
             watch: m.summary?.watch || null,
             failedChecks: failedChecks(m.summary),
+            invalid: m.summary?.invalid ?? null,
         })) : [];
         const count = (verdict) => runs.filter((r) => r.verdict === verdict).length;
         const cost = (pick) => received.reduce((n, r) => n + pick(r), 0);
@@ -511,6 +531,8 @@ function end(outcome, options = {}) {
             counts: { runs: runs.length, passed: count("passed"), failed: count("failed"), errored: count("errored"), notPlayed: count("not_played") },
             costUsd: { agent: cost((r) => r.agentUsage.costUsd), test: cost((r) => r.testUsage.costUsd) },
             runs,
+            invalid: invalidScenarios(runs),
+            sessionInvalid: endedInvalid,
         };
         writeAll(`${JSON.stringify(report)}\n`);
     }

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

@@ -49,6 +49,8 @@ export interface ConnectOptions {
  * code (`capacity: ...` gives capacity), when it starts with one. */
 export declare class CloudEnded extends Error {
     readonly code?: string;
+    /** The cloud's error as it sent it. */
+    readonly error: string;
     constructor(error: string);
 }
 /** The tunnel, the stream, or the connection failed after the session opened. `runs` are the ones already received. The CLI prints them and exits 2. */

package/dist/testing/src/client.js

@@ -15,9 +15,12 @@ import { businessRuns } from "./business.js";
  * code (`capacity: ...` gives capacity), when it starts with one. */
 export class CloudEnded extends Error {
     code;
+    /** The cloud's error as it sent it. */
+    error;
     constructor(error) {
         super(`the cloud stopped the session: ${error}`);
         this.name = "CloudEnded";
+        this.error = error;
         this.code = /^([a-z_]+):/.exec(error)?.[1];
     }
 }

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

@@ -0,0 +1,34 @@
+export declare const DEPLOY_LINE = "  flow deploy [--env staging|production] [--dir <folder>] [--version <v>] [--json]\n                            Put this agent on Flow's hosting, so it answers while this machine\n                            sleeps (flow deploy --help: status, promote, secret, secrets)\n  flow logs [--env staging|production] [--since 1h] [--follow] [--json]\n                            The hosted agent's recent log lines";
+export declare const LOGS_USAGE = "Usage:\n  flow logs [--env staging|production] [--since 1h] [--follow] [--json]\n\n  --env        Which (default: staging).\n  --since      How far back: 30s, 15m, 1h (the default) or 2d, at most 30d.\n  --follow     Keep printing new lines until Ctrl-C.\n  --json       One JSON object per line on stdout: { time, severity, text }.\n  --dir, --cloud, FLOW_FRAMEWORK_CLOUD_KEY: as for flow deploy (flow deploy --help).";
+export declare const DEPLOY_USAGE = "Usage:\n  flow deploy [--env staging|production] [--dir <folder>] [--version <v>] [--json]\n  flow deploy promote [--json]                             staging's live version to production\n  flow deploy status [--env staging|production] [--json]   what is live, its version, when, and its URL\n  flow deploy secret <NAME> [--env staging|production]     the value on stdin\n  flow deploy secrets --from-env [<file>] [--env staging|production]\n                                                           every value in <file> (default: the agent's .env)\n\n  --env        Where (default: staging). Production takes only an agent whose buildAgent passes\n               options.host on to createAgent, with no database of its own.\n  --dir        The agent's folder (default: .): package.json, package-lock.json, src/agent.ts.\n  --version    A label for this version (default: the folder's git commit, if any).\n  --cloud      The cloud's address (default: FLOW_FRAMEWORK_CLOUD, else https://flow.engineer/observe).\n  --from-env   With secrets: send each non-empty value in the file as a secret (never the CI key,\n               the cloud's address, or a name Flow sets itself, such as the\n               FLOW_FRAMEWORK_TRACES_* that flow link writes). Prints names only.\n  --json       Print one JSON answer on stdout (progress goes to stderr).\n\nstatus shows both environments unless --env names one. The last deploy this folder made is kept\nin .flow/deploys.json (never packed).\n\nEnvironment (or the agent folder's .env):\n  FLOW_FRAMEWORK_CLOUD_KEY   The agent's CI key (oci_...): flow setup writes it, or make one on\n                             your agent's Developers page. CHINWAG_CLOUD_KEY, its older name, works too.";
+/** Names the host sets on the agent's service itself, which it refuses as secrets. */
+export declare const HOST_NAMES: RegExp;
+/**
+ * Left out of the packed folder: dependencies (the build runs npm ci), git, every .env, and the
+ * framework's local results (.flow, .chinwag before the rename), which the hosted agent never reads.
+ */
+export declare const PACK_EXCLUDES: string[];
+export declare const MAX_BUNDLE: number;
+/**
+ * A .env file's names and values: NAME=value lines, `export ` allowed, values in single or double
+ * quotes taken as written (double quotes understand \n), an unquoted value up to a ` #` comment.
+ */
+export declare function parseEnv(text: string): Map<string, string>;
+/** The agent's folder as a .tgz at `bundle`, without PACK_EXCLUDES. */
+export declare function pack(dir: string, bundle: string): void;
+export interface DeployOptions {
+    /** Where the value of `flow deploy secret` comes from (default: stdin). */
+    readStdin?: () => string;
+    /** Milliseconds between looks at a building deploy, or new log lines with --follow (default 3000). */
+    pollMs?: number;
+    /** With `flow logs --follow`: stop after this many looks (tests); default never. */
+    maxPolls?: number;
+    /** The clock, for --since (tests). */
+    now?: () => number;
+}
+/** `flow deploy ...`. */
+export declare function deployCli(argv: string[], env?: NodeJS.ProcessEnv, options?: DeployOptions): Promise<number>;
+/** `flow logs ...`. */
+export declare function logsCli(argv: string[], env?: NodeJS.ProcessEnv, options?: DeployOptions): Promise<number>;
+/** --since as seconds: 30s, 15m, 1h, 2d. */
+export declare function sinceSeconds(since: string): number | undefined;

package/dist/testing/src/deploy.js

@@ -0,0 +1,535 @@
+// `flow deploy`: puts the agent in this folder on Flow's hosting, through the cloud (observe's
+// /v1/hosting routes) with the agent's CI key. Node's own modules only.
+//
+//   flow deploy [--env staging|production] [--dir .] [--version <v>] [--json]   pack, upload, build, go live
+//   flow deploy promote [--json]                                                 staging's live version to production
+//   flow deploy status [--env staging|production] [--json]                       what is live, its version, when, its URL
+//   flow logs [--env staging|production] [--since 1h] [--follow] [--json]        the hosted agent's log lines
+//   flow deploy secret <NAME> [--env staging|production] [--json]                a secret, its value read from stdin
+//   flow deploy secrets --from-env [<file>] [--env staging|production] [--json]  every value in the agent's .env
+//
+// The folder is packed without node_modules, .git, .env files and the framework's local results
+// (.flow); its package-lock.json is installed with `npm ci` in the build, and the build runs
+// hosting's lint (its findings are printed here). Nothing here prints a key or a secret's value.
+import { execFileSync } from "node:child_process";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { RUN } from "../../src/names.js";
+const DEFAULT_CLOUD = "https://flow.engineer/observe";
+export const DEPLOY_LINE = `  flow deploy [--env staging|production] [--dir <folder>] [--version <v>] [--json]
+                            Put this agent on Flow's hosting, so it answers while this machine
+                            sleeps (flow deploy --help: status, promote, secret, secrets)
+  flow logs [--env staging|production] [--since 1h] [--follow] [--json]
+                            The hosted agent's recent log lines`;
+export const LOGS_USAGE = `Usage:
+  flow logs [--env staging|production] [--since 1h] [--follow] [--json]
+
+  --env        Which (default: staging).
+  --since      How far back: 30s, 15m, 1h (the default) or 2d, at most 30d.
+  --follow     Keep printing new lines until Ctrl-C.
+  --json       One JSON object per line on stdout: { time, severity, text }.
+  --dir, --cloud, FLOW_FRAMEWORK_CLOUD_KEY: as for flow deploy (flow deploy --help).`;
+export const DEPLOY_USAGE = `Usage:
+  flow deploy [--env staging|production] [--dir <folder>] [--version <v>] [--json]
+  flow deploy promote [--json]                             staging's live version to production
+  flow deploy status [--env staging|production] [--json]   what is live, its version, when, and its URL
+  flow deploy secret <NAME> [--env staging|production]     the value on stdin
+  flow deploy secrets --from-env [<file>] [--env staging|production]
+                                                           every value in <file> (default: the agent's .env)
+
+  --env        Where (default: staging). Production takes only an agent whose buildAgent passes
+               options.host on to createAgent, with no database of its own.
+  --dir        The agent's folder (default: .): package.json, package-lock.json, src/agent.ts.
+  --version    A label for this version (default: the folder's git commit, if any).
+  --cloud      The cloud's address (default: FLOW_FRAMEWORK_CLOUD, else ${DEFAULT_CLOUD}).
+  --from-env   With secrets: send each non-empty value in the file as a secret (never the CI key,
+               the cloud's address, or a name Flow sets itself, such as the
+               FLOW_FRAMEWORK_TRACES_* that flow link writes). Prints names only.
+  --json       Print one JSON answer on stdout (progress goes to stderr).
+
+status shows both environments unless --env names one. The last deploy this folder made is kept
+in .flow/deploys.json (never packed).
+
+Environment (or the agent folder's .env):
+  FLOW_FRAMEWORK_CLOUD_KEY   The agent's CI key (oci_...): flow setup writes it, or make one on
+                             your agent's Developers page. CHINWAG_CLOUD_KEY, its older name, works too.`;
+/** The CLI's own settings in a .env: never sent as secrets. */
+const CLI_NAMES = new Set(["FLOW_FRAMEWORK_CLOUD_KEY", "CHINWAG_CLOUD_KEY", "FLOW_FRAMEWORK_CLOUD", "CHINWAG_CLOUD"]);
+/** Names the host sets on the agent's service itself, which it refuses as secrets. */
+export const HOST_NAMES = /^(FLOW_AGENT_ID|FLOW_AGENT_NAME|FLOW_ENVIRONMENT|FLOW_STORE_URL|FLOW_STORE_TOKEN|FLOW_STORE_FRAMEWORK|FLOW_STORE_CHINWAG|FLOW_API_TOKEN|FLOW_PLAYGROUND_TOKEN|AGENT_VERSION|AGENT_DIR|PORT)$|^(FLOW_STORE_|CHINWAG_TRACES_|FLOW_FRAMEWORK_TRACES_|K_)/;
+const SECRET_NAME = /^[A-Z][A-Z0-9_]{0,63}$/;
+/** A name `secrets --from-env` sends: two characters at least, as the host takes them. */
+const ENV_SECRET_NAME = /^[A-Z][A-Z0-9_]{1,63}$/;
+/**
+ * Left out of the packed folder: dependencies (the build runs npm ci), git, every .env, and the
+ * framework's local results (.flow, .chinwag before the rename), which the hosted agent never reads.
+ */
+export const PACK_EXCLUDES = ["node_modules", ".git", ".env", ".env.*", ".DS_Store", ".flow", ".chinwag"];
+export const MAX_BUNDLE = 50 * 1024 * 1024;
+const GIVE_UP_MS = 20 * 60 * 1000;
+/**
+ * A .env file's names and values: NAME=value lines, `export ` allowed, values in single or double
+ * quotes taken as written (double quotes understand \n), an unquoted value up to a ` #` comment.
+ */
+export function parseEnv(text) {
+    const out = new Map();
+    for (const raw of text.split(/\r?\n/)) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const m = line.match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/);
+        if (!m)
+            continue;
+        let value = m[2];
+        const quote = value[0];
+        if ((quote === '"' || quote === "'") && value.lastIndexOf(quote) > 0) {
+            value = value.slice(1, value.lastIndexOf(quote));
+            if (quote === '"')
+                value = value.replace(/\\n/g, "\n");
+        }
+        else {
+            value = value.replace(/\s+#.*$/, "").trim();
+        }
+        out.set(m[1], value);
+    }
+    return out;
+}
+function readEnvFile(file) {
+    try {
+        return parseEnv(readFileSync(file, "utf8"));
+    }
+    catch {
+        return new Map();
+    }
+}
+/** The agent's folder as a .tgz at `bundle`, without PACK_EXCLUDES. */
+export function pack(dir, bundle) {
+    execFileSync("tar", ["-czf", bundle, ...PACK_EXCLUDES.map((p) => `--exclude=${p}`), "-C", dir, "."], { stdio: ["ignore", "ignore", "inherit"] });
+}
+class Refused extends Error {
+    code;
+    /** The cloud has no such route (an older Flow): a plain 404 or 405, not one of its JSON errors. */
+    missing;
+    constructor(message, code, missing = false) {
+        super(message);
+        this.code = code;
+        this.missing = missing;
+    }
+}
+class Usage extends Error {
+}
+/** What this Flow's cloud cannot do yet; the CLI side is ready for when it can. */
+class NotAvailable extends Error {
+}
+/** `flow deploy ...`. */
+export function deployCli(argv, env = process.env, options = {}) {
+    return cloudCli("deploy", argv, env, options);
+}
+/** `flow logs ...`. */
+export function logsCli(argv, env = process.env, options = {}) {
+    return cloudCli("logs", argv, env, options);
+}
+async function cloudCli(top, argv, env, options) {
+    const usage = top === "logs" ? LOGS_USAGE : DEPLOY_USAGE;
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                env: { type: "string" },
+                dir: { type: "string", default: "." },
+                version: { type: "string" },
+                cloud: { type: "string" },
+                "from-env": { type: "boolean" },
+                since: { type: "string" },
+                follow: { type: "boolean", short: "f" },
+                json: { type: "boolean" },
+                help: { type: "boolean", short: "h" },
+            },
+        });
+    }
+    catch (error) {
+        console.error(`${error.message}\n\n${usage}`);
+        return 2;
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        console.log(usage);
+        return 0;
+    }
+    const json = Boolean(values.json);
+    const say = json ? (line) => console.error(line) : (line) => console.log(line);
+    const fail = (code, message, exit, next) => {
+        if (json)
+            console.log(JSON.stringify({ ok: false, error: { code, message }, next: next ?? null }));
+        console.error(next ? `${message}\nNext: ${next}` : message);
+        return exit;
+    };
+    const command = top === "logs" ? "logs" : positionals[0];
+    const args = top === "logs" ? positionals : positionals.slice(1);
+    const given = values.env;
+    if (given !== undefined && given !== "staging" && given !== "production")
+        return fail("usage", `--env is staging or production\n\n${usage}`, 2);
+    if (command !== "logs" && (values.since !== undefined || values.follow))
+        return fail("usage", `--since and --follow go with flow logs\n\n${usage}`, 2);
+    const environment = given ?? "staging";
+    const dir = resolve(values.dir);
+    const dotEnv = readEnvFile(join(dir, ".env"));
+    const setting = (...names) => {
+        for (const name of names)
+            if (env[name])
+                return env[name];
+        for (const name of names)
+            if (dotEnv.get(name))
+                return dotEnv.get(name);
+        return undefined;
+    };
+    const key = setting("FLOW_FRAMEWORK_CLOUD_KEY", "CHINWAG_CLOUD_KEY");
+    if (!key)
+        return fail("no_ci_key", "Set FLOW_FRAMEWORK_CLOUD_KEY to your agent's CI key (oci_...), in the environment or the agent's .env.", 2, `${RUN} setup`);
+    const cloud = (values.cloud || setting("FLOW_FRAMEWORK_CLOUD", "CHINWAG_CLOUD") || DEFAULT_CLOUD).replace(/\/$/, "");
+    const api = async (method, path, body) => {
+        const res = await fetch(cloud + path, {
+            method,
+            headers: { authorization: `Bearer ${key}`, ...(body === undefined ? {} : { "content-type": "application/json" }) },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await res.text();
+        let answer = {};
+        try {
+            answer = JSON.parse(text);
+        }
+        catch {
+            // not JSON: the status says it
+        }
+        if (!res.ok) {
+            const why = answer.error?.message ?? `${res.status} ${res.statusText}`;
+            const missing = (res.status === 404 || res.status === 405) && typeof answer.error?.code !== "string";
+            throw new Refused(answer.error?.hint ? `${why} (${answer.error.hint})` : why, answer.error?.code ?? "refused", missing);
+        }
+        return answer;
+    };
+    const ctx = { api, say, json, dir, pollMs: options.pollMs ?? 3000, maxPolls: options.maxPolls, now: options.now ?? Date.now };
+    try {
+        const [name, extra] = args;
+        if (command === "logs") {
+            if (name !== undefined)
+                throw new Usage(`flow logs takes no arguments.\n\n${usage}`);
+            return await logs(ctx, environment, values.since ?? "1h", Boolean(values.follow));
+        }
+        if (extra !== undefined || (name !== undefined && command !== "secret" && command !== "secrets"))
+            throw new Usage(`Too many arguments.\n\n${usage}`);
+        if (command === "promote")
+            return await promote(ctx);
+        if (command === "status")
+            return await status(ctx, given ? [given] : ["staging", "production"]);
+        if (command === "secret")
+            return await secret(ctx, name, environment, options.readStdin ?? (() => readFileSync(0, "utf8")));
+        if (command === "secrets") {
+            if (!values["from-env"])
+                throw new Usage(`secrets takes --from-env [<file>]\n\n${usage}`);
+            return await secretsFromEnv(ctx, resolve(name ? name : join(dir, ".env")), environment);
+        }
+        if (command !== undefined)
+            throw new Usage(`Unknown command: deploy ${command}\n\n${usage}`);
+        return await deploy(ctx, dir, environment, values.version);
+    }
+    catch (error) {
+        if (error instanceof Usage)
+            return fail("usage", error.message, 2);
+        if (error instanceof NotAvailable)
+            return fail("not_available", error.message, 1);
+        if (error instanceof Refused)
+            return fail(error.code, `Refused: ${error.message}`, 1);
+        return fail("network", `Could not reach ${cloud}: ${error.message}`, 1);
+    }
+}
+async function deploy(ctx, dir, env, version) {
+    for (const file of ["package.json", "package-lock.json", "src/agent.ts"]) {
+        if (!existsSync(join(dir, file)))
+            throw new Usage(`${join(dir, file)} is missing: deploy the agent's folder (npm install makes package-lock.json).`);
+    }
+    version ??= gitVersion(dir);
+    const tmp = mkdtempSync(join(tmpdir(), "flow-deploy-"));
+    try {
+        const bundle = join(tmp, "agent.tgz");
+        pack(dir, bundle);
+        const size = statSync(bundle).size;
+        if (size > MAX_BUNDLE)
+            throw new Usage(`The packed folder is ${mb(size)}, over ${mb(MAX_BUNDLE)}. Leave large files out of it.`);
+        ctx.say(`Packed ${dir} (${mb(size)})${version ? `, version ${version}` : ""}.`);
+        const made = await ctx.api("POST", "/v1/hosting/deploys", { environment: env, ...(version ? { version } : {}) });
+        const put = await fetch(made.upload_url, { method: "PUT", headers: { "content-type": "application/gzip" }, body: readFileSync(bundle) });
+        if (!put.ok)
+            throw new Refused(`the upload failed (${put.status})`, "upload_failed");
+        await ctx.api("POST", `/v1/hosting/deploys/${made.deploy.id}/start`);
+        remember(ctx.dir, env, made.deploy.id);
+        ctx.say(`Deploy ${made.deploy.id} to ${env}: building.`);
+        return await follow(ctx, made.deploy.id);
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}
+async function promote(ctx) {
+    const { deploy } = await ctx.api("POST", "/v1/hosting/promote");
+    remember(ctx.dir, "production", deploy.id);
+    ctx.say(`Promoting staging's ${deploy.version ?? "live version"} to production (${deploy.id}).`);
+    return await follow(ctx, deploy.id);
+}
+async function secret(ctx, name, env, readStdin) {
+    if (!name || !SECRET_NAME.test(name))
+        throw new Usage(`A secret's name is upper case letters, digits and _ (like ANTHROPIC_API_KEY).\n\n${DEPLOY_USAGE}`);
+    if (process.stdin.isTTY)
+        console.error(`Paste ${name}'s value for ${env}, then press Enter and Ctrl-D:`);
+    const value = readStdin().replace(/\r?\n$/, "");
+    if (!value)
+        throw new Usage("No value on stdin.");
+    const saved = await ctx.api("PUT", `/v1/hosting/secrets/${name}`, { environment: env, value });
+    const next = `${RUN} deploy${env === "production" ? " --env production" : ""}`;
+    if (ctx.json)
+        console.log(JSON.stringify({ ok: true, secret: { name: saved.name, last4: saved.last4, environment: env }, next }));
+    ctx.say(`Saved ${saved.name} (••••${saved.last4}) for ${env}. It takes effect on the next deploy.`);
+    ctx.say(`Next: ${next}`);
+    return 0;
+}
+/** Every non-empty value in a .env file as a secret, one each; the names only are printed. */
+async function secretsFromEnv(ctx, file, env) {
+    if (!existsSync(file))
+        throw new Usage(`${file} is missing.`);
+    const entries = [...parseEnv(readFileSync(file, "utf8"))].filter(([, value]) => value !== "");
+    const saved = [];
+    const skipped = [];
+    const refused = [];
+    for (const [name, value] of entries) {
+        if (CLI_NAMES.has(name))
+            continue;
+        if (HOST_NAMES.test(name)) {
+            skipped.push({ name, why: "set by Flow" });
+            ctx.say(`  ${name} skipped (set by Flow)`);
+            continue;
+        }
+        if (!ENV_SECRET_NAME.test(name)) {
+            skipped.push({ name, why: "not upper case letters, digits and _" });
+            ctx.say(`  ${name} skipped: a secret's name is upper case letters, digits and _`);
+            continue;
+        }
+        try {
+            await ctx.api("PUT", `/v1/hosting/secrets/${name}`, { environment: env, value });
+        }
+        catch (error) {
+            if (!(error instanceof Refused))
+                throw error;
+            refused.push({ name, message: error.message });
+            ctx.say(`  ${name} refused: ${error.message}`);
+            continue;
+        }
+        saved.push(name);
+        ctx.say(`  ${name} set`);
+    }
+    const next = `${RUN} deploy${env === "production" ? " --env production" : ""}`;
+    if (ctx.json)
+        console.log(JSON.stringify({ ok: refused.length === 0, environment: env, saved, skipped, refused, next }));
+    ctx.say(saved.length ? `Saved ${saved.length} secret${saved.length === 1 ? "" : "s"} for ${env}. They take effect on the next deploy.` : `No secrets saved from ${file}.`);
+    if (saved.length)
+        ctx.say(`Next: ${next}`);
+    return refused.length ? 1 : 0;
+}
+/** Follows a deploy until it is live, refused or failed, printing each change. */
+async function follow(ctx, id) {
+    const until = Date.now() + GIVE_UP_MS;
+    let last = "";
+    for (;;) {
+        const { deploy } = await ctx.api("GET", `/v1/hosting/deploys/${id}`);
+        if (deploy.status !== last) {
+            last = deploy.status;
+            if (!["live", "refused", "failed", "replaced"].includes(deploy.status))
+                ctx.say(`  ${deploy.status}…`);
+        }
+        if (["live", "refused", "failed", "replaced"].includes(deploy.status)) {
+            for (const f of deploy.findings ?? [])
+                ctx.say(`  ${f.level === "error" ? "✗" : "!"} ${f.code}: ${f.message}`);
+            const live = deploy.status === "live" || deploy.status === "replaced";
+            const url = live ? (deploy.url ?? (await address(ctx, deploy.environment))) : null;
+            const next = !live
+                ? deploy.status === "refused"
+                    ? `fix the errors above, then ${RUN} deploy${deploy.environment === "production" ? " --env production" : ""}`
+                    : `see the deploy's page in the dashboard, then ${RUN} deploy again`
+                : deploy.environment === "staging"
+                    ? `try it in your agent's Playground (Staging) in the dashboard, then ${RUN} deploy promote`
+                    : "open your agent's Playground (Production) in the dashboard";
+            if (ctx.json) {
+                const { id: deployId, environment, status, version, findings, error } = deploy;
+                console.log(JSON.stringify({ ok: live, deploy: { id: deployId, environment, status, version, findings: findings ?? [], error }, url, next }));
+            }
+            if (live) {
+                ctx.say(`Live in ${deploy.environment}.`);
+                ctx.say(`URL: ${url ?? NO_URL}`);
+                ctx.say(`Next: ${next}`);
+                return 0;
+            }
+            if (!ctx.json)
+                console.error(deploy.status === "refused" ? "Refused: fix the errors above and deploy again." : `Failed: ${deploy.error ?? "the build or the service did not start"}.`);
+            else
+                ctx.say(deploy.status === "refused" ? "Refused." : `Failed: ${deploy.error ?? "the build or the service did not start"}.`);
+            return 1;
+        }
+        if (Date.now() > until) {
+            ctx.say(`Still ${deploy.status} after 20 minutes. Its page in the dashboard shows where it is.`);
+            return 1;
+        }
+        await new Promise((r) => setTimeout(r, ctx.pollMs));
+    }
+}
+const NO_URL = "not available on this Flow yet (the dashboard's Playground opens it)";
+/** The service's address, when the cloud tells it (GET /v1/hosting/address); null when it does not. */
+async function address(ctx, environment) {
+    try {
+        const { url } = await ctx.api("GET", `/v1/hosting/address?environment=${encodeURIComponent(environment)}`);
+        return typeof url === "string" && url ? url : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Where `flow deploy` keeps the last deploy it made per environment, for `deploy status`: in .flow, never packed. */
+const STATE = join(".flow", "deploys.json");
+function remember(dir, environment, id) {
+    try {
+        const file = join(dir, STATE);
+        const known = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+        mkdirSync(join(dir, ".flow"), { recursive: true });
+        writeFileSync(file, `${JSON.stringify({ ...known, [environment]: { id } }, null, 2)}\n`);
+    }
+    catch {
+        // only a convenience for status
+    }
+}
+function remembered(dir, environment) {
+    try {
+        const id = JSON.parse(readFileSync(join(dir, STATE), "utf8"))[environment]?.id;
+        return typeof id === "string" && /^hdp_[0-9A-Za-z]+$/.test(id) ? id : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `flow deploy status`: per environment, what is live, its version, when, and its URL. */
+async function status(ctx, environments) {
+    const found = [];
+    for (const environment of environments) {
+        let deploys = [];
+        let from = null;
+        try {
+            deploys = (await ctx.api("GET", `/v1/hosting/deploys?environment=${environment}`)).deploys ?? [];
+            from = "list";
+        }
+        catch (error) {
+            if (!(error instanceof Refused) || !error.missing)
+                throw error;
+            // This Flow lists deploys by CI key only to a dashboard member: the last one this folder made.
+            const id = remembered(ctx.dir, environment);
+            if (id) {
+                deploys = [(await ctx.api("GET", `/v1/hosting/deploys/${id}`)).deploy];
+                from = "this_folder";
+            }
+        }
+        const newestFirst = [...deploys].sort((a, b) => String(b.created_at ?? "").localeCompare(String(a.created_at ?? "")));
+        const live = newestFirst.find((d) => d.status === "live") ?? null;
+        const top = newestFirst[0] ?? null;
+        const serving = live ?? top;
+        const pending = top && top !== serving && !["live", "refused", "failed", "replaced"].includes(top.status) ? { id: top.id, status: top.status, version: top.version } : null;
+        const url = live ? (live.url ?? (await address(ctx, environment))) : null;
+        found.push({ environment, deploy: serving, pending, url, from });
+    }
+    const anyLive = found.some((f) => f.deploy?.status === "live");
+    const next = anyLive
+        ? `${RUN} logs${found.length === 1 && found[0].environment === "production" ? " --env production" : ""}`
+        : `${RUN} deploy`;
+    if (ctx.json) {
+        console.log(JSON.stringify({ ok: true, environments: Object.fromEntries(found.map((f) => [f.environment, f.deploy ? { deploy: pick(f.deploy), pending: f.pending, url: f.url, from: f.from } : null])), next }));
+        return 0;
+    }
+    for (const f of found) {
+        if (!f.deploy) {
+            ctx.say(`${f.environment}: no deploy known${f.from === null ? " (this Flow lists deploys to a dashboard member only, and this folder has made none: the dashboard shows them)" : ""}.`);
+            continue;
+        }
+        const d = f.deploy;
+        const when = d.updated_at ?? d.created_at;
+        ctx.say(`${f.environment}: ${d.status}${d.version ? `, version ${d.version}` : ""}, deploy ${d.id}${when ? `, ${d.status === "live" ? "deployed" : "updated"} ${when}` : ""}${f.from === "this_folder" ? " (the last deploy from this folder)" : ""}`);
+        if (d.status === "live")
+            ctx.say(`  URL: ${f.url ?? NO_URL}`);
+        if (f.pending)
+            ctx.say(`  then ${f.pending.id}${f.pending.version ? ` (${f.pending.version})` : ""}: ${f.pending.status}…`);
+    }
+    ctx.say(`Next: ${next}`);
+    return 0;
+}
+const pick = (d) => ({
+    id: d.id,
+    environment: d.environment,
+    status: d.status,
+    version: d.version,
+    source: d.source ?? null,
+    created_at: d.created_at ?? null,
+    updated_at: d.updated_at ?? null,
+});
+/** --since as seconds: 30s, 15m, 1h, 2d. */
+export function sinceSeconds(since) {
+    const m = since.match(/^(\d+)(s|m|h|d)$/);
+    if (!m)
+        return undefined;
+    const n = Number(m[1]);
+    return n * { s: 1, m: 60, h: 3600, d: 86400 }[m[2]];
+}
+/**
+ * `flow logs`: the hosted agent's log lines, from GET /v1/hosting/logs?environment=&since=&after=
+ * → { lines: [{ time, severity, text }], next } (next: the cursor for the lines after these).
+ * A Flow without that route says so and exits 1.
+ */
+async function logs(ctx, environment, since, followLines) {
+    const seconds = sinceSeconds(since);
+    if (seconds === undefined || seconds <= 0 || seconds > 30 * 86400)
+        throw new Usage(`--since is a duration such as 30s, 15m, 1h or 2d (at most 30d).\n\n${LOGS_USAGE}`);
+    const from = new Date(ctx.now() - seconds * 1000).toISOString();
+    let after;
+    let polls = 0;
+    for (;;) {
+        const query = new URLSearchParams({ environment, ...(after ? { after } : { since: from }) });
+        let page;
+        try {
+            page = await ctx.api("GET", `/v1/hosting/logs?${query}`);
+        }
+        catch (error) {
+            if (error instanceof Refused && error.missing) {
+                throw new NotAvailable(`Logs are not available on this Flow yet: its cloud has no logs route for a CI key. The dashboard shows the agent's deploys; ${RUN} deploy status shows what is live.`);
+            }
+            throw error;
+        }
+        for (const line of page.lines ?? []) {
+            if (ctx.json)
+                console.log(JSON.stringify({ time: line.time, severity: line.severity ?? null, text: line.text }));
+            else
+                console.log(`${line.time} ${(line.severity ?? "").padEnd(7)} ${line.text}`);
+        }
+        if (page.next)
+            after = page.next;
+        polls++;
+        if (!followLines || (ctx.maxPolls !== undefined && polls >= ctx.maxPolls))
+            return 0;
+        await new Promise((r) => setTimeout(r, ctx.pollMs));
+    }
+}
+function gitVersion(dir) {
+    try {
+        return execFileSync("git", ["-C", dir, "rev-parse", "--short", "HEAD"], { stdio: ["ignore", "pipe", "ignore"] }).toString().trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const mb = (n) => `${(n / 1024 / 1024).toFixed(1)} MB`;

package/dist/testing/src/print-run.js

@@ -1,4 +1,4 @@
-import { runVerdict } from "./report.js";
+import { runVerdict, unsupported } from "./report.js";
 const usd = (n) => `$${n.toFixed(4)}`;
 /** Prints each run once. A run already shown as it finished is not printed again with the summary. */
 export function runPrinter(log = console.log) {
@@ -8,6 +8,11 @@ export function runPrinter(log = console.log) {
             return;
         printed.add(r.runId);
         const verdict = runVerdict(r);
+        // A scenario the cloud could not play: its file and what is wrong in it, not a run of the agent.
+        if (r.invalid) {
+            log(`INVALID  ${r.scenario} #${r.run} (${r.channel}) ${r.runId}: the cloud could not play this scenario: ${r.invalid.path}: ${r.invalid.reason}${unsupported(r.invalid.reason)}`);
+            return;
+        }
         const gaveUp = verdict === "passed" && r.ended === "gave_up" ? " (passed, the person gave up)" : "";
         const retried = r.retried ? "; tried once more" : "";
         // An errored run: the cloud could not play or judge it, so its checks say nothing about the agent.

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

@@ -246,6 +246,12 @@ export interface RunSummary {
     /** The cloud's code when it could not play or judge the run (judge_failed, spend_cap, simulator_failed, ...).
      * The run then says nothing about the agent, whatever `passed` and `ended` say. */
     error?: string;
+    /** With error scenario_invalid: the scenario file the cloud could not play, and what is wrong in it
+     * (`unsupported: ...` when the cloud does not know a key). */
+    invalid?: {
+        path: string;
+        reason: string;
+    };
 }
 export interface SessionSummary {
     sessionId: string;

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

@@ -26,6 +26,27 @@ export interface ReportRun {
         text: string;
         reason: string;
     }>;
+    /** The scenario file the cloud could not play and what is wrong in it (error scenario_invalid); else null. */
+    invalid: {
+        path: string;
+        reason: string;
+    } | null;
+}
+/** A scenario the cloud could not play, once per scenario. */
+export interface InvalidScenario {
+    scenario: string;
+    path: string;
+    reason: string;
+}
+/** The cloud ended the whole session scenario_invalid: what it said after the code (null when nothing),
+ * whether that looks like a cloud older than this client, and the scenario files this session sent. */
+export interface SessionInvalid {
+    reason: string | null;
+    olderCloud: boolean;
+    sent: Array<{
+        scenario: string;
+        path: string;
+    }>;
 }
 /** `flow test --json`: one document on stdout, whatever the exit. */
 export interface JsonReport {
@@ -50,6 +71,10 @@ export interface JsonReport {
         test: number;
     };
     runs: ReportRun[];
+    /** Each scenario the cloud could not play; the other scenarios played. */
+    invalid: InvalidScenario[];
+    /** Set when the cloud ended the whole session scenario_invalid; else null. */
+    sessionInvalid: SessionInvalid | null;
 }
 /** A run's verdict: errored when the cloud names an error for it or ended it run_failed, since the cloud
  * could not play or judge it and that says nothing about the agent (a judge_failed run can end goal_met). */
@@ -65,6 +90,27 @@ export declare function finishedOutcome(runs: Array<{
 }>): Outcome;
 /** What stopped a session, or the open, as an outcome. `opened`: the session had opened. */
 export declare function stoppedOutcome(error: unknown, opened: boolean): Outcome;
+/** The scenarios the cloud could not play, once each, from the runs it reported (a run per channel and --runs). */
+export declare function invalidScenarios(runs: Array<{
+    scenario: string;
+    invalid?: {
+        path: string;
+        reason: string;
+    } | null;
+}>): InvalidScenario[];
+/** The lines that name each scenario the cloud could not play. */
+export declare function invalidLines(invalid: InvalidScenario[]): string[];
+/** A reason naming a key the cloud does not know: the client may be newer than the cloud. */
+export declare function unsupported(reason: string): string;
+/** A session the cloud ended scenario_invalid; null for any other stop. A tools/ or checks/ file with
+ * its reason is the suite's own problem; anything else (no reason, or a scenario, which a current
+ * cloud reports as that scenario's run) suggests a cloud older than this client. */
+export declare function sessionInvalid(error: unknown, sent: Array<{
+    scenario: string;
+    path: string;
+}>): SessionInvalid | null;
+/** The lines that say why the session ended scenario_invalid. */
+export declare function sessionInvalidLines(info: SessionInvalid): string[];
 /** The error as the JSON report says it: the cloud's status, code and Retry-After when it answered. */
 export declare function reportError(error: unknown, message: string): ReportError;
 /** The connection's error code, from the error or what caused it. */

package/dist/testing/src/report.js

@@ -38,6 +38,48 @@ export function stoppedOutcome(error, opened) {
     // Something on this machine: the agent would not build before the open, or broke the session after it.
     return opened ? "failed" : "invalid";
 }
+/** The scenarios the cloud could not play, once each, from the runs it reported (a run per channel and --runs). */
+export function invalidScenarios(runs) {
+    const out = new Map();
+    for (const r of runs)
+        if (r.invalid)
+            out.set(`${r.scenario}\n${r.invalid.path}`, { scenario: r.scenario, path: r.invalid.path, reason: r.invalid.reason });
+    return [...out.values()];
+}
+/** The lines that name each scenario the cloud could not play. */
+export function invalidLines(invalid) {
+    if (!invalid.length)
+        return [];
+    const lines = [`${invalid.length} ${invalid.length === 1 ? "scenario" : "scenarios"} could not be played (fix ${invalid.length === 1 ? "it" : "them"} and run again):`];
+    for (const i of invalid)
+        lines.push(`  ${i.scenario}: ${i.path}: ${i.reason}${unsupported(i.reason)}`);
+    return lines;
+}
+/** A reason naming a key the cloud does not know: the client may be newer than the cloud. */
+export function unsupported(reason) {
+    return reason.startsWith("unsupported: ") ? " (the test cloud does not know this key; it may be older than this client)" : "";
+}
+/** A session the cloud ended scenario_invalid; null for any other stop. A tools/ or checks/ file with
+ * its reason is the suite's own problem; anything else (no reason, or a scenario, which a current
+ * cloud reports as that scenario's run) suggests a cloud older than this client. */
+export function sessionInvalid(error, sent) {
+    if (!(error instanceof CloudEnded))
+        return null;
+    const match = /^scenario_invalid(?::\s*(.*))?$/s.exec(error.error.trim());
+    if (!match)
+        return null;
+    const reason = match[1]?.trim() || null;
+    const suiteFile = reason !== null && /^(?:\S*\/)?(?:tools|checks)\/[^:]+:\s*\S/.test(reason);
+    return { reason, olderCloud: !suiteFile, sent };
+}
+/** The lines that say why the session ended scenario_invalid. */
+export function sessionInvalidLines(info) {
+    const lines = [`The test cloud could not play this suite${info.reason ? `: ${info.reason}` : " and gave no reason."}`];
+    if (info.olderCloud)
+        lines.push("the test cloud may be older than this client");
+    lines.push(`Scenarios sent: ${info.sent.map((s) => `${s.scenario} (${s.path})`).join(", ") || "none"}`);
+    return lines;
+}
 /** The error as the JSON report says it: the cloud's status, code and Retry-After when it answered. */
 export function reportError(error, message) {
     const refusal = postErrorOf(error);

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

@@ -1,3 +1,4 @@
+import { type SessionInvalid } from "./report.ts";
 /** Where every session's results go, in the agent's folder; `flow new` git-ignores .flow/. */
 export declare const LAST_SESSION: string;
 /** The last session's file in dir: LAST_SESSION, else, before a run has written it, the one from before the rename (.chinwag/). */
@@ -29,7 +30,15 @@ export interface LastSession {
             text: string;
             reason?: string;
         }>;
+        /** The scenario file the cloud could not play and what is wrong in it (error scenario_invalid). */
+        invalid?: {
+            path: string;
+            reason: string;
+        };
     }>;
+    /** The cloud ended the whole session scenario_invalid: its reason, whether the cloud looks older
+     * than the client, and the scenario files sent. */
+    sessionInvalid?: SessionInvalid;
 }
 export declare const SHOW_LINE = "  flow show <run-id|last> [--json]\n                            Print one run's record from the test cloud: its checks with the\n                            judge's reasons, the transcript and the tool calls (flow show --help)";
 /** `flow show`: returns the exit status. */

package/docs/agents.md

@@ -190,4 +190,41 @@ version in `package.json` for production.
 
 ## Host it
 
-Coming soon: `npx @flow-engineer/flow deploy`, to keep the agent answering while the laptop sleeps.
+`npx @flow-engineer/flow deploy` puts the agent on Flow's hosting, so it answers while the laptop
+sleeps. It needs `package.json`, `package-lock.json` and `src/agent.ts`, whose `buildAgent` passes
+`options.host` on to `createAgent`, and the agent's CI key in `FLOW_FRAMEWORK_CLOUD_KEY` (the
+environment, else `.env`; `flow setup` writes it).
+
+```sh
+npx @flow-engineer/flow deploy secrets --from-env .env [--env staging|production] [--json]
+npx @flow-engineer/flow deploy [--env staging|production] [--version <v>] [--json]
+npx @flow-engineer/flow deploy promote [--json]
+npx @flow-engineer/flow deploy status [--env staging|production] [--json]
+npx @flow-engineer/flow logs [--env staging|production] [--since 1h] [--follow] [--json]
+npx @flow-engineer/flow deploy secret NAME [--env staging|production] < value.txt
+```
+
+- `deploy` packs the folder (without `node_modules`, `.git`, `.env*` and `.flow`, at most 50 MB),
+  uploads it, and follows the build until it is live, refused or failed. The default is staging;
+  production refuses an agent that ignores `host` or brings its own database, and the build
+  refuses an agent on a newer framework than Flow hosts yet. `--json` prints
+  `{ ok, deploy: { id, environment, status, version, findings, error }, url, next }` on stdout
+  (`url` is null when the cloud does not say it yet; the human output then says "URL: not available
+  on this Flow yet"); progress goes to stderr. The deploy's id is kept in `.flow/deploys.json`.
+- `promote` moves staging's live version to production, with no new build.
+- `status` shows, per environment (both unless `--env`), the deploy serving it (`status`, `version`,
+  `id`, `updated_at`), its URL and a newer one still building. `--json` prints
+  `{ ok, environments: { staging: { deploy, pending, url, from } | null, production: ... }, next }`;
+  `from` is `list` (the cloud's list) or `this_folder` (the last deploy from `.flow/deploys.json`, on
+  a Flow whose cloud does not list deploys to a CI key yet).
+- `logs` prints the hosted agent's log lines from `--since` (30s, 15m, 1h, 2d; default 1h), and with
+  `--follow` keeps printing new ones; `--json` is one `{ time, severity, text }` per line. On a Flow
+  whose cloud has no logs route yet it says so: `error.code` `not_available`, exit 1.
+- `secrets --from-env` sends each non-empty value in the file as a secret, never the CI key, the
+  cloud's address or a name Flow sets itself (`FLOW_FRAMEWORK_TRACES_*`, `FLOW_STORE_*`, `PORT`, ...);
+  `--json` prints `{ ok, environment, saved, skipped, refused, next }`. `secret NAME` reads one value
+  from stdin. Names only are printed, never values; a secret takes effect on the next deploy.
+- Exit codes: 0 live or saved, 1 refused, failed or not reachable, 2 a usage problem (no CI key, a
+  missing file, a bad name). On an error, `--json` prints `{ ok: false, error: { code, message }, next }`.
+
+Run each answer's `next`. Promote, or deploy to production, only when the owner says so.

package/package.json

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