@modelworks/quack 0.0.0-stage → 0.2.8

package/dist/agents/opencode.js

@@ -0,0 +1,409 @@
+/**
+ * OpenCode agent — injects SSE circuits as OpenAI-compatible providers
+ * via `OPENCODE_CONFIG_CONTENT`, plus the global `modelworks` MCP server.
+ *
+ * @module
+ */
+import { spawn, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { refreshToken } from "../auth.js";
+import { loadCredentials } from "../auth.js";
+import { readState, readConfig } from "../project.js";
+import { startProxy } from "../proxy.js";
+import { fetchRunFromApi, saveRunRecord } from "../history.js";
+import buildInfo from "../build-info.json" with { type: "json" };
+const AGENT_VERSION = buildInfo.version;
+const AGENT_BUILD = `${AGENT_VERSION}+${buildInfo.build} (${buildInfo.commit}${buildInfo.dirty ? "-dirty" : ""})`;
+/** `npm` package for OpenAI-compatible providers. */
+const OPENAI_COMPATIBLE_PACKAGE = "@opencode/ai/providers/openai-compatible";
+/** Detect whether a binary is on PATH. */
+function hasBinary(bin) {
+    try {
+        const cmd = process.platform === "win32" ? "where" : "which";
+        const result = spawnSync(cmd, [bin], { stdio: "ignore" });
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Check if a file exists and is executable at a specific path. */
+function hasBinaryAt(binPath) {
+    try {
+        fs.accessSync(binPath, fs.constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Resolve the opencode binary: prefer V2 (MCP 2.0 support), fall back to V1. */
+function resolveOpencodeBinary() {
+    // V2: on PATH as "opencode2", or at ~/.opencode/bin/opencode2
+    if (hasBinary("opencode2"))
+        return { bin: "opencode2", isV2: true };
+    const v2Path = path.join(os.homedir(), ".opencode", "bin", "opencode2");
+    if (hasBinaryAt(v2Path))
+        return { bin: v2Path, isV2: true };
+    // V1: on PATH as "opencode"
+    if (hasBinary("opencode"))
+        return { bin: "opencode", isV2: false };
+    return null;
+}
+/** Install methods for opencode, in priority order. */
+const OPENCODE_INSTALL = [
+    { label: "curl", cmd: "curl -fsSL https://opencode.ai/install | bash", check: () => hasBinary("curl") },
+    { label: "npm", cmd: "npm i -g @opencode/cli", check: () => hasBinary("npm") },
+    { label: "bun", cmd: "bun install -g @opencode/cli", check: () => hasBinary("bun") },
+    { label: "brew", cmd: "brew install opencode", check: () => hasBinary("brew") },
+];
+/** Should this circuit be injected as an OpenAI-compatible provider? */
+function isInjectableSseCircuit(entry) {
+    return (entry.adapters.includes("OPEN_AI_SSE") && entry.sse_adaptor_uid !== null);
+}
+/**
+ * Resolve which circuit to use as the default OpenCode model.
+ *
+ * Resolution order:
+ * 1. `config.default_circuit` if it's SSE-compatible and injected
+ * 2. First injectable SSE circuit in state (fallback, not persisted)
+ * 3. `null` — no default model injected
+ *
+ * Prints a warning to stderr if `default_circuit` is stale (not in the
+ * circuits array) or not SSE-compatible.
+ *
+ * @returns the OpenCode model ID (`circuit-<uid>/<uid>`) or `null`.
+ */
+export function resolveDefaultModel(config, state) {
+    const injectedCircuits = Object.values(state.circuits).filter(isInjectableSseCircuit);
+    if (injectedCircuits.length === 0)
+        return null;
+    const configured = config.default_circuit;
+    if (configured) {
+        // Check the circuit exists in the config's circuits array.
+        const inConfig = config.circuits.some((c) => c.circuit_uid === configured);
+        if (!inConfig) {
+            console.error(`⚠ default_circuit '${configured}' not found in circuits — using ${injectedCircuits[0].circuit_name} as default`);
+        }
+        else {
+            const entry = state.circuits[configured];
+            if (entry && isInjectableSseCircuit(entry)) {
+                return `circuit-${configured}/${configured}`;
+            }
+            console.error(`⚠ default_circuit '${configured}' is not SSE-compatible — using ${injectedCircuits[0].circuit_name} as default`);
+        }
+    }
+    // Fallback: first injectable SSE circuit.
+    const first = injectedCircuits[0];
+    return `circuit-${first.circuit_uid}/${first.circuit_uid}`;
+}
+/** Build the OpenCode config from project state. */
+export function buildOpenCodeConfig(state, port, defaultModel) {
+    const proxyBase = `http://localhost:${port}`;
+    const config = {
+        $schema: "https://opencode.ai/config.json",
+        mcp: {
+            servers: {
+                "ModelWorks x.MCP": {
+                    type: "remote",
+                    url: `${proxyBase}/api/x.mcp`,
+                    oauth: false,
+                    // x.mcp requires MCP 2.0 (server/discover) and rejects the
+                    // legacy initialize handshake. "auto" probes then falls back
+                    // to legacy, which gets rejected — so force 2026-07-28.
+                    protocol: "2026-07-28",
+                    // Dummy auth header — the proxy overrides it with the real
+                    // Bearer token. Without this, OpenCode sees no auth config and
+                    // prompts the user to authenticate ("MCP Authentication Required").
+                    headers: {
+                        Authorization: "Bearer quack",
+                    },
+                },
+            },
+        },
+        providers: {},
+    };
+    if (defaultModel) {
+        config.model = defaultModel;
+    }
+    for (const entry of Object.values(state.circuits)) {
+        if (!isInjectableSseCircuit(entry))
+            continue;
+        const providerKey = `circuit-${entry.circuit_uid}`;
+        const provider = {
+            name: "ModelWorks",
+            package: OPENAI_COMPATIBLE_PACKAGE,
+            settings: {
+                baseURL: `${proxyBase}/api/circuit-adaptors/${entry.sse_adaptor_uid}/query`,
+                // Dummy apiKey — the proxy overrides the Authorization header with the real token.
+                apiKey: "quack",
+            },
+            models: {
+                [entry.circuit_uid]: { name: `${entry.owner_username}/${entry.circuit_name}` },
+            },
+        };
+        config.providers[providerKey] = provider;
+    }
+    return config;
+}
+export function summarizeInjection(state) {
+    const injected = [];
+    const skipped = [];
+    for (const entry of Object.values(state.circuits)) {
+        if (isInjectableSseCircuit(entry)) {
+            injected.push({
+                circuit_uid: entry.circuit_uid,
+                name: entry.circuit_name,
+                sse_adaptor_uid: entry.sse_adaptor_uid,
+            });
+        }
+        else if (!entry.adapters.includes("OPEN_AI_SSE")) {
+            skipped.push({
+                circuit_uid: entry.circuit_uid,
+                name: entry.circuit_name,
+                reason: "not SSE-compatible",
+            });
+        }
+        else if (entry.sse_adaptor_uid === null) {
+            skipped.push({
+                circuit_uid: entry.circuit_uid,
+                name: entry.circuit_name,
+                reason: "no SSE adaptor",
+            });
+        }
+    }
+    return { injected, skipped };
+}
+/** Print install hints when the `opencode` binary is missing. */
+function printInstallHint() {
+    console.error("\n✗ opencode is not installed.\n");
+    console.error("Install with one of:");
+    for (const method of OPENCODE_INSTALL) {
+        const detected = method.check() ? " (detected)" : "";
+        console.error(`  ${method.label.padEnd(5)} ${method.cmd}${detected}`);
+    }
+    console.error("");
+}
+/** Load credentials for the history callback. Returns null if not logged in. */
+function loadCredentialsForHistory() {
+    return loadCredentials();
+}
+/** Resolve the caller's username from the API (for run history records). */
+async function resolveCallerUsername(creds) {
+    try {
+        const res = await fetch(`${creds.api_base}/api/users/token`, {
+            headers: { Authorization: `Bearer ${creds.access_token}` },
+        });
+        if (res.ok) {
+            const body = (await res.json());
+            return body.payload?.username ?? creds.user_uid;
+        }
+    }
+    catch {
+        // Fall back to user_uid.
+    }
+    return creds.user_uid;
+}
+/** The OpenCode agent plugin. */
+export const opencodeAgent = {
+    name: "opencode",
+    description: "Launch OpenCode with SSE circuits as model providers",
+    binary: "opencode",
+    installHints: OPENCODE_INSTALL.map((m) => `${m.label}: ${m.cmd}`),
+    buildConfig(ctx) {
+        const defaultModel = resolveDefaultModel(ctx.config, ctx.state);
+        const config = buildOpenCodeConfig(ctx.state, ctx.proxyPort, defaultModel);
+        return {
+            OPENCODE_CONFIG: JSON.stringify(config, null, 2),
+        };
+    },
+    async launch(ctx, opts) {
+        // Resolve the opencode binary (prefer V2 for MCP 2.0 support).
+        const resolved = resolveOpencodeBinary();
+        if (opts.debug) {
+            console.error(`[quack] resolved opencode binary: ${resolved ? resolved.bin + " (V" + (resolved.isV2 ? "2" : "1") + ")" : "null"}`);
+        }
+        if (!opts.print && !resolved) {
+            printInstallHint();
+            return { exitCode: 1, proxyPort: 0 };
+        }
+        // Open debug log file if --debug is set.
+        let debugFd;
+        let debugPath;
+        const writeDebug = (entry) => {
+            if (debugFd !== undefined) {
+                fs.writeSync(debugFd, entry + "\n");
+            }
+        };
+        if (opts.debug && !opts.print) {
+            debugPath = path.join(process.cwd(), ".quack", "debug.log");
+            // Truncate the file at start.
+            try {
+                fs.writeFileSync(debugPath, "");
+                debugFd = fs.openSync(debugPath, "a");
+            }
+            catch {
+                // If .quack/ doesn't exist, fall back to /tmp.
+                debugPath = `/tmp/quack-debug-${Date.now()}.log`;
+                fs.writeFileSync(debugPath, "");
+                debugFd = fs.openSync(debugPath, "a");
+            }
+            process.stderr.write(`[quack] debug log: ${debugPath}\n`);
+        }
+        // Start the proxy.
+        const proxy = await startProxy({
+            apiBase: ctx.apiBase,
+            getAccessToken: ctx.getAccessToken,
+            refreshToken,
+            onLog: (opts.verbose || opts.debug)
+                ? (method, path, status) => {
+                    process.stderr.write(`[quack] ${method} ${path} → ${status}\n`);
+                }
+                : undefined,
+            onDebug: opts.debug
+                ? (entry) => writeDebug(entry)
+                : undefined,
+            // Fire-and-forget: fetch and save run records after each stream completes.
+            onRunComplete: opts.print
+                ? undefined
+                : (runUid) => {
+                    // Don't block the proxy — fire and forget.
+                    void (async () => {
+                        try {
+                            const creds = loadCredentialsForHistory();
+                            if (!creds)
+                                return;
+                            const currentState = readState();
+                            const callerUsername = await resolveCallerUsername(creds);
+                            const record = await fetchRunFromApi(runUid, creds, currentState.circuits, callerUsername);
+                            if (record)
+                                saveRunRecord(record);
+                        }
+                        catch {
+                            // Silent — don't crash the proxy on history save failures.
+                        }
+                    })();
+                },
+        });
+        if (opts.verbose || opts.debug) {
+            process.stderr.write(`[quack] proxy listening on http://localhost:${proxy.port} → ${ctx.apiBase}\n`);
+        }
+        // Build the config.
+        const state = readState();
+        const config = readConfig();
+        const defaultModel = resolveDefaultModel(config, state);
+        const openCodeConfig = buildOpenCodeConfig(state, proxy.port, defaultModel);
+        const configJson = JSON.stringify(openCodeConfig, null, 2);
+        const summary = summarizeInjection(state);
+        if (opts.print) {
+            console.log(`Proxy: http://localhost:${proxy.port} → ${ctx.apiBase}`);
+            console.log("");
+            console.log("Injected OpenCode config (OPENCODE_CONFIG):");
+            console.log(configJson);
+            console.log("");
+            console.log(`Injected ${summary.injected.length} circuit(s) as OpenAI-compatible providers:`);
+            for (const c of summary.injected) {
+                console.log(`  ✓ ${c.name} (${c.circuit_uid}) → ${c.sse_adaptor_uid}`);
+            }
+            if (summary.skipped.length > 0) {
+                console.log(`Skipped ${summary.skipped.length} circuit(s):`);
+                for (const c of summary.skipped) {
+                    console.log(`  ✗ ${c.name} (${c.circuit_uid}) — ${c.reason}`);
+                }
+            }
+            proxy.close();
+            return { exitCode: null, proxyPort: proxy.port };
+        }
+        // Write the config to a temp file and point OPENCODE_CONFIG at it.
+        // V1's OPENCODE_CONFIG_CONTENT (inline JSON) works for simple top-level
+        // overrides like `model`, but doesn't reliably deep-merge `mcp.servers`.
+        // OPENCODE_CONFIG (file path, "custom-path" scope) is what the user's
+        // own wrapper uses for full configs with MCP servers.
+        //
+        // The filename includes the quack version + timestamp to avoid any
+        // config caching by file path.
+        const configFile = path.join(os.tmpdir(), `quack-opencode-config-v${AGENT_VERSION}-${Date.now()}-${proxy.port}.json`);
+        fs.writeFileSync(configFile, configJson);
+        // Write startup info to the debug log.
+        // Spawn opencode with the config file path injected via env.
+        // V2 uses a background service — pass --standalone so it runs a private
+        // server that picks up OPENCODE_CONFIG fresh every launch.
+        const spawnArgs = resolved?.isV2
+            ? ["--standalone", "--log-level", "debug", ...opts.args]
+            : ["--log-level", "debug", ...opts.args];
+        if (opts.debug) {
+            writeDebug(`=== quack startup ${new Date().toISOString()} ===`);
+            writeDebug(`quack version: ${AGENT_BUILD}`);
+            writeDebug(`quack PID: ${process.pid}`);
+            writeDebug(`opencode binary: ${resolved.bin} (V${resolved?.isV2 ? "2" : "1"})`);
+            writeDebug(`spawn args: ${JSON.stringify(spawnArgs)}`);
+            writeDebug(`config file: ${configFile}`);
+            writeDebug(`config:\n${configJson}`);
+            writeDebug("");
+        }
+        if (opts.debug || opts.verbose) {
+            console.error(`[quack] spawning opencode: ${resolved.bin} ${spawnArgs.join(" ")}`);
+            console.error(`[quack] OPENCODE_CONFIG: ${configFile}`);
+            console.error(`[quack] quack PID: ${process.pid}`);
+        }
+        const child = spawn(resolved.bin, spawnArgs, {
+            stdio: "inherit",
+            env: {
+                ...process.env,
+                OPENCODE_CONFIG: configFile,
+                // Clear any inherited OPENCODE_CONFIG_CONTENT from the user's shell
+                // (e.g. from oc.sh wrapper) — it would override our model setting.
+                OPENCODE_CONFIG_CONTENT: "",
+                QUACK_API_KEY: "quack",
+            },
+        });
+        // Log the opencode PID once it spawns.
+        if (opts.debug || opts.verbose) {
+            child.on("spawn", () => {
+                console.error(`[quack] opencode PID: ${child.pid}`);
+            });
+        }
+        // Forward signals to opencode.
+        const forwardSignal = (sig) => {
+            if (!child.killed)
+                child.kill(sig);
+        };
+        process.on("SIGINT", () => forwardSignal("SIGINT"));
+        process.on("SIGTERM", () => forwardSignal("SIGTERM"));
+        // Wait for opencode to exit, then close the proxy.
+        const exitCode = await new Promise((resolve) => {
+            child.on("exit", (code) => {
+                resolve(code ?? 0);
+            });
+            child.on("error", (err) => {
+                if (err.code === "ENOENT") {
+                    printInstallHint();
+                }
+                else {
+                    console.error(`opencode failed to start: ${err.message}`);
+                }
+                resolve(1);
+            });
+        });
+        // Clean up the temp config file.
+        try {
+            fs.unlinkSync(configFile);
+        }
+        catch {
+            // Ignore cleanup errors.
+        }
+        proxy.close();
+        // Close debug log file if open.
+        if (debugFd !== undefined) {
+            try {
+                fs.closeSync(debugFd);
+            }
+            catch {
+                // Ignore.
+            }
+        }
+        return { exitCode, proxyPort: proxy.port };
+    },
+};

package/dist/agents/registry.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Agent registry — lists all built-in agents and resolves which one
+ * to launch when the user runs bare `quack` (no args).
+ *
+ * Adding a new agent: create `src/agents/<name>.ts` exporting an
+ * `Agent`, then add it to the `BUILTIN_AGENTS` array below. It will
+ * automatically appear in `quack agents list` and become available
+ * as `quack <name>`.
+ *
+ * @module
+ */
+import type { Agent } from "./types.js";
+/** All agents built into this version of quack. */
+export declare const BUILTIN_AGENTS: Agent[];
+/** Detect whether a binary is on PATH. */
+export declare function hasBinary(bin: string): boolean;
+/** Check if a file exists and is executable at a specific path. */
+export declare function hasBinaryAt(binPath: string): boolean;
+/** Is this agent's binary installed (on PATH or at a known location)? */
+export declare function isAgentAvailable(agent: Agent): boolean;
+/** List all built-in agents. */
+export declare function listAgents(): Agent[];
+/** Look up an agent by name. Returns `undefined` if not found. */
+export declare function getAgent(name: string): Agent | undefined;
+/** List agents whose binary is installed on PATH. */
+export declare function listAvailableAgents(): Agent[];
+/** Whether stdin is an interactive TTY (for the picker prompt). */
+export declare function isInteractive(): boolean;
+/**
+ * Result of resolving which agent to launch for bare `quack`.
+ *
+ * - `agent` — the resolved agent (binary is installed).
+ * - `error` — resolution failed; `message` explains what to do.
+ */
+export type ResolveResult = {
+    ok: true;
+    agent: Agent;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Resolve which agent to launch for bare `quack`.
+ *
+ * Resolution order:
+ *  1. `default_agent` from config.json — validate + availability check
+ *  2. `last_agent` from state.json — validate + availability check
+ *  3. Interactive picker (if TTY) — shows installed agents to pick from
+ *  4. Non-interactive — error with guidance
+ *
+ * `available`/`last` are caller-provided to keep this function pure
+ * (no file I/O). The caller reads config/state and passes the values.
+ */
+export declare function resolveAgent(defaultAgent: string | undefined, lastAgent: string | undefined): ResolveResult;

package/dist/agents/registry.js

@@ -0,0 +1,134 @@
+/**
+ * Agent registry — lists all built-in agents and resolves which one
+ * to launch when the user runs bare `quack` (no args).
+ *
+ * Adding a new agent: create `src/agents/<name>.ts` exporting an
+ * `Agent`, then add it to the `BUILTIN_AGENTS` array below. It will
+ * automatically appear in `quack agents list` and become available
+ * as `quack <name>`.
+ *
+ * @module
+ */
+import { spawnSync } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { opencodeAgent } from "./opencode.js";
+/** All agents built into this version of quack. */
+export const BUILTIN_AGENTS = [
+    opencodeAgent,
+];
+/** Detect whether a binary is on PATH. */
+export function hasBinary(bin) {
+    try {
+        const cmd = process.platform === "win32" ? "where" : "which";
+        const result = spawnSync(cmd, [bin], { stdio: "ignore" });
+        return result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Check if a file exists and is executable at a specific path. */
+export function hasBinaryAt(binPath) {
+    try {
+        accessSync(binPath, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Is this agent's binary installed (on PATH or at a known location)? */
+export function isAgentAvailable(agent) {
+    // opencode: check both V2 (opencode2) and V1 (opencode)
+    if (agent.name === "opencode") {
+        if (hasBinary("opencode2"))
+            return true;
+        const home = process.env.HOME ?? "";
+        if (home && hasBinaryAt(`${home}/.opencode/bin/opencode2`))
+            return true;
+        if (hasBinary("opencode"))
+            return true;
+        return false;
+    }
+    return hasBinary(agent.binary);
+}
+/** List all built-in agents. */
+export function listAgents() {
+    return BUILTIN_AGENTS;
+}
+/** Look up an agent by name. Returns `undefined` if not found. */
+export function getAgent(name) {
+    return BUILTIN_AGENTS.find((a) => a.name === name);
+}
+/** List agents whose binary is installed on PATH. */
+export function listAvailableAgents() {
+    return BUILTIN_AGENTS.filter(isAgentAvailable);
+}
+/** Whether stdin is an interactive TTY (for the picker prompt). */
+export function isInteractive() {
+    return process.stdin.isTTY === true;
+}
+/**
+ * Resolve which agent to launch for bare `quack`.
+ *
+ * Resolution order:
+ *  1. `default_agent` from config.json — validate + availability check
+ *  2. `last_agent` from state.json — validate + availability check
+ *  3. Interactive picker (if TTY) — shows installed agents to pick from
+ *  4. Non-interactive — error with guidance
+ *
+ * `available`/`last` are caller-provided to keep this function pure
+ * (no file I/O). The caller reads config/state and passes the values.
+ */
+export function resolveAgent(defaultAgent, lastAgent) {
+    // 1. config.json default_agent
+    if (defaultAgent) {
+        const agent = getAgent(defaultAgent);
+        if (!agent) {
+            return {
+                ok: false,
+                message: `Default agent "${defaultAgent}" is not a known agent. Supported: ${BUILTIN_AGENTS.map((a) => a.name).join(", ")}. Fix .quack/config.json.`,
+            };
+        }
+        if (!isAgentAvailable(agent)) {
+            return {
+                ok: false,
+                message: `Default agent "${defaultAgent}" is not installed. Install it, or change "default_agent" in .quack/config.json to an installed agent.\n\nSupported agents: ${BUILTIN_AGENTS.map((a) => `  ${a.name} (${a.binary})`).join("\n")}`,
+            };
+        }
+        return { ok: true, agent };
+    }
+    // 2. state.json last_agent
+    if (lastAgent) {
+        const agent = getAgent(lastAgent);
+        if (agent && isAgentAvailable(agent)) {
+            return { ok: true, agent };
+        }
+        // Fall through to picker if last_agent is gone/uninstalled.
+    }
+    // 3. Interactive picker — only if TTY
+    const available = listAvailableAgents();
+    if (available.length === 0) {
+        return {
+            ok: false,
+            message: `No supported agent is installed. Install one of:\n${BUILTIN_AGENTS.map((a) => `  ${a.name} (${a.binary})`).join("\n")}`,
+        };
+    }
+    if (!isInteractive()) {
+        // Non-interactive: if exactly one agent is available, use it.
+        if (available.length === 1) {
+            return { ok: true, agent: available[0] };
+        }
+        return {
+            ok: false,
+            message: `No default agent set and multiple are installed. Set "default_agent" in .quack/config.json to one of: ${available.map((a) => a.name).join(", ")}.`,
+        };
+    }
+    // Interactive with one available agent — just use it (no pointless prompt).
+    if (available.length === 1) {
+        return { ok: true, agent: available[0] };
+    }
+    // Interactive with multiple — will be handled by the caller's prompt.
+    // Signal that a prompt is needed.
+    return { ok: false, message: "__PROMPT__" };
+}

package/dist/agents/types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Agent plugin interface.
+ *
+ * An agent is a tool that quack can launch with ModelWorks circuits
+ * wired in (e.g. OpenCode, Cursor, Claude Code). Agents are built into
+ * quack — no external installation. New agents appear automatically
+ * when quack is updated.
+ *
+ * @module
+ */
+import type { QuackConfig, QuackState } from "../types.js";
+/** Options passed to {@link Agent.buildConfig} and {@link Agent.launch}. */
+export interface AgentContext {
+    /** The local proxy port (requests to the proxy get auth injected). */
+    proxyPort: number;
+    /** Upstream API base URL, e.g. `https://modelworks.ai`. */
+    apiBase: string;
+    /** Returns the current (possibly-refreshed) access token. */
+    getAccessToken: () => string;
+    /** The project's cached state (circuits, adaptors, versions). */
+    state: QuackState;
+    /** The project's committable config (default_agent, default_circuit, circuits). */
+    config: QuackConfig;
+}
+/** Options for {@link Agent.launch}. */
+export interface LaunchOptions {
+    /** Args to forward to the agent binary. */
+    args: string[];
+    /** If true, log proxy requests to stderr. */
+    verbose: boolean;
+    /** If true, log full proxy request/response details to .quack/debug.log. */
+    debug: boolean;
+    /** If true, print the config and exit without launching. */
+    print: boolean;
+}
+/** Result of a launch. `exitCode` is null if `--print` was used. */
+export interface LaunchResult {
+    exitCode: number | null;
+    proxyPort: number;
+}
+/** A built-in agent plugin. */
+export interface Agent {
+    /** Short name used as the `quack <name>` command (e.g. `"opencode"`). */
+    name: string;
+    /** One-line description shown in `quack agents list`. */
+    description: string;
+    /** The binary name to look for on PATH (e.g. `"opencode"`). */
+    binary: string;
+    /** Install hint lines shown when the binary is missing. */
+    installHints: string[];
+    /**
+     * Build the tool-specific config/env from the project state.
+     * Returns env vars to inject when spawning the agent.
+     */
+    buildConfig(ctx: AgentContext): Record<string, string>;
+    /**
+     * Start the proxy (already started by the caller), build the config,
+     * and spawn the agent. On `--print`, print the config and return
+     * without spawning.
+     */
+    launch(ctx: AgentContext, opts: LaunchOptions): Promise<LaunchResult>;
+}

package/dist/agents/types.js

@@ -0,0 +1,11 @@
+/**
+ * Agent plugin interface.
+ *
+ * An agent is a tool that quack can launch with ModelWorks circuits
+ * wired in (e.g. OpenCode, Cursor, Claude Code). Agents are built into
+ * quack — no external installation. New agents appear automatically
+ * when quack is updated.
+ *
+ * @module
+ */
+export {};