@flow-engineer/flow 0.2.0 → 0.2.1

package/dist/testing/src/chat.js

@@ -0,0 +1,117 @@
+// `flow chat`: talk to the agent in this folder from the terminal, with no account and no channel.
+// It builds the agent from src/agent.ts (buildAgent({ events }), as `flow test` does) with the
+// model key in .env, and writes as the agent's first test person, the way the playground does
+// (agent.simulate). Each line read from stdin is one message; the agent's replies are printed once
+// its turn is over, so it works typed by a person or piped by a coding agent:
+//   printf 'hi\nA latte please\n' | npx @flow-engineer/flow chat
+// --json prints each thing the agent sends as one JSON line. The conversation lives only as long as
+// the command. Exit status: 0 done (stdin ended), 1 usage or the agent could not be built.
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+import { loadEnv } from "./report.js";
+export const CHAT_LINE = `  flow chat [--channel <name>] [--person <phone>] [--json]
+                            Talk to the agent in this folder from the terminal: one message per line
+                            of stdin, no account needed (only the model key in .env)`;
+const USAGE = `Usage:\n${CHAT_LINE}
+
+Writes as the agent's first test person (createAgent({ testPeople })) on its first channel, unless
+--person or --channel says otherwise. Exit status: 0 done, 1 usage or the agent could not be built.`;
+/** Runs `flow chat`; resolves to the exit status. */
+export async function chatCli(args, input = process.stdin) {
+    let values;
+    try {
+        ({ values } = parseArgs({ args, strict: true, options: { channel: { type: "string" }, person: { type: "string" }, json: { type: "boolean", default: false }, help: { type: "boolean", short: "h", default: false } } }));
+    }
+    catch (error) {
+        console.error(`flow chat: ${error.message.split(". ")[0]}\n\n${USAGE}`);
+        return 1;
+    }
+    if (values.help) {
+        console.log(USAGE);
+        return 0;
+    }
+    loadEnv(undefined);
+    const file = join(process.cwd(), "src", "agent.ts");
+    if (!existsSync(file)) {
+        console.error(`flow chat: no src/agent.ts here. Run it from your agent's folder (npx @flow-engineer/flow init makes one).`);
+        return 1;
+    }
+    const turns = [];
+    let agent;
+    try {
+        const module = await import(__rewriteRelativeImportExtension(pathToFileURL(file).href));
+        if (typeof module.buildAgent !== "function")
+            throw new Error("src/agent.ts must export buildAgent({ events }).");
+        agent = module.buildAgent({ events: [(event) => turns.forEach((listener) => listener(event))] });
+    }
+    catch (error) {
+        console.error(`flow chat: ${error.message}`);
+        return 1;
+    }
+    const person = values.person ? agent.testPeople().find((p) => p.phone.replace(/\D/g, "") === values.person.replace(/\D/g, "")) : agent.testPeople()[0];
+    const channel = values.channel ? agent.channels().find((c) => c.name === values.channel) : agent.channels()[0];
+    if (!person || !channel) {
+        console.error(!person
+            ? `flow chat: ${values.person ? `${values.person} is not one of the agent's testPeople` : "the agent has no testPeople"}; declare them in createAgent({ testPeople: [{ name, phone }] }).`
+            : `flow chat: ${values.channel ? `no channel named ${values.channel}` : "the agent has no channels"}; it has ${agent.channels().map((c) => c.name).join(", ") || "none"}.`);
+        return 1;
+    }
+    agent.attachPlayground(({ outbound }) => print(outbound, channel.name, values.json === true));
+    turns.push((event) => {
+        if (event.type === "model.error")
+            console.error(`flow chat: the model failed: ${String(event.error ?? event.message ?? "error")}`);
+    });
+    const prompt = process.stdin.isTTY && input === process.stdin;
+    if (!values.json)
+        console.error(`Talking to the agent on ${channel.name} as ${person.name} (${person.phone}). Ctrl-D ends.`);
+    const lines = createInterface({ input, terminal: false });
+    if (prompt)
+        process.stderr.write("you: ");
+    let conversationId;
+    for await (const line of lines) {
+        const text = line.trim();
+        if (text) {
+            const taken = await agent.simulate({ person: person.phone, channel: channel.name, message: text });
+            if (taken)
+                await agent.conversation((conversationId = taken.conversationId))?.whenIdle();
+        }
+        if (prompt)
+            process.stderr.write("you: ");
+    }
+    // A tool still running in the background answers in a turn of its own: wait for it before leaving.
+    while (conversationId && agent.status().backgroundTasks > 0) {
+        await new Promise((done) => turns.push((event) => event.type === "task.done" && done()));
+        await agent.conversation(conversationId)?.whenIdle();
+    }
+    await agent.flushTraces();
+    return 0;
+}
+/** One thing the agent sent, as a person would read it (or one JSON line). */
+function print(outbound, channel, json) {
+    if (outbound.type === "typing" || outbound.type === "status" || outbound.type === "read")
+        return;
+    if (json)
+        return void process.stdout.write(`${JSON.stringify({ channel, ...outbound })}\n`);
+    if (outbound.type === "reaction")
+        return void process.stdout.write(`agent reacted ${outbound.emoji}\n`);
+    if (outbound.type === "template")
+        return void process.stdout.write(`agent: [template ${outbound.name}]\n`);
+    const extra = [
+        outbound.image && `[photo ${outbound.image.url}]`,
+        outbound.link && `[${outbound.link.label}: ${outbound.link.url}]`,
+        outbound.buttons?.map((b) => `[${b}]`).join(" "),
+        outbound.list && `[${outbound.list.button}: ${outbound.list.rows.map((r) => r.title).join(" | ")}]`,
+    ].filter(Boolean);
+    process.stdout.write(`agent: ${[outbound.text, ...extra].filter(Boolean).join(" ")}\n`);
+}

package/dist/testing/src/chinwag.js

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

package/dist/testing/src/cli.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
-// The flow command. `flow new <name>` makes ./<name>/, an agent started from the café example
-// (testing/src/new.ts). `flow test`, or `flow` with flags, runs an agent's tests in the cloud,
+// The flow command. `flow new <name>` makes ./<name>/, an agent started from the café example, and
+// `flow init` the same agent in the current folder (testing/src/new.ts). `flow chat` talks to the
+// agent in this folder from the terminal (testing/src/chat.ts). `flow test`, or `flow` with flags, runs an agent's tests in the cloud,
 // from the agent's folder:
 //   flow test [--cloud https://flow.engineer/observe] [--runs 3] [--only late-order,refund | --failed] [--json]
 // A hosted cloud (any --cloud off this machine, the default included) needs the
@@ -15,6 +16,8 @@
 // (what each run ended as and the judge's reasons, never the messages), and --failed runs again the
 // scenarios that did not pass. --json prints one report (testing/src/report.ts) on stdout at every exit,
 // and `flow show <run>` prints one run's record from the cloud (testing/src/show.ts).
+// `flow login`, `logout`, `whoami`, `setup` and `link` sign in to flow.engineer and get the agent's
+// keys and its phone link (testing/src/account.ts).
 var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
     if (typeof path === "string" && /^\.\.?\//.test(path)) {
         return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
@@ -33,12 +36,15 @@ import { OBSERVE_URL, setting } from "../../src/traces.js";
 import { cloudHeaders, runInCloud, SessionStopped } from "./client.js";
 import { runPrinter } from "./print-run.js";
 import { checkEndpointCli } from "./check-endpoint.js";
+import { ACCOUNT_COMMANDS, ACCOUNT_LINES, accountCli } from "./account.js";
+import { CHAT_LINE, chatCli } from "./chat.js";
 import { httpAgent } from "./http-agent.js";
-import { newStandalone, packageRoot } from "./new.js";
+import { initHere, newStandalone, packageRoot } from "./new.js";
 import { EXIT, finishedOutcome, loadEnv, networkCode, reportError, runVerdict, stoppedOutcome } from "./report.js";
 import { LAST_SESSION, lastSessionIn, SHOW_LINE, showCli } from "./show.js";
 import { loadSuite, parseScenario, parseToolFile, suiteHash } from "./suite.js";
-const NEW_LINE = "  flow new <name>           Make ./<name>/, a new agent started from the café example";
+const NEW_LINE = `  flow new <name>           Make ./<name>/, a new agent started from the café example
+  flow init                 Make that agent in the current folder, named after it`;
 const TEST_LINE = `  flow test [options]       Run the agent's tests in a test cloud, from the agent's folder
                             (src/agent.ts exports buildAgent({ model, events, tools }) and tools;
                             the tests are in tests/scenarios and tests/tools)`;
@@ -91,14 +97,19 @@ with the judge's reasons. Never the messages. The folder is git-ignored and the
 Environment (also read from the agent folder's .env, or --dotenv; variables already set win;
 the CHINWAG_ names from before the rename still work):
   FLOW_FRAMEWORK_CLOUD     The test cloud, when --cloud is not given
-  FLOW_FRAMEWORK_CLOUD_KEY The agent's CI key, for a hosted cloud (oci_...: make one at
-                           https://flow.engineer/observe, your agent, Developers)
+  FLOW_FRAMEWORK_CLOUD_KEY The agent's CI key, for a hosted cloud (oci_...: flow setup
+                           writes it, or make one at https://flow.engineer/observe, your agent, Developers)
   FLOW_FRAMEWORK_AGENT_TOKEN
                            With --agent-url: sent to it as authorization: Bearer <token>
   OPENROUTER_API_KEY       The agent's model key, or OPENAI_API_KEY, ANTHROPIC_API_KEY or
                            GEMINI_API_KEY: the first with a value is used`;
 const TEST_USAGE = `Usage:\n${TEST_LINE}\n\n${TEST_OPTIONS}`;
-const USAGE = `Usage:\n${NEW_LINE}\n${TEST_LINE}\n${SHOW_LINE}\n${CHECK_LINE}\n  flow --version            Show the version\n\n${TEST_OPTIONS}`;
+const USAGE = `Usage:\n${NEW_LINE}\n${CHAT_LINE}\n${TEST_LINE}\n${SHOW_LINE}\n${CHECK_LINE}\n${ACCOUNT_LINES}\n  flow --version            Show the version\n\n${TEST_OPTIONS}`;
+const NEXT_STEPS = `  2. Add one model key: cp .env.example .env; the file says where to make one
+  3. npx @flow-engineer/flow chat, and type to it (or npm start for the playground)
+  4. npx @flow-engineer/flow link: signs in, writes the other keys, prints the link for your phone;
+     keep npm start running and text it
+  5. Tell your coding agent what to build: its skills are in .claude/skills/`;
 checkNode(process.versions.node);
 if (process.argv[2] === "check-endpoint") {
     // Its token may be in the agent folder's .env; no value is ever printed.
@@ -107,6 +118,10 @@ if (process.argv[2] === "check-endpoint") {
 }
 if (process.argv[2] === "show")
     process.exit(await showCli(process.argv.slice(3)));
+if (process.argv[2] === "chat")
+    process.exit(await chatCli(process.argv.slice(3)));
+if (ACCOUNT_COMMANDS.has(process.argv[2] ?? ""))
+    process.exit(await accountCli(process.argv[2], process.argv.slice(3)));
 const TEST_FLAGS = {
     cloud: { type: "string" },
     runs: { type: "string", default: "1" },
@@ -134,7 +149,7 @@ if (values.version) {
     process.exit(0);
 }
 if (values.help || process.argv.length <= 2) {
-    console.log(command === "new" ? NEW_USAGE : command === "test" ? TEST_USAGE : USAGE);
+    console.log(command === "new" || command === "init" ? NEW_USAGE : command === "test" ? TEST_USAGE : USAGE);
     process.exit(0);
 }
 if (command === "new") {
@@ -148,9 +163,23 @@ if (command === "new") {
     }
     console.log(`Made ./${name}/ from the café example (Pip). Next:
   1. cd ${name} && npm install
-  2. Add one model key: cp .env.example .env; the file says where to make one
-  3. npm start, then open the link it prints
-  4. Tell your coding agent what to build: its skills are in .claude/skills/`);
+${NEXT_STEPS}`);
+    process.exit(0);
+}
+if (command === "init") {
+    let name;
+    try {
+        if (rest.length)
+            throw new Error("Usage: flow init (it makes the agent in the current folder; flow new <name> makes a folder for it)");
+        name = initHere();
+    }
+    catch (error) {
+        console.error(error.message);
+        process.exit(1);
+    }
+    console.log(`Made ${name}, started from the café example (Pip), in this folder. Next:
+  1. npm install
+${NEXT_STEPS}`);
     process.exit(0);
 }
 /** Every human line of `flow test`: stdout, or stderr with --json, where stdout is the report. */
@@ -183,7 +212,7 @@ try {
     });
 }
 catch (error) {
-    const where = !ciKey && cloud.replace(/\/+$/, "") === OBSERVE_URL ? ` Make a key at ${OBSERVE_URL}: your agent, Developers.` : "";
+    const where = !ciKey && cloud.replace(/\/+$/, "") === OBSERVE_URL ? " Run npx @flow-engineer/flow login, then npx @flow-engineer/flow setup, to get one into .env." : "";
     invalid(`${error.message}${where}`);
 }
 const dir = process.cwd();
@@ -499,7 +528,7 @@ function stoppedReason(error, cloud) {
 }
 /** The command's flags, or exits 1 with what is wrong and that command's usage. */
 function parseCommandLine() {
-    const isNew = process.argv[2] === "new";
+    const isNew = process.argv[2] === "new" || process.argv[2] === "init";
     const options = isNew ? { help: TEST_FLAGS.help, version: TEST_FLAGS.version } : TEST_FLAGS;
     try {
         return parseArgs({ allowPositionals: true, strict: true, options: options });

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

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

package/dist/testing/src/client.js

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

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

@@ -0,0 +1,143 @@
+export declare const LOGIN_URL = "https://flow.engineer";
+/** The longest one request to flow.engineer may take; login's polls are cut shorter by what is left of --timeout. */
+export declare const REQUEST_TIMEOUT_MS = 30000;
+/** A login URL a token may go to: https, or http to this machine only (a local flow.engineer). */
+export declare function safeLoginUrl(url: string): boolean;
+/** flow.engineer, or FLOW_FRAMEWORK_LOGIN_URL, without trailing slashes (trimmed from the end, in linear time). */
+export declare function loginUrl(env?: NodeJS.ProcessEnv): string;
+/** ~/.config/flow-framework/credentials.json (XDG_CONFIG_HOME when set), written at mode 0600. */
+export declare function credentialsPath(env?: NodeJS.ProcessEnv): string;
+export interface Credentials {
+    token: string;
+    expires_at?: string;
+    /** The server that issued it, so logout revokes it there. */
+    url: string;
+}
+/**
+ * The token to use: FLOW_FRAMEWORK_TOKEN, else the credentials file's (with `url`, the server that
+ * issued it, the only one it is sent to); undefined when signed out.
+ */
+export declare function currentToken(env?: NodeJS.ProcessEnv): {
+    token: string;
+    from: "env" | "file";
+    url?: string;
+} | undefined;
+export declare function readCredentials(env?: NodeJS.ProcessEnv): Credentials | undefined;
+export declare function saveCredentials(credentials: Credentials, env?: NodeJS.ProcessEnv): string;
+export declare function deleteCredentials(env?: NodeJS.ProcessEnv): boolean;
+/** A device code started by `flow login` and not approved yet, kept for `flow login --wait`. */
+export interface PendingLogin extends DeviceStart {
+    /** When the code expires, in ms since the epoch. */
+    expires_at: number;
+    /** The server that issued it. */
+    url: string;
+}
+/** ~/.config/flow-framework/pending.json, written at mode 0600 and deleted once the code is used or expired. */
+export declare function pendingPath(env?: NodeJS.ProcessEnv): string;
+export declare function readPending(env?: NodeJS.ProcessEnv): PendingLogin | undefined;
+export declare function savePending(pending: PendingLogin, env?: NodeJS.ProcessEnv): void;
+export declare function deletePending(env?: NodeJS.ProcessEnv): void;
+export interface DeviceStart {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    interval: number;
+    expires_in: number;
+}
+export type TokenAnswer = {
+    status: "signed_in";
+    token: string;
+    expires_at?: string;
+    account?: Account;
+} | {
+    status: "authorization_pending" | "slow_down" | "expired_token" | "access_denied";
+};
+export interface Account {
+    email: string;
+    account: string;
+}
+export interface SetupAnswer {
+    agent_id: string;
+    /** Only the keys minted in this call come back (those the request did not say it has). */
+    cloud_key?: string;
+    traces_key?: string;
+    messaging_key?: string;
+    /** Each channel's shared sender and phone link, only while Flow has that channel open. */
+    telegram_sender?: string;
+    whatsapp_sender?: string;
+    imessage_sender?: string;
+    whatsapp_link?: string;
+    imessage_link?: string;
+    /** Missing only when the server could not make one; the keys it minted are written anyway. */
+    join_code?: string;
+    account?: Account;
+    app_id?: string;
+    dashboard_url?: string;
+    /** The flow.engineer page that opens Telegram with the join message filled in. */
+    try_url?: string;
+    telegram_link?: string;
+    /** The try page per channel with a sender: {telegram: ".../try/<code>?c=telegram", ...}. */
+    try_urls?: Record<string, string>;
+    /** The account's free-trial counts per channel; limit null is unlimited. iMessage also counts the people it may reach. */
+    trial?: Record<string, {
+        limit: number | null;
+        used: number;
+        contacts?: {
+            limit: number;
+            used: number;
+        };
+    }>;
+    /** The answer fields of the keys made in this call. */
+    minted?: string[];
+    next?: string[];
+    /** Up to 20 lines for the owner, shown as they are. */
+    warnings?: string[];
+}
+/** The answer's warnings: its strings only, at most 20. */
+export declare function warningsOf(body: Record<string, unknown>): string[];
+/** Retry-After as seconds from now (delta-seconds or an HTTP date); undefined when absent or unreadable. */
+export declare function retryAfterSeconds(header: string | null, now?: number): number | undefined;
+/**
+ * The server answered with an error status; `code` is its `error` field when it gave one, `next` its
+ * next step, and `fields` the whole answer (a failed setup carries the keys it minted anyway).
+ */
+export declare class LoginRefused extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly next: string | undefined;
+    readonly fields: Record<string, unknown>;
+    /** Seconds the server asked to wait (Retry-After), for a 429. */
+    readonly retryAfter: number | undefined;
+    constructor(status: number, code: string, message: string, next?: string, fields?: Record<string, unknown>, retryAfter?: number);
+}
+/** The server answered nothing in time: `ms` is how long this request was given. */
+export declare class TimedOut extends Error {
+    readonly ms: number;
+    constructor(url: string, ms: number);
+}
+/** `clientName` and `hostname` are shown on the approval page. */
+export declare function startDevice(url: string, clientName: string, hostname: string): Promise<DeviceStart>;
+/** `timeoutMs` cuts this one poll short (login gives it what is left of --timeout). */
+export declare function pollToken(url: string, deviceCode: string, timeoutMs?: number): Promise<TokenAnswer>;
+export declare function revoke(url: string, token: string): Promise<void>;
+export declare function whoami(url: string, token: string): Promise<Account>;
+export declare function setup(url: string, token: string, request: {
+    name: string;
+    hostname: string;
+    channels: string[];
+    have: string[];
+}): Promise<SetupAnswer>;
+/** The agent's .env names for what setup hands back; only the keys' and the join's names are sent as `have`. */
+export declare const SETUP_ENV: {
+    readonly cloud_key: "FLOW_FRAMEWORK_CLOUD_KEY";
+    readonly traces_key: "FLOW_FRAMEWORK_TRACES_KEY";
+    readonly messaging_key: "FLOW_MESSAGING_KEY";
+    readonly telegram_sender: "FLOW_MESSAGING_TELEGRAM_SENDER";
+    readonly whatsapp_sender: "FLOW_MESSAGING_WHATSAPP_SENDER";
+    readonly imessage_sender: "FLOW_MESSAGING_IMESSAGE_SENDER";
+    readonly join_code: "FLOW_FRAMEWORK_JOIN_CODE";
+    readonly try_url: "FLOW_FRAMEWORK_TRY_URL";
+};
+/** The phone link for a join code, built as the server builds its try_url, for a .env from before setup kept it. */
+export declare function tryLink(url: string, joinCode: string, channel: string): string;