@gigaai/newton 0.3.0

package/dist/executor.js

@@ -0,0 +1,287 @@
+import { readFileSync } from "node:fs";
+import { cpus } from "node:os";
+import { resolve } from "node:path";
+import { AcpAgentSession } from "./acp.js";
+import { agentCallKey, loadResumeCache, RunJournal } from "./journal.js";
+import { balancedSlice, extractJson, INVALID, structuredOutputInstruction, structuredOutputRetryPrompt, validateAgainstSchema, } from "./schema.js";
+const AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
+const SCRIPT_PARAMS = ["agent", "parallel", "pipeline", "phase", "log", "args", "budget", "Date", "Math"];
+export function loadWorkflow(file) {
+    const absolute = resolve(file);
+    const source = readFileSync(absolute, "utf8");
+    const metaMatch = source.match(/export\s+const\s+meta\s*=/);
+    if (!metaMatch || metaMatch.index === undefined) {
+        throw new Error(`${file}: workflow must begin with \`export const meta = { name, description, ... }\``);
+    }
+    const braceStart = source.indexOf("{", metaMatch.index);
+    const metaLiteral = braceStart === -1 ? undefined : balancedSlice(source, braceStart);
+    if (!metaLiteral) {
+        throw new Error(`${file}: could not parse the meta object literal`);
+    }
+    let meta;
+    try {
+        meta = new Function(`"use strict"; return (${metaLiteral});`)();
+    }
+    catch (error) {
+        throw new Error(`${file}: meta must be a pure object literal (${error.message})`);
+    }
+    if (!meta?.name || !meta?.description) {
+        throw new Error(`${file}: meta requires both \`name\` and \`description\``);
+    }
+    const body = source.replace(/export\s+const\s+meta\s*=/, "const meta =");
+    return { file: absolute, meta, body };
+}
+/** Compile without running — catches syntax errors and non-literal meta. */
+export function compileWorkflow(workflow) {
+    new AsyncFunction(...SCRIPT_PARAMS, workflow.body);
+}
+// Wall-clock and randomness would silently break resume replay, so scripts get
+// guarded shims instead of the real globals. Pass timestamps in via --args.
+const guardedDate = new Proxy(Date, {
+    get(target, prop, receiver) {
+        if (prop === "now") {
+            return () => {
+                throw new Error("Date.now() is unavailable in workflows (breaks resume); pass timestamps via --args");
+            };
+        }
+        return Reflect.get(target, prop, receiver);
+    },
+    construct(target, argArray) {
+        if (argArray.length === 0) {
+            throw new Error("new Date() without arguments is unavailable in workflows (breaks resume)");
+        }
+        return Reflect.construct(target, argArray);
+    },
+});
+const guardedMath = Object.create(Math, {
+    random: {
+        value: () => {
+            throw new Error("Math.random() is unavailable in workflows (breaks resume); vary prompts by index instead");
+        },
+    },
+});
+class Semaphore {
+    queue = [];
+    available;
+    constructor(size) {
+        this.available = size;
+    }
+    async acquire() {
+        if (this.available > 0) {
+            this.available -= 1;
+            return;
+        }
+        await new Promise((resolveWait) => this.queue.push(resolveWait));
+    }
+    release() {
+        const next = this.queue.shift();
+        if (next)
+            next();
+        else
+            this.available += 1;
+    }
+}
+const AGENT_PREAMBLE = [
+    "You are a worker inside a deterministic multi-agent workflow.",
+    "Your final message is returned verbatim to a script, not shown to a human —",
+    "return raw data with no greetings, preamble, or offers of further help.",
+    "",
+].join("\n");
+export async function runWorkflow(options) {
+    const startedAt = Date.now();
+    const workflow = loadWorkflow(options.file);
+    const scriptFn = new AsyncFunction(...SCRIPT_PARAMS, workflow.body);
+    const workspace = resolve(options.cwd);
+    const journal = new RunJournal(workspace);
+    const resumeCache = options.resumeRunId ? loadResumeCache(workspace, options.resumeRunId) : undefined;
+    const reporter = options.reporter;
+    const maxAgents = options.maxAgents ?? 200;
+    const agentTimeoutMs = options.agentTimeoutMs ?? 20 * 60 * 1000;
+    const concurrency = options.concurrency ?? Math.min(16, Math.max(2, cpus().length - 2));
+    const semaphore = new Semaphore(concurrency);
+    const budgetTotal = options.budgetTokens ?? null;
+    let agentCounter = 0;
+    let outputTokens = 0;
+    let currentPhase;
+    journal.append({
+        type: "workflow_start",
+        runId: journal.runId,
+        file: workflow.file,
+        name: workflow.meta.name,
+        args: options.args ?? null,
+        resumedFrom: options.resumeRunId ?? null,
+    });
+    reporter.start(workflow.meta, journal.runId, journal.runDir);
+    const budget = {
+        total: budgetTotal,
+        spent: () => outputTokens,
+        remaining: () => (budgetTotal === null ? Infinity : Math.max(0, budgetTotal - outputTokens)),
+    };
+    async function agentFn(prompt, callOptions = {}) {
+        if (typeof prompt !== "string" || !prompt.trim()) {
+            throw new Error("agent() requires a non-empty prompt string");
+        }
+        const spec = {
+            provider: callOptions.provider,
+            model: callOptions.model,
+            effort: callOptions.effort,
+            access: callOptions.access,
+            command: callOptions.command,
+        };
+        const id = ++agentCounter;
+        if (id > maxAgents) {
+            throw new Error(`agent cap reached (${maxAgents}); raise with --max-agents`);
+        }
+        if (budgetTotal !== null && outputTokens >= budgetTotal) {
+            throw new Error(`token budget exhausted (${outputTokens}/${budgetTotal} output tokens)`);
+        }
+        const key = agentCallKey(prompt, spec, callOptions.schema ?? null);
+        const label = callOptions.label ?? prompt.replace(/\s+/g, " ").trim().slice(0, 64);
+        const phase = callOptions.phase ?? currentPhase;
+        const cachedQueue = resumeCache?.get(key);
+        if (cachedQueue && cachedQueue.length > 0) {
+            const result = cachedQueue.shift();
+            journal.append({ type: "agent_end", id, key, label, phase, status: "ok", cached: true, result });
+            reporter.agentStart(id, label, spec, phase, true);
+            reporter.agentEnd(id, true, 0, "cached");
+            return result;
+        }
+        await semaphore.acquire();
+        const agentStartedAt = Date.now();
+        reporter.agentStart(id, label, spec, phase, false);
+        journal.append({ type: "agent_start", id, key, label, phase, spec, prompt });
+        const trace = journal.traceWriter(id);
+        try {
+            const fullPrompt = AGENT_PREAMBLE + prompt + (callOptions.schema ? structuredOutputInstruction(callOptions.schema) : "");
+            const session = new AcpAgentSession({
+                spec,
+                prompt: fullPrompt,
+                cwd: callOptions.cwd ? resolve(workspace, callOptions.cwd) : workspace,
+                timeoutMs: callOptions.timeoutMs ?? agentTimeoutMs,
+                trace,
+            });
+            let turn = await session.prompt();
+            let result = turn.text;
+            let failure = turn.error;
+            if (!failure && callOptions.schema) {
+                for (let attempt = 0;; attempt++) {
+                    const parsed = extractJson(turn.text);
+                    const errors = parsed === INVALID
+                        ? ["response contained no parseable JSON"]
+                        : validateAgainstSchema(parsed, callOptions.schema);
+                    if (errors.length === 0) {
+                        result = parsed;
+                        break;
+                    }
+                    if (attempt >= 2) {
+                        failure = `structured output failed after ${attempt + 1} attempts: ${errors.join("; ")}`;
+                        break;
+                    }
+                    turn = await session.promptAgain(structuredOutputRetryPrompt(errors, callOptions.schema));
+                    if (turn.error) {
+                        failure = turn.error;
+                        break;
+                    }
+                }
+            }
+            session.close();
+            const seconds = Math.round((Date.now() - agentStartedAt) / 1000);
+            const turnTokens = turn.usage?.outputTokens ?? 0;
+            outputTokens += turnTokens;
+            if (failure) {
+                journal.append({ type: "agent_end", id, key, label, phase, status: "error", error: failure, seconds });
+                reporter.agentEnd(id, false, seconds, failure);
+                return null;
+            }
+            journal.append({
+                type: "agent_end",
+                id,
+                key,
+                label,
+                phase,
+                status: "ok",
+                seconds,
+                toolCalls: turn.toolCalls,
+                usage: turn.usage,
+                result,
+            });
+            reporter.agentEnd(id, true, seconds, turn.usage ? `${turn.toolCalls} tools · ${turnTokens} out-tok` : `${turn.toolCalls} tools`);
+            return result;
+        }
+        finally {
+            semaphore.release();
+        }
+    }
+    async function parallelFn(thunks) {
+        if (!Array.isArray(thunks) || thunks.some((t) => typeof t !== "function")) {
+            throw new Error("parallel() takes an array of zero-argument functions");
+        }
+        return Promise.all(thunks.map((thunk) => Promise.resolve()
+            .then(thunk)
+            .catch((error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            journal.append({ type: "log", message: `parallel task failed: ${message}` });
+            reporter.log(`parallel task failed: ${message}`);
+            return null;
+        })));
+    }
+    async function pipelineFn(items, ...stages) {
+        if (!Array.isArray(items))
+            throw new Error("pipeline() takes an array of items first");
+        if (stages.length === 0 || stages.some((s) => typeof s !== "function")) {
+            throw new Error("pipeline() takes one or more stage functions after the items");
+        }
+        return Promise.all(items.map(async (item, index) => {
+            let previous = item;
+            for (const stage of stages) {
+                try {
+                    previous = await stage(previous, item, index);
+                }
+                catch (error) {
+                    const message = error instanceof Error ? error.message : String(error);
+                    journal.append({ type: "log", message: `pipeline item ${index} dropped: ${message}` });
+                    reporter.log(`pipeline item ${index} dropped: ${message}`);
+                    return null;
+                }
+            }
+            return previous;
+        }));
+    }
+    function phaseFn(title) {
+        if (typeof title !== "string")
+            throw new Error("phase() takes a title string");
+        currentPhase = title;
+        journal.append({ type: "phase", title });
+        reporter.phase(title);
+    }
+    function logFn(message) {
+        const text = typeof message === "string" ? message : JSON.stringify(message);
+        journal.append({ type: "log", message: text });
+        reporter.log(text);
+    }
+    try {
+        const result = await scriptFn(agentFn, parallelFn, pipelineFn, phaseFn, logFn, options.args, budget, guardedDate, guardedMath);
+        const runResult = {
+            runId: journal.runId,
+            status: "ok",
+            result: result === undefined ? null : result,
+            agents: agentCounter,
+            outputTokens,
+            durationMs: Date.now() - startedAt,
+        };
+        journal.append({ type: "workflow_end", status: "ok", result: runResult.result, agents: agentCounter, outputTokens });
+        return runResult;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        journal.append({ type: "workflow_end", status: "error", error: message, agents: agentCounter, outputTokens });
+        return {
+            runId: journal.runId,
+            status: "error",
+            error: message,
+            agents: agentCounter,
+            outputTokens,
+            durationMs: Date.now() - startedAt,
+        };
+    }
+}

package/dist/journal.js

@@ -0,0 +1,72 @@
+import { createHash, randomBytes } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Durable run artifacts under <workspace>/.newton/runs/<runId>/:
+ *   journal.jsonl        — one entry per lifecycle event; the resume source
+ *   agents/<id>.jsonl    — full ACP wire trace per agent (the future evals feed)
+ */
+export class RunJournal {
+    runId;
+    runDir;
+    journalPath;
+    constructor(workspace, runId) {
+        this.runId = runId ?? newRunId();
+        this.runDir = join(workspace, ".newton", "runs", this.runId);
+        this.journalPath = join(this.runDir, "journal.jsonl");
+        mkdirSync(join(this.runDir, "agents"), { recursive: true });
+    }
+    append(entry) {
+        const record = { t: new Date().toISOString(), ...entry };
+        appendFileSync(this.journalPath, `${JSON.stringify(record)}\n`, "utf8");
+    }
+    traceWriter(agentId) {
+        const tracePath = join(this.runDir, "agents", `${agentId}.jsonl`);
+        return (event) => {
+            appendFileSync(tracePath, `${JSON.stringify({ t: new Date().toISOString(), ...event })}\n`, "utf8");
+        };
+    }
+}
+function newRunId() {
+    const now = new Date();
+    const stamp = now
+        .toISOString()
+        .replace(/[-:]/g, "")
+        .replace(/\..+/, "")
+        .replace("T", "-");
+    return `${stamp}-${randomBytes(3).toString("hex")}`;
+}
+export function agentCallKey(prompt, spec, schema) {
+    return createHash("sha256")
+        .update(JSON.stringify({ prompt, spec, schema }))
+        .digest("hex")
+        .slice(0, 32);
+}
+/**
+ * Resume cache: successful agent results from a prior run, keyed by
+ * (prompt, spec, schema) hash. Duplicate keys replay in call order.
+ */
+export function loadResumeCache(workspace, runId) {
+    const journalPath = join(workspace, ".newton", "runs", runId, "journal.jsonl");
+    if (!existsSync(journalPath)) {
+        throw new Error(`No journal found for run "${runId}" (looked at ${journalPath})`);
+    }
+    const cache = new Map();
+    for (const line of readFileSync(journalPath, "utf8").split("\n")) {
+        if (!line.trim())
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (entry.type === "agent_end" && entry.status === "ok" && typeof entry.key === "string") {
+            const queue = cache.get(entry.key) ?? [];
+            queue.push(entry.result);
+            cache.set(entry.key, queue);
+        }
+    }
+    return cache;
+}

package/dist/progress.js

@@ -0,0 +1,61 @@
+const useColor = process.stderr.isTTY && !process.env.NO_COLOR;
+const paint = (code, text) => (useColor ? `[${code}m${text}` : text);
+const dim = (t) => paint("2", t);
+const bold = (t) => paint("1", t);
+const green = (t) => paint("32", t);
+const red = (t) => paint("31", t);
+const cyan = (t) => paint("36", t);
+function specLabel(spec) {
+    if (spec.command?.length)
+        return spec.command[0];
+    return [spec.provider ?? "openai", spec.model].filter(Boolean).join("/");
+}
+/** Human progress on stderr; stdout stays clean for the result JSON. */
+export class HumanReporter {
+    start(meta, runId, runDir) {
+        process.stderr.write(`${bold(`◆ ${meta.name}`)} ${dim(`— run ${runId}`)}\n${dim(`  ${runDir}`)}\n`);
+    }
+    phase(title) {
+        process.stderr.write(`${cyan(`▸ ${title}`)}\n`);
+    }
+    log(message) {
+        process.stderr.write(`${dim(`· ${message}`)}\n`);
+    }
+    agentStart(id, label, spec, phase, cached) {
+        const suffix = cached ? dim(" (cached)") : "";
+        process.stderr.write(`  ${dim(`#${id}`)} ${specLabel(spec)} ${dim("·")} ${label}${suffix}\n`);
+    }
+    agentEnd(id, ok, seconds, detail) {
+        const mark = ok ? green("✔") : red("✖");
+        const summary = ok ? detail : detail.split("\n")[0].slice(0, 200);
+        process.stderr.write(`  ${mark} ${dim(`#${id}`)} ${seconds}s ${dim(`· ${summary}`)}\n`);
+    }
+    done(run) {
+        const mark = run.status === "ok" ? green("✔") : red("✖");
+        process.stderr.write(`${mark} ${bold(run.status)} ${dim(`· ${run.agents} agents · ${run.outputTokens} out-tok · ${Math.round(run.durationMs / 1000)}s`)}\n`);
+    }
+}
+/** NDJSON events on stdout — the machine-readable surface for driving agents. */
+export class JsonReporter {
+    emit(event) {
+        process.stdout.write(`${JSON.stringify(event)}\n`);
+    }
+    start(meta, runId, runDir) {
+        this.emit({ event: "start", name: meta.name, runId, runDir });
+    }
+    phase(title) {
+        this.emit({ event: "phase", title });
+    }
+    log(message) {
+        this.emit({ event: "log", message });
+    }
+    agentStart(id, label, spec, phase, cached) {
+        this.emit({ event: "agent_start", id, label, spec, phase, cached });
+    }
+    agentEnd(id, ok, seconds, detail) {
+        this.emit({ event: "agent_end", id, ok, seconds, detail });
+    }
+    done(run) {
+        this.emit({ event: "result", ...run });
+    }
+}

package/dist/providers.js

@@ -0,0 +1,255 @@
+import { execFileSync } from "node:child_process";
+import { accessSync, constants, existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { delimiter, dirname, join } from "node:path";
+function findOnPath(binary) {
+    for (const dir of (process.env.PATH ?? "").split(delimiter)) {
+        if (!dir)
+            continue;
+        const candidate = join(dir, binary);
+        try {
+            accessSync(candidate, constants.X_OK);
+            return candidate;
+        }
+        catch {
+            // keep scanning
+        }
+    }
+    return undefined;
+}
+/** Combined stdout+stderr of a short command, or undefined on any failure. */
+function probe(command) {
+    try {
+        return execFileSync("sh", ["-c", `${command} 2>&1`], { timeout: 4000, encoding: "utf8" });
+    }
+    catch {
+        return undefined;
+    }
+}
+function fileContains(path, needle) {
+    try {
+        return readFileSync(path, "utf8").includes(needle);
+    }
+    catch {
+        return false;
+    }
+}
+function envAuth(...vars) {
+    const found = vars.find((v) => process.env[v]);
+    return found ? { state: "ok", detail: `${found} set` } : undefined;
+}
+function codexSandbox(access) {
+    switch (access) {
+        case "read":
+            return "read-only";
+        case "full":
+            return "danger-full-access";
+        default:
+            return "workspace-write";
+    }
+}
+const PROVIDERS = [
+    {
+        name: "codex",
+        aliases: ["openai"],
+        bins: ["codex-acp"],
+        bundled: { pkg: "@agentclientprotocol/codex-acp", bin: "codex-acp" },
+        npxPkg: "@agentclientprotocol/codex-acp",
+        acceptsModel: true,
+        args: (spec) => {
+            // Approvals off: agents act within the sandbox instead of round-tripping
+            // permission prompts. Access is controlled by the sandbox mode itself.
+            const args = ["-c", 'approval_policy="never"', "-c", `sandbox_mode="${codexSandbox(spec.access)}"`];
+            if (spec.model)
+                args.push("-c", `model="${spec.model}"`);
+            if (spec.effort)
+                args.push("-c", `model_reasoning_effort="${spec.effort}"`);
+            return args;
+        },
+        auth: () => {
+            const status = probe("codex login status");
+            if (status && /logged in/i.test(status))
+                return { state: "ok", detail: status.trim().split("\n")[0] };
+            return (envAuth("CODEX_API_KEY", "OPENAI_API_KEY") ?? {
+                state: "none",
+                detail: "run `codex login` or set OPENAI_API_KEY",
+            });
+        },
+    },
+    {
+        name: "claude",
+        aliases: ["anthropic", "claude-code"],
+        bins: ["claude-agent-acp", "claude-code-acp"],
+        npxPkg: "@agentclientprotocol/claude-agent-acp",
+        acceptsModel: true,
+        args: () => [],
+        env: (spec) => (spec.model ? { ANTHROPIC_MODEL: spec.model } : {}),
+        auth: () => {
+            const fromEnv = envAuth("ANTHROPIC_API_KEY");
+            if (fromEnv)
+                return fromEnv;
+            if (fileContains(join(homedir(), ".claude.json"), "oauthAccount")) {
+                return { state: "ok", detail: "Claude Code account in ~/.claude.json" };
+            }
+            return findOnPath("claude")
+                ? { state: "unknown", detail: "claude CLI installed; login state not detectable" }
+                : { state: "none", detail: "install Claude Code and log in, or set ANTHROPIC_API_KEY" };
+        },
+    },
+    {
+        name: "gemini",
+        aliases: ["google"],
+        bins: ["gemini"],
+        npxPkg: "@google/gemini-cli",
+        acceptsModel: true,
+        args: (spec) => {
+            const args = ["--experimental-acp"];
+            if (spec.model)
+                args.push("-m", spec.model);
+            if (spec.access === "full")
+                args.push("--yolo");
+            return args;
+        },
+        auth: () => existsSync(join(homedir(), ".gemini", "oauth_creds.json"))
+            ? { state: "ok", detail: "Google OAuth in ~/.gemini" }
+            : (envAuth("GEMINI_API_KEY", "GOOGLE_API_KEY") ?? {
+                state: "none",
+                detail: "run `gemini` once to log in, or set GEMINI_API_KEY",
+            }),
+    },
+    {
+        name: "cursor",
+        aliases: ["cursor-agent"],
+        bins: ["cursor-agent-acp"],
+        npxPkg: "cursor-agent-acp",
+        acceptsModel: false,
+        args: () => [],
+        auth: () => {
+            if (!findOnPath("cursor-agent")) {
+                return { state: "none", detail: "cursor-agent CLI not installed" };
+            }
+            const status = probe("cursor-agent status");
+            return status && /logged in/i.test(status)
+                ? { state: "ok", detail: "cursor-agent logged in" }
+                : { state: "none", detail: "run `cursor-agent login`" };
+        },
+    },
+    {
+        name: "opencode",
+        aliases: [],
+        bins: ["opencode"],
+        npxPkg: "opencode-ai",
+        acceptsModel: false,
+        args: () => ["acp"],
+        auth: () => existsSync(join(homedir(), ".local", "share", "opencode", "auth.json"))
+            ? { state: "ok", detail: "credentials in ~/.local/share/opencode" }
+            : { state: "unknown", detail: "no auth.json found; opencode may use provider env vars" },
+    },
+    {
+        name: "qwen",
+        aliases: ["qwen-code"],
+        bins: ["qwen"],
+        npxPkg: "@qwen-code/qwen-code",
+        acceptsModel: true,
+        args: (spec) => {
+            const args = ["--acp"];
+            if (spec.model)
+                args.push("-m", spec.model);
+            return args;
+        },
+        auth: () => existsSync(join(homedir(), ".qwen", "oauth_creds.json"))
+            ? { state: "ok", detail: "Qwen OAuth in ~/.qwen" }
+            : (envAuth("DASHSCOPE_API_KEY", "OPENAI_API_KEY") ?? {
+                state: "none",
+                detail: "run `qwen` once to log in",
+            }),
+    },
+    {
+        name: "goose",
+        aliases: [],
+        bins: ["goose"],
+        acceptsModel: false,
+        args: () => ["acp"],
+        auth: () => existsSync(join(homedir(), ".config", "goose", "config.yaml"))
+            ? { state: "ok", detail: "config in ~/.config/goose" }
+            : { state: "none", detail: "run `goose configure`" },
+    },
+    {
+        name: "copilot",
+        aliases: ["github-copilot"],
+        bins: ["copilot-language-server"],
+        npxPkg: "@github/copilot-language-server",
+        acceptsModel: false,
+        args: () => ["--acp"],
+        auth: () => {
+            const status = probe("gh auth status");
+            return status && /logged in/i.test(status)
+                ? { state: "unknown", detail: "gh logged in; Copilot subscription not verified" }
+                : { state: "unknown", detail: "uses GitHub auth; not detectable here" };
+        },
+    },
+];
+function findProvider(name) {
+    return PROVIDERS.find((p) => p.name === name || p.aliases.includes(name));
+}
+/**
+ * Locate an npm-distributed launcher script relative to this package.
+ * Fails inside standalone binaries (no node_modules) — callers fall back
+ * to PATH and then npx so the compiled `newton` binary still works.
+ */
+function resolveBundledBin(pkg, binName) {
+    try {
+        const require = createRequire(import.meta.url);
+        const pkgJsonPath = require.resolve(`${pkg}/package.json`);
+        const pkgJson = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+        const rel = pkgJson.bin?.[binName];
+        return rel ? join(dirname(pkgJsonPath), rel) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveAgentCommand(spec) {
+    if (spec.command?.length) {
+        const [command, ...args] = spec.command;
+        return { command: command, args, env: {}, modelHandled: false };
+    }
+    const name = spec.provider ?? "codex";
+    const provider = findProvider(name);
+    if (!provider) {
+        const known = PROVIDERS.map((p) => p.name).join(" | ");
+        throw new Error(`Unknown provider "${name}". Use ${known}, or pass command: ["my-agent", "--acp"].`);
+    }
+    const args = provider.args(spec);
+    const env = provider.env?.(spec) ?? {};
+    const modelHandled = Boolean(spec.model) && provider.acceptsModel;
+    if (provider.bundled) {
+        const script = resolveBundledBin(provider.bundled.pkg, provider.bundled.bin);
+        if (script)
+            return { command: process.execPath, args: [script, ...args], env, modelHandled };
+    }
+    for (const bin of provider.bins) {
+        const onPath = findOnPath(bin);
+        if (onPath)
+            return { command: onPath, args, env, modelHandled };
+    }
+    if (provider.npxPkg) {
+        return { command: "npx", args: ["-y", provider.npxPkg, ...args], env, modelHandled };
+    }
+    throw new Error(`Provider "${provider.name}" needs one of [${provider.bins.join(", ")}] on PATH — no npx fallback exists for it.`);
+}
+export function describeProviders() {
+    return PROVIDERS.map((provider) => {
+        const bundled = provider.bundled && resolveBundledBin(provider.bundled.pkg, provider.bundled.bin);
+        const onPath = provider.bins.map(findOnPath).find(Boolean);
+        const resolvesVia = bundled ?? onPath ?? (provider.npxPkg ? `npx -y ${provider.npxPkg}` : "not installed");
+        return {
+            provider: provider.name,
+            aliases: provider.aliases,
+            resolvesVia,
+            installed: Boolean(bundled ?? onPath),
+            auth: provider.auth(),
+        };
+    });
+}