@b3labs/b3iq-cli 0.0.0-stage → 0.1.0

package/dist/commands/native-agents.js

@@ -0,0 +1,291 @@
+import { spawn } from "node:child_process";
+import { mkdir, writeFile, readdir, lstat, readFile, symlink, readlink, unlink, realpath } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { configDir } from "../lib/config.js";
+import { explainModelNotServed, requireContext } from "../lib/diagnosis.js";
+import { probeManagement } from "../lib/management-probe.js";
+import { CliError, isJSON, isQuiet, log, success } from "../lib/output.js";
+import { DESKTOP_SERVER_LIFECYCLE_INSTRUCTIONS } from "../lib/desktop-server-lifecycle.js";
+import { InferenceGateway, gatewayKey, savedGatewayKey, nativeInputModalities } from "../lib/inference.js";
+import { openCodeConfig } from "./opencode.js";
+import { claudeGatewayBase, claudeDesktopConnection, claudeDesktopReference } from "./claude-desktop.js";
+const claudeCredentialOverrides = ["ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_API_KEY", "CLAUDE_CODE_USE_BEDROCK", "CLAUDE_CODE_USE_VERTEX", "CLAUDE_CODE_USE_FOUNDRY"];
+export function nativeSetupResult(client, prepared) {
+    const activation = client === "codex" ? prepared.codexDesktop ? ["open", prepared.codexDesktop.installed_launcher ?? prepared.codexDesktop.launcher] : prepared.profile ? ["codex", "--profile", prepared.profile] : undefined
+        : client === "claude" && !prepared.desktop ? ["env", ...claudeCredentialOverrides.flatMap(key => ["-u", key]), "claude", ...prepared.args]
+            : undefined;
+    const scope = client === "codex" ? prepared.desktop ? "isolated_desktop_instance" : "opt_in_profile"
+        : client === "claude" && prepared.desktop ? prepared.claudeDesktop?.activated ? "activated_desktop_configuration" : prepared.claudeDesktop?.saved ? "saved_inactive_configuration" : "desktop_connection_export"
+            : client === "opencode" && prepared.desktop ? "provider_registration" : "selected_session";
+    return { client, launch_surface: prepared.desktop ? "desktop" : "terminal",
+        desktop_configuration_changed: client === "codex" ? Boolean(prepared.codexDesktop) : client === "claude" ? Boolean(prepared.claudeDesktop?.saved?.changed || prepared.claudeDesktop?.activated) : client === "opencode" && Boolean(prepared.installedConfig),
+        defaults_changed: Boolean(prepared.claudeDesktop?.activated),
+        configuration_scope: scope,
+        directory: prepared.dir, config: prepared.config,
+        ...(prepared.setupName ? { setup_name: prepared.setupName } : {}),
+        ...(activation ? { activation_argv: activation,
+            activation_command: activation.map(arg => /^[a-zA-Z0-9_./:@=-]+$/.test(arg) ? arg : `'${arg.replace(/'/g, `'"'"'`)}'`).join(" ") } : {}),
+        ...(prepared.profile ? { profile: prepared.profile } : {}),
+        ...(prepared.selection ? { model_selection: prepared.selection } : {}),
+        instructions: client === "codex" && prepared.desktop ? "Open the launcher for a separate B3IQ desktop instance. Normal desktop and CLI defaults remain unchanged while it runs. Its settings and history are separate; select your local project in this instance. This integration is experimental. No OpenAI account credentials are copied."
+            : client === "codex" ? "Use activation_argv to select B3IQ. Plain codex and the desktop retain their normal defaults. Do not merge this profile into config.toml."
+                : client === "claude" && prepared.desktop ? "Use desktop_setup for exact configuration and activation status. Setup preserves defaults unless --activate was explicitly supplied. Restore the original selection with b3iq inference restore claude --desktop, with Claude closed."
+                    : client === "claude" ? "Use activation_argv for a B3IQ terminal session (POSIX). Plain claude and desktop retain their normal defaults. Do not merge this file into settings.json or change shell exports."
+                        : "Select B3IQ and its exact model ID in the native picker. Registration preserves existing defaults; do not merge selected-session model or agent overrides into global settings.",
+        ...(prepared.codexDesktop ? { desktop_setup: prepared.codexDesktop } : {}),
+        ...(prepared.claudeDesktop ? { desktop_setup: claudeDesktopReference(prepared.claudeDesktop) } : {}),
+        ...(prepared.modelCatalog ? { model_catalog: prepared.modelCatalog } : {}),
+        ...(prepared.mediaConfig ? { media_mcp_config: prepared.mediaConfig } : {}),
+        ...(prepared.skillsPlugin ? { shared_skills_plugin: prepared.skillsPlugin } : {}),
+        ...(prepared.openCodeVersion ? { client_major_version: prepared.openCodeVersion } : {}),
+        ...(prepared.installedConfig ? { installed_config: prepared.installedConfig } : {}),
+        ...(prepared.backup ? { backup: prepared.backup } : {}),
+    };
+}
+export function printNativeSetupResult(client, prepared, activated = false) {
+    const receipt = nativeSetupResult(client, prepared);
+    if (client === "codex" && prepared.codexDesktop && !isJSON() && !isQuiet()) {
+        success(activated ? "B3IQ Codex desktop launch requested." : "B3IQ Codex desktop setup saved. The app has not been opened.");
+        log("Normal Codex desktop and CLI defaults are unchanged.");
+        process.stderr.write(`\n${activated ? "Open it again later" : "Open it now"}:\n  ${receipt.activation_command}\n\n`);
+        if (!activated)
+            log("To save and open in one step, rerun your setup command with --activate.");
+        log("Select your local project in the separate B3IQ window. This integration is experimental.");
+        return;
+    }
+    process.stdout.write(JSON.stringify(receipt) + "\n");
+}
+export async function installCodexProfile(prepared, directory = process.env.CODEX_HOME ?? join(homedir(), ".codex")) {
+    const content = await readFile(prepared.config, "utf8");
+    const profile = `b3iq-${createHash("sha256").update(content).digest("hex").slice(0, 16)}`;
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const path = join(directory, `${profile}.config.toml`);
+    try {
+        await writeFile(path, content, { flag: "wx", mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        const info = await lstat(path);
+        if (!info.isFile() || info.isSymbolicLink() || await readFile(path, "utf8") !== content) {
+            throw new CliError("The B3IQ Codex profile already contains different settings. Inspect that profile before retrying; the normal Codex configuration was not changed.", "usage");
+        }
+    }
+    prepared.profile = profile;
+    prepared.installedConfig = path;
+    prepared.args = ["--profile", profile];
+}
+export function codexCatalog(model, context, desktop = false) {
+    return { models: [{
+                slug: model.id, display_name: desktop ? `B3IQ · ${model.id}` : model.id, description: "Owned B3IQ inference",
+                base_instructions: `Runtime model identity: the selected served model ID is ${JSON.stringify(model.id)}. Your client application is Codex and your inference provider is B3IQ. If asked which model you are using, report that exact configured model ID and provider, separately from the client application. Do not infer model identity from learned persona claims, tool names or old conversation text. This metadata does not establish training provenance or capabilities beyond the serving profile.\n\n` +
+                    "You are a coding agent working with the user in their local project. Complete authorized coding tasks using the available client tools. Read and follow applicable AGENTS.md and project instructions before editing. When a task uses a skill, read its SKILL.md and any required references before acting. Keep changes within the authorized project or disposable worktree, preserve unrelated work, and verify changed behavior with appropriate checks. Keep the human's Git authorship. Report actual outcomes and remaining limitations; do not claim a tool ran or a test passed without its result. Ask only for missing information or actions that need additional authorization." +
+                    (desktop ? `\n\n${DESKTOP_SERVER_LIFECYCLE_INSTRUCTIONS}` : ""),
+                supported_reasoning_levels: [], shell_type: "unified_exec", visibility: "list", supported_in_api: true,
+                priority: 1, availability_nux: null, upgrade: null, support_verbosity: false, default_verbosity: null,
+                apply_patch_tool_type: "freeform", truncation_policy: { mode: "tokens", limit: Math.min(10000, Math.floor(context / 4)) },
+                context_window: context, max_context_window: context, effective_context_window_percent: 90,
+                input_modalities: nativeInputModalities(model), experimental_supported_tools: [], tool_mode: "direct",
+                supports_parallel_tool_calls: true, supports_search_tool: true, prefer_websockets: false, use_responses_lite: false,
+                include_skills_usage_instructions: true, include_plugin_usage_instructions: true, include_apps_usage_instructions: false,
+                supports_reasoning_summary_parameter: false, default_reasoning_summary: "none", node_repl_disabled: true,
+            }] };
+}
+export async function requireNativeContext(model, client, machine, desktop) {
+    try {
+        return requireContext(model, { client, machine, desktop });
+    }
+    catch (error) {
+        if (!(error instanceof CliError))
+            throw error;
+        const diagnostic = error.diagnosis?.diagnostic;
+        if (diagnostic !== "context_window_insufficient" && diagnostic !== "context_metadata_missing")
+            throw error;
+        return requireContext(model, { client, machine, desktop, management: await probeManagement(machine) });
+    }
+}
+function mcpConfig(options, entrypoint) {
+    return { command: process.execPath, args: [entrypoint, "mcp", "media", "--gateway-url", new InferenceGateway(options).base.toString(),
+            ...(options.machine ? ["--machine", options.machine] : []), ...(options.outputDir ? ["--output-dir", options.outputDir] : [])] };
+}
+function claudeEnvironment(model, gateway, context, machine) {
+    const base = claudeGatewayBase(gateway.base);
+    const aliases = Object.fromEntries(["OPUS", "FABLE", "SONNET", "HAIKU"].flatMap(family => [
+        [`ANTHROPIC_DEFAULT_${family}_MODEL_NAME`, `B3IQ · ${model}`],
+        [`ANTHROPIC_DEFAULT_${family}_MODEL_DESCRIPTION`, "Uses the same selected owned B3IQ model."],
+    ]));
+    return {
+        ...aliases,
+        ANTHROPIC_BASE_URL: base, ANTHROPIC_MODEL: model,
+        ANTHROPIC_DEFAULT_OPUS_MODEL: model, ANTHROPIC_DEFAULT_SONNET_MODEL: model, ANTHROPIC_DEFAULT_HAIKU_MODEL: model,
+        ANTHROPIC_DEFAULT_FABLE_MODEL: model, ANTHROPIC_SMALL_FAST_MODEL: model,
+        CLAUDE_CODE_SUBAGENT_MODEL: model, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1",
+        CLAUDE_CODE_MAX_OUTPUT_TOKENS: "8192", CLAUDE_CODE_AUTO_COMPACT_WINDOW: String(context),
+        ...(context < 1000000 ? { CLAUDE_CODE_DISABLE_1M_CONTEXT: "1" } : {}),
+        ...(machine ? { ANTHROPIC_CUSTOM_HEADERS: `x-b3iq-node-id: ${machine}` } : {}),
+    };
+}
+export async function nativeEntrypoint(own, invoked = process.argv[1]) {
+    if (invoked) {
+        const path = resolve(invoked);
+        const [actual, expected] = await Promise.all([realpath(path).catch(() => ""), realpath(own).catch(() => "")]);
+        if (actual && actual === expected)
+            return path;
+    }
+    return own;
+}
+export async function prepareNativeAgent(client, modelID, options, root, openCode = {}) {
+    if (openCode.setupName !== undefined && (client !== "codex" || !openCode.desktop || !/^[a-z0-9][a-z0-9_-]{0,63}$/.test(openCode.setupName)))
+        throw new CliError("--setup-name requires Codex desktop setup and 1–64 lowercase letters, digits, underscores or hyphens, starting with a letter or digit.", "usage");
+    if ((client === "claude" || client === "codex") && openCode.desktop && !options.key)
+        options = { ...options, key: await savedGatewayKey() };
+    const gateway = new InferenceGateway(options), models = await gateway.models();
+    const model = models.find(row => row.id === modelID);
+    if (!model)
+        throw explainModelNotServed(modelID, models.length, options.machine);
+    const context = await requireNativeContext(model, client, options.machine, Boolean(openCode.desktop));
+    const fingerprint = createHash("sha256").update(JSON.stringify([client, model.id, gateway.base.href, options.machine,
+        ...(client === "opencode" ? [openCode.version ?? 2, Boolean(openCode.desktop)] : client === "codex" && openCode.desktop ? ["isolated-desktop-v1", ...(openCode.setupName ? ["setup-name", openCode.setupName] : [])] : [])])).digest("hex").slice(0, 16);
+    const dir = root ?? join(configDir(), "native-agents", fingerprint);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    const extension = import.meta.url.endsWith(".ts") ? "ts" : "js";
+    const entrypoint = await nativeEntrypoint(fileURLToPath(new URL(`../index.${extension}`, import.meta.url)));
+    const media = mcpConfig(options, entrypoint);
+    if (client === "opencode") {
+        const value = openCodeConfig(model, context, gateway.base.toString(), media, options.machine, openCode);
+        const content = JSON.stringify(value, null, 2), config = join(dir, "opencode.json");
+        await writeFile(config, content + "\n", { mode: 0o600 });
+        return { dir, config, selection: `b3iq/${model.id}`, openCodeVersion: openCode.version ?? 2, desktop: Boolean(openCode.desktop), args: [],
+            env: { B3IQ_GATEWAY_API_KEY: options.key ?? await gatewayKey(), OPENCODE_CONFIG_CONTENT: content } };
+    }
+    if (client === "codex") {
+        const catalog = join(dir, "models.json");
+        await writeFile(catalog, JSON.stringify(codexCatalog(model, context, Boolean(openCode.desktop)), null, 2) + "\n", { mode: 0o600 });
+        const bindings = {
+            model: model.id, model_provider: "b3iq", model_catalog_json: catalog, web_search: "disabled",
+            model_context_window: context, model_auto_compact_token_limit: Math.floor(context * 0.8),
+            "model_providers.b3iq.name": "B3IQ", "model_providers.b3iq.base_url": gateway.base.toString(),
+            "model_providers.b3iq.wire_api": "responses",
+            "model_providers.b3iq.auth.command": process.execPath,
+            "model_providers.b3iq.auth.args": [entrypoint, "inference", "credential", ...(openCode.desktop ? ["--saved"] : [])],
+            "model_providers.b3iq.auth.timeout_ms": 5000, "model_providers.b3iq.auth.refresh_interval_ms": 300000,
+            "model_providers.b3iq.supports_websockets": false,
+            ...(openCode.desktop ? { "model_providers.b3iq.requires_openai_auth": false, approval_policy: "on-request", sandbox_mode: "workspace-write" } : {}),
+            "model_providers.b3iq.request_max_retries": 1, "model_providers.b3iq.stream_max_retries": 1,
+            "features.unbounded_connection_retries": false,
+            ...(options.machine ? { "model_providers.b3iq.http_headers": { "x-b3iq-node-id": options.machine } } : {}),
+            "mcp_servers.b3iq_media.command": media.command, "mcp_servers.b3iq_media.args": [...media.args, ...(openCode.desktop ? ["--saved-key"] : [])],
+            ...(!openCode.desktop ? { "mcp_servers.b3iq_media.env_vars": ["B3IQ_GATEWAY_API_KEY"] } : {}),
+        };
+        const config = join(dir, "codex.toml");
+        await writeFile(config, Object.entries(bindings).map(([key, value]) => `${key} = ${toml(value)}`).join("\n") + "\n", { mode: 0o600 });
+        return { dir, config, modelCatalog: catalog, desktop: Boolean(openCode.desktop), ...(openCode.setupName ? { setupName: openCode.setupName } : {}), args: Object.entries(bindings).flatMap(([key, value]) => ["-c", `${key}=${toml(value)}`]), env: { B3IQ_GATEWAY_API_KEY: options.key ?? await gatewayKey() } };
+    }
+    const connection = claudeDesktopConnection(gateway.base, process.execPath, entrypoint, options.machine, model.id);
+    if (openCode.desktop) {
+        const desktopGateway = new InferenceGateway({ ...options, gateway: connection.inferenceGatewayBaseUrl + "/v1" });
+        const discovery = await desktopGateway.json("/models");
+        const rows = discovery.data;
+        if (!Array.isArray(rows) || !rows.some(row => row.id === connection.inferenceModels?.[0].name && row.b3iq?.served_model === model.id && row.b3iq.compatibility === "claude-desktop-v1")) {
+            throw new CliError("The gateway has not qualified this desktop compatibility connection. Deploy the matching gateway and verify the selected model and machine before saving or activation.", "api");
+        }
+    }
+    const desktopFile = join(dir, "claude-desktop-connection.json");
+    await writeFile(desktopFile, JSON.stringify(connection, null, 2) + "\n", { mode: 0o600 });
+    const claudeDesktop = { config_file: desktopFile, connection, selected_model: model.id };
+    if (openCode.desktop)
+        return { dir, config: desktopFile, desktop: true, claudeDesktop, args: [], env: {} };
+    const env = claudeEnvironment(model.id, gateway, context, options.machine);
+    const settings = join(dir, "claude-settings.json"), mcp = join(dir, "mcp.json");
+    const shellQuote = (value) => `'${value.replace(/'/g, `'"'"'`)}'`;
+    await writeFile(settings, JSON.stringify({ model: model.id, availableModels: [model.id], enforceAvailableModels: true,
+        alwaysThinkingEnabled: false, env, apiKeyHelper: `${shellQuote(process.execPath)} ${shellQuote(entrypoint)} inference credential` }, null, 2) + "\n", { mode: 0o600 });
+    await writeFile(mcp, JSON.stringify({ mcpServers: { b3iq_media: media } }, null, 2) + "\n", { mode: 0o600 });
+    const plugin = await sharedSkillsPlugin(dir);
+    const key = options.key ?? await gatewayKey();
+    return { dir, config: settings, claudeDesktop, mediaConfig: mcp, ...(plugin ? { skillsPlugin: plugin } : {}), args: ["--settings", settings, "--mcp-config", mcp, ...(plugin ? ["--plugin-dir", plugin] : [])], env: { ...env, B3IQ_GATEWAY_API_KEY: key } };
+}
+async function sharedSkillsPlugin(dir) {
+    const configured = process.env.AGENTS_ROOT?.trim();
+    const source = resolve(configured ? configured.replace(/^~(?=\/|$)/, homedir()) : join(homedir(), ".agents", "skills"));
+    let entries;
+    try {
+        entries = await readdir(source, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    const plugin = join(dir, "shared-skills"), skills = join(plugin, "skills");
+    await mkdir(join(plugin, ".claude-plugin"), { recursive: true, mode: 0o700 });
+    await mkdir(skills, { recursive: true, mode: 0o700 });
+    await writeFile(join(plugin, ".claude-plugin", "plugin.json"), JSON.stringify({ name: "b3iq-shared-skills", version: "0.1.0", description: "Skills from your shared agents directory" }), { mode: 0o600 });
+    const selected = new Set();
+    for (const entry of entries) {
+        if (!entry.isDirectory() && !entry.isSymbolicLink())
+            continue;
+        const target = join(source, entry.name);
+        try {
+            await readFile(join(target, "SKILL.md"), "utf8");
+        }
+        catch {
+            continue;
+        }
+        selected.add(entry.name);
+        const destination = join(skills, entry.name);
+        let existing;
+        try {
+            existing = await lstat(destination);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        if (existing) {
+            if (!existing.isSymbolicLink())
+                throw new CliError("A generated skill destination contains an unexpected file. Preserve it and inspect the B3IQ setup directory.", "usage");
+            if (await readlink(destination) === target)
+                continue;
+            await unlink(destination);
+        }
+        await symlink(target, destination, "dir");
+    }
+    for (const entry of await readdir(skills, { withFileTypes: true })) {
+        if (!selected.has(entry.name) && entry.isSymbolicLink())
+            await unlink(join(skills, entry.name));
+    }
+    return plugin;
+}
+function toml(value) {
+    if (Array.isArray(value))
+        return `[${value.map(toml).join(", ")}]`;
+    if (value !== null && typeof value === "object")
+        return `{ ${Object.entries(value).map(([key, item]) => `${JSON.stringify(key)} = ${toml(item)}`).join(", ")} }`;
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined)
+        throw new CliError("Unsupported configuration value.", "usage");
+    return encoded;
+}
+export async function launchNativeAgent(client, prepared, args) {
+    if (client === "codex")
+        await installCodexProfile(prepared);
+    const env = { ...process.env, ...prepared.env };
+    if (client === "opencode")
+        env.PWD = process.cwd();
+    if (client === "claude") {
+        for (const key of claudeCredentialOverrides)
+            delete env[key];
+    }
+    if (client === "opencode" && prepared.openCodeVersion === 2 && args.some(arg => arg === "--server" || arg.startsWith("--server="))) {
+        throw new CliError("B3IQ OpenCode launches use a private server. Configure a remote OpenCode server separately instead of passing --server.", "usage");
+    }
+    await new Promise((resolvePromise, reject) => {
+        const child = spawn(client, [...args, ...prepared.args, ...(client === "opencode" && prepared.openCodeVersion === 2 ? ["--standalone"] : [])], { env, stdio: "inherit" });
+        child.once("error", () => reject(new CliError(`Install ${client} before launching it through B3IQ.`, "usage")));
+        child.once("exit", (code, signal) => { process.exitCode = code ?? (signal ? 130 : 1); resolvePromise(); });
+    });
+}

package/dist/commands/opencode.js

@@ -0,0 +1,161 @@
+import { mkdir, readFile, writeFile, rename, unlink, lstat, link, rmdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { execFile } from "node:child_process";
+import { parse, modify, applyEdits } from "jsonc-parser";
+import { CliError } from "../lib/output.js";
+import { inferenceKeyPath, nativeInputModalities } from "../lib/inference.js";
+const agentIDs = ["build", "plan", "general", "explore", "title", "summary", "compaction"];
+export async function detectOpenCodeVersion() {
+    return new Promise((resolvePromise, reject) => {
+        execFile("opencode", ["--version"], { timeout: 5000, maxBuffer: 4096 }, (error, stdout) => {
+            const version = stdout?.trim().match(/^(?:opencode\s+v?)?([12])\.\d+\.\d+(?:[-+][\w.-]+)?$/)?.[1];
+            if (error || !version)
+                return reject(new CliError("Install OpenCode on PATH and check opencode --version, or specify --client-version 1|2 for a supported client.", "usage"));
+            resolvePromise(version === "1" ? 1 : 2);
+        });
+    });
+}
+export function openCodeConfig(model, context, baseURL, media, machine, setup = {}) {
+    if (model.id.includes("#"))
+        throw new CliError("OpenCode model IDs cannot contain a variant separator (#).", "usage");
+    const version = setup.version ?? 2, selection = `b3iq/${model.id}`;
+    const apiKey = setup.desktop ? `{file:${inferenceKeyPath()}}` : "{env:B3IQ_GATEWAY_API_KEY}";
+    const configuredSkills = process.env.AGENTS_ROOT?.trim();
+    const skills = configuredSkills ? [resolve(configuredSkills.replace(/^~(?=\/|$)/, homedir()))] : [];
+    const limits = { context, output: 8192 };
+    const agents = Object.fromEntries(agentIDs.map(id => [id, { model: selection }]));
+    const mcp = { type: "local", command: [media.command, ...media.args],
+        ...(setup.desktop ? { environment: { B3IQ_GATEWAY_API_KEY: apiKey } } : {}) };
+    if (version === 1)
+        return {
+            $schema: "https://opencode.ai/config.json",
+            ...(!setup.desktop ? { model: selection, small_model: selection, agent: agents } : {}),
+            provider: { b3iq: { npm: "@ai-sdk/openai", name: "B3IQ", options: {
+                        baseURL, apiKey, ...(machine ? { headers: { "x-b3iq-node-id": machine } } : {}),
+                    }, models: { [model.id]: { name: model.id, tool_call: true, reasoning: false,
+                            modalities: { input: nativeInputModalities(model), output: ["text"] }, limit: limits } } } },
+            mcp: { b3iq_media: { ...mcp, enabled: true } },
+            ...(skills.length ? { skills: { paths: skills } } : {}),
+        };
+    return {
+        $schema: "https://opencode.ai/config.json",
+        ...(!setup.desktop ? { model: selection, agents } : {}),
+        providers: { b3iq: { package: "@opencode/ai/providers/openai-compatible/responses", name: "B3IQ",
+                settings: { baseURL, apiKey, encoding: "none" },
+                ...(machine ? { headers: { "x-b3iq-node-id": machine } } : {}),
+                models: { [model.id]: { modelID: model.id, name: model.id,
+                        capabilities: { tools: true, input: nativeInputModalities(model), output: ["text"] }, limit: limits } },
+            } }, mcp: { servers: { b3iq_media: { ...mcp, codemode: false } } },
+        ...(skills.length ? { skills } : {}),
+    };
+}
+export function openCodeConfigDirectory() {
+    return process.env.OPENCODE_CONFIG_DIR ?? join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "opencode");
+}
+export async function installOpenCodeConfig(config, version, expectedKey, directory = openCodeConfigDirectory(), keyFile = inferenceKeyPath()) {
+    let saved;
+    try {
+        saved = (await readFile(keyFile, "utf8")).trim();
+    }
+    catch {
+        throw new CliError("Save the dashboard key with b3iq inference key-save before installing desktop settings.", "auth");
+    }
+    if (saved !== expectedKey)
+        throw new CliError("The saved dashboard key differs from the discovery key. Save the current key before installing desktop settings.", "auth");
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    const lock = join(directory, ".b3iq-config.lock");
+    try {
+        await mkdir(lock, { mode: 0o700 });
+    }
+    catch {
+        throw new CliError("Another B3IQ setup is using this OpenCode config directory. Inspect its .b3iq-config.lock before retrying.", "usage");
+    }
+    let temp;
+    try {
+        const existing = [];
+        for (const name of ["opencode.json", "opencode.jsonc"]) {
+            const path = join(directory, name);
+            try {
+                const info = await lstat(path);
+                if (!info.isFile() || info.isSymbolicLink())
+                    throw new CliError("OpenCode config is not a regular file. Inspect it before applying B3IQ settings.", "usage");
+                existing.push(path);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
+        }
+        if (existing.length > 1)
+            throw new CliError("Both OpenCode JSON and JSONC configs exist. Merge the generated settings manually to preserve their precedence.", "usage");
+        const path = existing[0] ?? join(directory, "opencode.jsonc");
+        const original = existing.length ? await readFile(path, "utf8") : "{}\n";
+        const errors = [];
+        const value = parse(original, errors, { allowTrailingComma: true });
+        if (errors.length || !value || typeof value !== "object" || Array.isArray(value))
+            throw new CliError("OpenCode config is not a valid JSONC object. Fix it or merge the generated settings manually.", "usage");
+        const current = value;
+        if ((version === 2 && ("provider" in current || "agent" in current || "small_model" in current)) ||
+            (version === 1 && ("providers" in current || "agents" in current)))
+            throw new CliError("Existing OpenCode config uses another major version. Migrate it with OpenCode before installing B3IQ settings.", "usage");
+        const object = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+        const providers = version === 2 ? "providers" : "provider";
+        if (current[providers] !== undefined && !object(current[providers]) ||
+            current.mcp !== undefined && !object(current.mcp) ||
+            version === 2 && object(current.mcp) && current.mcp.servers !== undefined && !object(current.mcp.servers)) {
+            throw new CliError("Inspect existing OpenCode provider and MCP objects before adding B3IQ settings.", "usage");
+        }
+        let updated = original;
+        const set = (path, value) => {
+            updated = applyEdits(updated, modify(updated, path, value, { formattingOptions: { insertSpaces: true, tabSize: 2 } }));
+        };
+        const add = (path, existing, proposed) => {
+            if (existing === undefined) {
+                set(path, proposed);
+                return;
+            }
+            if (object(existing) && object(proposed)) {
+                for (const [key, value] of Object.entries(proposed))
+                    add([...path, key], existing[key], value);
+            }
+            else if (JSON.stringify(existing) !== JSON.stringify(proposed)) {
+                throw new CliError(`Existing OpenCode setting ${path.join(".")} conflicts with B3IQ registration. Inspect it before retrying; no client settings were changed.`, "usage");
+            }
+        };
+        add([providers, "b3iq"], current[providers]?.b3iq, config[providers].b3iq);
+        const oldMcp = version === 2 ? current.mcp?.servers : current.mcp;
+        const proposedMcp = version === 2 ? config.mcp.servers : config.mcp;
+        add(version === 2 ? ["mcp", "servers", "b3iq_media"] : ["mcp", "b3iq_media"], oldMcp?.b3iq_media, proposedMcp.b3iq_media);
+        if (config.skills) {
+            const old = version === 2 ? current.skills : current.skills?.paths;
+            const added = version === 2 ? config.skills : config.skills.paths;
+            if (old !== undefined && (!Array.isArray(old) || old.some(x => typeof x !== "string")))
+                throw new CliError("Inspect existing OpenCode skill paths before merging B3IQ settings.", "usage");
+            const merged = [...new Set([...(old ?? []), ...added])];
+            if (JSON.stringify(old) !== JSON.stringify(merged))
+                set(version === 2 ? ["skills"] : ["skills", "paths"], merged);
+        }
+        if (updated === original)
+            return { config: path };
+        const backup = existing.length ? `${path}.b3iq-backup-${randomUUID()}` : undefined;
+        if (backup)
+            await writeFile(backup, original, { flag: "wx", mode: 0o600 });
+        temp = `${path}.b3iq-${randomUUID()}`;
+        await writeFile(temp, updated.endsWith("\n") ? updated : updated + "\n", { flag: "wx", mode: 0o600 });
+        if (existing.length && await readFile(path, "utf8") !== original)
+            throw new CliError("OpenCode config changed during setup. Retry after inspecting the backup.", "usage");
+        if (!existing.length) {
+            await link(temp, path);
+        }
+        else
+            await rename(temp, path);
+        return { config: path, ...(backup ? { backup } : {}) };
+    }
+    finally {
+        if (temp)
+            await unlink(temp).catch(() => { });
+        await rmdir(lock);
+    }
+}

package/dist/commands/plugins.js

@@ -0,0 +1,67 @@
+import { api } from "../lib/api.js";
+import { resolveMachine, machineLabel, noteReportedOffline } from "../lib/machines.js";
+import { queuedThenWait } from "../lib/commands-wait.js";
+import { CliError, emit, emitIds, isQuiet, success, table } from "../lib/output.js";
+export async function pluginsList(machine) {
+    if (machine)
+        return machinePlugins(machine);
+    const { plugins } = await api.plugins();
+    if (isQuiet()) {
+        emitIds(plugins.map((p) => p.name));
+        return;
+    }
+    emit(plugins, () => {
+        table(["PLUGIN", "WHAT IT ADDS"], plugins.map((p) => [p.name, p.description]));
+    });
+}
+async function machinePlugins(machine) {
+    const node = await resolveMachine(machine);
+    const plugins = (await api.node(node.node_id)).plugins ?? [];
+    if (isQuiet()) {
+        emitIds(plugins.map((p) => p.name));
+        return;
+    }
+    emit(plugins, () => {
+        if (plugins.length === 0) {
+            process.stderr.write(`${machineLabel(node)} has no plugins. See what it can install: \`b3iq plugins list\`.\n`);
+            return;
+        }
+        table(["PLUGIN", "VERSION", "STATE"], plugins.map((p) => [p.name, p.version, p.reason ? `${p.state} (${p.reason})` : p.state]));
+    });
+}
+const INSTALL_TIMEOUT_MS = 25 * 60 * 1000;
+const UNINSTALL_TIMEOUT_MS = 10 * 60 * 1000;
+export async function pluginsInstall(name, machine, wait) {
+    if (!name)
+        throw new CliError("Usage: b3iq plugins install <plugin> --machine <m>", "usage", 1);
+    const node = await resolveMachine(machine);
+    noteReportedOffline(node);
+    const row = await queuedThenWait(node.node_id, await api.installPlugin(node.node_id, name), {
+        wait,
+        timeoutMs: INSTALL_TIMEOUT_MS,
+        describe: `install ${name} on ${machineLabel(node)}`,
+    });
+    emit(row, () => {
+        if (row.status === "completed")
+            success(`${name} installed on ${machineLabel(node)}.`);
+        else
+            process.stdout.write(`${row.command_id}\n`);
+    });
+}
+export async function pluginsRemove(name, machine, wait) {
+    if (!name)
+        throw new CliError("Usage: b3iq plugins remove <plugin> --machine <m>", "usage", 1);
+    const node = await resolveMachine(machine);
+    noteReportedOffline(node);
+    const row = await queuedThenWait(node.node_id, await api.uninstallPlugin(node.node_id, name), {
+        wait,
+        timeoutMs: UNINSTALL_TIMEOUT_MS,
+        describe: `remove ${name} from ${machineLabel(node)}`,
+    });
+    emit(row, () => {
+        if (row.status === "completed")
+            success(`${name} removed from ${machineLabel(node)}.`);
+        else
+            process.stdout.write(`${row.command_id}\n`);
+    });
+}

package/dist/commands/runtimes.js

@@ -0,0 +1,76 @@
+import { api } from "../lib/api.js";
+import { explainRuntimeMissing } from "../lib/diagnosis.js";
+import { resolveMachine, machineLabel, noteReportedOffline } from "../lib/machines.js";
+import { enqueueAndWait } from "../lib/commands-wait.js";
+import { CliError, emit, emitIds, isQuiet, success, table } from "../lib/output.js";
+export async function runtimesCheck(machine) {
+    const node = await resolveMachine(machine);
+    const row = await enqueueAndWait(node.node_id, "model.catalog", {}, { wait: true, timeoutMs: 120_000, describe: "check runtime updates" });
+    const detail = await api.nodeCommand(node.node_id, row.command_id);
+    const catalog = detail.command.result;
+    const entries = catalog?.runtime_catalog ?? [];
+    emit(entries, () => table(["RUNTIME", "INSTALLED", "PINNED TARGET", "UPDATE", "POLICY"], entries.filter(r => r.update).map(r => [r.runtime_id ?? r.kind, r.update.installed_version ?? "unknown", r.update.target_version, r.update.state, r.update.policy.mode === "scheduled" ? `daily ${r.update.policy.hour_utc}:00 UTC` : "manual"])));
+}
+export async function runtimesUpgrade(selector, machine, target, wait) {
+    if (!selector || !target || !/^\d+\.\d+\.\d+$/.test(target))
+        throw new CliError("Usage: b3iq runtimes upgrade <runtime-id> --machine <m> --target-version <pinned-version> [--no-wait]. Get the target with b3iq runtimes check --machine <m>.", "usage", 1);
+    const node = await resolveMachine(machine);
+    noteReportedOffline(node);
+    const row = await enqueueAndWait(node.node_id, "runtime.upgrade", { runtime_id: selector, target_version: target }, { wait, timeoutMs: 65 * 60_000, describe: `upgrade ${selector}; waits for active inference, then briefly restarts` });
+    emit(row, () => process.stdout.write(`${row.command_id}: ${row.status}\n`));
+}
+export async function runtimesPolicy(selector, machine, mode, hour) {
+    if (!selector || !["manual", "scheduled"].includes(mode ?? "") || (mode === "scheduled" && (!hour || !/^(?:[01]?\d|2[0-3])$/.test(hour))))
+        throw new CliError("Usage: b3iq runtimes policy <runtime-id> --machine <m> --mode manual|scheduled [--hour-utc 0..23]. Scheduled upgrades use a daily one-hour window and only the plugin's pinned release.", "usage", 1);
+    const node = await resolveMachine(machine);
+    const row = await enqueueAndWait(node.node_id, "runtime.update_policy", { runtime_id: selector, mode, ...(mode === "scheduled" ? { hour_utc: Number(hour) } : {}) }, { wait: true, timeoutMs: 120_000, describe: `save ${selector} update policy` });
+    emit(row, () => success("Runtime update policy saved."));
+}
+export async function runtimesList(machine) {
+    const node = await resolveMachine(machine);
+    const runtimes = (await api.node(node.node_id)).runtimes ?? [];
+    const rid = (r) => r.runtime_id ?? r.id ?? r.runtime_kind ?? r.kind ?? "";
+    if (isQuiet()) {
+        emitIds(runtimes.map(rid));
+        return;
+    }
+    emit(runtimes, () => {
+        if (runtimes.length === 0) {
+            process.stderr.write(`${machineLabel(node)} reports no runtimes (agent offline?).\n`);
+            return;
+        }
+        table(["RUNTIME", "VERSION", "STATUS", "ENDPOINT", "SELF-HEAL"], runtimes.map((r) => [
+            rid(r),
+            r.runtime_version ?? r.version ?? "—",
+            r.status ?? (r.available === false ? "unreachable" : "available"),
+            (r.base_url ?? "").replace(/^https?:\/\//, ""),
+            r.auto_restart === "uncovered" ? "no" : r.auto_restart === "covered" ? "yes" : "—",
+        ]));
+    });
+}
+const RESTART_TIMEOUT_MS = 5 * 60 * 1000;
+export async function runtimesRestart(selector, machine, wait) {
+    if (!selector)
+        throw new CliError("Usage: b3iq runtimes restart <runtime> --machine <m>", "usage", 1);
+    const node = await resolveMachine(machine);
+    noteReportedOffline(node);
+    const runtimes = (await api.node(node.node_id)).runtimes ?? [];
+    const lower = selector.trim().toLowerCase();
+    const matches = runtimes.filter((r) => [r.runtime_id, r.id, r.runtime_kind, r.kind].some((v) => v?.toLowerCase() === lower));
+    if (matches.length === 0) {
+        throw explainRuntimeMissing(selector, node.node_id, machineLabel(node));
+    }
+    const target = matches[0];
+    const runtimeId = target.runtime_id ?? target.id ?? selector;
+    const row = await enqueueAndWait(node.node_id, "runtime.restart", { runtime_id: runtimeId }, {
+        wait,
+        timeoutMs: RESTART_TIMEOUT_MS,
+        describe: `restart ${runtimeId} on ${machineLabel(node)}`,
+    });
+    emit(row, () => {
+        if (row.status === "completed")
+            success(`${runtimeId} restarted on ${machineLabel(node)}.`);
+        else
+            process.stdout.write(`${row.command_id}\n`);
+    });
+}