@flow-engineer/flow 0.2.1 → 0.2.3

package/dist/cli/src/run.js

@@ -0,0 +1,523 @@
+// Runs an organization's CLI on Stricli (@stricli/core, the framework Sentry's CLI is built on):
+// command groups whose help lists their subcommands (`acme order`, `acme order -h`), help for every
+// command (`acme order place -h`), typo suggestions, typed flags and positional arguments. On top of
+// it, the conventions agents and scripts rely on: --json (and --fields) on every tool command,
+// --dry-run on anything that changes things, --yes needed without a terminal for what may delete or
+// overwrite, and fixed exit codes. The commands come from the server's tools at run time, shaped by
+// the CLI file (commands.ts).
+import { runTerminal } from "./terminal.js";
+import { randomUUID } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { Client, InsufficientScopeError, SdkHttpError, StreamableHTTPClientTransport, UnauthorizedError } from "@modelcontextprotocol/client";
+import { buildApplication, buildCommand, buildRouteMap, numberParser, run as runStricli } from "@stricli/core";
+import { isSignedIn, signIn, signOut, storedProvider } from "./auth.js";
+import { BUILT_IN, commandTable, flagKind, flagName, findCommand, isCustom, skillFile, tokenEnvOf, typeHint, } from "./commands.js";
+export const EXIT = { ok: 0, failed: 1, usage: 2, signIn: 3, approval: 4, unreachable: 5 };
+export function processIO() {
+    return {
+        write: (text) => void process.stdout.write(text),
+        writeError: (text) => void process.stderr.write(text),
+        interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        async *lines(prompt) {
+            const rl = createInterface({ input: process.stdin, output: process.stderr });
+            if (prompt) {
+                rl.setPrompt(prompt);
+                rl.prompt();
+            }
+            try {
+                for await (const line of rl) {
+                    yield line;
+                    if (prompt)
+                        rl.prompt();
+                }
+            }
+            finally {
+                rl.close();
+            }
+        },
+        async confirm(question) {
+            const rl = createInterface({ input: process.stdin, output: process.stderr });
+            try {
+                return /^y(es)?$/i.test((await rl.question(`${question} [y/N] `)).trim());
+            }
+            finally {
+                rl.close();
+            }
+        },
+    };
+}
+/** A failure the CLI reports with its own exit code. */
+class CliExit extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+/** Takes `--server` and `--token` out before the commands are known (they decide which commands exist). */
+function connectionFlags(argv) {
+    const rest = [];
+    const found = {};
+    for (let i = 0; i < argv.length; i++) {
+        const m = /^--(server|token)(?:=(.*))?$/.exec(argv[i]);
+        if (!m)
+            rest.push(argv[i]);
+        else
+            found[m[1]] = m[2] ?? argv[++i] ?? "";
+    }
+    return { rest, server: found.server, token: found.token };
+}
+function callMeta(config, command) {
+    return { "chinwag/surface": "cli", "chinwag/command": command, "chinwag/client-version": config.version ?? "1", "chinwag/idempotency-key": randomUUID() };
+}
+function envName(config, suffix) {
+    return `${config.name.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_${suffix}`;
+}
+function noServer(config) {
+    return `No server: pass --server <url> or set ${envName(config, "SERVER")}.`;
+}
+/** Run the CLI once; resolves with its exit code. */
+export async function runCli(config, argv, io = processIO()) {
+    io.signal?.throwIfAborted();
+    const env = io.env ?? process.env;
+    const name = config.name;
+    const { rest, server: given, token: givenToken } = connectionFlags(argv);
+    const server = given ?? config.server ?? env[envName(config, "SERVER")];
+    const token = givenToken ?? env[tokenEnvOf(config)];
+    if (rest[0] === "chat" && !config.commands?.[rest[0]])
+        return runTerminal(config, server, token, rest, io);
+    const asksHelp = rest.length === 0 || rest[0] === "-h" || rest[0] === "--help";
+    let client;
+    let tools = [];
+    let problem;
+    if (server && rest[0] !== "auth") {
+        try {
+            client = await connect(config, server, token, io.signal);
+            io.signal?.throwIfAborted();
+            tools = await listTools(client);
+        }
+        catch (error) {
+            await client?.close();
+            client = undefined;
+            problem = explain(config, server, error);
+        }
+    }
+    if (io.signal?.aborted) {
+        await client?.close();
+        return EXIT.failed;
+    }
+    if (problem && !asksHelp) {
+        io.writeError(`${problem.message}\n`);
+        return problem.code;
+    }
+    const stricliProcess = {
+        stdout: { write: (text) => io.write(text) },
+        stderr: { write: (text) => io.writeError(text) },
+        env: { ...env, ...(env.NO_COLOR ? { STRICLI_NO_COLOR: "1" } : {}) },
+        exitCode: undefined,
+    };
+    const context = {
+        process: stricliProcess,
+        cli: {
+            call: async (tool, input) => {
+                if (!client)
+                    throw new CliExit(EXIT.unreachable, noServer(config));
+                return valueOf(await client.callTool({ name: tool, arguments: input, _meta: callMeta(config, findCommand(commandTable(config, tools), rest)?.command.words.join(" ") ?? "custom") }));
+            },
+            print: (value, options = {}) => io.write(`${render(value, options)}\n`),
+        },
+    };
+    const disconnect = () => { void client?.close(); };
+    io.signal?.addEventListener("abort", disconnect, { once: true });
+    try {
+        const app = buildApplication(routes(config, server, tools, client, io), {
+            name,
+            scanner: { caseStyle: "original" },
+            determineExitCode: (error) => (error instanceof CliExit ? error.code : needsSignIn(error) ? EXIT.signIn : EXIT.failed),
+        });
+        await runStricli(app, rest, { ...context, process: stricliProcess });
+    }
+    finally {
+        io.signal?.removeEventListener("abort", disconnect);
+        await client?.close();
+    }
+    if (problem)
+        io.writeError(`\n${problem.message}\n`);
+    const code = Number(stricliProcess.exitCode ?? 0);
+    if (code < 0) {
+        // Stricli's own: an unknown command or a wrong argument. Point at the help of what was typed.
+        const words = rest.filter((w) => !w.startsWith("-"));
+        io.writeError(`Run \`${[name, ...wordsKnown(words, config, tools)].join(" ")} --help\` to see how to use it.\n`);
+        return EXIT.usage;
+    }
+    return code;
+}
+/** The words of the command line that name a group or command, for the help hint. */
+function wordsKnown(words, config, tools) {
+    const paths = [...commandTable(config, tools).map((c) => c.words.join(" ")), ...BUILT_IN, "auth login", "auth logout", "auth status"];
+    const known = [];
+    for (const w of words) {
+        const next = [...known, w].join(" ");
+        if (!paths.some((p) => p === next || p.startsWith(`${next} `)))
+            break;
+        known.push(w);
+    }
+    return known;
+}
+async function connect(config, server, token, signal) {
+    const provider = token ? { token: async () => token } : isSignedIn(config, server) ? storedProvider(config, server, undefined, signal) : undefined;
+    const client = new Client({ name: `${config.name}-cli`, version: config.version ?? "1" });
+    try {
+        await client.connect(new StreamableHTTPClientTransport(new URL(server), provider ? { authProvider: provider } : {}));
+        signal?.throwIfAborted();
+    }
+    catch (error) {
+        await client.close();
+        throw error;
+    }
+    return client;
+}
+async function listTools(client) {
+    const tools = [];
+    let cursor;
+    do {
+        const page = await client.listTools(cursor ? { cursor } : {});
+        tools.push(...page.tools);
+        cursor = page.nextCursor;
+    } while (cursor);
+    return tools;
+}
+/** Why the server could not be used, as one line and an exit code. */
+function explain(config, server, error) {
+    if (needsSignIn(error))
+        return new CliExit(EXIT.signIn, `Sign in first: ${config.name} auth login (or set ${tokenEnvOf(config)}).`);
+    const status = error instanceof SdkHttpError ? error.data?.status : undefined;
+    const why = short(error.message);
+    return new CliExit(EXIT.unreachable, status ? `${server} answered ${status}, not as an MCP server: is this its /mcp address? (${why})` : `Could not reach ${server}: ${why}`);
+}
+/** A server's error as one short line: a web page answering instead of an MCP server is not printed whole. */
+function short(message) {
+    if (/<html|<!doctype/i.test(message))
+        return "it answered with a web page, not an MCP server (is this the /mcp address?)";
+    const line = message.split("\n")[0];
+    return line.length > 200 ? `${line.slice(0, 200)}…` : line;
+}
+/** Only a real challenge means sign in: a 401, or a 403 asking for more scope. Any other 403 is a refusal. */
+function needsSignIn(error) {
+    if (error instanceof UnauthorizedError || error instanceof InsufficientScopeError)
+        return true;
+    return error instanceof SdkHttpError && error.data?.status === 401;
+}
+/** The command tree: groups from the commands' words, then the CLI's own commands. */
+function routes(config, server, tools, client, io) {
+    const root = { children: new Map() };
+    for (const c of commandTable(config, tools)) {
+        let node = root;
+        for (const word of c.words) {
+            if (!node.children.has(word))
+                node.children.set(word, { children: new Map() });
+            node = node.children.get(word);
+        }
+        node.command = c.config && isCustom(c.config) ? c.config.command : toolCommand(config, c, client, io);
+    }
+    const build = (node, path) => {
+        const out = {};
+        for (const [word, child] of node.children) {
+            const here = [...path, word];
+            if (child.command && child.children.size)
+                throw new Error(`${config.name}: "${here.join(" ")}" is both a command and a group; a word is one or the other.`);
+            if (child.command)
+                out[word] = child.command;
+            else {
+                const sub = build(child, here);
+                out[word] = buildRouteMap({ routes: sub, docs: { brief: config.groups?.[here.join(" ")] ?? Object.keys(sub).join(", ") } });
+            }
+        }
+        return out;
+    };
+    const top = build(root, []);
+    for (const word of BUILT_IN)
+        if (top[word])
+            throw new Error(`${config.name}: "${word}" is the CLI's own command; name yours something else.`);
+    const notice = server ? `Server: ${server}` : noServer(config);
+    return buildRouteMap({
+        routes: { ...top,
+            chat: top.chat ?? buildCommand({ docs: { brief: "Chat with the agent in a terminal (chat --help)" }, parameters: {}, func() { } }),
+            tools: toolsCommand(tools, io), skill: skillCommand(config, tools, io), auth: authRoutes(config, server, io) },
+        docs: { brief: config.description ?? config.name, fullDescription: `${config.description ?? config.name}\n\n${notice}\n--server <url> and --token <token> work on every command.` },
+    });
+}
+/** Flags the CLI puts on tool commands itself. */
+const OWN_FLAGS = ["json", "fields", "dry-run", "yes"];
+/** A tool as a Stricli command: its input as flags (and the CLI file's positional arguments). */
+function toolCommand(config, c, client, io) {
+    const tool = c.tool;
+    const settings = c.config && !isCustom(c.config) ? c.config : undefined;
+    const args = settings?.args ?? [];
+    const props = tool.inputSchema.properties ?? {};
+    const required = new Set(tool.inputSchema.required ?? []);
+    const writes = tool.annotations?.readOnlyHint !== true;
+    const destructive = writes && tool.annotations?.destructiveHint !== false;
+    const byFlag = new Map();
+    const flags = {};
+    for (const [field, schema] of Object.entries(props)) {
+        if (args.includes(field))
+            continue;
+        const key = flagName(field);
+        if (OWN_FLAGS.includes(key))
+            throw new Error(`${config.name}: ${tool.name}'s input ${field} clashes with the CLI's --${key}.`);
+        byFlag.set(key, field);
+        flags[key] = flagSpec(field, schema, !required.has(field));
+    }
+    flags.json = { kind: "boolean", brief: "Print JSON: for scripts and agents", optional: true, withNegated: false };
+    flags.fields = { kind: "parsed", parse: (v) => v.split(",").map((f) => f.trim()).filter(Boolean), brief: "Only these fields, comma-separated (a.b for nested ones)", placeholder: "a,b", optional: true };
+    if (writes)
+        flags["dry-run"] = { kind: "boolean", brief: "Show the call it would make, and send nothing", optional: true, withNegated: false };
+    if (destructive)
+        flags.yes = { kind: "boolean", brief: "Don't ask first (needed without a terminal)", optional: true, withNegated: false };
+    const examples = settings?.examples?.length ? `\n\nExamples:\n${settings.examples.map((e) => `  ${e}`).join("\n")}` : "";
+    const usage = `${config.name} ${c.words.join(" ")}`;
+    return buildCommand({
+        docs: { brief: c.summary, fullDescription: `${tool.description ?? c.summary}${examples}` },
+        parameters: {
+            flags: flags,
+            positional: { kind: "tuple", parameters: args.map((field) => ({ brief: props[field]?.description ?? field.replace(/_/g, " "), placeholder: field, parse: parserFor(field, props[field] ?? {}), optional: !required.has(field) })) },
+        },
+        async func(parsed, ...positional) {
+            const input = {};
+            args.forEach((field, i) => {
+                if (positional[i] !== undefined)
+                    input[field] = positional[i];
+            });
+            for (const [key, field] of byFlag)
+                if (parsed[key] !== undefined)
+                    input[field] = parsed[key];
+            if (writes && parsed["dry-run"])
+                return void io.write(`${JSON.stringify({ dryRun: true, tool: tool.name, arguments: input }, null, parsed.json ? undefined : 2)}\n`);
+            if (destructive && !parsed.yes) {
+                if (!io.interactive)
+                    throw new CliExit(EXIT.approval, `${usage} may delete or overwrite: run it again with --yes.`);
+                if (!(await io.confirm(`${usage} may delete or overwrite. Go ahead?`)))
+                    throw new CliExit(EXIT.approval, "Stopped; nothing was sent.");
+            }
+            if (!client)
+                throw new CliExit(EXIT.unreachable, noServer(config));
+            const result = await client.callTool({ name: tool.name, arguments: input, _meta: callMeta(config, c.words.join(" ")) }).catch((error) => {
+                throw needsSignIn(error) ? explain(config, "", error) : error;
+            });
+            if (result.isError)
+                throw new CliExit(EXIT.failed, textOf(result.content) || `${tool.name} failed.`);
+            io.write(`${render(valueOf(result), { json: Boolean(parsed.json), fields: parsed.fields, columns: settings?.columns, view: settings?.view })}\n`);
+        },
+    });
+}
+function flagSpec(field, schema, optional) {
+    const brief = schema.description ?? field.replace(/_/g, " ");
+    const kind = flagKind(schema);
+    if (schema.enum && schema.enum.every((v) => typeof v === "string"))
+        return { kind: "enum", values: schema.enum, brief, optional };
+    if (kind === "boolean")
+        return optional ? { kind: "boolean", brief, optional: true, withNegated: false } : { kind: "parsed", parse: parseBoolean, brief, placeholder: "true|false" };
+    if (kind === "list")
+        return { kind: "parsed", parse: parserFor(field, schema.items ?? {}), variadic: ",", brief: `${brief} (repeat the flag, or comma-separated)`, placeholder: flagKind(schema.items ?? {}), optional };
+    if (kind === "json")
+        return { kind: "parsed", parse: parserFor(field, schema), brief: `${schema.description ? `${schema.description}: ` : ""}JSON ${typeHint(schema)}, or @file.json`, placeholder: "json", optional };
+    return { kind: "parsed", parse: parserFor(field, schema), brief, placeholder: kind === "string" ? "text" : kind, optional };
+}
+function parseBoolean(v) {
+    if (/^(true|1|yes)$/i.test(v))
+        return true;
+    if (/^(false|0|no)$/i.test(v))
+        return false;
+    throw new Error("must be true or false");
+}
+function parserFor(field, schema) {
+    const kind = flagKind(schema);
+    if (kind === "number")
+        return numberParser;
+    if (kind === "integer") {
+        return (v) => {
+            const n = numberParser(v);
+            if (!Number.isInteger(n))
+                throw new Error(`${field} must be a whole number`);
+            return n;
+        };
+    }
+    if (kind === "boolean")
+        return parseBoolean;
+    if (kind === "json")
+        return (v) => JSON.parse(v.startsWith("@") ? readFileSync(v.slice(1), "utf8") : v);
+    return String;
+}
+function toolsCommand(tools, io) {
+    return buildCommand({
+        docs: { brief: "Every tool, with its input and output schema", fullDescription: "Every tool the server has, or one tool's full description: its input, output and hints." },
+        parameters: {
+            flags: {
+                search: { kind: "parsed", parse: String, brief: "Only tools whose name or description has this", placeholder: "text", optional: true },
+                json: { kind: "boolean", brief: "Print JSON", optional: true, withNegated: false },
+            },
+            positional: { kind: "tuple", parameters: [{ brief: "One tool's name", placeholder: "tool", parse: String, optional: true }] },
+        },
+        func(flags, named) {
+            if (named) {
+                const one = tools.find((t) => t.name === named);
+                if (!one)
+                    throw new CliExit(EXIT.usage, `No tool named ${named}.`);
+                return void io.write(`${JSON.stringify(one, null, flags.json ? undefined : 2)}\n`);
+            }
+            const q = flags.search?.toLowerCase();
+            const picked = tools.filter((t) => !q || `${t.name} ${t.title ?? ""} ${t.description ?? ""}`.toLowerCase().includes(q));
+            if (flags.json)
+                return void io.write(`${JSON.stringify(picked)}\n`);
+            const width = Math.max(4, ...picked.map((t) => t.name.length));
+            io.write(`${picked.map((t) => `${t.name.padEnd(width)}  ${t.title ?? ""}${t.annotations?.readOnlyHint ? "" : "  (changes things)"}`).join("\n")}\n`);
+        },
+    });
+}
+function skillCommand(config, tools, io) {
+    return buildCommand({
+        docs: { brief: "This CLI's SKILL.md for coding agents", fullDescription: "Every command, flag, JSON shape and exit code, for Claude Code, Codex or Cursor. --write puts it in <dir>/<name>-cli/SKILL.md." },
+        parameters: { flags: { write: { kind: "parsed", parse: String, brief: "Write it into this skills folder", placeholder: "dir", optional: true } } },
+        async func(flags) {
+            const text = skillFile(config, tools);
+            if (!flags.write)
+                return void io.write(text);
+            const { mkdirSync, writeFileSync } = await import("node:fs");
+            const { join } = await import("node:path");
+            const folder = join(flags.write, `${config.name}-cli`);
+            mkdirSync(folder, { recursive: true });
+            writeFileSync(join(folder, "SKILL.md"), text);
+            io.writeError(`Wrote ${join(folder, "SKILL.md")}\n`);
+        },
+    });
+}
+function authRoutes(config, server, io) {
+    const need = () => {
+        if (!server)
+            throw new CliExit(EXIT.usage, noServer(config));
+        return server;
+    };
+    return buildRouteMap({
+        docs: { brief: "Sign in, sign out, or see who is signed in" },
+        routes: {
+            login: buildCommand({
+                docs: { brief: "Sign in on the organization's own login page" },
+                parameters: {},
+                async func() {
+                    await signIn(config, need(), io.signal);
+                    io.writeError(`Signed in to ${need()}.\n`);
+                },
+            }),
+            logout: buildCommand({
+                docs: { brief: "Forget this computer's sign-in" },
+                parameters: {},
+                func() {
+                    signOut(config, need());
+                    io.writeError(`Signed out of ${need()}.\n`);
+                },
+            }),
+            status: buildCommand({
+                docs: { brief: "Whether you are signed in, and how" },
+                parameters: { flags: { json: { kind: "boolean", brief: "Print JSON", optional: true, withNegated: false } } },
+                func(flags) {
+                    const s = need();
+                    const env = (io.env ?? process.env)[tokenEnvOf(config)];
+                    const source = env ? "env" : isSignedIn(config, s) ? "login" : null;
+                    if (flags.json)
+                        return void io.write(`${JSON.stringify({ server: s, signedIn: source !== null, source })}\n`);
+                    io.write(`${s}: ${env ? `using ${tokenEnvOf(config)}` : source ? "signed in" : "not signed in"}\n`);
+                },
+            }),
+        },
+    });
+}
+function textOf(content) {
+    return content.filter((b) => b.type === "text").map((b) => b.text).join("\n");
+}
+function valueOf(result) {
+    if (result.isError)
+        throw new CliExit(EXIT.failed, textOf(result.content) || "The tool failed.");
+    if (result.structuredContent !== undefined)
+        return result.structuredContent;
+    const text = textOf((result.content ?? []));
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** A field by its dotted path ("event.id"). */
+function get(value, path) {
+    let v = value;
+    for (const part of path.split("."))
+        v = v && typeof v === "object" ? v[part] : undefined;
+    return v;
+}
+function pick(value, fields) {
+    if (Array.isArray(value))
+        return value.map((v) => pick(v, fields));
+    if (!value || typeof value !== "object")
+        return value;
+    const out = {};
+    for (const f of fields) {
+        const v = get(value, f);
+        if (v !== undefined)
+            out[f] = v;
+    }
+    return out;
+}
+function render(value, options) {
+    const shown = options.fields ? pick(value, options.fields) : value;
+    if (options.json)
+        return JSON.stringify(shown);
+    return human(shown, options.fields ?? options.columns, options.fields ?? options.view);
+}
+/** For people: a table for a list of records (also one inside an object, its other fields after it), field lines for one record, else the value. */
+function human(value, columns, view) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value))
+        return table(value, columns);
+    if (value && typeof value === "object") {
+        const record = value;
+        const lists = Object.keys(record).filter((k) => isRecords(record[k]));
+        if (lists.length === 1 && !view) {
+            const rest = Object.keys(record).filter((k) => k !== lists[0]);
+            return [table(record[lists[0]], columns), ...(rest.length ? ["", fields(record, rest)] : [])].join("\n");
+        }
+        return fields(record, view ?? Object.keys(record));
+    }
+    return JSON.stringify(value);
+}
+function isRecords(v) {
+    return Array.isArray(v) && v.length > 0 && v.every((r) => r && typeof r === "object" && !Array.isArray(r));
+}
+function table(rows, columns) {
+    if (!rows.length)
+        return "(none)";
+    if (!isRecords(rows))
+        return rows.map(cell).join("\n");
+    const first = rows[0];
+    const cols = columns ?? Object.keys(first).filter((k) => isScalar(first[k])).slice(0, 6);
+    const cells = rows.map((r) => cols.map((c) => cell(get(r, c))));
+    const widths = cols.map((c, i) => Math.max(c.length, ...cells.map((row) => row[i].length)));
+    const line = (parts) => parts.map((p, i) => p.padEnd(widths[i])).join("  ").trimEnd();
+    return [line(cols.map((c) => c.toUpperCase())), ...cells.map(line)].join("\n");
+}
+function fields(record, keys) {
+    const width = Math.max(...keys.map((k) => k.length));
+    return keys.map((k) => `${k.padEnd(width)}  ${cell(get(record, k))}`).join("\n");
+}
+function isScalar(v) {
+    return v === null || ["string", "number", "boolean"].includes(typeof v);
+}
+function cell(v) {
+    if (v === undefined || v === null)
+        return "";
+    if (Array.isArray(v) && v.every(isScalar))
+        return v.join(", ");
+    return isScalar(v) ? String(v) : JSON.stringify(v);
+}

package/dist/cli/src/terminal.d.ts

@@ -0,0 +1,3 @@
+import { type CliConfig } from "./commands.ts";
+import type { CliIO } from "./run.ts";
+export declare function runTerminal(config: CliConfig, server: string | undefined, token: string | undefined, argv: string[], io: CliIO): Promise<number>;

package/dist/cli/src/terminal.js

@@ -0,0 +1,135 @@
+// Chat uses the agent's authenticated terminal endpoint; it never calls an MCP tool.
+import { mkdirSync, readFileSync, writeFileSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { parseArgs, styleText } from "node:util";
+import { configDir, isSignedIn, storedAccessToken } from "./auth.js";
+import { tokenEnvOf } from "./commands.js";
+export async function runTerminal(config, server, token, argv, io) {
+    const usage = `${config.name} chat ["<message>"] [--json] [--new]`;
+    let flags;
+    try {
+        flags = parseArgs({ args: argv.slice(1), allowPositionals: true, options: { json: { type: "boolean" }, new: { type: "boolean" }, help: { type: "boolean", short: "h" } } });
+    }
+    catch {
+        io.writeError(`Usage: ${usage}\n`);
+        return 2;
+    }
+    if (flags.values.help) {
+        io.write(`${usage}\nTalk to the agent. --new forgets this terminal's saved conversation reference; shared person history stays with the agent.\n`);
+        return 0;
+    }
+    if (flags.positionals.length > 1) {
+        io.writeError(`Usage: ${usage}\n`);
+        return 2;
+    }
+    const single = flags.positionals.length === 1;
+    if (!single && !io.interactive) {
+        io.writeError(`chat needs a terminal; for a single reply use ${config.name} chat "<message>".\n`);
+        return 2;
+    }
+    if (!server) {
+        io.writeError("Pass --server <url> or configure the MCP server.\n");
+        return 5;
+    }
+    const stored = !token && isSignedIn(config, server);
+    try {
+        if (stored)
+            token = await storedAccessToken(config, server, false, io.signal);
+    }
+    catch {
+        io.writeError(`Sign in again: ${config.name} auth login.\n`);
+        return 3;
+    }
+    if (!token) {
+        io.writeError(`Sign in first: ${config.name} auth login (or set ${tokenEnvOf(config)}).\n`);
+        return 3;
+    }
+    const humanChat = !single && !flags.values.json;
+    const endpoint = config.agent ?? new URL("/agent/terminal", server).href;
+    const file = join(configDir(config), "chat.json");
+    let saved = {};
+    try {
+        saved = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch { }
+    if (flags.values.new)
+        delete saved[endpoint];
+    async function send(text) {
+        let response;
+        const clearStatus = humanChat && Boolean(process.stderr.isTTY) && (io.env ?? process.env).TERM !== "dumb";
+        if (humanChat)
+            io.writeError(`${styleText("dim", "  Waiting for reply…")}${clearStatus ? "" : "\n"}`);
+        const request = () => fetch(endpoint, { method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${token}` }, body: JSON.stringify({ text, ...(saved[endpoint] ? { conversationId: saved[endpoint] } : {}) }), signal: io.signal ? AbortSignal.any([io.signal, AbortSignal.timeout(10 * 60_000)]) : AbortSignal.timeout(10 * 60_000) });
+        try {
+            response = await request();
+            if (response.status === 401 && stored) {
+                await response.body?.cancel();
+                token = await storedAccessToken(config, server, true, io.signal);
+                if (token)
+                    response = await request();
+            }
+        }
+        catch {
+            response = undefined;
+        }
+        finally {
+            if (clearStatus)
+                io.writeError("\r\u001b[2K");
+        }
+        if (!response) {
+            io.writeError("Could not reach the agent.\n");
+            return 5;
+        }
+        if (response.status === 401 || response.status === 403) {
+            io.writeError(`Sign in first: ${config.name} auth login.\n`);
+            return 3;
+        }
+        if (!response.ok) {
+            io.writeError(`The agent could not finish (${response.status}).\n`);
+            return 1;
+        }
+        let result;
+        try {
+            result = await response.json();
+        }
+        catch {
+            io.writeError("The agent returned invalid JSON.\n");
+            return 1;
+        }
+        if (typeof result.conversationId !== "string" || !Array.isArray(result.replies)) {
+            io.writeError("The agent returned an invalid reply.\n");
+            return 1;
+        }
+        io.signal?.throwIfAborted();
+        saved[endpoint] = result.conversationId;
+        mkdirSync(configDir(config), { recursive: true, mode: 0o700 });
+        writeFileSync(file, `${JSON.stringify(saved)}\n`, { mode: 0o600 });
+        chmodSync(file, 0o600);
+        const messages = result.replies.filter(r => r.type === "message").map(r => r.text ?? "");
+        if (flags.values.json)
+            io.write(`${JSON.stringify(result)}\n`);
+        else if (humanChat && messages.length)
+            io.write(`\n${styleText(["bold", "green"], config.name)}\n${messages.join("\n\n")}\n\n`);
+        else
+            io.write(`${messages.join("\n")}\n`);
+        return 0;
+    }
+    if (single)
+        return send(flags.positionals[0]);
+    if (!io.lines) {
+        io.writeError("This CLI input does not support chat.\n");
+        return 2;
+    }
+    io.writeError(humanChat ? `\n${styleText("bold", `${config.name} chat`)}\n${styleText("dim", "Type /exit or press Ctrl-D to leave.")}\n\n` : "Type /exit or press Ctrl-D to leave.\n");
+    for await (const line of io.lines(humanChat ? `${styleText(["bold", "cyan"], "You")} › ` : undefined)) {
+        const text = line.trim();
+        if (text === "/exit")
+            break;
+        if (text) {
+            const code = await send(text);
+            if (code)
+                return code;
+        }
+    }
+    return 0;
+}

package/dist/flow-messaging/src/client.d.ts

@@ -28,8 +28,8 @@ export declare class Client {
     get<T>(path: string): Promise<T>;
     /** A file's bytes: GET /v1/files/{id} answers them or redirects to a signed URL, which fetch follows without the key. */
     download(fileId: string): Promise<Uint8Array>;
-    /** A POST with its own Idempotency-Key, kept across the retries of this one call; `tries: 1` for courtesies. */
-    post<T>(path: string, body: unknown, tries?: number): Promise<T>;
+    /** A POST with its own Idempotency-Key (the caller's, else a new one), kept across the retries of this one call; `tries: 1` for courtesies. */
+    post<T>(path: string, body: unknown, tries?: number, idempotencyKey?: string): Promise<T>;
     private request;
 }
 /**