@bivy/bivy 0.10.1-staging.176 → 0.10.1-staging.178

package/README.md

@@ -62,7 +62,7 @@ Environment variables passed to the one-line installer change what it does:
 | Track the dev channel (new build on every merge to `main`) | `BIVY_CHANNEL=staging` |
 | Pin an exact version | `BIVY_VERSION=0.1.0` |
 | Install without sudo, into a user-owned prefix | `BIVY_NPM_PREFIX=~/.local` |
-| Preinstall every bundled agent runtime | `BIVY_INSTALL_ALL_AGENTS=1` |
+| Preinstall every known upstream agent | `BIVY_INSTALL_ALL_AGENTS=1` |
 
 For example: `BIVY_CHANNEL=staging curl -fsSL https://bivy.sh/install.sh | bash`.
 
@@ -146,8 +146,8 @@ the rest are explicitly Beta in the picker and support matrix:
 
 | Agent | Command | Notes |
 |---|---|---|
-| Pi | `bivy run pi` | Default; bundled |
-| Claude Code | `bivy run claude` | Bundled SDK |
+| Pi | `bivy run pi` | Uses the operator-installed `pi` command and Pi auth/config |
+| Claude Code | `bivy run claude` | Uses the operator-installed `claude` command through an SDK bridge |
 | Codex | `bivy run codex` | Installs `@openai/codex` |
 | OpenCode | `bivy run opencode` | Installs `opencode-ai` |
 | Gemini CLI | `bivy run gemini` | Installs `@google/gemini-cli` |
@@ -169,9 +169,10 @@ the rest are explicitly Beta in the picker and support matrix:
 Any other command works via `bivy run -- ./your-agent --flags`. ACP-capable
 agents can be promoted to Bivy's governed protocol path for per-tool approvals
 and native resume. To add a reusable process or ACP agent to both the CLI and web
-picker without changing Bivy, scaffold and install a declarative
-[plugin manifest](docs/plugins.md) with `bivy plugin init`; the plugin SDK,
-JSON Schema, diagnostics, and ACP conformance test support external authors.
+picker without changing Bivy, run `bivy agent add`, or scaffold and install a
+declarative [plugin manifest](docs/plugins.md) with `bivy plugin init`. Both use
+the same schema/store; the plugin SDK, diagnostics, and ACP conformance fixtures
+support distributable or custom protocol bridges.
 
 [`docs/runtime-support-matrix.md`](docs/runtime-support-matrix.md) lists exactly
 what each agent supports — resume, model selection, approvals, sandboxing.
@@ -186,7 +187,8 @@ bivy sessions         # list live and saved sessions
 bivy resume           # resume the most recent session
 bivy open             # open the web app (requires relay setup)
 bivy automation init  # create .bivy/automations.yaml
-bivy plugin list      # installed declarative agent plugins
+bivy agent add        # connect an existing ACP or process agent
+bivy plugin list      # installed declarative integration packages
 bivy status           # config summary and node reachability
 bivy doctor           # health check
 bivy logs -f          # tail node logs

package/bin/bivy.mjs

@@ -60,7 +60,7 @@ function resolveAppDir() {
   return path.join(os.homedir(), ".bivy");
 }
 const appDir = resolveAppDir();
-// Propagate the resolved data dir to every child process (daemon, native-pi,
+// Propagate the resolved data dir to every Bivy child process (daemon, helpers,
 // exec, …) via the environment so none of them independently fall back to
 // <repoRoot>/.bivy. The daemon reads BIVY_DATA_DIR (see src/server.ts).
 process.env.BIVY_DATA_DIR = appDir;
@@ -142,12 +142,11 @@ function resolveUpdateChannel(args) {
 }
 const packaged = fs.existsSync(path.join(repoRoot, "dist", "server.js"));
 const serverEntry = path.join(repoRoot, packaged ? "dist/server.js" : "src/server.ts");
-const nativePiEntry = path.join(repoRoot, packaged ? "dist/native-pi.js" : "src/native-pi.ts");
 const bivyLoginEntry = path.join(repoRoot, packaged ? "dist/bivy-login.js" : "src/bivy-login.ts");
-const credentialIngestEntry = path.join(repoRoot, packaged ? "dist/credential-ingest-cli.js" : "src/credential-ingest-cli.ts");
 const automationEntry = path.join(repoRoot, packaged ? "dist/automation-cli.js" : "src/automation-cli.ts");
 const configEntry = path.join(repoRoot, packaged ? "dist/config-cli.js" : "src/config-cli.ts");
 const pluginEntry = path.join(repoRoot, packaged ? "dist/plugin-cli.js" : "src/plugin-cli.ts");
+const agentEntry = path.join(repoRoot, packaged ? "dist/agent-cli.js" : "src/agent-cli.ts");
 const relaySetupEntry = path.join(repoRoot, packaged ? "dist/relay-setup.js" : "src/relay-setup.ts");
 // Dependency-free hosted-endpoint helper. Shipped to dist/ in the release
 // artifact (src/ is not packaged), so resolve it the same packaged-aware way as
@@ -432,7 +431,7 @@ function hasModelConfig(config) {
 }
 
 const SETUP_AGENT_CHOICES = [
-  { key: "p", label: "Pi (default, sign in to ChatGPT/Claude/Copilot or paste a model key)", runtimeId: "pi", needsBivyModel: true },
+  { key: "p", label: "Pi (default; uses your existing login and configuration)", runtimeId: "pi", command: "pi", needsBivyModel: false, loginHint: "Sign in through Pi (/login)" },
   { key: "c", label: "Claude Code", runtimeId: "claude-code-sdk", command: "claude", authProbe: ["auth", "status"], needsBivyModel: false, loginHint: "Sign in through Claude Code" },
   { key: "x", label: "Codex", runtimeId: "codex", command: "codex", authProbe: ["login", "status"], needsBivyModel: false, loginHint: "Sign in through Codex" },
   { key: "o", label: "OpenCode", runtimeId: "opencode", command: "opencode", needsBivyModel: false },
@@ -463,20 +462,13 @@ function nativeAgentAuthDetected(choice) {
   // Conservative file fallbacks for older CLI versions without a status command.
   if (choice.command === "codex") return fs.existsSync(path.join(os.homedir(), ".codex", "auth.json"));
   if (choice.command === "claude") return fs.existsSync(path.join(os.homedir(), ".claude", ".credentials.json"));
+  if (choice.command === "pi") {
+    const agentDir = process.env.PI_CODING_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+    return fs.existsSync(path.join(agentDir, "auth.json"));
+  }
   return false;
 }
 
-async function ingestSetupAgentLogin(choice) {
-  if (!choice || !["claude-code-sdk", "codex"].includes(choice.runtimeId)) return false;
-  const code = await run(nodeBin, [
-    ...nodeScriptArgs(credentialIngestEntry),
-    choice.runtimeId,
-    path.join(appDir, "credentials"),
-    path.join(appDir, "pi"),
-  ], { cwd: repoRoot, env: process.env, stdio: "ignore" });
-  return code === 0;
-}
-
 function url(config) {
   return `http://localhost:${config.port}`;
 }
@@ -626,7 +618,8 @@ async function ensurePythonCommand(command, packageName, label) {
 
 // Single source of truth for what `bivy agents:install` installs, so its help
 // text (see printHelp) can never drift from what it actually does (#113).
-const BUNDLED_AGENTS = [
+const KNOWN_AGENT_INSTALLS = [
+  { command: "pi", npmPackage: "@earendil-works/pi-coding-agent", label: "Pi" },
   { command: "claude", npmPackage: "@anthropic-ai/claude-code", label: "Claude Code" },
   { command: "codex", npmPackage: "@openai/codex", label: "Codex" },
   { command: "opencode", npmPackage: "opencode-ai/opencode", label: "OpenCode" },
@@ -635,11 +628,11 @@ const BUNDLED_AGENTS = [
   { command: "gemini", npmPackage: "@google/gemini-cli", label: "Gemini CLI" },
 ];
 
-async function ensureBundledAgents() {
+async function ensureKnownAgents() {
   if (process.env.BIVY_SKIP_AGENT_PREINSTALL === "1") return true;
-  console.log(c.dim("Ensuring bundled agent runtimes are installed…"));
+  console.log(c.dim("Ensuring known agent integrations are installed…"));
   const results = [await ensureNodePackage("@anthropic-ai/claude-agent-sdk")];
-  for (const agent of BUNDLED_AGENTS) {
+  for (const agent of KNOWN_AGENT_INSTALLS) {
     results.push(
       agent.pythonPackage
         ? await ensurePythonCommand(agent.command, agent.pythonPackage, agent.label)
@@ -652,7 +645,8 @@ async function ensureBundledAgents() {
 }
 
 async function ensureSetupAgent(choice) {
-  if (!choice || choice.runtimeId === "pi") return true;
+  if (!choice) return true;
+  if (choice.runtimeId === "pi") return ensureNpmCommand("pi", "@earendil-works/pi-coding-agent", "Pi");
   if (choice.runtimeId === "claude-code-sdk") {
     const sdk = await ensureNodePackage("@anthropic-ai/claude-agent-sdk");
     const cli = await ensureNpmCommand("claude", "@anthropic-ai/claude-code", "Claude Code");
@@ -669,9 +663,9 @@ async function ensureSetupAgent(choice) {
 }
 
 // The CLI-agent rows come from bin/agent-manifest.json — generated from
-// CLI_AGENT_SPECS (`npm run gen:agent-manifest`), so the terminal `bivy run`
-// agents never drift from the web picker's. A sync test guards the JSON. The two
-// native rows (Pi, Claude Code) aren't CLI specs and stay defined here.
+// AGENT_PROFILES (`npm run gen:agent-manifest`), so the terminal `bivy run`
+// agents never drift from the web picker's. A sync test guards the JSON. Agent
+// integrations that need a bridge still point at the operator's installed CLI.
 function loadAgentManifest() {
   try {
     const raw = fs.readFileSync(path.join(__dirname, "agent-manifest.json"), "utf8");
@@ -758,8 +752,8 @@ function manifestHeadlessFlags(id) {
   return plugin?.headlessFlags?.length ? plugin.headlessFlags : undefined;
 }
 
-const BUILTIN_TERMINAL_AGENTS = new Map([
-  ["pi", { label: "Pi", type: "native-pi" }],
+const AGENT_INTEGRATIONS = new Map([
+  ["pi", { label: "Pi", type: "command", command: "pi", npmPackage: "@earendil-works/pi-coding-agent" }],
   ["claude", { label: "Claude Code", type: "command", command: "claude", npmPackage: "@anthropic-ai/claude-code" }],
   ["openclaw", { label: "OpenClaw", type: "command", command: process.env.BIVY_OPENCLAW_COMMAND || "openclaw" }],
   ...loadAgentManifest().map((a) => [
@@ -817,7 +811,7 @@ function customTerminalAgent(agentId) {
 
 function terminalAgent(agentId) {
   const id = (agentId || resolveDefaultAgent()).toLowerCase();
-  return { id, agent: BUILTIN_TERMINAL_AGENTS.get(id) ?? customTerminalAgent(id) };
+  return { id, agent: AGENT_INTEGRATIONS.get(id) ?? customTerminalAgent(id) };
 }
 
 async function waitForNode(config, timeoutMs = 8000) {
@@ -880,10 +874,7 @@ async function resolveRunSpec(agentId, extraArgs) {
   }
   const { id, agent } = terminalAgent(agentId);
   if (!agent) {
-    return { error: `Unknown agent: ${agentId}. Built-ins: ${[...BUILTIN_TERMINAL_AGENTS.keys()].join(", ")}. Or: bivy run -- <command>.` };
-  }
-  if (agent.type === "native-pi") {
-    return { spec: { agent: id, label: agent.label, command: nodeBin, args: [...nodeScriptArgs(nativePiEntry), ...extraArgs] } };
+    return { error: `Unknown agent: ${agentId}. Known integrations: ${[...AGENT_INTEGRATIONS.keys()].join(", ")}. Or: bivy run -- <command>.` };
   }
   const command = await ensureTerminalCommand(agent);
   if (!command) {
@@ -1420,19 +1411,15 @@ async function cmdNodes(args = []) {
   console.log("");
 }
 
-// `bivy agents` — list the agents Bivy can launch (its built-in terminal agents),
-// showing which are installed on PATH. `bivy run <agent>` starts one; the bundled
-// ones are installed with `bivy agents:install`. `--json` for machine-readable output.
+// `bivy agents` — list integrations and the upstream agents found on PATH.
+// `bivy run <agent>` starts the user's native agent; `--json` is machine-readable.
 function cmdAgents(args = []) {
   if (args.includes("-h") || args.includes("--help")) {
-    console.log("Usage: bivy agents [--json]\n\nList the agents Bivy can launch ('bivy run <agent>') and which are installed on PATH. 'bivy agents:install' installs the bundled ones.");
+    console.log("Usage: bivy agents [--json]\n\nList the agents Bivy can launch ('bivy run <agent>') and which are installed on PATH. 'bivy agents:install' installs the known upstream agents.");
     return;
   }
   const asJson = args.includes("--json");
-  const rows = [...BUILTIN_TERMINAL_AGENTS.entries()].map(([id, meta]) => {
-    if (meta.type === "native-pi") {
-      return { id, label: meta.label, type: meta.type, command: null, installed: true, path: null };
-    }
+  const rows = [...AGENT_INTEGRATIONS.entries()].map(([id, meta]) => {
     const command = meta.command || id;
     const resolved = whichOnPath(command);
     return { id, label: meta.label, type: meta.type, command, installed: Boolean(resolved), path: resolved || null, ...(meta.plugin ? { plugin: meta.plugin } : {}) };
@@ -1443,11 +1430,9 @@ function cmdAgents(args = []) {
     return;
   }
 
-  console.log(c.bold("\n  Agents") + c.dim("  (bivy run <agent> — 'bivy agents:install' adds the bundled ones)\n"));
+  console.log(c.bold("\n  Agents") + c.dim("  (bivy run <agent> — 'bivy agents:install' adds the known upstream agents)\n"));
   for (const row of rows) {
-    const status = row.type === "native-pi"
-      ? c.green("● built-in")
-      : row.installed ? c.green("● installed") : c.dim("○ not installed");
+    const status = row.installed ? c.green("● installed") : c.dim("○ not installed");
     const where = row.path ? c.dim(`  ${row.path}`) : "";
     const source = row.plugin ? c.dim(`  plugin:${row.plugin}`) : "";
     console.log(`  ${c.cyan(row.id.padEnd(12))} ${String(row.label).padEnd(16)} ${status}${source}${where}`);
@@ -1502,13 +1487,8 @@ async function cmdShim(args = []) {
       process.exit(1);
       return;
     }
-    const builtin = BUILTIN_TERMINAL_AGENTS.get(agent);
-    if (builtin && builtin.type === "native-pi") {
-      console.error(c.red(`"${agent}" is Bivy's own native runtime, not a standalone binary — nothing to shim. Just run 'bivy -a ${agent}'.`));
-      process.exit(1);
-      return;
-    }
-    const agentCmd = builtin?.command || agent;
+    const integration = AGENT_INTEGRATIONS.get(agent);
+    const agentCmd = integration?.command || agent;
     const shimDir = path.resolve(argValue(rest, "dir") || defaultShimDir());
     const force = rest.includes("--force");
     const headlessOverride = argValue(rest, "headless");
@@ -1694,16 +1674,16 @@ async function cmdExec(args = []) {
 }
 
 // `bivy completions <bash|zsh|fish>` — print a shell completion script to eval or
-// install. Covers the top-level commands and the built-in agent ids.
+// install. Covers the top-level commands and known integration ids.
 function cmdCompletions(args = []) {
   const shell = (args[0] || "").toLowerCase();
   const commands = [
-    "run", "sessions", "ls", "resume", "promote", "rename", "nodes", "agents", "agents:install", "shim", "takeover", "token", "exec",
+    "run", "sessions", "ls", "resume", "promote", "rename", "nodes", "agent", "agents", "agents:install", "shim", "takeover", "token", "exec",
     "send", "attach", "kill", "setup", "start", "stop", "restart", "status", "doctor", "diagnostics", "logs", "login",
     "update", "update:log", "automation", "config", "plugin", "open", "service", "secrets", "voice", "link", "relay:setup",
     "github:connect", "github:app-create", "github:app-connect", "github:app-sync", "prune", "uninstall", "help", "version",
   ];
-  const agents = [...BUILTIN_TERMINAL_AGENTS.keys()];
+  const agents = [...AGENT_INTEGRATIONS.keys()];
 
   if (shell === "bash") {
     console.log(`# bivy bash completion — add to ~/.bashrc:  eval "$(bivy completions bash)"
@@ -1806,11 +1786,6 @@ async function cmdRun(args = []) {
     // path a phone uses). The command must resolve on the REMOTE node's PATH, so
     // send the agent's bare command rather than this machine's absolute path.
     if (target.source === "relay") {
-      if (agentId !== "--" && terminalAgent(agentId).agent?.type === "native-pi") {
-        console.error(c.red("Pi runs only on the local node. For --node, pick an installed agent (e.g. claude, codex)."));
-        process.exit(1);
-        return;
-      }
       const remoteCommand = agentId === "--" ? resolved.spec.command : (terminalAgent(agentId).agent?.command || resolved.spec.command);
       const spec = { ...resolved.spec, command: remoteCommand, name, model, workspace: undefined };
       console.log(c.dim(`Starting on ${c.cyan(target.name)} over the relay…`));
@@ -3473,8 +3448,8 @@ async function cmdSetup(args = []) {
   // `bivy github:app-create` / `github:app-connect`. One app covers every repo,
   // and the node mints its own tokens, so there's no per-repo token to set up here.
 
-  // Model access is part of activation, not a post-success footnote. Pi/Aider use
-  // Bivy's provider login; offer it inline so setup cannot imply the first task
+  // Model access is part of activation, not a post-success footnote. Integrations
+  // marked needsBivyModel use Bivy's provider login; offer it inline so setup cannot imply the first task
   // is ready while the required credential is still absent. Agent-native auth is
   // explained in the readiness checklist below because those CLIs own the flow.
   let agentAuthReady = setupAgent?.needsBivyModel ? hasModelConfig(config) : nativeAgentAuthDetected(setupAgent);
@@ -3492,17 +3467,15 @@ async function cmdSetup(args = []) {
     }
   } else if (setupAgent && !setupAgent.needsBivyModel) {
     if (agentAuthReady) {
-      const imported = await ingestSetupAgentLogin(setupAgent);
-      console.log(c.green(`\n  ✓ Existing ${setupAgent.label} login detected — Bivy will reuse it in the terminal and PWA${imported ? " and stored it in the encrypted vault" : ""}.`));
+      console.log(c.green(`\n  ✓ Existing ${setupAgent.label} login detected — Bivy will connect without replacing the agent's credential store.`));
     } else if (setupAgent.command) {
-      console.log(`\n${setupAgent.label} owns its login. After sign-in, Bivy stores compatible credential fields in its encrypted vault so the terminal, PWA, and your other Bivy nodes can reuse them.`);
+      console.log(`\n${setupAgent.label} owns its login and configuration. Bivy connects to that existing agent state rather than copying it into a separate default credential store.`);
       const signInNow = await askYesNo(`Open ${setupAgent.label} now to sign in? (Exit it when sign-in is complete.)`, true);
       if (signInNow) {
         rl.pause();
         const loginCode = await run(setupAgent.command, [], { cwd: config.workspace, env: startEnv(config) });
         rl.resume();
         agentAuthReady = loginCode === 0 || nativeAgentAuthDetected(setupAgent);
-        if (agentAuthReady) await ingestSetupAgentLogin(setupAgent);
       }
     }
   }
@@ -3857,11 +3830,11 @@ async function cmdDoctor(args = []) {
       ? c.green("relay connected") + (relayApp ? c.dim(`  ${relayApp}`) : "")
       : c.yellow("configured, not connected") + (relayErr ? c.dim(`  (${relayErr})`) : "");
   console.log(`  ${relayConfigured ? (relayConnected ? ok : warn) : c.dim("○")} remote ${relayLine}`);
-  // Derived from BUILTIN_TERMINAL_AGENTS (the same list 'bivy agents'/'bivy run'
+  // Derived from AGENT_INTEGRATIONS (the same list 'bivy agents'/'bivy run'
   // use) rather than a hand-maintained list, so it can't drift out of sync (#113).
-  const agentCommands = [...BUILTIN_TERMINAL_AGENTS.values()].filter((a) => a.type === "command").map((a) => a.command);
+  const agentCommands = [...AGENT_INTEGRATIONS.values()].filter((a) => a.type === "command").map((a) => a.command);
   const agents = agentCommands.filter((a) => commandExists(a));
-  console.log(`  ${mark(agents.length > 0, true)} agents on PATH: ${agents.length ? c.cyan(agents.join(", ")) : c.dim("none (built-in Pi still works; 'bivy agents:install')")}`);
+  console.log(`  ${mark(agents.length > 0, true)} agents on PATH: ${agents.length ? c.cyan(agents.join(", ")) : c.dim("none ('bivy agents:install' can install known upstream agents)")}`);
   if (status?.eventLog) {
     const healthy = status.eventLog.ok !== false;
     const mib = Number(status.eventLog.bytes || 0) / (1024 * 1024);
@@ -4024,7 +3997,7 @@ async function runUpdate(args = []) {
       console.log(c.yellow(`npm reported an issue (exit ${code}). Try: sudo npm i -g @bivy/bivy@${channel}`));
       process.exit(code);
     }
-    await ensureBundledAgents();
+    await ensureKnownAgents();
     const config = loadConfig();
     await waitForIdleSessions(config, { skip: skipWait });
     if (config.service && (await restartServiceReconciled(config))) {
@@ -4060,7 +4033,7 @@ async function runUpdate(args = []) {
   const pull = await run("git", ["pull", "--ff-only", "origin", branch || "main"], { cwd: repoRoot });
   if (pull !== 0) console.log(c.yellow("git pull reported an issue; continuing."));
   await run("npm", [fs.existsSync(path.join(repoRoot, "package-lock.json")) ? "ci" : "install", "--no-audit", "--no-fund"], { cwd: repoRoot });
-  await ensureBundledAgents();
+  await ensureKnownAgents();
   const config = loadConfig();
   await waitForIdleSessions(config, { skip: skipWait });
   if (config.service && (await restartServiceReconciled(config))) {
@@ -4377,7 +4350,7 @@ function printHelp() {
 ${c.bold("bivy")} — Bivy node CLI
 
   ${c.cyan("bivy run claude")}   Run a native agent (real CLI/TUI) as a relay-visible session
-  ${c.cyan("bivy run <agent>")}  ${[...BUILTIN_TERMINAL_AGENTS.keys()].join(" | ")} | -- <command>
+  ${c.cyan("bivy run <agent>")}  ${[...AGENT_INTEGRATIONS.keys()].join(" | ")} | -- <command>
   ${c.cyan("bivy run <agent> --name <label>")}  Name the session (shown in 'bivy sessions' and the app)
   ${c.cyan("bivy run <agent> --model <model>")}  Run with a specific model (passed to the agent, shown in the cockpit)
   ${c.cyan("bivy run <agent> --node <name>")}  Start the session on another registered node
@@ -4410,7 +4383,8 @@ ${c.bold("bivy")} — Bivy node CLI
   ${c.cyan("bivy login")}      Sign into a model provider (Pi /login)
   ${c.cyan("bivy update")}     Update Bivy + install deps + restart service (waits for active sessions to finish a turn; --force to skip)
   ${c.cyan("bivy update:log")} Show output of the last (or in-progress) update
-  ${c.cyan("bivy agents:install")}  Install bundled agents (${BUNDLED_AGENTS.map((a) => a.label).join(", ")})
+  ${c.cyan("bivy agent add")}        Connect an existing user-owned agent
+  ${c.cyan("bivy agents:install")}  Install known upstream agents (${KNOWN_AGENT_INSTALLS.map((a) => a.label).join(", ")})
   ${c.cyan("bivy open")}       Open the remote web/PWA app
   ${c.cyan("bivy service")}    install | uninstall | status
   ${c.cyan("bivy uninstall")}    Remove Bivy and all its data (--keep-sessions, --keep-worktrees, --dry-run)
@@ -4452,7 +4426,7 @@ async function main() {
         console.log(`Usage: bivy run <agent> [--name <label>] [--model <model>] [--node <name>] [--clone [remote]] [--workspace <dir>] | -- <command>
 
 Run a native agent (real CLI/TUI) as a relay-visible session.
-Agents: ${[...BUILTIN_TERMINAL_AGENTS.keys()].join(", ")}, or -- <command> for anything else.
+Agents: ${[...AGENT_INTEGRATIONS.keys()].join(", ")}, or -- <command> for anything else.
 An agent's own --help passes through, e.g. 'bivy run claude --help'.`);
         break;
       }
@@ -4475,6 +4449,11 @@ An agent's own --help passes through, e.g. 'bivy run claude --help'.`);
     case "nodes":
       await cmdNodes(args);
       break;
+    case "agent": {
+      if (!(await ensureDeps())) process.exit(1);
+      process.exit(await run(nodeBin, [...nodeScriptArgs(agentEntry), ...args], { cwd: process.cwd(), env: process.env }));
+      break;
+    }
     case "agents":
       cmdAgents(args);
       break;
@@ -4579,11 +4558,11 @@ An agent's own --help passes through, e.g. 'bivy run claude --help'.`);
     case "agents:install":
     case "runtimes:install":
       if (args.includes("-h") || args.includes("--help")) {
-        console.log(`Usage: bivy agents:install\n\nInstall bundled agent runtimes (${BUNDLED_AGENTS.map((a) => a.label).join(", ")}).`);
+        console.log(`Usage: bivy agents:install\n\nInstall known agent integrations (${KNOWN_AGENT_INSTALLS.map((a) => a.label).join(", ")}).`);
         break;
       }
       if (!(await ensureDeps())) process.exit(1);
-      await ensureBundledAgents();
+      await ensureKnownAgents();
       break;
     case "open": {
       if (args.includes("-h") || args.includes("--help")) {

package/dist/agent-cli.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+/** First-class BYO-agent convenience CLI backed by the ordinary plugin manifest. */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+import { currentBivyVersion } from "./app-version.js";
+import { defaultDataDir } from "./data-dir.js";
+import { recommendedBivyRange } from "./plugin-sdk/index.js";
+import { installPlugin, listInstalledPlugins, removePlugin } from "./plugins/store.js";
+function option(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+function positional(args) {
+    const valued = new Set(["--command", "--transport", "--adapter", "--args", "--name", "--prompt-mode", "--data-dir"]);
+    const out = [];
+    for (let index = 0; index < args.length; index += 1) {
+        if (valued.has(args[index])) {
+            index += 1;
+            continue;
+        }
+        if (!args[index].startsWith("-"))
+            out.push(args[index]);
+    }
+    return out;
+}
+function fail(message, json) {
+    if (json)
+        console.log(JSON.stringify({ ok: false, error: message }));
+    else
+        console.error(`error: ${message}`);
+    process.exit(1);
+}
+function parseArgs(value) {
+    if (!value)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(value);
+    }
+    catch {
+        throw new Error("--args must be a JSON string array");
+    }
+    if (!Array.isArray(parsed) || !parsed.every((item) => typeof item === "string")) {
+        throw new Error("--args must be a JSON string array");
+    }
+    return parsed;
+}
+function localManifest(args) {
+    const id = positional(args)[1]?.trim().toLowerCase() ?? "";
+    if (!/^[a-z][a-z0-9-]{1,47}$/.test(id))
+        throw new Error("Agent id must be a lowercase slug of 2-48 characters");
+    const command = option(args, "--command")?.trim();
+    if (!command)
+        throw new Error("--command is required");
+    const transport = (option(args, "--transport") ?? option(args, "--adapter") ?? "acp").toLowerCase();
+    if (transport !== "acp" && transport !== "process")
+        throw new Error("--transport must be acp or process");
+    const adapterArgs = parseArgs(option(args, "--args"));
+    const name = option(args, "--name")?.trim() || id.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+    const promptModeValue = option(args, "--prompt-mode") ?? "stdin";
+    if (promptModeValue !== "stdin" && promptModeValue !== "argv")
+        throw new Error("--prompt-mode must be stdin or argv");
+    const promptMode = promptModeValue;
+    return {
+        apiVersion: "bivy.sh/v1alpha1",
+        kind: "Plugin",
+        metadata: {
+            id,
+            name,
+            version: "0.1.0",
+            description: `Local integration for the ${name} agent.`,
+        },
+        requires: { bivy: recommendedBivyRange(currentBivyVersion()) },
+        contributes: {
+            agents: [{
+                    id,
+                    name,
+                    authOwner: "agent",
+                    adapter: transport === "acp"
+                        ? { kind: "acp", command, ...(adapterArgs.length ? { args: adapterArgs } : {}) }
+                        : { kind: "process", command, ...(adapterArgs.length ? { args: adapterArgs } : {}), promptMode },
+                }],
+        },
+    };
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+    const json = args.includes("--json");
+    const dataDir = path.resolve(option(args, "--data-dir") ?? defaultDataDir());
+    if (!command || command === "help" || args.includes("--help") || args.includes("-h")) {
+        console.log(`Usage:
+  bivy agent add <id> --command <command> [--transport acp|process] [--args '["..."]']
+  bivy agent list [--json]
+  bivy agent remove <integration-id>
+
+Adds an existing user-owned agent through the same declarative package contract used by every external integration.`);
+        return;
+    }
+    try {
+        if (command === "add") {
+            const manifest = localManifest(args);
+            const existingPackage = listInstalledPlugins(dataDir).some((plugin) => plugin.id === manifest.metadata.id);
+            if (!existingPackage) {
+                const runtimeModule = await import("./runtime/index.js");
+                const retained = runtimeModule.canonicalAgentId(manifest.contributes.agents[0].id);
+                if (retained)
+                    throw new Error(`Agent id ${manifest.contributes.agents[0].id} conflicts with retained integration ${retained}; choose a unique id`);
+            }
+            const temp = fs.mkdtempSync(path.join(os.tmpdir(), "bivy-agent-add-"));
+            const file = path.join(temp, "bivy.plugin.yaml");
+            try {
+                fs.writeFileSync(file, stringifyYaml(manifest), { mode: 0o600 });
+                const result = installPlugin(file, { dataDir, force: args.includes("--force"), bivyVersion: currentBivyVersion() });
+                const body = { ok: true, id: manifest.metadata.id, path: result.path, replaced: result.replaced, restartRequired: true };
+                if (json)
+                    console.log(JSON.stringify(body, null, 2));
+                else {
+                    console.log(`${result.replaced ? "Updated" : "Added"} agent integration ${manifest.metadata.name} (${manifest.metadata.id}).`);
+                    console.log("Restart Bivy to activate it: bivy restart");
+                }
+            }
+            finally {
+                fs.rmSync(temp, { recursive: true, force: true });
+            }
+            return;
+        }
+        if (command === "list" || command === "ls") {
+            const rows = listInstalledPlugins(dataDir).flatMap((plugin) => plugin.manifest?.contributes.agents.map((agent) => ({
+                id: agent.id,
+                name: agent.name,
+                package: plugin.id,
+                version: plugin.manifest.metadata.version,
+                transport: agent.adapter.kind,
+                command: agent.adapter.command,
+                status: plugin.errors.length ? "invalid" : "installed",
+            })) ?? []);
+            if (json)
+                console.log(JSON.stringify({ ok: true, agents: rows }, null, 2));
+            else if (!rows.length)
+                console.log("No installed agent integration packages.");
+            else
+                for (const row of rows)
+                    console.log(`${row.id}\t${row.transport}\t${row.command}\t${row.package}@${row.version}`);
+            return;
+        }
+        if (command === "remove" || command === "rm") {
+            const id = positional(args)[1];
+            if (!id)
+                fail("Usage: bivy agent remove <integration-id>", json);
+            const installed = listInstalledPlugins(dataDir);
+            const direct = installed.find((plugin) => plugin.id === id);
+            const matches = direct ? [direct] : installed.filter((plugin) => plugin.manifest?.contributes.agents.some((agent) => agent.id === id));
+            if (matches.length > 1)
+                throw new Error(`Agent id ${id} is contributed by multiple invalid packages; remove one with bivy plugin remove <package-id>`);
+            const packageId = matches[0]?.id ?? id;
+            const removed = removePlugin(packageId, dataDir);
+            if (json)
+                console.log(JSON.stringify({ ok: true, id, packageId, removed }));
+            else
+                console.log(removed ? `Removed ${id} (${packageId}). Restart Bivy to deactivate it.` : `Agent integration ${id} is not installed.`);
+            return;
+        }
+        fail(`Unknown agent command: ${command}`, json);
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error), json);
+    }
+}
+await main();

package/dist/agents/claude-code/integration.js

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import { defineAgentIntegration } from "../definition.js";
+import { withExactCapabilitySurface } from "../../runtime/types.js";
+import { ClaudeCodeRuntime, claudeRuntimeFromEnv, claudeSdkInstalled, } from "./runtime.js";
+export const CLAUDE_TESTED_VERSION = "0.3.220";
+const CLAUDE_CAPABILITIES = withExactCapabilitySurface({
+    toolInterception: true,
+    modelSelection: true,
+    packages: false,
+    resume: true,
+    fork: true,
+    usageReporting: true,
+    nativeSessionDiscovery: true,
+    nativeSessionAdoption: true,
+    streamingBehaviors: ["steer"],
+});
+export function claudeCodeIntegration(origin) {
+    return defineAgentIntegration({
+        // Compatibility id retained for existing sessions; aliases expose the agent's
+        // ordinary product/command names without making SDK transport part of the UX.
+        id: "claude-code-sdk",
+        aliases: ["claude", "claude-code"],
+        visible: true,
+        origin,
+        describe: () => {
+            const bridgeInstalled = claudeSdkInstalled();
+            const options = claudeRuntimeFromEnv();
+            const agentInstalled = Boolean(options.executablePath);
+            const installed = bridgeInstalled && agentInstalled;
+            return {
+                id: "claude-code-sdk",
+                executionMode: "protocol",
+                displayName: "Claude Code",
+                description: "The operator-installed Claude Code agent, connected through Anthropic's SDK bridge for streaming, model selection, and governed tool calls.",
+                status: installed ? "available" : "external",
+                packageName: "@anthropic-ai/claude-code",
+                language: "TypeScript",
+                capabilities: { ...CLAUDE_CAPABILITIES, interactiveTui: agentInstalled },
+                nativeSandbox: true,
+                supportTier: "supported",
+                testedVersion: CLAUDE_TESTED_VERSION,
+                source: origin,
+                authOwner: "agent",
+                notes: installed
+                    ? "Uses the Claude Code executable already on this node, including its native auth, configuration, and sessions. Set BIVY_CLAUDE_MODEL to pick a default model."
+                    : agentInstalled
+                        ? "The Claude Code agent is installed, but this Bivy distribution is missing its SDK bridge dependency."
+                        : "Install and sign in to Claude Code on this node; Bivy will connect to that existing agent.",
+                install: installed || agentInstalled ? undefined : {
+                    label: "Install Claude Code",
+                    description: "Installs Anthropic's Claude Code agent on this node.",
+                    command: "npm install --global @anthropic-ai/claude-code",
+                },
+            };
+        },
+        create: (sessionOptions) => {
+            const options = claudeRuntimeFromEnv();
+            if (!options.executablePath)
+                throw new Error("Claude Code command not found on PATH: claude");
+            return new ClaudeCodeRuntime({
+                ...options,
+                sandbox: sessionOptions.sandbox,
+                attachToChat: sessionOptions.attachToChat,
+            });
+        },
+        install: (prefix) => ({
+            command: "npm",
+            args: ["install", "--global", "--prefix", prefix, "@anthropic-ai/claude-code"],
+            display: `npm install --global --prefix ${prefix} @anthropic-ai/claude-code`,
+        }),
+    });
+}