@hanamorilabs/tab 0.1.0

package/dist/clients.js

@@ -0,0 +1,103 @@
+/**
+ * What each agent needs in its environment to run on a tab.
+ *
+ * Two wire shapes exist. Claude Code speaks the Anthropic Messages API and
+ * reads `ANTHROPIC_BASE_URL`; everything else speaks OpenAI and reads
+ * `OPENAI_BASE_URL`. The proxy serves both. Provider-specific agents get the
+ * provider-scoped base so the proxy picks the right key.
+ *
+ * An unknown command gets both sets, so `tab <anything>` still routes
+ * whichever API the program happens to use.
+ */
+const KNOWN = {
+    claude: {
+        command: "claude",
+        label: "Claude Code",
+        shape: "anthropic",
+        install: "npm i -g @anthropic-ai/claude-code",
+    },
+    codex: {
+        command: "codex",
+        label: "Codex",
+        shape: "openai",
+        install: "npm i -g @openai/codex",
+        // An isolated CODEX_HOME does the real work (see codex-home.ts); this
+        // flag is belt and braces for versions that honour it.
+        args: ["-c", 'preferred_auth_method="apikey"'],
+        isolatedHome: "codex",
+    },
+    grok: {
+        command: "grok",
+        label: "Grok",
+        shape: "openai",
+        provider: "xai",
+        install: "see https://docs.x.ai for the Grok CLI",
+    },
+    kimi: {
+        command: "kimi",
+        label: "Kimi",
+        shape: "openai",
+        provider: "moonshot",
+        install: "see https://platform.moonshot.ai for the Kimi CLI",
+    },
+    gemini: {
+        command: "gemini",
+        label: "Gemini CLI",
+        shape: "openai",
+        provider: "google",
+        install: "npm i -g @google/gemini-cli",
+    },
+};
+export function knownClients() {
+    return Object.keys(KNOWN);
+}
+export function clientFor(name) {
+    const known = KNOWN[name];
+    if (known)
+        return known;
+    return {
+        command: name,
+        label: name,
+        // Unknown: we do not know which API it speaks, so both are set below.
+        shape: "openai",
+        install: `make sure \`${name}\` is on your PATH`,
+    };
+}
+/** `<proxy>/v1` or `<proxy>/v1/<provider>` for vendor-scoped OpenAI routes. */
+export function openaiBase(proxyUrl, provider) {
+    return provider ? `${proxyUrl}/v1/${provider}` : `${proxyUrl}/v1`;
+}
+/**
+ * The environment to hand the child. Existing variables for the same API are
+ * overridden on purpose: a stray `OPENAI_BASE_URL` from another tool would
+ * otherwise route around the tab, which is the one thing this must not do.
+ */
+export function envFor(input) {
+    const spec = clientFor(input.name);
+    const known = input.name in KNOWN;
+    const env = { ...(input.base ?? process.env) };
+    const setAnthropic = () => {
+        env.ANTHROPIC_BASE_URL = input.proxyUrl;
+        env.ANTHROPIC_API_KEY = input.presentedKey;
+        // Claude Code prefers an auth token when one is set; make sure a stale
+        // one cannot win over the tab key.
+        delete env.ANTHROPIC_AUTH_TOKEN;
+    };
+    const setOpenAI = () => {
+        env.OPENAI_BASE_URL = openaiBase(input.proxyUrl, spec.provider);
+        env.OPENAI_API_KEY = input.presentedKey;
+    };
+    if (!known) {
+        setAnthropic();
+        setOpenAI();
+    }
+    else if (spec.shape === "anthropic") {
+        setAnthropic();
+    }
+    else {
+        setOpenAI();
+    }
+    // So the child, and anything it spawns, can tell it is on a tab.
+    env.FLOCKTAB_PROXY_URL = input.proxyUrl;
+    return { spec, env };
+}

package/dist/codex-home.js

@@ -0,0 +1,49 @@
+/**
+ * An isolated Codex home for runs on a tab.
+ *
+ * Codex resolves auth from `$CODEX_HOME/auth.json` and its provider from
+ * `$CODEX_HOME/config.toml`, and a stored ChatGPT login or a custom
+ * `model_provider` there wins over anything in the environment. So a plain
+ * `OPENAI_BASE_URL` never reaches the tab for a signed-in user. `tab codex`
+ * therefore points `CODEX_HOME` at a directory it owns, with an API-key auth
+ * file and one provider: the tab, over the Responses wire the proxy serves.
+ *
+ * The person's own `~/.codex` is never read or written.
+ */
+import { chmod, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+export function codexAuthJson(presentedKey) {
+    return `${JSON.stringify({ auth_mode: "apikey", OPENAI_API_KEY: presentedKey })}\n`;
+}
+/** Codex's /status prints the provider *id*, not its name, so the id says which FlockTab this is. */
+export function codexProviderId(mode) {
+    return mode === "self-hosted" ? "FlockTab - Self-hosted" : "FlockTab - Hosted";
+}
+export function codexConfigToml(proxyUrl, model, mode = "hosted") {
+    const id = codexProviderId(mode);
+    const lines = [
+        `model_provider = ${JSON.stringify(id)}`,
+        ...(model ? [`model = ${JSON.stringify(model)}`] : []),
+        ``,
+        `[model_providers.${JSON.stringify(id)}]`,
+        `name = ${JSON.stringify(id)}`,
+        `base_url = ${JSON.stringify(`${proxyUrl}/v1`)}`,
+        `env_key = "OPENAI_API_KEY"`,
+        `wire_api = "responses"`,
+        ``,
+    ];
+    return lines.join("\n");
+}
+/** Write the home and return its path. Files are owner-only. */
+export async function prepareCodexHome(input) {
+    const home = path.join(input.baseDir, "codex");
+    await mkdir(home, { recursive: true, mode: 0o700 });
+    await chmod(home, 0o700);
+    const auth = path.join(home, "auth.json");
+    const config = path.join(home, "config.toml");
+    await writeFile(auth, codexAuthJson(input.presentedKey), { mode: 0o600 });
+    await writeFile(config, codexConfigToml(input.proxyUrl, input.model, input.mode ?? "hosted"), { mode: 0o600 });
+    await chmod(auth, 0o600);
+    await chmod(config, 0o600);
+    return home;
+}

package/dist/config.js

@@ -0,0 +1,123 @@
+/**
+ * Where `tab` keeps what it needs: the proxy to talk to, the machine session
+ * from `tab login`, the unlock, and one virtual key per Agent this machine
+ * has run as. One JSON file, owner-only, under the home directory.
+ *
+ * Login is per machine; which Agent a folder runs as lives in that folder's
+ * `.flocktab` (see project.ts) and points at an entry in `agents` here. The
+ * unlock is stored here so `tab claude` is one command. That is the user's
+ * own machine and their own choice, the same trade every CLI makes with a
+ * token file. Environment variables override the file for CI.
+ */
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+export const HOSTED_PROXY = "https://proxy.flocktab.com";
+export const LOCAL_PROXY = "http://127.0.0.1:8787";
+export function configDir(env = process.env) {
+    return env.FLOCKTAB_HOME?.trim() || path.join(homedir(), ".flocktab");
+}
+export function configPath(env = process.env) {
+    return path.join(configDir(env), "config.json");
+}
+/** A proxy base without a trailing slash or a stray `/v1`. */
+export function normalizeProxyUrl(raw) {
+    let url = raw.trim().replace(/\/+$/, "");
+    url = url.replace(/\/v1$/, "");
+    if (!/^https?:\/\//.test(url))
+        url = `http://${url}`;
+    return url;
+}
+export function isLocalProxy(url) {
+    try {
+        const host = new URL(url).hostname;
+        return host === "127.0.0.1" || host === "localhost" || host === "::1";
+    }
+    catch {
+        return false;
+    }
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function str(value) {
+    return typeof value === "string" && value.trim() ? value : undefined;
+}
+function readAgents(raw) {
+    const out = {};
+    for (const [slug, value] of Object.entries(raw)) {
+        if (!isRecord(value) || typeof value.key !== "string")
+            continue;
+        out[slug] = {
+            key: value.key,
+            agentId: str(value.agentId) ?? "",
+            agentName: str(value.agentName) ?? slug,
+        };
+    }
+    return out;
+}
+/**
+ * The saved config, with the environment on top. `FLOCKTAB_PROXY_URL` and
+ * `FLOCKTAB_UNLOCK` override their fields; `FLOCKTAB_KEY` is an Agent key
+ * for CI and scripts, used as the `env` Agent without any folder picker.
+ */
+export async function loadConfig(env = process.env) {
+    let fromFile = {};
+    try {
+        const parsed = JSON.parse(await readFile(configPath(env), "utf8"));
+        if (isRecord(parsed)) {
+            fromFile = {
+                ...(str(parsed.proxyUrl) ? { proxyUrl: parsed.proxyUrl } : {}),
+                ...(parsed.mode === "hosted" || parsed.mode === "self-hosted" ? { mode: parsed.mode } : {}),
+                ...(str(parsed.token) ? { token: parsed.token } : {}),
+                ...(str(parsed.consoleUrl) ? { consoleUrl: parsed.consoleUrl } : {}),
+                ...(str(parsed.flockName) ? { flockName: parsed.flockName } : {}),
+                ...(str(parsed.unlock) ? { unlock: parsed.unlock } : {}),
+                ...(isRecord(parsed.agents) ? { agents: readAgents(parsed.agents) } : {}),
+            };
+        }
+    }
+    catch {
+        // No file yet, or unreadable: fall through to env.
+    }
+    const proxyUrl = env.FLOCKTAB_PROXY_URL?.trim() || fromFile.proxyUrl;
+    const envKey = env.FLOCKTAB_KEY?.trim();
+    const unlock = env.FLOCKTAB_UNLOCK?.trim() || fromFile.unlock;
+    if (!proxyUrl)
+        return undefined;
+    if (!fromFile.token && !envKey)
+        return undefined;
+    const normalized = normalizeProxyUrl(proxyUrl);
+    const agents = { ...(fromFile.agents ?? {}) };
+    if (envKey)
+        agents.env = { key: envKey, agentId: "", agentName: "env" };
+    return {
+        proxyUrl: normalized,
+        mode: fromFile.mode ?? (isLocalProxy(normalized) ? "self-hosted" : "hosted"),
+        ...(fromFile.token ? { token: fromFile.token } : {}),
+        ...(fromFile.consoleUrl ? { consoleUrl: fromFile.consoleUrl } : {}),
+        ...(fromFile.flockName ? { flockName: fromFile.flockName } : {}),
+        ...(unlock ? { unlock } : {}),
+        agents,
+    };
+}
+export async function saveConfig(config, env = process.env) {
+    const dir = configDir(env);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const file = configPath(env);
+    await writeFile(file, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    // mkdir/writeFile modes are masked by umask; set them explicitly.
+    await chmod(dir, 0o700);
+    await chmod(file, 0o600);
+    return file;
+}
+export async function clearConfig(env = process.env) {
+    await rm(configPath(env), { force: true });
+}
+/**
+ * The key a client presents: the virtual key, then the unlock after a dot.
+ * With no unlock (self-hosted, or no BYOK on the flock) it is the bare key.
+ */
+export function presentedKey(input) {
+    return input.unlock ? `${input.key}.${input.unlock}` : input.key;
+}

package/dist/console-api.js

@@ -0,0 +1,34 @@
+/**
+ * The console, spoken with the machine session: which Agents the flock has,
+ * make one, key one. All three are `/api/cli/*` with `Bearer ft_cli_...`.
+ * Injectable fetch so the folder picker is testable without a console.
+ */
+export class ConsoleApiError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "ConsoleApiError";
+    }
+}
+async function call(consoleUrl, token, path, init, fetchImpl) {
+    const response = await fetchImpl(`${consoleUrl}${path}`, {
+        ...init,
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json", ...(init.headers ?? {}) },
+    });
+    const body = (await response.json().catch(() => ({})));
+    if (!response.ok) {
+        const detail = body.error ?? `console answered ${response.status}`;
+        throw new ConsoleApiError(body.hint ? `${detail} (${body.hint})` : detail, response.status);
+    }
+    return body;
+}
+export async function listAgents(consoleUrl, token, fetchImpl = fetch) {
+    return call(consoleUrl, token, "/api/cli/agents", { method: "GET" }, fetchImpl);
+}
+export async function createAgent(consoleUrl, token, input, fetchImpl = fetch) {
+    return call(consoleUrl, token, "/api/cli/agents", { method: "POST", body: JSON.stringify(input) }, fetchImpl);
+}
+export async function issueAgentKey(consoleUrl, token, agentId, fetchImpl = fetch) {
+    return call(consoleUrl, token, `/api/cli/agents/${encodeURIComponent(agentId)}/key`, { method: "POST" }, fetchImpl);
+}

package/dist/device-login.js

@@ -0,0 +1,120 @@
+/**
+ * The CLI half of `tab login`: ask the console for a code, put the person in
+ * front of it, and poll until they approve. The key arrives over the poll,
+ * never through the clipboard or the screen.
+ *
+ * Pure apart from `fetch` and `openBrowser`, both injectable, so the whole
+ * dance is testable without a console.
+ */
+export class DeviceLoginError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DeviceLoginError";
+    }
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object";
+}
+export async function startDeviceLogin(consoleUrl, fetchImpl = fetch) {
+    const response = await fetchImpl(`${consoleUrl}/api/cli/login/start`, { method: "POST" });
+    if (!response.ok)
+        throw new DeviceLoginError(`console answered ${response.status} to login start`);
+    const body = await response.json();
+    if (!isRecord(body) ||
+        typeof body.userCode !== "string" ||
+        typeof body.deviceSecret !== "string" ||
+        typeof body.verifyUrl !== "string") {
+        throw new DeviceLoginError("console returned an unexpected login start");
+    }
+    return {
+        userCode: body.userCode,
+        deviceSecret: body.deviceSecret,
+        verifyUrl: body.verifyUrl,
+        expiresAt: typeof body.expiresAt === "string" ? body.expiresAt : "",
+        intervalMs: typeof body.intervalMs === "number" ? body.intervalMs : 2_000,
+    };
+}
+/**
+ * Poll until approved. Backs off a little on server errors instead of
+ * hammering, and gives up at `deadline` or when the console says expired.
+ */
+export async function waitForApproval(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    const sleep = input.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const now = input.now ?? (() => Date.now());
+    let interval = Math.max(500, input.intervalMs);
+    // The device secret travels as a bearer, never in the URL, so it stays
+    // out of access logs.
+    const url = `${input.consoleUrl}/api/cli/login/poll`;
+    const init = { headers: { authorization: `Bearer ${input.deviceSecret}` } };
+    while (now() < input.deadline) {
+        let response;
+        try {
+            response = await fetchImpl(url, init);
+        }
+        catch {
+            await sleep(interval);
+            interval = Math.min(interval * 2, 15_000);
+            continue;
+        }
+        if (response.status === 410)
+            throw new DeviceLoginError("the code expired before it was approved");
+        if (!response.ok) {
+            await sleep(interval);
+            interval = Math.min(interval * 2, 15_000);
+            continue;
+        }
+        const body = await response.json().catch(() => undefined);
+        if (isRecord(body) && body.status === "approved" && typeof body.token === "string") {
+            const flock = isRecord(body.flock) ? body.flock : {};
+            return {
+                token: body.token,
+                flock: {
+                    id: typeof flock.id === "string" ? flock.id : "",
+                    name: typeof flock.name === "string" ? flock.name : "flock",
+                    plan: typeof flock.plan === "string" ? flock.plan : "solo",
+                    byok: flock.byok === true,
+                },
+                ...(typeof body.proxyUrl === "string" ? { proxyUrl: body.proxyUrl } : {}),
+            };
+        }
+        await sleep(interval);
+    }
+    throw new DeviceLoginError("timed out waiting for approval");
+}
+/**
+ * Where the console lives: FLOCKTAB_CONSOLE_URL, else flocktab.com. A
+ * local proxy is no reason to guess a local console; a self-hosted proxy
+ * settles on flocktab.com, and a developer's stack sets the variable.
+ */
+export function defaultConsoleUrl(_proxyUrl, env = process.env) {
+    const configured = env.FLOCKTAB_CONSOLE_URL?.trim();
+    if (configured)
+        return configured.replace(/\/+$/, "");
+    return "https://console.flocktab.com";
+}
+/**
+ * A self-hosted proxy knows which console it settles through and says so
+ * on /health; ask it before falling back to the static default, so `tab
+ * login` against 127.0.0.1:8787 lands on flocktab.com when that is where
+ * the ledger is.
+ */
+export async function consoleUrlFor(proxyUrl, env = process.env, fetchImpl = fetch) {
+    const configured = env.FLOCKTAB_CONSOLE_URL?.trim();
+    if (configured)
+        return configured.replace(/\/+$/, "");
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 3_000);
+        const response = await fetchImpl(`${proxyUrl}/health`, { signal: controller.signal });
+        clearTimeout(timer);
+        const body = await response.json().catch(() => undefined);
+        if (isRecord(body) && typeof body.console === "string" && /^https?:\/\//.test(body.console)) {
+            return body.console.replace(/\/+$/, "");
+        }
+    }
+    catch {
+        // The proxy is down or old; the default still works for hosted flocks.
+    }
+    return defaultConsoleUrl(proxyUrl, env);
+}

package/dist/folder.js

@@ -0,0 +1,47 @@
+import { execFileSync } from "node:child_process";
+function parseGitRepo(remote) {
+    const trimmed = remote.trim();
+    const ssh = /^git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/i.exec(trimmed);
+    if (ssh)
+        return `${ssh[1]}/${ssh[2]}`;
+    try {
+        const url = new URL(trimmed);
+        if (!/(^|\.)github\.com$/i.test(url.hostname))
+            return null;
+        const segs = url.pathname.replace(/^\//, "").replace(/\.git$/i, "").split("/");
+        if (segs.length < 2 || !segs[0] || !segs[1])
+            return null;
+        return `${segs[0]}/${segs[1]}`;
+    }
+    catch {
+        return null;
+    }
+}
+export function gitRepoFromCwd(cwd) {
+    try {
+        const remote = execFileSync("git", ["-C", cwd, "remote", "get-url", "origin"], {
+            encoding: "utf8",
+            timeout: 800,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        return parseGitRepo(remote);
+    }
+    catch {
+        return null;
+    }
+}
+/** Fire-and-forget: tell the proxy which folder this Agent is in. */
+export function reportFolder(proxyUrl, presentedKey) {
+    const cwd = process.cwd();
+    const git = gitRepoFromCwd(cwd);
+    void fetch(`${proxyUrl}/v1/here`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${presentedKey}`,
+            "content-type": "application/json",
+        },
+        body: JSON.stringify({ cwd, git }),
+    }).catch(() => {
+        // The Agent still runs if this misses.
+    });
+}

package/dist/project.js

@@ -0,0 +1,75 @@
+/**
+ * Which Agent a folder runs as: `.flocktab` in the project, one line of
+ * JSON naming the Agent's slug. No secrets in it, so it can be committed;
+ * the key for that Agent lives in the machine's config. Found by walking up
+ * from the working directory to the git root (or the filesystem root), so
+ * `tab claude` in a subfolder is the same Agent as at the top.
+ */
+import { access, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+export const PROJECT_FILE = ".flocktab";
+async function exists(file) {
+    try {
+        await access(file);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** The nearest `.flocktab` at or above `cwd`, stopping at a `.git` boundary. */
+export async function findProjectFile(cwd) {
+    let dir = path.resolve(cwd);
+    for (;;) {
+        const candidate = path.join(dir, PROJECT_FILE);
+        if (await exists(candidate))
+            return candidate;
+        if (await exists(path.join(dir, ".git")))
+            return undefined;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+export async function readProject(cwd) {
+    const file = await findProjectFile(cwd);
+    if (!file)
+        return undefined;
+    try {
+        const parsed = JSON.parse(await readFile(file, "utf8"));
+        const agent = parsed && typeof parsed === "object" ? parsed.agent : undefined;
+        if (typeof agent === "string" && /^[a-z0-9][a-z0-9-]*$/.test(agent))
+            return { file, agent };
+    }
+    catch {
+        // Unreadable: treat as absent and ask again.
+    }
+    return undefined;
+}
+/** Where a new `.flocktab` goes: the git root above `cwd` when there is one, else `cwd`. */
+export async function projectRoot(cwd) {
+    let dir = path.resolve(cwd);
+    for (;;) {
+        if (await exists(path.join(dir, ".git")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return path.resolve(cwd);
+        dir = parent;
+    }
+}
+export async function writeProject(dir, config) {
+    const file = path.join(dir, PROJECT_FILE);
+    await writeFile(file, `${JSON.stringify(config)}\n`);
+    return file;
+}
+/** A default Agent name for a folder: its basename, kebab-cased. */
+export function agentNameFor(dir) {
+    return path
+        .basename(path.resolve(dir))
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64) || "agent";
+}