@flow-engineer/flow 0.2.0 → 0.2.2

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

@@ -0,0 +1,176 @@
+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;
+}
+/** setup's flow_key: the agent's one Flow key, for this mode (test or live). */
+export interface FlowKey {
+    env?: string;
+    value?: string;
+    kid?: string;
+    mode?: string;
+    scopes?: string[];
+    agent_id?: string;
+    minted?: boolean;
+    /** When the key it replaced stops working (null: at once, or there was none). */
+    previous_expires_at?: string | null;
+}
+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 agent's one Flow key (FLOW_KEY), only when made in this call: its value is shown once. */
+    flow_key?: FlowKey;
+    /** The account's Flow trial model credit, when the agent has no provider key; absent: none (warnings say why). */
+    model_credit?: {
+        limit_usd?: number;
+        left_usd?: number;
+        base_url?: string;
+        default_model?: string;
+    };
+    /** 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[];
+    rotate?: true | string[];
+    rotate_now?: true;
+}): Promise<SetupAnswer>;
+/** GET /credit's answer: the account's Flow trial credit in US dollars. */
+export interface ModelCredit {
+    limit_usd?: number;
+    spent_usd?: number;
+    left_usd?: number;
+    default_model?: string;
+    models?: string[];
+}
+/** The credit left on the account of a FLOW_KEY; `baseURL` is Flow's model API (flowModelURL). */
+export declare function modelCredit(baseURL: string, key: string): Promise<ModelCredit>;
+/** 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;

package/dist/testing/src/flow-login.js

@@ -0,0 +1,274 @@
+// The flow.engineer side of `flow login`, `logout`, `whoami` and `setup`: every call to it, and
+// where the Flow CLI token is kept. Only this file knows the server's routes and field names
+// (flow.engineer's CLI sign-in contract).
+//   POST /cli/device {client_name, hostname}  -> {device_code, user_code, verification_uri, verification_uri_complete, interval, expires_in}
+//   POST /cli/token {device_code}             -> {access_token, expires_at, account}, or 400 {error} as RFC 8628 has it:
+//                                                authorization_pending, slow_down, expired_token, access_denied, invalid_grant
+//   POST /cli/revoke (bearer) {}              ends this token
+//   GET  /cli/whoami (bearer)                 -> {account, email, token}
+//   POST /cli/setup (bearer) {name, hostname, channels, have, rotate?, rotate_now?}
+//        -> {agent_id, cloud_key?, traces_key?, messaging_key?, flow_key?, model_credit?, join_code, account, app_id,
+//            dashboard_url, try_url, <channel>_sender?, <channel>_link? (telegram, whatsapp, imessage: each only while
+//            that shared sender is open), try_urls?, trial?, minted, next}; a 502 carries every field that worked too;
+//        flow_key is the agent's one Flow key, {env: "FLOW_KEY", value: "flow_test_...", kid, mode, scopes, agent_id,
+//        minted: true, previous_expires_at}, only when made in this call (in every answer of that call, errors too;
+//        absent when have names FLOW_KEY and rotate does not); for now only the model uses it;
+//        model_credit is the account's Flow trial model credit, {limit_usd, left_usd, base_url, default_model}, when
+//        have names no provider key and the account has the credit (left_usd 0 when used up), else absent with
+//        the reason in warnings; every folder's setup makes its own key, the credit is the account's;
+//        rotate is true (every key) or the answer fields to make again, such as ["flow_key"]; rotate_now: true
+//        ends the old FLOW_KEY at once instead of 24 h later (previous_expires_at);
+//        429 slow_down with Retry-After; 403 for a trial limit (sandbox_allowance_used, ...), its next prose
+//        Any answer may carry warnings: up to 20 strings to show the owner as they are.
+//   GET  <model URL>/credit (bearer FLOW_KEY) -> {limit_usd, spent_usd, left_usd, default_model, models};
+//        the model URL is src/model.ts's flowModelURL (flow.engineer/llm/framework/v1); 401 invalid_api_key,
+//        403 insufficient_scope (the key lacks model), 402 trial_credit_used or trial_credit_unavailable
+// Every error is flat: {"error": "<code>", "error_description": "<sentence>", "next": "<command, URL or sentence>"}
+// (the model API's are OpenAI's shape, {"error": {message, type, code, next}}).
+// The token is opaque (fcli_...), good only for /cli/*, and sent only to the server that issued it,
+// over https (http only to this machine). Every request gives up after REQUEST_TIMEOUT_MS at most.
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { configDir, configFile, RUN, setting } from "../../src/names.js";
+export 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 const REQUEST_TIMEOUT_MS = 30_000;
+/** A login URL a token may go to: https, or http to this machine only (a local flow.engineer). */
+export function safeLoginUrl(url) {
+    const parsed = URL.parse(url);
+    if (!parsed)
+        return false;
+    if (parsed.protocol === "https:")
+        return true;
+    return parsed.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname);
+}
+/** flow.engineer, or FLOW_FRAMEWORK_LOGIN_URL, without trailing slashes (trimmed from the end, in linear time). */
+export function loginUrl(env = process.env) {
+    const url = setting("LOGIN_URL", env) || LOGIN_URL;
+    let end = url.length;
+    while (end > 0 && url[end - 1] === "/")
+        end--;
+    return url.slice(0, end);
+}
+/** ~/.config/flow-framework/credentials.json (XDG_CONFIG_HOME when set), written at mode 0600. */
+export function credentialsPath(env = process.env) {
+    return join(configDir(env), "credentials.json");
+}
+/** The credentials file to read or delete: credentialsPath, else ~/.config/chinwag/credentials.json while only it exists. */
+const savedCredentialsPath = (env) => configFile("credentials.json", env);
+/**
+ * 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 function currentToken(env = process.env) {
+    const fromEnv = setting("TOKEN", env)?.trim();
+    if (fromEnv)
+        return { token: fromEnv, from: "env" };
+    const saved = readCredentials(env);
+    return saved ? { token: saved.token, from: "file", url: saved.url || LOGIN_URL } : undefined;
+}
+export function readCredentials(env = process.env) {
+    const path = savedCredentialsPath(env);
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const saved = JSON.parse(readFileSync(path, "utf8"));
+        return typeof saved.token === "string" && saved.token ? saved : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function saveCredentials(credentials, env = process.env) {
+    const path = credentialsPath(env);
+    mkdirSync(join(path, ".."), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify(credentials, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600); // a file that was already there keeps its mode on write
+    return path;
+}
+export function deleteCredentials(env = process.env) {
+    const path = savedCredentialsPath(env);
+    if (!existsSync(path))
+        return false;
+    rmSync(path);
+    return true;
+}
+/** ~/.config/flow-framework/pending.json, written at mode 0600 and deleted once the code is used or expired. */
+export function pendingPath(env = process.env) {
+    return join(configDir(env), "pending.json");
+}
+export function readPending(env = process.env) {
+    try {
+        const saved = JSON.parse(readFileSync(pendingPath(env), "utf8"));
+        return typeof saved.device_code === "string" && typeof saved.expires_at === "number" ? saved : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function savePending(pending, env = process.env) {
+    const path = pendingPath(env);
+    mkdirSync(join(path, ".."), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify(pending, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(path, 0o600);
+}
+export function deletePending(env = process.env) {
+    rmSync(pendingPath(env), { force: true });
+}
+/** The answer's warnings: its strings only, at most 20. */
+export function warningsOf(body) {
+    return Array.isArray(body.warnings) ? body.warnings.filter((w) => typeof w === "string" && w !== "").slice(0, 20) : [];
+}
+/** Retry-After as seconds from now (delta-seconds or an HTTP date); undefined when absent or unreadable. */
+export function retryAfterSeconds(header, now = Date.now()) {
+    if (!header)
+        return undefined;
+    const value = header.trim();
+    if (/^\d+$/.test(value))
+        return Number(value);
+    const at = Date.parse(value);
+    return Number.isNaN(at) ? undefined : Math.max(0, Math.ceil((at - now) / 1000));
+}
+/**
+ * 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 class LoginRefused extends Error {
+    status;
+    code;
+    next;
+    fields;
+    /** Seconds the server asked to wait (Retry-After), for a 429. */
+    retryAfter;
+    constructor(status, code, message, next, fields = {}, retryAfter) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.next = next;
+        this.fields = fields;
+        this.retryAfter = retryAfter;
+    }
+}
+/** The server answered nothing in time: `ms` is how long this request was given. */
+export class TimedOut extends Error {
+    ms;
+    constructor(url, ms) {
+        super(`${url} did not answer within ${Math.ceil(ms / 1000)} s.`);
+        this.ms = ms;
+    }
+}
+async function call(url, path, options = {}) {
+    if (!safeLoginUrl(url)) {
+        throw new LoginRefused(0, "insecure_login_url", `${url} is not https: the sign-in and its token go only over https (http only to localhost).`, `set FLOW_FRAMEWORK_LOGIN_URL to an https address, or unset it to use ${LOGIN_URL}`);
+    }
+    const timeoutMs = Math.max(0, Math.min(options.timeoutMs ?? REQUEST_TIMEOUT_MS, REQUEST_TIMEOUT_MS));
+    const headers = { accept: "application/json" };
+    if (options.token)
+        headers.authorization = `Bearer ${options.token}`;
+    if (options.body !== undefined)
+        headers["content-type"] = "application/json";
+    let response;
+    let text;
+    try {
+        response = await fetch(`${url}${path}`, {
+            method: options.method ?? "POST",
+            headers,
+            body: options.body === undefined ? undefined : JSON.stringify(options.body),
+            redirect: options.token ? "error" : "follow", // a redirect would carry the token to another address
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+        text = await response.text();
+    }
+    catch (error) {
+        if (error.name === "TimeoutError")
+            throw new TimedOut(url, timeoutMs);
+        throw error;
+    }
+    let body = {};
+    try {
+        body = text ? JSON.parse(text) : {};
+    }
+    catch {
+        if (response.ok)
+            throw new LoginRefused(response.status, "bad_answer", `${url}${path} answered ${response.status} with no JSON.`);
+    }
+    return { status: response.status, body, retryAfter: retryAfterSeconds(response.headers.get("retry-after")) };
+}
+function refused(path, answer, url) {
+    // A bare 404: this server has no CLI sign-in (an older one, or not flow.engineer at all).
+    if (answer.status === 404 && typeof answer.body.error !== "string") {
+        return new LoginRefused(404, "server_unsupported", `${url} has no ${path}, so it cannot sign in the Flow CLI: it is an older server, or not flow.engineer.`, url === LOGIN_URL ? `${RUN}@latest login` : `unset FLOW_FRAMEWORK_LOGIN_URL to use ${LOGIN_URL}, or point it at a server that has /cli/`, answer.body);
+    }
+    const code = typeof answer.body.error === "string" ? answer.body.error : answer.status === 401 ? "not_signed_in" : `http_${answer.status}`;
+    const detail = typeof answer.body.error_description === "string" ? answer.body.error_description : typeof answer.body.message === "string" ? answer.body.message : "";
+    const next = typeof answer.body.next === "string" && answer.body.next ? answer.body.next : undefined;
+    const sentence = detail.endsWith(".") ? detail.slice(0, -1) : detail;
+    return new LoginRefused(answer.status, code, `${path} answered ${answer.status} ${code}${sentence ? `: ${sentence}` : ""}.`, next, answer.body, answer.retryAfter);
+}
+/** `clientName` and `hostname` are shown on the approval page. */
+export async function startDevice(url, clientName, hostname) {
+    const answer = await call(url, "/cli/device", { body: { client_name: clientName, hostname } });
+    if (answer.status !== 200 || typeof answer.body.device_code !== "string")
+        throw refused("/cli/device", answer, url);
+    return answer.body;
+}
+const WAITING = new Set(["authorization_pending", "slow_down", "expired_token", "access_denied"]);
+/** `timeoutMs` cuts this one poll short (login gives it what is left of --timeout). */
+export async function pollToken(url, deviceCode, timeoutMs) {
+    const answer = await call(url, "/cli/token", { body: { device_code: deviceCode }, timeoutMs });
+    const token = answer.body.access_token;
+    if (answer.status === 200 && typeof token === "string") {
+        return { status: "signed_in", token, expires_at: answer.body.expires_at, account: answer.body.account };
+    }
+    const error = answer.body.error;
+    if (typeof error === "string" && WAITING.has(error))
+        return { status: error };
+    throw refused("/cli/token", answer, url);
+}
+export async function revoke(url, token) {
+    const answer = await call(url, "/cli/revoke", { token, body: {} });
+    // 401: the token had already ended, which is what logout wants.
+    if (answer.status >= 300 && answer.status !== 401)
+        throw refused("/cli/revoke", answer, url);
+}
+export async function whoami(url, token) {
+    const answer = await call(url, "/cli/whoami", { token, method: "GET" });
+    if (answer.status !== 200)
+        throw refused("/cli/whoami", answer, url);
+    return answer.body;
+}
+export async function setup(url, token, request) {
+    const answer = await call(url, "/cli/setup", { token, body: request });
+    // A 200 is returned whole even without a join code: the keys it minted are shown only now.
+    if (answer.status !== 200)
+        throw refused("/cli/setup", answer, url);
+    return answer.body;
+}
+/** The credit left on the account of a FLOW_KEY; `baseURL` is Flow's model API (flowModelURL). */
+export async function modelCredit(baseURL, key) {
+    let end = baseURL.length;
+    while (end > 0 && baseURL[end - 1] === "/")
+        end--;
+    const answer = await call(baseURL.slice(0, end), "/credit", { token: key, method: "GET" });
+    if (answer.status !== 200) {
+        // OpenAI's error shape: {"error": {message, code, next}}.
+        const inner = answer.body.error && typeof answer.body.error === "object" ? answer.body.error : undefined;
+        throw refused("/credit", inner ? { ...answer, body: { error: inner.code, error_description: inner.message, next: inner.next } } : answer, baseURL);
+    }
+    return answer.body;
+}
+/** The agent's .env names for what setup hands back; only the keys' and the join's names are sent as `have`. */
+export const SETUP_ENV = {
+    cloud_key: "FLOW_FRAMEWORK_CLOUD_KEY",
+    traces_key: "FLOW_FRAMEWORK_TRACES_KEY",
+    messaging_key: "FLOW_MESSAGING_KEY",
+    telegram_sender: "FLOW_MESSAGING_TELEGRAM_SENDER",
+    whatsapp_sender: "FLOW_MESSAGING_WHATSAPP_SENDER",
+    imessage_sender: "FLOW_MESSAGING_IMESSAGE_SENDER",
+    join_code: "FLOW_FRAMEWORK_JOIN_CODE",
+    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 function tryLink(url, joinCode, channel) {
+    return `${url}/try/${encodeURIComponent(joinCode)}?c=${encodeURIComponent(channel)}`;
+}

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

@@ -2,8 +2,21 @@
 export declare function checkName(name: string): void;
 /** The @flow-engineer/flow package's folder: the root of a clone, or the installed package. */
 export declare function packageRoot(from?: string): string;
+/** The longest display name: the join message carries it (flow.engineer's /try cuts it there too). */
+export declare const MAX_DISPLAY_NAME = 60;
+/** The name people call the agent, from the package name when none was given: "my-shop" is "my shop". */
+export declare function displayNameOf(given: string | undefined, packageName: string): string;
+interface MakeOptions {
+    root?: string;
+    /** What people call the agent; the package name in words when not given. */
+    displayName?: string;
+}
 /** Makes `<into>/<name>` (the current folder by default) and returns it. */
-export declare function newStandalone(name: string, options?: {
+export declare function newStandalone(name: string, options?: MakeOptions & {
     into?: string;
-    root?: string;
 }): string;
+/** The package name `flow init` gives the agent in `dir`: the folder's name in lowercase and dashes. */
+export declare function folderName(dir: string): string;
+/** Makes the agent in `dir` (the current folder by default), named after the folder; returns its name. */
+export declare function initHere(dir?: string, options?: MakeOptions): string;
+export {};

package/dist/testing/src/new.js

@@ -1,9 +1,12 @@
 // `flow new <name>`: makes ./<name>/, an agent of its own started from the café example (Pip),
-// that depends on the @flow-engineer/flow package. Its imports become "@flow-engineer/flow" and "@flow-engineer/flow/simulators", and
-// the coding-agent skills go in .claude/skills/, with an AGENTS.md (and a CLAUDE.md importing it)
-// pointing at them. Inside a clone, `npm run new -- <name>` makes agents/<name>/ instead.
+// that depends on the @flow-engineer/flow package. Its imports become "@flow-engineer/flow",
+// "@flow-engineer/flow/simulators" and "@flow-engineer/flow/flow-messaging", and the coding-agent
+// skills go in .claude/skills/, with an AGENTS.md (and a CLAUDE.md importing it) pointing at them.
+// `flow init` makes the same agent in the current folder. Inside a clone, `npm run new -- <name>`
+// makes agents/<name>/ instead. `--display-name` is what people call the agent ("FlatX agent"), kept
+// as package.json's displayName: the message a phone sends to reach it is "Hi <it> (ref <code>)".
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 const NAME = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 /** Throws unless `name` can be an agent's folder and package name. */
@@ -36,8 +39,10 @@ const TSCONFIG = {
     },
     include: ["src"],
 };
-const ENV_EXAMPLE = `# One model key. The first line with a value is the one used.
-# Make it at the provider, then paste it here. Never commit this file.
+const ENV_EXAMPLE = `# The model key. The first line with a value is the one used. npx @flow-engineer/flow setup writes
+# FLOW_KEY, the agent's one Flow key, which calls models on the account's free trial credit, so no
+# provider key is needed; your own, made at the provider and pasted on its line, wins over it.
+# Never commit this file.
 #   OPENROUTER_API_KEY   https://openrouter.ai/keys
 #   OPENAI_API_KEY       https://platform.openai.com/api-keys
 #   ANTHROPIC_API_KEY    https://console.anthropic.com/settings/keys
@@ -46,11 +51,12 @@ OPENROUTER_API_KEY=
 OPENAI_API_KEY=
 ANTHROPIC_API_KEY=
 GEMINI_API_KEY=
+FLOW_KEY=
 
 # Optional. The model id for that provider; empty is that provider's default.
 # CAFE_MODEL=
 
-# The test cloud (npx flow test --synthetic) and traces. Sign in at https://flow.engineer/observe,
+# The test cloud (npx @flow-engineer/flow test --synthetic) and traces. Sign in at https://flow.engineer/observe,
 # add the agent, and on its Developers page make a CI key (oci_..., shown once); the trace key is
 # from the same site.
 FLOW_FRAMEWORK_CLOUD=https://flow.engineer/observe
@@ -62,21 +68,61 @@ const agentsMd = (name) => `# ${name}
 
 A chat agent on Flow Framework (https://github.com/flow-engineer/flow), started from its café example (Pip).
 
-- Load the skills in \`.claude/skills/\` before changing it: \`flow-framework\` to build the agent, \`flow-framework-tools\`
-  for its tools and their test files, \`flow-framework-tests\` for its test scenarios.
+- Load the skills in \`.claude/skills/\` before changing it: \`flow-framework\` to build the agent (and its MCP
+  server and CLI), \`flow-framework-tools\` for its tools and their test files, \`flow-framework-tests\` for its test
+  scenarios, \`flow-framework-context\` to gather what the tools are written from out of an existing
+  codebase, and \`flow-framework-auth\` for sign-in.
 - \`agent/AGENTS.md\` is the agent's own prompt, not instructions for coding agents.
-- \`npm start\` runs it in the playground. The owner puts one model key in \`.env\` (never read or
-  print it): \`OPENROUTER_API_KEY\`, \`OPENAI_API_KEY\`, \`ANTHROPIC_API_KEY\` or \`GEMINI_API_KEY\`.
-  \`npm run typecheck\` checks the types, \`npm test -- --synthetic\` runs the tests in the test
-  cloud at https://flow.engineer/observe with the owner's \`FLOW_FRAMEWORK_CLOUD_KEY\` (\`npx flow --help\`).
+- The model key goes in \`.env\` (never read or print it): \`npx @flow-engineer/flow link\` (or \`setup\`)
+  writes \`FLOW_KEY\`, the agent's one Flow key, which calls models on Flow's free trial credit, so no provider key is needed; a key the owner types
+  (\`OPENROUTER_API_KEY\`, \`OPENAI_API_KEY\`, \`ANTHROPIC_API_KEY\` or \`GEMINI_API_KEY\`) wins over it. \`npm start\` runs it in the playground,
+  and \`npx @flow-engineer/flow link\` signs in, puts its other keys in \`.env\` and prints the link that
+  reaches it from a phone while \`npm start\` runs.
+- When the owner asks how to test it, recommend first the playground (\`npm start\`, then open the link
+  it prints: the test people and the channels side by side), then their phone (the \`link\`).
+- Your own checks, not the owner's way to test: \`npx @flow-engineer/flow chat\` talks to it in the
+  terminal, \`npm run typecheck\` checks the types, \`npm test -- --synthetic\` runs the tests in the
+  test cloud at https://flow.engineer/observe with the owner's \`FLOW_FRAMEWORK_CLOUD_KEY\`
+  (\`npx @flow-engineer/flow --help\`).
+- The guide for coding agents, with exit codes and next steps: https://github.com/flow-engineer/flow/blob/main/docs/agents.md
+- \`npm run mcp\` serves the same tools as an MCP server (src/mcp.ts) and \`npm run cli -- --help\` is
+  its command line (src/cli.ts). \`npx flow check\` checks the tools and the CLI file for both.
 `;
+/** The longest display name: the join message carries it (flow.engineer's /try cuts it there too). */
+export const MAX_DISPLAY_NAME = 60;
+/** The name people call the agent, from the package name when none was given: "my-shop" is "my shop". */
+export function displayNameOf(given, packageName) {
+    const name = (given ?? "").replace(/[()]/g, " ").replace(/\s+/g, " ").trim();
+    if (name.length > MAX_DISPLAY_NAME)
+        throw new Error(`--display-name is at most ${MAX_DISPLAY_NAME} characters, such as "FlatX agent".`);
+    return name || packageName.replace(/-/g, " ");
+}
 /** Makes `<into>/<name>` (the current folder by default) and returns it. */
 export function newStandalone(name, options = {}) {
     checkName(name);
-    const root = options.root ?? packageRoot();
+    const displayName = displayNameOf(options.displayName, name);
     const dir = join(options.into ?? process.cwd(), name);
     if (existsSync(dir))
         throw new Error(`${dir} already exists: pick another name or remove it.`);
+    makeAgent(dir, name, displayName, options.root ?? packageRoot());
+    return dir;
+}
+/** What `flow init` writes into a folder; it refuses a folder that holds any of them, so nothing is overwritten. */
+const MADE = ["package.json", "tsconfig.json", "src", "agent", "tests", ".env.example", "AGENTS.md", "CLAUDE.md", ".npmrc"];
+/** The package name `flow init` gives the agent in `dir`: the folder's name in lowercase and dashes. */
+export function folderName(dir) {
+    return basename(dir).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "my-agent";
+}
+/** Makes the agent in `dir` (the current folder by default), named after the folder; returns its name. */
+export function initHere(dir = process.cwd(), options = {}) {
+    const taken = MADE.filter((f) => existsSync(join(dir, f)));
+    if (taken.length)
+        throw new Error(`${dir} has ${taken.join(", ")} already: run flow init in an empty folder, or flow new <name> to make one.`);
+    const name = folderName(dir);
+    makeAgent(dir, name, displayNameOf(options.displayName, name), options.root ?? packageRoot());
+    return name;
+}
+function makeAgent(dir, name, displayName, root) {
     const cafe = join(root, "examples", "cafe");
     for (const part of ["agent", "src", "tests"])
         cpSync(join(cafe, part), join(dir, part), { recursive: true });
@@ -84,26 +130,40 @@ export function newStandalone(name, options = {}) {
         const path = join(dir, "src", file);
         const source = readFileSync(path, "utf8")
             .replace(/(["'])(\.\.\/)+src\/index\.ts\1/g, '"@flow-engineer/flow"')
-            .replace(/(["'])(\.\.\/)+simulators\/src\/index\.ts\1/g, '"@flow-engineer/flow/simulators"');
-        if (/["']\.\.\/\.\.\//.test(source))
+            .replace(/(["'])(\.\.\/)+simulators\/src\/index\.ts\1/g, '"@flow-engineer/flow/simulators"')
+            .replace(/(["'])(\.\.\/)+flow-messaging\/src\/index\.ts\1/g, '"@flow-engineer/flow/flow-messaging"')
+            .replace(/(["'])(\.\.\/)+mcp\/src\/index\.ts\1/g, '"@flow-engineer/flow/mcp"')
+            .replace(/(["'])(\.\.\/)+cli\/src\/index\.ts\1/g, '"@flow-engineer/flow/cli"');
+        // The CLI is the agent's own command, named after it.
+        const text = file === "cli.ts" ? source.replace(/name: "cafe"/, `name: "${name}"`).replace(/CAFE_SERVER/g, `${name.toUpperCase().replace(/-/g, "_")}_SERVER`) : source;
+        if (/["']\.\.\/\.\.\//.test(text))
             throw new Error(`flow: ${file} imports a file outside the agent; only Flow Framework's public entries can be rewritten.`);
-        writeFileSync(path, source);
+        writeFileSync(path, text);
     }
     const own = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
     const pkg = {
         name,
+        // What people call it: the message a phone sends to reach it is "Hi <displayName> (ref <code>)".
+        displayName,
         version: "0.1.0",
         private: true,
         description: `${name}: a Flow Framework agent, started from the café example.`,
         type: "module",
+        bin: { [name]: "src/cli.ts" },
         engines: own.engines,
-        scripts: { start: "node --env-file-if-exists=.env src/main.ts", test: "flow test", typecheck: "tsc --noEmit" },
-        dependencies: { "@flow-engineer/flow": `^${own.version}` },
+        scripts: { start: "node --env-file-if-exists=.env src/main.ts", mcp: "node src/mcp.ts", cli: "node src/cli.ts", test: "flow test", typecheck: "tsc --noEmit" },
+        // The café serves its tools over MCP (src/mcp.ts) and as a CLI (src/cli.ts): their SDKs, pinned as Flow Framework pins them.
+        dependencies: { "@flow-engineer/flow": `^${own.version}`, ...own.peerDependencies },
         devDependencies: { "@types/node": own.devDependencies["@types/node"], typescript: own.devDependencies.typescript },
     };
     writeFileSync(join(dir, "package.json"), `${JSON.stringify(pkg, null, 2)}\n`);
     writeFileSync(join(dir, "tsconfig.json"), `${JSON.stringify(TSCONFIG, null, 2)}\n`);
-    writeFileSync(join(dir, ".gitignore"), "node_modules/\n.env\n.flow/\n");
+    // An existing .gitignore (flow init in a fresh repository) keeps its lines and gets the missing ones.
+    const ignore = join(dir, ".gitignore");
+    const ignored = existsSync(ignore) ? readFileSync(ignore, "utf8") : "";
+    const missing = ["node_modules/", ".env", ".flow/"].filter((line) => !ignored.split("\n").includes(line));
+    if (missing.length)
+        writeFileSync(ignore, `${ignored}${ignored && !ignored.endsWith("\n") ? "\n" : ""}${missing.join("\n")}\n`);
     // npm install then refuses a Node older than the engines field says, before .ts files fail to load.
     writeFileSync(join(dir, ".npmrc"), "engine-strict=true\n");
     writeFileSync(join(dir, ".env.example"), ENV_EXAMPLE);
@@ -118,5 +178,4 @@ export function newStandalone(name, options = {}) {
     }
     writeFileSync(join(dir, "AGENTS.md"), agentsMd(name));
     writeFileSync(join(dir, "CLAUDE.md"), "@AGENTS.md\n");
-    return dir;
 }

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

@@ -0,0 +1,4 @@
+export declare const PLUGIN_LINE = "  flow plugin --server <url> --out <dir>  Write Claude Code and Agent Plugins packages";
+export declare function pluginProblems(dir: string, out: string): string[];
+export declare function writePlugins(dir: string, server: string, out: string, name?: string): void;
+export declare function pluginCli(argv: string[], dir?: string): number;