@flow-engineer/flow 0.3.4 → 0.4.1

package/dist/src/business-events/signature.js

@@ -0,0 +1,36 @@
+// Flow-Signature on a business's pushed events: `t=<unix seconds>,v1=<hex HMAC-SHA256>` of
+// "t.{t}.{raw body}", with the secret the business was given (whsec_...). t may be at most 5 minutes
+// off. Several v1 values are allowed, so a secret can be rotated without dropping events.
+import { createHmac, timingSafeEqual } from "node:crypto";
+/** How far a signature's `t` may be from now. */
+export const SIGNATURE_TOLERANCE_MS = 5 * 60_000;
+/** The hex HMAC for `t` (unix seconds) and the raw body. */
+export function eventSignature(secret, t, body) {
+    return createHmac("sha256", secret).update(`t.${t}.${body}`).digest("hex");
+}
+/** The Flow-Signature header for this body, signed now (ms since the epoch). */
+export function signEvent(secret, body, now = Date.now()) {
+    const t = Math.floor(now / 1000);
+    return `t=${t},v1=${eventSignature(secret, t, body)}`;
+}
+/** Whether the header signs this body with this secret, at most 5 minutes from `now` (ms). */
+export function verifyEventSignature(secret, header, body, now = Date.now()) {
+    if (!header)
+        return false;
+    let t = null;
+    const v1 = [];
+    for (const part of header.split(",")) {
+        const [k, v] = part.trim().split("=", 2);
+        if (k === "t" && v && /^\d+$/.test(v))
+            t = Number(v);
+        else if (k === "v1" && v)
+            v1.push(v);
+    }
+    if (t === null || !v1.length || Math.abs(now - t * 1000) > SIGNATURE_TOLERANCE_MS)
+        return false;
+    const want = Buffer.from(eventSignature(secret, t, body), "hex");
+    return v1.some((s) => {
+        const got = Buffer.from(s, "hex");
+        return got.length === want.length && timingSafeEqual(got, want);
+    });
+}

package/dist/src/business-events/testlist.d.ts

@@ -0,0 +1,15 @@
+export interface EventTestList {
+    /** Whether a business-started send may go to this address. */
+    allows(address: string): boolean;
+    /** Whether a list applies at all (false on production). */
+    enforced: boolean;
+}
+/** The numbers in a comma-separated list: spaces dropped, anything not E.164 left out. */
+export declare function parseTestNumbers(value: string | undefined): string[];
+export declare function eventTestList(options?: {
+    env?: Record<string, string | undefined>;
+    variable?: string;
+    numbers?: string[];
+    testing?: boolean;
+    madeUp?: RegExp;
+}): EventTestList;

package/dist/src/business-events/testlist.js

@@ -0,0 +1,24 @@
+// The test list: off production, a send the business starts (an event's message, a nudge, a held
+// send when it comes due) goes only to addresses on it, so a staging copy of real data never
+// reaches a real customer. Replies to people who wrote first are never checked here.
+//
+// - FLOW_ENVIRONMENT=production: no list, everyone.
+// - Otherwise: the numbers in `variable` (default FLOW_TEST_NUMBERS; comma-separated E.164, spaces
+//   fine, anything else ignored), or `numbers`; none sends nothing (fail closed).
+// - `testing` adds the addresses `madeUp` matches (a test run's made-up numbers).
+const E164 = /^\+\d{8,15}$/;
+/** The numbers in a comma-separated list: spaces dropped, anything not E.164 left out. */
+export function parseTestNumbers(value) {
+    return (value ?? "")
+        .split(",")
+        .map((n) => n.replace(/\s+/g, ""))
+        .filter((n) => E164.test(n));
+}
+export function eventTestList(options = {}) {
+    const env = options.env ?? process.env;
+    if (env.FLOW_ENVIRONMENT === "production")
+        return { enforced: false, allows: () => true };
+    const listed = new Set(options.numbers ? parseTestNumbers(options.numbers.join(",")) : parseTestNumbers(env[options.variable ?? "FLOW_TEST_NUMBERS"]));
+    const madeUp = options.madeUp;
+    return { enforced: true, allows: (address) => listed.has(address) || (options.testing === true && madeUp !== undefined && madeUp.test(address)) };
+}

package/dist/src/index.d.ts

@@ -13,3 +13,4 @@ export type { TracesOptions } from "./traces.ts";
 export { tool, toSpec, type ChatAuth, type ChatAuthContext, type CredentialProvider, type Credentials, type SignIn, type Tool, type ToolContext, type ToolHints } from "./tools.ts";
 export type { Attachment, ChannelInfo, ChatMessage, Deliver, Incoming, ListRow, Media, Model, ModelRequest, ModelResponse, Outbound, PersonMessage, Template, TemplateButton, TemplateDefinition, ToolCall, ToolSpec, Transcribe } from "./types.ts";
 export { z } from "zod";
+export * from "./business-events/index.ts";

package/dist/src/index.js

@@ -10,3 +10,4 @@ export { flowModel, flowModelURL, openAICompatible } from "./model.js";
 export { Store } from "./store.js";
 export { tool, toSpec } from "./tools.js";
 export { z } from "zod";
+export * from "./business-events/index.js";

package/dist/testing/src/business.js

@@ -3,7 +3,8 @@
 // cloud's commands move and with copies of the agent's own channels, so its sends go through what
 // the agent wraps around them and come to the cloud with the run's time. The person writes through
 // agent.message(), as a provider's webhook would, so they are a person the agent can nudge.
-import { createHmac, randomBytes } from "node:crypto";
+import { randomBytes } from "node:crypto";
+import { signEvent } from "../../src/index.js";
 /** One minute: the clock moves this far at a time, and what came due runs at each step. */
 export const STEP_MS = 60_000;
 export function businessRuns(ctx) {
@@ -56,11 +57,10 @@ export function businessRuns(ctx) {
     };
     const event = async (run, command) => {
         const body = JSON.stringify(command.envelope);
-        const t = Math.floor(run.clock / 1000);
         const secret = command.signature === "bad" ? `whsec_test_${randomBytes(18).toString("hex")}` : run.secret;
         const headers = { "content-type": "application/json", "idempotency-key": command.envelope.id };
         if (command.signature !== "missing")
-            headers["flow-signature"] = `t=${t},v1=${createHmac("sha256", secret).update(`t.${t}.${body}`).digest("hex")}`;
+            headers["flow-signature"] = signEvent(secret, body, run.clock);
         const response = await run.agent.fetch(new Request(`http://agent.test${command.path ?? "/v1/events"}`, { method: "POST", headers, body }));
         const text = await response.text();
         let parsed = text;

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

@@ -1,6 +1,6 @@
-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 DEPLOY_LINE = "  flow deploy [--env staging|production] [--dir <folder>] [--version <v>] [--no-secrets] [--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.";
+export declare const DEPLOY_USAGE = "Usage:\n  flow deploy [--env staging|production] [--dir <folder>] [--version <v>] [--no-secrets] [--json]\n                                                           one command, first deploy included: sends the\n                                                           .env's new or changed values as secrets, then\n                                                           packs, builds and follows it to live\n  flow deploy promote [--no-secrets] [--json]              staging's live version to production (the\n                                                           .env's new or changed values sent there first)\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]     one secret, the value on stdin\n  flow deploy secrets --from-env [<file>] [--env staging|production]\n                                                           every value in <file> now (default: the agent's .env);\n                                                           flow deploy does this itself\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, with +dirty\n               when the folder has uncommitted changes).\n  --no-secrets Deploy without sending the .env's values as secrets.\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\nflow deploy (and deploy promote, for production) sends each non-empty .env value as a secret (the\nsame names as secrets --from-env sends) before the service starts, and later only the new or changed ones: .flow/secrets.json keeps a\nhash per name, never a value. It prints names only.\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;
 /**
@@ -32,3 +32,5 @@ export declare function deployCli(argv: string[], env?: NodeJS.ProcessEnv, optio
 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;
+/** The folder's git commit, with +dirty when the folder has changes not committed (what is packed is the folder as it is). */
+export declare function gitVersion(dir: string): string | undefined;

package/dist/testing/src/deploy.js

@@ -1,8 +1,9 @@
 // `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 [--env staging|production] [--dir .] [--version <v>] [--no-secrets] [--json]
+//                                                                                pack, send .env's new or changed values as secrets, upload, build, go live
+//   flow deploy promote [--no-secrets] [--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
@@ -12,13 +13,14 @@
 // (.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 { createHash } from "node:crypto";
 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]
+export const DEPLOY_LINE = `  flow deploy [--env staging|production] [--dir <folder>] [--version <v>] [--no-secrets] [--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]
@@ -32,23 +34,34 @@ export const LOGS_USAGE = `Usage:
   --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 [--env staging|production] [--dir <folder>] [--version <v>] [--no-secrets] [--json]
+                                                           one command, first deploy included: sends the
+                                                           .env's new or changed values as secrets, then
+                                                           packs, builds and follows it to live
+  flow deploy promote [--no-secrets] [--json]              staging's live version to production (the
+                                                           .env's new or changed values sent there first)
   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 secret <NAME> [--env staging|production]     one secret, the value on stdin
   flow deploy secrets --from-env [<file>] [--env staging|production]
-                                                           every value in <file> (default: the agent's .env)
+                                                           every value in <file> now (default: the agent's .env);
+                                                           flow deploy does this itself
 
   --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).
+  --version    A label for this version (default: the folder's git commit, if any, with +dirty
+               when the folder has uncommitted changes).
+  --no-secrets Deploy without sending the .env's values as secrets.
   --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).
 
+flow deploy (and deploy promote, for production) sends each non-empty .env value as a secret (the
+same names as secrets --from-env sends) before the service starts, and later only the new or changed ones: .flow/secrets.json keeps a
+hash per name, never a value. It prints names only.
+
 status shows both environments unless --env names one. The last deploy this folder made is kept
 in .flow/deploys.json (never packed).
 
@@ -144,6 +157,7 @@ async function cloudCli(top, argv, env, options) {
                 version: { type: "string" },
                 cloud: { type: "string" },
                 "from-env": { type: "boolean" },
+                "no-secrets": { type: "boolean" },
                 since: { type: "string" },
                 follow: { type: "boolean", short: "f" },
                 json: { type: "boolean" },
@@ -212,9 +226,11 @@ async function cloudCli(top, argv, env, options) {
         }
         return answer;
     };
-    const ctx = { api, say, json, dir, pollMs: options.pollMs ?? 3000, maxPolls: options.maxPolls, now: options.now ?? Date.now };
+    const ctx = { api, say, json, dir, pollMs: options.pollMs ?? 3000, maxPolls: options.maxPolls, now: options.now ?? Date.now, keyId: createHash("sha256").update(key).digest("hex").slice(0, 16) };
     try {
         const [name, extra] = args;
+        if (values["no-secrets"] && command !== undefined && command !== "promote")
+            throw new Usage(`--no-secrets goes with flow deploy and deploy promote\n\n${usage}`);
         if (command === "logs") {
             if (name !== undefined)
                 throw new Usage(`flow logs takes no arguments.\n\n${usage}`);
@@ -223,7 +239,7 @@ async function cloudCli(top, argv, env, options) {
         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);
+            return await promote(ctx, !values["no-secrets"]);
         if (command === "status")
             return await status(ctx, given ? [given] : ["staging", "production"]);
         if (command === "secret")
@@ -235,7 +251,7 @@ async function cloudCli(top, argv, env, options) {
         }
         if (command !== undefined)
             throw new Usage(`Unknown command: deploy ${command}\n\n${usage}`);
-        return await deploy(ctx, dir, environment, values.version);
+        return await deploy(ctx, dir, environment, values.version, !values["no-secrets"]);
     }
     catch (error) {
         if (error instanceof Usage)
@@ -247,12 +263,16 @@ async function cloudCli(top, argv, env, options) {
         return fail("network", `Could not reach ${cloud}: ${error.message}`, 1);
     }
 }
-async function deploy(ctx, dir, env, version) {
+async function deploy(ctx, dir, env, version, withSecrets) {
     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);
+    if (version === undefined) {
+        version = gitVersion(dir);
+        if (version?.endsWith("+dirty"))
+            console.error("Warning: deploying uncommitted changes; commit first so the version names what runs.");
+    }
     const tmp = mkdtempSync(join(tmpdir(), "flow-deploy-"));
     try {
         const bundle = join(tmp, "agent.tgz");
@@ -262,6 +282,10 @@ async function deploy(ctx, dir, env, version) {
             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 } : {}) });
+        // The agent exists on the host once its first deploy is made, so its secrets go now, before
+        // the build starts: the service's first version starts with them.
+        if (withSecrets)
+            await secretsFirst(ctx, env, "deploy");
         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");
@@ -274,7 +298,26 @@ async function deploy(ctx, dir, env, version) {
         rmSync(tmp, { recursive: true, force: true });
     }
 }
-async function promote(ctx) {
+/**
+ * The .env's new or changed values as secrets for `env`, before what would start without them;
+ * a refused one stops it there. The names sent are printed.
+ */
+async function secretsFirst(ctx, env, what) {
+    const file = join(ctx.dir, ".env");
+    if (!existsSync(file))
+        return;
+    const sent = await sendSecrets(ctx, file, env, true);
+    if (sent.refused.length) {
+        const one = sent.refused.length === 1;
+        throw new Refused(`${sent.refused.map((r) => r.name).join(", ")} could not be saved as ${one ? "a secret" : "secrets"} for ${env} (${sent.refused.map((r) => `${r.name}: ${r.message}`).join("; ")}), so this ${what} did not start. Fix or remove ${one ? "it" : "them"} in .env, then ${RUN} deploy${what === "promote" ? " promote" : ""} again (or add --no-secrets)`, "secret_refused");
+    }
+    if (sent.saved.length)
+        ctx.say(`Sent ${sent.saved.length} secret${sent.saved.length === 1 ? "" : "s"} from .env to ${env}: ${sent.saved.join(", ")}.`);
+}
+async function promote(ctx, withSecrets) {
+    // Production keeps secrets of its own: the .env's go there first, so the promoted version has them.
+    if (withSecrets)
+        await secretsFirst(ctx, "production", "promote");
     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}).`);
@@ -296,47 +339,98 @@ async function secret(ctx, name, env, readStdin) {
     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.`);
+/** Where flow deploy keeps a hash per secret it sent (never a value), to send only new or changed ones. */
+const SENT = join(".flow", "secrets.json");
+const secretHash = (ctx, env, name, value) => createHash("sha256").update(`${ctx.keyId}\0${env}\0${name}\0${value}`).digest("hex");
+function sentHashes(dir) {
+    try {
+        const known = JSON.parse(readFileSync(join(dir, SENT), "utf8"));
+        return known && typeof known === "object" ? known : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Every non-empty value in a .env file as a secret, one each, the names only printed; with
+ * `onlyChanged`, the ones .flow/secrets.json shows were already sent are left alone. Each one saved
+ * is recorded there as a hash.
+ */
+async function sendSecrets(ctx, file, env, onlyChanged) {
     const entries = [...parseEnv(readFileSync(file, "utf8"))].filter(([, value]) => value !== "");
-    const saved = [];
-    const skipped = [];
-    const refused = [];
+    const out = { saved: [], skipped: [], refused: [], unchanged: [] };
+    const all = sentHashes(ctx.dir);
+    const scope = `${ctx.keyId}:${env}`;
+    const known = { ...(all[scope] ?? {}) };
     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)`);
+            out.skipped.push({ name, why: "set by Flow" });
+            if (!onlyChanged)
+                ctx.say(`  ${name} skipped (set by Flow)`);
             continue;
         }
         if (!ENV_SECRET_NAME.test(name)) {
-            skipped.push({ name, why: "not upper case letters, digits and _" });
+            out.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;
         }
+        const hash = secretHash(ctx, env, name, value);
+        if (onlyChanged && known[name] === hash) {
+            out.unchanged.push(name);
+            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}`);
+            out.refused.push({ name, message: error.message });
+            console.error(`  ${name} refused: ${error.message}`);
             continue;
         }
-        saved.push(name);
-        ctx.say(`  ${name} set`);
+        out.saved.push(name);
+        known[name] = hash;
+        if (!onlyChanged)
+            ctx.say(`  ${name} set`);
     }
-    const next = `${RUN} deploy${env === "production" ? " --env production" : ""}`;
+    if (out.saved.length) {
+        try {
+            mkdirSync(join(ctx.dir, ".flow"), { recursive: true });
+            writeFileSync(join(ctx.dir, SENT), `${JSON.stringify({ ...all, [scope]: known }, null, 2)}\n`);
+        }
+        catch {
+            // only saves sending them again next time
+        }
+    }
+    return out;
+}
+/** `flow deploy secrets --from-env`: every non-empty value in a .env file as a secret now. */
+async function secretsFromEnv(ctx, file, env) {
+    if (!existsSync(file))
+        throw new Usage(`${file} is missing.`);
+    const { saved, skipped, refused } = await sendSecrets(ctx, file, env, false);
+    const deployCmd = `${RUN} deploy${env === "production" ? " --env production" : ""}`;
+    const neverDeployed = refused.length > 0 && refused.every((r) => /never been deployed/.test(r.message));
+    const next = neverDeployed ? `${deployCmd} (it sends the .env's values itself)` : deployCmd;
     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(`Saved ${saved.length} secret${saved.length === 1 ? "" : "s"} for ${env}. They take effect on the next deploy.`);
+    if (refused.length) {
+        console.error(neverDeployed
+            ? `Refused: this agent has not been deployed yet, so ${env} took no secrets. ${deployCmd} deploys it and sends the .env's values as secrets before it starts.`
+            : `Refused: ${refused.length} secret${refused.length === 1 ? "" : "s"} not saved (${refused.map((r) => r.name).join(", ")}).`);
+        console.error(`Next: ${next}`);
+        return 1;
+    }
+    if (!saved.length)
+        ctx.say(`No secrets saved from ${file}.`);
+    else
         ctx.say(`Next: ${next}`);
-    return refused.length ? 1 : 0;
+    return 0;
 }
 /** Follows a deploy until it is live, refused or failed, printing each change. */
 async function follow(ctx, id) {
@@ -524,12 +618,23 @@ async function logs(ctx, environment, since, followLines) {
         await new Promise((r) => setTimeout(r, ctx.pollMs));
     }
 }
-function gitVersion(dir) {
+/** The folder's git commit, with +dirty when the folder has changes not committed (what is packed is the folder as it is). */
+export function gitVersion(dir) {
+    let sha;
     try {
-        return execFileSync("git", ["-C", dir, "rev-parse", "--short", "HEAD"], { stdio: ["ignore", "pipe", "ignore"] }).toString().trim() || undefined;
+        sha = execFileSync("git", ["-C", dir, "rev-parse", "--short", "HEAD"], { stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
     }
     catch {
         return undefined;
     }
+    if (!sha)
+        return undefined;
+    try {
+        const changes = execFileSync("git", ["-C", dir, "status", "--porcelain", "--", "."], { stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+        return changes ? `${sha}+dirty` : sha;
+    }
+    catch {
+        return sha;
+    }
 }
 const mb = (n) => `${(n / 1024 / 1024).toFixed(1)} MB`;

package/docs/agents.md

@@ -173,6 +173,13 @@ preview card's title becomes the phone's notification instead of the message's t
 action use `link` (`agent.nudge({ to, text, link: { label, url } })`, or the agent's send with
 `link`), not a URL in the text.
 
+When the business's backend should tell people what happened (an order shipped, an item is back),
+mount `flowEvents` instead of writing a route: one signed `POST /v1/events`, each event sent by its
+delivery level (critical at once, standard after quiet hours, optional merged or dropped), with the
+agent's own wording checked against the template's values. The envelope, signing, answers and a
+mounting sample are in `docs/events.md` in the package
+(https://github.com/flow-engineer/flow/blob/main/docs/events.md).
+
 ## Shared test numbers and privacy
 
 The free trial runs on Flow's shared Telegram bot, WhatsApp number and iMessage line. Sending an
@@ -195,23 +202,40 @@ sleeps. It needs `package.json`, `package-lock.json` and `src/agent.ts`, whose `
 `options.host` on to `createAgent`, and the agent's CI key in `FLOW_FRAMEWORK_CLOUD_KEY` (the
 environment, else `.env`; `flow setup` writes it).
 
+One command deploys, the first time included:
+
+```sh
+npx @flow-engineer/flow deploy
+```
+
+It sends the `.env`'s values as the agent's secrets, then builds and follows it to live. The rest:
+
 ```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 [--env staging|production] [--version <v>] [--no-secrets] [--json]
+npx @flow-engineer/flow deploy promote [--no-secrets] [--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
+npx @flow-engineer/flow deploy secrets --from-env [<file>] [--env staging|production] [--json]
 ```
 
+- `deploy` first sends each non-empty value in the agent's `.env` as a secret for that
+  environment, before the service starts, so the first live version has its keys: never the CI
+  key, the cloud's address or a name Flow sets itself (`FLOW_FRAMEWORK_TRACES_*`, `FLOW_STORE_*`,
+  `PORT`, ...). Later deploys send only the new or changed ones (`.flow/secrets.json` keeps a hash
+  per name, never a value). It prints the names it sent, never values; `--no-secrets` sends none.
+  A secret the host refuses stops the deploy before it starts, naming it.
 - `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.
+  on this Flow yet"); progress goes to stderr. The deploy's id is kept in `.flow/deploys.json`. The
+  version is the folder's git commit, `<sha>+dirty` (with a warning) when the folder has
+  uncommitted changes, since what is packed is the folder as it is; `--version` names it yourself.
+- `promote` moves staging's live version to production, with no new build. Production keeps its
+  own secrets: promote sends the `.env`'s new or changed values there first (`--no-secrets` sends none).
 - `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 }`;
@@ -220,10 +244,11 @@ npx @flow-engineer/flow deploy secret NAME [--env staging|production] < value.tx
 - `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.
+- `secret NAME` (one value from stdin) and `secrets --from-env` (every value in a file, now) are for
+  changing a secret by hand; `deploy` already sends the `.env`. `--json` prints
+  `{ ok, environment, saved, skipped, refused, next }`. Before the agent's first deploy the host has
+  no agent to keep them for: they are refused, exit 1, and `next` is `deploy`. 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 }`.