@geteigen/cli 0.0.0-stage → 3.0.0

package/dist/cli/src/index.js

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import { createInterface } from "readline";
+import { loginWithPairingCode, logout } from "./auth.js";
+import { DEFAULT_SERVER_URL, loadConfig } from "./config.js";
+import { ensureCursorAuth } from "./cursorAuth.js";
+import { startWorker } from "./worker.js";
+import { clearMachineConfig, connectMachine, loadMachineConfig } from "./machineConfig.js";
+import { followLogs, installService, readDaemonPid, serviceStatus, startDaemon, stopDaemon, uninstallService, } from "./service.js";
+const program = new Command();
+function prompt(question) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+program
+    .name("eigen")
+    .description("CLI worker for Eigen — run local Cursor, Claude Code, Codex, and OpenCode agents")
+    .version("1.1.0");
+program
+    .command("login")
+    .description("Pair CLI with your Eigen account (Clerk via web pairing code)")
+    .action(async () => {
+    try {
+        console.log(chalk.gray("\n  1. Sign in on the web app\n  2. Open /cli-pair and generate a code\n  3. Enter that code below\n"));
+        const serverUrlRaw = await prompt(`Server URL [${DEFAULT_SERVER_URL}]: `);
+        const serverUrl = serverUrlRaw || DEFAULT_SERVER_URL;
+        const code = await prompt("Pairing code: ");
+        if (!code) {
+            console.error(chalk.red("Pairing code is required."));
+            process.exit(1);
+        }
+        const spinner = ora("Pairing…").start();
+        try {
+            const config = await loginWithPairingCode(serverUrl, code);
+            spinner.succeed(`Paired as ${chalk.cyan(config.email)}`);
+        }
+        catch (err) {
+            spinner.fail(err.message);
+            process.exit(1);
+        }
+    }
+    catch {
+        process.exit(1);
+    }
+});
+program
+    .command("logout")
+    .description("Clear stored credentials")
+    .action(() => {
+    logout();
+    console.log(chalk.green("Logged out."));
+});
+program
+    .command("status")
+    .description("Show connection status and logged-in user")
+    .action(async () => {
+    const config = loadConfig();
+    if (!config) {
+        console.log(chalk.yellow("Not logged in."));
+        return;
+    }
+    console.log(chalk.blue("Logged in as:"), chalk.cyan(config.email));
+    console.log(chalk.blue("Server:"), config.serverUrl);
+    const spinner = ora("Checking server…").start();
+    try {
+        const res = await fetch(`${config.serverUrl}/api/rooms`, {
+            headers: { Authorization: `Bearer ${config.token}` },
+        });
+        if (!res.ok) {
+            spinner.fail(`Server returned ${res.status}`);
+            return;
+        }
+        const rooms = (await res.json());
+        spinner.succeed(`Server online — ${rooms.length} room(s)`);
+        for (const room of rooms) {
+            console.log(chalk.gray(`  • ${room.name || room.id}`));
+        }
+    }
+    catch (err) {
+        spinner.fail(`Cannot reach server: ${err.message}`);
+    }
+});
+function collect(value, previous) {
+    return [...previous, value];
+}
+/** Roots from `--root` flags plus EIGEN_WORK_ROOT (comma/colon separated). */
+function workRoots(flags) {
+    const fromEnv = (process.env.EIGEN_WORK_ROOT || "").split(/[,:]/).map((p) => p.trim()).filter(Boolean);
+    return [...flags, ...fromEnv];
+}
+program
+    .command("connect")
+    .description("Connect this computer or server with a setup token from Eigen → Machines")
+    .requiredOption("--token <token>", "Setup token (mt_…)")
+    .option("--server <url>", "API server URL", DEFAULT_SERVER_URL)
+    .option("--name <name>", "Name shown in Eigen (defaults to the token's name or the hostname)")
+    .action(async (opts) => {
+    const spinner = ora("Connecting this machine…").start();
+    try {
+        const machine = await connectMachine({ serverUrl: opts.server, token: opts.token, name: opts.name });
+        spinner.succeed(`Connected as ${chalk.cyan(machine.name)}`);
+        console.log(chalk.gray("\n  Next: keep it running in the background with"));
+        console.log(`    ${chalk.cyan("eigen service install")}   ${chalk.gray("(starts at boot)")}`);
+        console.log(chalk.gray("  or run it in this terminal with"));
+        console.log(`    ${chalk.cyan("eigen start")}\n`);
+    }
+    catch (err) {
+        spinner.fail(err.message);
+        process.exit(1);
+    }
+});
+program
+    .command("disconnect")
+    .description("Forget this machine's credential (remove it in Eigen → Machines to revoke it)")
+    .action(() => {
+    console.log(clearMachineConfig() ? chalk.green("Machine credential removed.") : chalk.yellow("This machine isn't connected with a token."));
+});
+program
+    .command("start")
+    .description("Start the worker")
+    .option("--repo <path>", "Override repository path for all prompts")
+    .option("--root <dir>", "Folder agents may work in (repeatable)", collect, [])
+    .option("--daemon", "Run in the background (logs to ~/.config/steer/worker.log)")
+    .action(async (opts) => {
+    // Docker / scripted installs: trade the setup token on first start.
+    if (!loadMachineConfig() && process.env.EIGEN_MACHINE_TOKEN?.trim()) {
+        try {
+            const machine = await connectMachine({
+                serverUrl: DEFAULT_SERVER_URL,
+                token: process.env.EIGEN_MACHINE_TOKEN,
+                name: process.env.EIGEN_MACHINE_NAME,
+            });
+            console.log(chalk.green(`Connected as ${machine.name}`));
+        }
+        catch (err) {
+            console.error(chalk.red(`Couldn't connect with EIGEN_MACHINE_TOKEN: ${err.message}`));
+            process.exit(1);
+        }
+    }
+    const machine = loadMachineConfig();
+    const config = machine ? null : loadConfig();
+    if (!machine && !config) {
+        console.error(chalk.red("Not connected. Run `eigen login` (your computer) or `eigen connect --token …` (a server)."));
+        process.exit(1);
+    }
+    const roots = workRoots(opts.root);
+    if (opts.daemon) {
+        const args = [...(opts.repo ? ["--repo", opts.repo] : []), ...opts.root.flatMap((r) => ["--root", r])];
+        try {
+            const { pid, log } = startDaemon(args);
+            console.log(chalk.green(`Worker running in the background (pid ${pid}).`));
+            console.log(chalk.gray(`  Logs: ${log}\n  Stop: eigen stop`));
+        }
+        catch (err) {
+            console.error(chalk.red(err.message));
+            process.exit(1);
+        }
+        return;
+    }
+    // Signed-in laptops need Cursor's own login for local Cursor agents. Headless
+    // machines may only run Claude Code / Codex / OpenCode, and can't answer a browser login.
+    if (!machine && process.stdin.isTTY)
+        await ensureCursorAuth();
+    console.log(chalk.blue.bold("\n  Eigen Worker\n"));
+    console.log(chalk.gray(`  Server:  ${machine?.serverUrl ?? config.serverUrl}`));
+    console.log(chalk.gray(machine ? `  Machine: ${machine.name}` : `  User:    ${config.email}`));
+    if (roots.length)
+        console.log(chalk.gray(`  Folders: ${roots.join(", ")}`));
+    if (opts.repo)
+        console.log(chalk.gray(`  Repo:    ${opts.repo}`));
+    console.log();
+    startWorker({ repo: opts.repo, roots });
+});
+program
+    .command("stop")
+    .description("Stop a worker started with --daemon")
+    .action(() => {
+    console.log(stopDaemon() ? chalk.green("Worker stopped.") : chalk.yellow("No background worker is running."));
+});
+const service = program.command("service").description("Run the worker as a background service (systemd / launchd)");
+service
+    .command("install")
+    .description("Install and start the service (restarts on crash, starts at boot)")
+    .option("--root <dir>", "Folder agents may work in (repeatable)", collect, [])
+    .action((opts) => {
+    if (!loadMachineConfig() && !loadConfig()) {
+        console.error(chalk.red("Connect first: `eigen connect --token …` (or `eigen login`)."));
+        process.exit(1);
+    }
+    try {
+        const notes = installService(opts.root.flatMap((r) => ["--root", r]));
+        console.log(chalk.green("✓ Eigen worker service installed and started"));
+        for (const note of notes)
+            console.log(chalk.gray(`  ${note}`));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+service
+    .command("uninstall")
+    .description("Stop and remove the service")
+    .action(() => {
+    try {
+        console.log(chalk.green(uninstallService()));
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+service
+    .command("status")
+    .description("Is the worker service running?")
+    .action(() => {
+    const machine = loadMachineConfig();
+    const status = serviceStatus();
+    const daemon = readDaemonPid();
+    console.log(chalk.blue("Machine:"), machine ? chalk.cyan(machine.name) : chalk.gray("(signed-in user, no machine token)"));
+    console.log(chalk.blue("Service:"), status.installed ? (status.running ? chalk.green(`running (${status.detail})`) : chalk.yellow(status.detail)) : chalk.gray("not installed"));
+    if (daemon)
+        console.log(chalk.blue("Background worker:"), chalk.green(`running (pid ${daemon})`));
+});
+service
+    .command("logs")
+    .description("Follow the worker's logs")
+    .action(() => {
+    try {
+        followLogs();
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
+program.parse();

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

@@ -0,0 +1,14 @@
+import type { AgentBackendKind } from "../../shared/backends/types.js";
+export interface ModelInfo {
+    id: string;
+    displayName: string;
+    description?: string;
+}
+/** Models available to the logged-in Cursor CLI on this machine. */
+export declare function listLocalModels(): Promise<ModelInfo[]>;
+export declare function listLocalClaudeModels(): Promise<ModelInfo[]>;
+export declare function listLocalCodexModels(): Promise<ModelInfo[]>;
+/** Parse `opencode models` output (`provider/model`, model may contain `/`). */
+export declare function parseOpencodeModels(stdout: string): ModelInfo[];
+export declare function listLocalOpencodeModels(): Promise<ModelInfo[]>;
+export declare function listLocalModelsForBackend(backend?: AgentBackendKind): Promise<ModelInfo[]>;

package/dist/cli/src/listModels.js

@@ -0,0 +1,196 @@
+import { execCli } from "./proc.js";
+import { CLAUDE_MODELS } from "../../shared/claudeModels.js";
+import { CODEX_MODELS } from "../../shared/codexModels.js";
+import { DEFAULT_OPENCODE_MODEL, OPENCODE_MODELS, } from "../../shared/opencodeModels.js";
+import { fetchAnthropicModels, fetchOpenaiCodingModels, mergeModelLists, parseCodexDebugModels, } from "../../shared/providerModels.js";
+const ANSI_RE = /\x1b\[[0-9;]*[a-zA-Z]/g;
+const MODEL_LINE_RE = /^([a-zA-Z0-9][a-zA-Z0-9._-]*)\s+[-–—]\s+(.+)$/;
+function stripAnsi(text) {
+    return text.replace(ANSI_RE, "").replace(/\r/g, "");
+}
+function parseModels(stdout) {
+    const models = [];
+    const seen = new Set();
+    for (const raw of stripAnsi(stdout).split("\n")) {
+        const line = raw.trim();
+        if (!line || /^available models$/i.test(line))
+            continue;
+        const m = line.match(MODEL_LINE_RE);
+        if (!m)
+            continue;
+        const id = m[1];
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        models.push({ id, displayName: m[2].trim() });
+    }
+    return models;
+}
+async function runListModels() {
+    try {
+        const { stdout } = await execCli("cursor", ["agent", "--list-models"], {
+            timeout: 60_000,
+            maxBuffer: 16 * 1024 * 1024,
+            env: {
+                ...process.env,
+                NO_COLOR: "1",
+                FORCE_COLOR: "0",
+                TERM: "dumb",
+            },
+        });
+        return stdout || "";
+    }
+    catch (err) {
+        const e = err;
+        if (e.stdout && String(e.stdout).trim())
+            return String(e.stdout);
+        if (e.code === "ENOENT") {
+            throw new Error("cursor CLI not found. Install Cursor and ensure `cursor` is on PATH.");
+        }
+        throw new Error(e.stderr?.trim() ||
+            e.message ||
+            "Failed to run `cursor agent --list-models`");
+    }
+}
+/** Models available to the logged-in Cursor CLI on this machine. */
+export async function listLocalModels() {
+    const stdout = await runListModels();
+    const models = parseModels(stdout);
+    if (models.length === 0) {
+        return [{ id: "auto", displayName: "Auto" }];
+    }
+    return models;
+}
+async function runCodexDebugModels() {
+    const attempts = [["debug", "models"], ["debug", "models", "--bundled"]];
+    let lastError = null;
+    for (const args of attempts) {
+        try {
+            const { stdout, stderr } = await execCli("codex", args, {
+                timeout: 30_000,
+                maxBuffer: 16 * 1024 * 1024,
+                env: {
+                    ...process.env,
+                    NO_COLOR: "1",
+                    FORCE_COLOR: "0",
+                    TERM: "dumb",
+                },
+            });
+            const text = `${stdout || ""}\n${stderr || ""}`;
+            if (text.trim())
+                return text;
+        }
+        catch (err) {
+            const e = err;
+            if (e.stdout && String(e.stdout).trim())
+                return String(e.stdout);
+            if (e.code === "ENOENT") {
+                throw new Error("codex CLI not found on PATH.");
+            }
+            lastError = new Error(e.stderr?.trim() || e.message || "Failed to run `codex debug models`");
+        }
+    }
+    throw lastError || new Error("`codex debug models` returned no output");
+}
+export async function listLocalClaudeModels() {
+    const live = [];
+    const key = process.env.ANTHROPIC_API_KEY?.trim();
+    if (key) {
+        try {
+            live.push(...(await fetchAnthropicModels(key)));
+        }
+        catch (err) {
+            console.warn("[listModels] Anthropic catalog failed:", err instanceof Error ? err.message : err);
+        }
+    }
+    return mergeModelLists(CLAUDE_MODELS, live);
+}
+export async function listLocalCodexModels() {
+    const live = [];
+    try {
+        live.push(...parseCodexDebugModels(await runCodexDebugModels()));
+    }
+    catch (err) {
+        console.warn("[listModels] `codex debug models` failed:", err instanceof Error ? err.message : err);
+    }
+    const key = process.env.OPENAI_API_KEY?.trim() || process.env.CODEX_API_KEY?.trim();
+    if (key) {
+        try {
+            live.push(...(await fetchOpenaiCodingModels(key)));
+        }
+        catch (err) {
+            console.warn("[listModels] OpenAI catalog failed:", err instanceof Error ? err.message : err);
+        }
+    }
+    return mergeModelLists(CODEX_MODELS, live);
+}
+/** Parse `opencode models` output (`provider/model`, model may contain `/`). */
+export function parseOpencodeModels(stdout) {
+    const models = [];
+    const seen = new Set();
+    for (const raw of stripAnsi(stdout).split("\n")) {
+        const id = raw.trim();
+        const slash = id.indexOf("/");
+        if (slash <= 0 || slash === id.length - 1)
+            continue;
+        const provider = id.slice(0, slash);
+        const name = id.slice(slash + 1);
+        if (!/^[a-z0-9][a-z0-9._-]*$/i.test(provider) || /\s/.test(name))
+            continue;
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        models.push({
+            id,
+            displayName: name,
+            description: provider[0].toUpperCase() + provider.slice(1),
+        });
+    }
+    return models;
+}
+export async function listLocalOpencodeModels() {
+    try {
+        const { stdout, stderr } = await execCli("opencode", ["models"], {
+            timeout: 60_000,
+            maxBuffer: 16 * 1024 * 1024,
+            env: {
+                ...process.env,
+                NO_COLOR: "1",
+                FORCE_COLOR: "0",
+                TERM: "dumb",
+            },
+        });
+        const models = parseOpencodeModels(`${stdout || ""}\n${stderr || ""}`);
+        if (models.length > 0) {
+            return [{ id: "auto", displayName: "Auto", description: "CLI default" }, ...models];
+        }
+    }
+    catch (err) {
+        const e = err;
+        if (e.stdout) {
+            const models = parseOpencodeModels(String(e.stdout));
+            if (models.length > 0) {
+                return [{ id: "auto", displayName: "Auto", description: "CLI default" }, ...models];
+            }
+        }
+        if (e.code !== "ENOENT") {
+            console.warn("[listModels] `opencode models` failed:", e.message || String(err));
+        }
+    }
+    const fallback = OPENCODE_MODELS.some((m) => m.id === DEFAULT_OPENCODE_MODEL)
+        ? OPENCODE_MODELS
+        : [
+            ...OPENCODE_MODELS,
+            { id: DEFAULT_OPENCODE_MODEL, displayName: DEFAULT_OPENCODE_MODEL },
+        ];
+    return fallback;
+}
+export async function listLocalModelsForBackend(backend = "cursor") {
+    if (backend === "claude-code")
+        return listLocalClaudeModels();
+    if (backend === "codex")
+        return listLocalCodexModels();
+    if (backend === "opencode")
+        return listLocalOpencodeModels();
+    return listLocalModels();
+}

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

@@ -0,0 +1,9 @@
+export interface CursorChatSession {
+    id: string;
+    createdAt: number;
+    updatedAt: number;
+    hasConversation: boolean;
+}
+/** MD5 of resolved repo path — matches Cursor's ~/.cursor/chats layout. */
+export declare function workspaceChatHash(repoPath: string): string;
+export declare function listChatSessions(repoPath: string): CursorChatSession[];

package/dist/cli/src/listSessions.js

@@ -0,0 +1,37 @@
+import { createHash } from "crypto";
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { join, resolve } from "path";
+/** MD5 of resolved repo path — matches Cursor's ~/.cursor/chats layout. */
+export function workspaceChatHash(repoPath) {
+    return createHash("md5").update(resolve(repoPath)).digest("hex");
+}
+export function listChatSessions(repoPath) {
+    const absRepo = resolve(repoPath);
+    const root = join(homedir(), ".cursor", "chats", workspaceChatHash(absRepo));
+    if (!existsSync(root))
+        return [];
+    const sessions = [];
+    for (const id of readdirSync(root, { withFileTypes: true })) {
+        if (!id.isDirectory())
+            continue;
+        const metaPath = join(root, id.name, "meta.json");
+        if (!existsSync(metaPath))
+            continue;
+        try {
+            const meta = JSON.parse(readFileSync(metaPath, "utf8"));
+            if (meta.cwd && resolve(meta.cwd) !== absRepo)
+                continue;
+            sessions.push({
+                id: id.name,
+                createdAt: meta.createdAtMs ?? 0,
+                updatedAt: meta.updatedAtMs ?? meta.createdAtMs ?? 0,
+                hasConversation: Boolean(meta.hasConversation),
+            });
+        }
+        catch {
+            // skip malformed entries
+        }
+    }
+    return sessions.sort((a, b) => b.updatedAt - a.updatedAt);
+}

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

@@ -0,0 +1,20 @@
+/**
+ * Headless machine credential (from `eigen connect --token mt_…`). Separate
+ * from the user login in config.json: it can only run agents on this machine
+ * and is revoked per machine from Eigen → Machines.
+ */
+export interface MachineConfig {
+    serverUrl: string;
+    machineId: string;
+    credential: string;
+    name: string;
+}
+export declare function loadMachineConfig(): MachineConfig | null;
+export declare function saveMachineConfig(config: MachineConfig): void;
+export declare function clearMachineConfig(): boolean;
+/** Trade a setup token for this machine's credential and save it. */
+export declare function connectMachine(input: {
+    serverUrl: string;
+    token: string;
+    name?: string;
+}): Promise<MachineConfig>;

package/dist/cli/src/machineConfig.js

@@ -0,0 +1,66 @@
+import { chmodSync, existsSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { arch, hostname, platform } from "os";
+import { join } from "path";
+import { getConfigDir } from "./config.js";
+const FILE = "machine.json";
+function machinePath() {
+    return join(getConfigDir(), FILE);
+}
+export function loadMachineConfig() {
+    const path = machinePath();
+    if (!existsSync(path))
+        return null;
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf-8"));
+        if (!parsed.serverUrl || !parsed.machineId || !parsed.credential)
+            return null;
+        return { serverUrl: parsed.serverUrl, machineId: parsed.machineId, credential: parsed.credential, name: parsed.name || "" };
+    }
+    catch {
+        return null;
+    }
+}
+export function saveMachineConfig(config) {
+    const path = machinePath();
+    writeFileSync(path, JSON.stringify(config, null, 2), { encoding: "utf-8", mode: 0o600 });
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // Windows: best effort
+    }
+}
+export function clearMachineConfig() {
+    const path = machinePath();
+    if (!existsSync(path))
+        return false;
+    rmSync(path);
+    return true;
+}
+/** Trade a setup token for this machine's credential and save it. */
+export async function connectMachine(input) {
+    const serverUrl = input.serverUrl.replace(/\/+$/, "");
+    const res = await fetch(`${serverUrl}/api/machines/connect`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            token: input.token.trim(),
+            hostname: hostname(),
+            os: platform(),
+            arch: arch(),
+            name: input.name?.trim() || undefined,
+        }),
+    });
+    const data = (await res.json().catch(() => ({})));
+    if (!res.ok || !data.machineId || !data.credential) {
+        throw new Error(data.error || `Server returned ${res.status}`);
+    }
+    const config = {
+        serverUrl,
+        machineId: data.machineId,
+        credential: data.credential,
+        name: data.name || hostname(),
+    };
+    saveMachineConfig(config);
+    return config;
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Open a native OS folder picker and return an absolute path.
+ * Returns null if the user cancels.
+ */
+export declare function pickFolder(): Promise<string | null>;

package/dist/cli/src/pickFolder.js

@@ -0,0 +1,65 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { platform } from "os";
+const execFileAsync = promisify(execFile);
+/**
+ * Open a native OS folder picker and return an absolute path.
+ * Returns null if the user cancels.
+ */
+export async function pickFolder() {
+    const os = platform();
+    try {
+        if (os === "darwin") {
+            const { stdout } = await execFileAsync("osascript", [
+                "-e",
+                'POSIX path of (choose folder with prompt "Select a repository folder")',
+            ]);
+            const path = stdout.trim().replace(/\/$/, "");
+            return path || null;
+        }
+        if (os === "win32") {
+            const script = [
+                "Add-Type -AssemblyName System.Windows.Forms",
+                "$d = New-Object System.Windows.Forms.FolderBrowserDialog",
+                '$d.Description = "Select a repository folder"',
+                "$d.ShowNewFolderButton = $true",
+                "if ($d.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) { Write-Output $d.SelectedPath }",
+            ].join("; ");
+            const { stdout } = await execFileAsync("powershell", [
+                "-NoProfile",
+                "-Command",
+                script,
+            ]);
+            const path = stdout.trim();
+            return path || null;
+        }
+        // Linux: prefer zenity, then kdialog
+        try {
+            const { stdout } = await execFileAsync("zenity", [
+                "--file-selection",
+                "--directory",
+                "--title=Select a repository folder",
+            ]);
+            const path = stdout.trim();
+            return path || null;
+        }
+        catch {
+            const { stdout } = await execFileAsync("kdialog", [
+                "--getexistingdirectory",
+                process.env.HOME || "/",
+                "--title",
+                "Select a repository folder",
+            ]);
+            const path = stdout.trim();
+            return path || null;
+        }
+    }
+    catch (err) {
+        const e = err;
+        // User cancel: osascript exit 1 / zenity exit 1
+        if (e.code === 1 || e.code === "1")
+            return null;
+        throw new Error(e.message ||
+            "Failed to open folder picker. On Linux install zenity or kdialog.");
+    }
+}

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

@@ -0,0 +1,23 @@
+import type { ChildProcess, SpawnOptions } from "child_process";
+/**
+ * Spawn an agent CLI (`cursor`, `claude`, `codex`). On Windows those are
+ * npm `.cmd` shims, which plain `spawn` can't launch without a shell —
+ * cross-spawn resolves the shim and escapes arguments safely.
+ */
+export declare function spawnCli(command: string, args: string[], options: SpawnOptions): ChildProcess;
+export interface ExecCliOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    timeout?: number;
+    maxBuffer?: number;
+}
+/** execFile-style helper on top of spawnCli: resolves `{ stdout, stderr }`, rejects on non-zero exit. */
+export declare function execCli(command: string, args: string[], options?: ExecCliOptions): Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Stop a CLI run. On Windows the child is the `.cmd` shim's cmd.exe, so kill
+ * the whole tree or the real agent keeps running.
+ */
+export declare function killCli(child: ChildProcess): void;