@flow-engineer/flow 0.3.3 → 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
 
@@ -648,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/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,6 +42,7 @@ 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";
@@ -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] ?? ""))

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/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.3",
+  "version": "0.3.4",
   "description": "An open-source runtime for chat agents that feel like a person texting back.",
   "license": "Apache-2.0",
   "repository": {