@hanamorilabs/tab 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# tab
+
+Run any AI agent on a FlockTab tab.
+
+```
+npm i -g @hanamorilabs/tab
+tab login          # once per machine: opens the console, approve this machine
+cd my-project
+tab claude         # first run here asks which Agent this folder runs as (or makes one)
+tab codex          # same Agent: it is in ./.flocktab
+tab grok           # Grok, routed to xAI through the tab
+tab kimi           # Kimi, routed to Moonshot through the tab
+tab aider --model gpt-4.1   # anything else: both APIs pointed at the tab
+```
+
+Login is per machine, the Agent is per folder. `tab login` approves the
+machine for your flock and stores a session in `~/.flocktab/config.json`
+(owner-only). The first `tab claude` or `tab codex` in a folder lists your
+Agents, lets you pick one or create one named after the folder ($50 cap,
+change it in the console), mints that Agent's key for this machine, and
+writes `.flocktab` with the Agent's name. No secrets in `.flocktab`, so
+commit it if you like; a teammate's first run mints their own key. `tab use`
+changes the folder's Agent.
+
+`tab <agent>` sets the variables that agent reads and runs it with your
+terminal attached. Claude Code reads `ANTHROPIC_BASE_URL`; everything else
+reads `OPENAI_BASE_URL`. Codex is special: a ChatGPT login or a custom
+provider in `~/.codex` would beat the environment, so `tab codex` gives it
+its own home under `~/.flocktab/codex` pinned to the tab, and never touches
+`~/.codex`. The proxy serves the OpenAI chat and Responses APIs and the
+Anthropic Messages API, so the same tab, cap and kill switch apply whichever
+one the agent speaks.
+
+The key the agent presents is `ft_live_<secret>.<unlock>`. On a hosted flock
+the unlock decrypts your provider key on the proxy for that one request and
+is never stored on the server; `tab` asks for it once, when the first Agent
+is keyed, and keeps it in the config file so `tab claude` is one command.
+Set `FLOCKTAB_PROXY_URL`, `FLOCKTAB_KEY` and `FLOCKTAB_UNLOCK` instead when
+you would rather not have a file or a folder, for example in CI.
+
+## Self-hosted
+
+The proxy runs on your box and holds the provider keys; the ledger, tabs and
+kill switch stay on flocktab.com. It is one small Rust binary. `tab up` asks
+for the keys once (typed without echo, saved owner-only to
+`~/.flocktab/proxy.env`), fetches `flocktab-proxy` for this machine into
+`~/.flocktab/bin`, and starts it in the background (log: `~/.flocktab/proxy.log`).
+`tab down` stops it; `tab update` fetches the newest proxy and restarts;
+`tab claude` starts it when it is down. No Docker, no checkout. Then
+`tab login`, pick **2 Self-hosted**: the proxy says which console it settles
+through, so the device code lands on flocktab.com. No unlock in this mode;
+Codex shows `FlockTab - Self-hosted` as its provider.
+
+## Secrets and colour
+
+The unlock and provider keys are typed with echo off (raw mode); the unlock is checked against the proxy before saving; a wrong unlock is refused, and `tab status` says `unlock ok` or `unlock is WRONG`. The check is `GET /v1/whoami` with the unlock, which decrypts the envelope in memory and answers `ok`/`wrong`, never the key. Output is coloured on a terminal; `NO_COLOR` turns it off, `FORCE_COLOR` turns it on for pipes.
+
+## Status
+
+```
+tab status
+proxy   http://127.0.0.1:8787  (self-hosted)  up
+flock   Hanamori Labs
+folder  flocktab-codex
+plan    team
+byok    provider keys on this box
+```

package/dist/cli.js

@@ -0,0 +1,611 @@
+#!/usr/bin/env node
+/**
+ * tab: run any AI agent on a FlockTab tab.
+ *
+ *   tab login              approve this machine in the console (once per machine)
+ *   tab claude [...args]   Claude Code on the tab
+ *   tab codex  [...args]   Codex on the tab
+ *   tab <cmd>  [...args]   anything else, both APIs pointed at the tab
+ *   tab use                pick (or change) the Agent this folder runs as
+ *   tab status             which flock, which Agent here, is the proxy up
+ *   tab up | down | update self-hosted: start, stop, or fetch the newest proxy
+ *   tab logout             forget the session and keys
+ *
+ * Login is per machine. The Agent is per folder: the first `tab claude` in
+ * a folder asks which Agent it runs as (or makes one) and writes `.flocktab`
+ * there. The child process gets the tab's environment and inherits the
+ * terminal, so an interactive agent behaves exactly as it does without `tab`.
+ */
+import { spawn } from "node:child_process";
+import { hostname } from "node:os";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import { bold, box, cyan, dim, green, heading, line, rows, underline, yellow } from "./ui.js";
+import { envFor, knownClients } from "./clients.js";
+import { prepareCodexHome } from "./codex-home.js";
+import { ConsoleApiError, createAgent, issueAgentKey, listAgents } from "./console-api.js";
+import { consoleUrlFor, DeviceLoginError, startDeviceLogin, waitForApproval } from "./device-login.js";
+import { clearConfig, configDir, configPath, HOSTED_PROXY, isLocalProxy, loadConfig, LOCAL_PROXY, normalizeProxyUrl, presentedKey, saveConfig, } from "./config.js";
+import { reportFolder } from "./folder.js";
+import { agentNameFor, projectRoot, readProject, writeProject } from "./project.js";
+import { downloadProxy, hasProxyEnv, packagedBinPath, proxyBinPath, proxyEnvPath, proxyLogPath, PROXY_VERSION, startProxy, stopProxy, tailProxyLog, writeProxyEnv, } from "./proxy-bin.js";
+import { proxyHealth, waitHealthy } from "./selfhost.js";
+const say = (text) => console.error(text);
+const ok = (text) => say(line("ok", text));
+const warn = (text) => say(line("warn", text));
+const fail = (text) => say(line("fail", text));
+function usage() {
+    const others = knownClients().filter((n) => n !== "claude" && n !== "codex");
+    const cmd = (name, what) => [`tab ${name}`, what];
+    say(`${heading("tab")} ${dim("- run any AI agent on a FlockTab tab")}
+`);
+    say(rows([
+        cmd("login", "approve this machine in the console, once"),
+        cmd("claude [args]", "Claude Code on the tab"),
+        cmd("codex [args]", "Codex on the tab"),
+        cmd(others.join(" | tab "), "the same, for those agents"),
+        cmd("<command> [args]", "any other agent, both APIs pointed at the tab"),
+        cmd("use", "pick or change the Agent this folder runs as (.flocktab)"),
+        cmd("status", "which flock, which Agent here, is the proxy up"),
+        cmd("up", "self-hosted: start the local proxy (fetches it the first time)"),
+        cmd("down", "self-hosted: stop the local proxy"),
+        cmd("update", "self-hosted: fetch the newest proxy and restart it"),
+        cmd("logout", "forget the session and keys"),
+    ].map(([k, v]) => [cyan(k), v])));
+    say(`
+${dim("Config")} ${configPath()}  ${dim("or FLOCKTAB_PROXY_URL, FLOCKTAB_KEY, FLOCKTAB_UNLOCK")}`);
+}
+async function whoami(proxyUrl, login) {
+    try {
+        const response = await fetch(`${proxyUrl}/v1/whoami`, {
+            headers: { authorization: `Bearer ${presentedKey(login)}` },
+        });
+        const body = (await response.json().catch(() => ({})));
+        if (!response.ok) {
+            const message = body.error?.message;
+            return { error: message ?? `whoami returned ${response.status}` };
+        }
+        return body;
+    }
+    catch {
+        return { error: "proxy unreachable" };
+    }
+}
+/**
+ * Without a terminal (CI, a script, `printf ... | tab up`) every answer
+ * comes from stdin, read once and handed out line by line; closing a
+ * readline interface ends stdin, so one interface per question cannot work.
+ */
+let piped;
+async function pipedLine() {
+    if (!piped) {
+        let text = "";
+        for await (const chunk of stdin)
+            text += chunk;
+        piped = text.split(/\r?\n/);
+    }
+    return (piped.shift() ?? "").trim();
+}
+async function ask(question) {
+    if (!stdin.isTTY) {
+        stdout.write(question);
+        const answer = await pipedLine();
+        stdout.write("\n");
+        return answer;
+    }
+    const rl = createInterface({ input: stdin, output: stdout, terminal: true });
+    try {
+        return (await rl.question(question)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+/**
+ * A secret is typed with echo off: raw mode, nothing printed per key, so
+ * neither the terminal nor its scrollback ever shows it. Without a TTY
+ * (piped input) it falls back to a plain line read, which is not echoed
+ * by the terminal either.
+ */
+async function askSecret(question) {
+    if (!stdin.isTTY || typeof stdin.setRawMode !== "function") {
+        stdout.write(question);
+        const answer = await pipedLine();
+        stdout.write("\n");
+        return answer;
+    }
+    stdout.write(question);
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding("utf8");
+    let value = "";
+    try {
+        return await new Promise((resolve, reject) => {
+            const onData = (chunk) => {
+                for (const ch of chunk) {
+                    if (ch === "\r" || ch === "\n") {
+                        stdin.off("data", onData);
+                        stdout.write("\n");
+                        resolve(value.trim());
+                        return;
+                    }
+                    if (ch === "\u0003") {
+                        stdin.off("data", onData);
+                        stdout.write("\n");
+                        reject(new Error("interrupted"));
+                        return;
+                    }
+                    if (ch === "\u007f" || ch === "\b") {
+                        value = value.slice(0, -1);
+                        continue;
+                    }
+                    if (ch >= " ")
+                        value += ch;
+                }
+            };
+            stdin.on("data", onData);
+        });
+    }
+    finally {
+        stdin.setRawMode(false);
+        stdin.pause();
+    }
+}
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+    const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // The URL is printed either way.
+    }
+}
+async function chooseProxy(current) {
+    const isCurrent = (url) => current !== undefined && normalizeProxyUrl(current) === url;
+    say(heading("Where is your FlockTab proxy?"));
+    say(rows([
+        [`${bold("1")}  Hosted`, `${dim(HOSTED_PROXY)}${isCurrent(HOSTED_PROXY) ? green("  current") : ""}`],
+        [`${bold("2")}  Self-hosted`, `${dim(LOCAL_PROXY)}${isCurrent(LOCAL_PROXY) ? green("  current") : ""}`],
+    ]));
+    const fallback = current && !isCurrent(HOSTED_PROXY) && !isCurrent(LOCAL_PROXY) ? current : isCurrent(LOCAL_PROXY) ? "2" : "1";
+    const choice = await ask(`Choose ${bold("1")} or ${bold("2")}, or paste a URL ${dim(`[${fallback}]`)}: `);
+    const picked = choice === "" ? fallback : choice;
+    return normalizeProxyUrl(picked === "1" ? HOSTED_PROXY : picked === "2" ? LOCAL_PROXY : picked);
+}
+const UNLOCK_TRIES = 3;
+/**
+ * Ask for the flock unlock only when a hosted flock has a provider key and
+ * none is saved yet, and check it against the proxy before saving: whoami
+ * decrypts the envelope in memory and answers ok or wrong, never the key.
+ * Self-hosted keys sit on the box in the clear, so there is no unlock.
+ */
+async function unlockIfNeeded(config, key) {
+    if (config.unlock)
+        return config.unlock;
+    const me = await whoami(config.proxyUrl, { key });
+    if ("error" in me || !me.byok || me.unlock === "none")
+        return undefined;
+    say("");
+    say(`This flock has a provider key saved. Your ${bold("unlock")} decrypts it for each call; it is typed without echo and never sent to the console.`);
+    for (let attempt = 1; attempt <= UNLOCK_TRIES; attempt += 1) {
+        const unlock = await askSecret(`${cyan("?")} Unlock ${dim("(blank to skip)")}: `);
+        if (!unlock) {
+            warn("No unlock saved. Calls will be blocked until you run tab login again.");
+            return undefined;
+        }
+        const check = await whoami(config.proxyUrl, { key, unlock });
+        if ("error" in check) {
+            warn(`Could not check the unlock (${check.error}). Saving it as typed.`);
+            return unlock;
+        }
+        if (check.unlock === "ok" || check.unlock === "none") {
+            ok("Unlock opens the provider key.");
+            return unlock;
+        }
+        fail(attempt < UNLOCK_TRIES
+            ? `That unlock does not open this flock's provider key. Try again (${UNLOCK_TRIES - attempt} left).`
+            : "That unlock does not open this flock's provider key. Not saved; run tab login when you have it.");
+    }
+    return undefined;
+}
+/**
+ * `tab login`: get a code, open the console, wait for approval. The machine
+ * session arrives over the poll. Nothing about Agents happens here.
+ */
+async function login(args, preferredProxy) {
+    if (args.includes("--paste") || args.includes("--as")) {
+        fail("tab login no longer takes --paste or --as: login is per machine, and each folder picks its Agent with tab use.");
+        return 2;
+    }
+    const existing = await loadConfig();
+    // An explicit proxy in the environment never gets a prompt (CI, scripts);
+    // otherwise `tab login` always asks, with the current one as the default,
+    // so switching between hosted and self-hosted is one keystroke.
+    const envProxy = process.env.FLOCKTAB_PROXY_URL?.trim();
+    const proxyUrl = envProxy
+        ? normalizeProxyUrl(envProxy)
+        : (preferredProxy ?? (await chooseProxy(existing?.proxyUrl)));
+    const mode = isLocalProxy(proxyUrl) ? "self-hosted" : "hosted";
+    const consoleUrl = await consoleUrlFor(proxyUrl);
+    let started;
+    try {
+        started = await startDeviceLogin(consoleUrl);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+        say(`Could not reach ${consoleUrl}.${mode === "self-hosted" ? ` Is the local proxy up? ${bold("tab up")}` : ""}`);
+        return 1;
+    }
+    say("");
+    say(box([
+        `${dim("Code")}     ${bold(yellow(started.userCode))}`,
+        `${dim("Approve")}  ${underline(cyan(started.verifyUrl))}`,
+    ], { title: "Approve this machine" }));
+    say("");
+    say(dim(`Opening the console in your browser. Sign in, check the code, approve this machine (${hostname()}).`));
+    openBrowser(started.verifyUrl);
+    let result;
+    try {
+        result = await waitForApproval({
+            consoleUrl,
+            deviceSecret: started.deviceSecret,
+            intervalMs: started.intervalMs,
+            deadline: Date.now() + 10 * 60_000,
+        });
+    }
+    catch (err) {
+        fail(err instanceof DeviceLoginError ? err.message : String(err));
+        return 1;
+    }
+    ok(`Approved for ${bold(result.flock.name)}`);
+    // Keys minted for another flock or proxy are not this login's; drop them.
+    const sameFlock = existing?.flockName === result.flock.name && existing?.proxyUrl === proxyUrl;
+    const config = {
+        proxyUrl,
+        mode,
+        token: result.token,
+        consoleUrl,
+        flockName: result.flock.name,
+        ...(sameFlock && existing?.unlock ? { unlock: existing.unlock } : {}),
+        agents: sameFlock ? (existing?.agents ?? {}) : {},
+    };
+    const file = await saveConfig(config);
+    ok(`Saved to ${dim(file)} ${dim("(owner-only)")}`);
+    say("");
+    say(`Now run ${bold("tab claude")} or ${bold("tab codex")} in a project folder: the first time, tab asks which Agent that folder runs as.`);
+    return 0;
+}
+/** No saved login: run the browser flow instead of failing. */
+async function ensureLogin() {
+    const config = await loadConfig();
+    if (config)
+        return config;
+    say(dim("Not logged in yet. Starting tab login."));
+    const code = await login([]);
+    if (code !== 0)
+        return undefined;
+    return loadConfig();
+}
+async function ensureProxy(config) {
+    const health = await proxyHealth(config.proxyUrl);
+    if (health.ok)
+        return true;
+    if (config.mode !== "self-hosted") {
+        fail(`FlockTab proxy at ${config.proxyUrl} is ${health.reason}.`);
+        return false;
+    }
+    warn(`Local proxy is ${health.reason}. Starting it.`);
+    if (!(await hasProxyEnv())) {
+        const written = await collectProviderKeys();
+        if (!written)
+            return false;
+    }
+    return bringUp(config.proxyUrl);
+}
+/** Start the binary and wait for its health line; on failure, show the log's tail. */
+async function bringUp(proxyUrl) {
+    const started = await startProxy((t) => say(dim(t)));
+    if (!started.ok) {
+        fail(started.message);
+        return false;
+    }
+    const ready = await waitHealthy(proxyUrl, 20_000);
+    if (!ready.ok) {
+        fail(`Proxy started but is not healthy: ${ready.reason}.`);
+        for (const line of await tailProxyLog())
+            say(dim(`  ${line}`));
+        say(dim(`Log: ${proxyLogPath()}`));
+        return false;
+    }
+    ok(`Proxy is up at ${proxyUrl} ${dim(`(flocktab-proxy ${PROXY_VERSION}, ${proxyBinPath()})`)}`);
+    return true;
+}
+/**
+ * The Agent this folder runs as. `.flocktab` names it; the machine config
+ * holds its key. Missing either: ask (or, with `.flocktab` present, mint the
+ * key silently for this machine), save both, carry on.
+ */
+async function resolveAgent(config, opts = {}) {
+    const agents = config.agents ?? {};
+    // CI and scripts: FLOCKTAB_KEY is the Agent, no folder involved.
+    if (agents.env && !opts.pick)
+        return agents.env;
+    const cwd = process.cwd();
+    const project = opts.pick ? undefined : await readProject(cwd);
+    if (project && agents[project.agent])
+        return agents[project.agent];
+    if (!config.token || !config.consoleUrl) {
+        fail(`This machine is not logged in. Run ${bold("tab login")}.`);
+        return undefined;
+    }
+    let listed;
+    try {
+        listed = await listAgents(config.consoleUrl, config.token);
+    }
+    catch (err) {
+        fail(err instanceof ConsoleApiError && err.status === 401 ? `Session expired. Run ${bold("tab login")}.` : String(err instanceof Error ? err.message : err));
+        return undefined;
+    }
+    const byName = new Map(listed.agents.map((a) => [a.slug, a]));
+    let chosen;
+    let created;
+    if (project) {
+        chosen = byName.get(project.agent);
+        if (!chosen) {
+            warn(`${project.file} names Agent ${bold(project.agent)}, which ${listed.flock.name} no longer has.`);
+        }
+    }
+    if (!chosen) {
+        const root = await projectRoot(cwd);
+        const suggested = agentNameFor(root);
+        say(heading(`Which Agent does this folder run as?`));
+        say(dim(`${root}  ·  flock ${listed.flock.name}`));
+        const options = listed.agents;
+        say(rows([
+            ...options.map((a, i) => [
+                `${bold(String(i + 1))}  ${a.name}`,
+                `${a.state === "open" ? green("open") : yellow(a.state)}  ${dim(`$${(Number(a.capCents) / 100).toFixed(2)} cap`)}${agents[a.slug] ? dim("  keyed here") : a.hasKey ? dim("  keyed elsewhere") : ""}`,
+            ]),
+            [`${bold("n")}  New Agent`, dim(`named ${suggested}, $50.00 cap`)],
+        ]));
+        const answer = await ask(`Choose 1-${options.length} or ${bold("n")} ${dim("[n]")}: `);
+        if (answer === "" || answer.toLowerCase() === "n") {
+            const name = (await ask(`${cyan("?")} Agent name ${dim(`[${suggested}]`)}: `)) || suggested;
+            created = { name };
+        }
+        else {
+            const index = Number.parseInt(answer, 10);
+            chosen = options[index - 1];
+            if (!chosen) {
+                fail("That is not one of the options.");
+                return undefined;
+            }
+        }
+    }
+    let issued;
+    try {
+        if (created) {
+            issued = await createAgent(config.consoleUrl, config.token, { name: created.name });
+            ok(`Created Agent ${bold(issued.agent.name)} with a $50.00 cap. Change it in the console.`);
+        }
+        else if (chosen) {
+            if (chosen.hasKey && !agents[chosen.slug]) {
+                warn(`${chosen.name} already has a key on another machine. Continuing replaces it there.`);
+                const go = await ask(`Replace it? ${dim("[y/N]")}: `);
+                if (!/^y(es)?$/i.test(go))
+                    return undefined;
+            }
+            issued = await issueAgentKey(config.consoleUrl, config.token, chosen.id);
+        }
+        else {
+            return undefined;
+        }
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
+        return undefined;
+    }
+    const login = { key: issued.key, agentId: issued.agent.id, agentName: issued.agent.name };
+    const next = { ...config, agents: { ...agents, [issued.agent.slug]: login } };
+    if (listed.flock.byok && config.mode === "hosted") {
+        const unlock = await unlockIfNeeded(next, issued.key);
+        if (unlock)
+            next.unlock = unlock;
+    }
+    await saveConfig(next);
+    config.agents = next.agents ?? {};
+    if (next.unlock)
+        config.unlock = next.unlock;
+    const file = await writeProject(await projectRoot(cwd), { agent: issued.agent.slug });
+    ok(`This folder runs as ${bold(issued.agent.name)} ${dim(`(${file})`)}`);
+    return login;
+}
+async function status() {
+    const config = await loadConfig();
+    if (!config) {
+        fail(`Not logged in. Run ${bold("tab login")}.`);
+        return 2;
+    }
+    const health = await proxyHealth(config.proxyUrl);
+    const proxyLine = `${config.proxyUrl}  ${dim(`(${config.mode})`)}  ${health.ok ? green("up") : yellow(health.reason)}`;
+    const pairs = [["proxy", proxyLine]];
+    if (config.flockName)
+        pairs.push(["flock", bold(config.flockName)]);
+    const project = await readProject(process.cwd());
+    const here = project ? config.agents?.[project.agent] : undefined;
+    pairs.push(["folder", project ? (here ? bold(here.agentName) : yellow(`${project.agent} (no key on this machine; run tab use)`)) : dim("no Agent yet; tab claude asks, or tab use")]);
+    let tone = health.ok ? "ok" : "warn";
+    if (health.ok && here) {
+        const me = await whoami(config.proxyUrl, { key: here.key, unlock: config.unlock });
+        if ("error" in me) {
+            pairs.push(["key", yellow(me.error)]);
+            tone = "warn";
+        }
+        else {
+            pairs.push(["plan", me.flock.plan]);
+            const byok = !me.byok
+                ? dim("no provider key on this flock")
+                : me.unlock === "none"
+                    ? green(me.mode === "self-hosted" ? "provider keys on this box" : "provider key saved")
+                    : me.unlock === "wrong"
+                        ? yellow("provider key saved, unlock is WRONG: run tab use")
+                        : me.unlock === "missing"
+                            ? yellow("provider key saved, NO unlock: run tab use")
+                            : green("provider key saved, unlock ok");
+            pairs.push(["byok", byok]);
+            if (me.byok && (me.unlock === "wrong" || me.unlock === "missing"))
+                tone = "warn";
+        }
+    }
+    say(box(rows(pairs, 0).split("\n"), { title: "FlockTab", tone }));
+    return tone === "ok" ? 0 : 1;
+}
+async function runAgent(name, args) {
+    const config = await ensureLogin();
+    if (!config)
+        return 2;
+    if (!(await ensureProxy(config)))
+        return 1;
+    const agent = await resolveAgent(config);
+    if (!agent)
+        return 1;
+    const key = presentedKey({ key: agent.key, unlock: config.unlock });
+    reportFolder(config.proxyUrl, key);
+    const { spec, env } = envFor({ name, proxyUrl: config.proxyUrl, presentedKey: key });
+    if (spec.isolatedHome === "codex") {
+        env.CODEX_HOME = await prepareCodexHome({
+            baseDir: configDir(),
+            proxyUrl: config.proxyUrl,
+            presentedKey: key,
+            mode: config.mode,
+        });
+    }
+    const child = spawn(spec.command, [...(spec.args ?? []), ...args], { stdio: "inherit", env });
+    return new Promise((resolve) => {
+        child.on("error", (err) => {
+            if (err.code === "ENOENT") {
+                fail(`${spec.label} is not installed (${spec.command} not on PATH). ${dim(spec.install)}`);
+                resolve(127);
+                return;
+            }
+            fail(err.message);
+            resolve(1);
+        });
+        child.on("close", (code, signal) => resolve(code ?? (signal ? 128 : 1)));
+    });
+}
+/** `tab use`: pick or change the Agent for this folder. */
+async function use() {
+    const config = await ensureLogin();
+    if (!config)
+        return 2;
+    if (!(await ensureProxy(config)))
+        return 1;
+    const agent = await resolveAgent(config, { pick: true });
+    return agent ? 0 : 1;
+}
+/**
+ * First `tab up` on a box: the provider keys the proxy will spend, typed
+ * without echo into ~/.flocktab/proxy.env (owner-only). They never go
+ * anywhere else; flocktab.com only ever sees reserve and settle.
+ */
+async function collectProviderKeys() {
+    say(heading("Provider keys for this machine"));
+    say(`They stay in ${dim(proxyEnvPath())} and are used by the proxy here. flocktab.com never sees them. Leave one blank to skip it; add more later in that file as ${dim("FLOCKTAB_PROVIDER_KEY_<PROVIDER>")}.`);
+    const keys = {};
+    for (const [id, label] of [
+        ["openai", "OpenAI"],
+        ["anthropic", "Anthropic"],
+        ["xai", "xAI"],
+    ]) {
+        keys[id] = await askSecret(`${cyan("?")} ${label} key ${dim("(blank to skip)")}: `);
+    }
+    if (!Object.values(keys).some((v) => v.trim())) {
+        fail("No keys typed. The proxy has nothing to spend; run tab up again when you have one.");
+        return false;
+    }
+    const file = await writeProxyEnv({ control: HOSTED_PROXY, keys });
+    ok(`Saved to ${dim(file)} ${dim("(owner-only)")}`);
+    return true;
+}
+async function selfHosted(action) {
+    const config = await loadConfig();
+    const proxyUrl = config?.mode === "self-hosted" ? config.proxyUrl : LOCAL_PROXY;
+    if (action === "down") {
+        const stopped = await stopProxy();
+        (stopped ? ok : warn)(stopped ? "Proxy stopped." : "Proxy was not running.");
+        return 0;
+    }
+    if (action === "update") {
+        await stopProxy();
+        if (packagedBinPath()) {
+            // The binary is part of the npm install; the newest one comes with the newest tab.
+            say(`The proxy ships with tab. Updating tab updates it: ${bold("npm i -g @hanamorilabs/tab@latest")}`);
+            const code = await new Promise((resolve) => {
+                const child = spawn(process.platform === "win32" ? "npm.cmd" : "npm", ["i", "-g", "@hanamorilabs/tab@latest"], { stdio: "inherit" });
+                child.on("error", () => resolve(1));
+                child.on("close", (c) => resolve(c ?? 1));
+            });
+            if (code !== 0) {
+                fail("npm could not update tab.");
+                return 1;
+            }
+        }
+        else {
+            const fetched = await downloadProxy((t) => say(dim(t)));
+            if (!fetched.ok) {
+                fail(fetched.message);
+                return 1;
+            }
+            ok(`Fetched flocktab-proxy ${PROXY_VERSION}.`);
+        }
+    }
+    if (!(await hasProxyEnv())) {
+        const written = await collectProviderKeys();
+        if (!written)
+            return 2;
+    }
+    if (!(await bringUp(proxyUrl)))
+        return 1;
+    if (!config)
+        say(`Next: ${bold("tab login")} and pick 2 Self-hosted to approve this machine.`);
+    return 0;
+}
+async function main(argv) {
+    const [command, ...rest] = argv;
+    switch (command) {
+        case undefined:
+        case "-h":
+        case "--help":
+        case "help":
+            usage();
+            return command === undefined ? 2 : 0;
+        case "login":
+            return login(rest);
+        case "logout":
+            await clearConfig();
+            ok("Forgot the session and keys on this machine.");
+            return 0;
+        case "use":
+            return use();
+        case "status":
+            return status();
+        case "up":
+            return selfHosted("up");
+        case "down":
+            return selfHosted("down");
+        case "update":
+            return selfHosted("update");
+        default:
+            return runAgent(command, rest);
+    }
+}
+main(process.argv.slice(2))
+    .then((code) => process.exit(code))
+    .catch((err) => {
+    fail(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});