@bivy/bivy 0.21.1 → 0.21.2-staging.10

package/bin/archive-install.mjs

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+/**
+ * Install and update from the self-contained GitHub release archives
+ * (scripts/release-archives.mjs). Layout under the install root
+ * (default ~/.local/share/bivy):
+ *
+ *   versions/<version>-<target>/   one extracted archive each
+ *   current -> versions/…          the active one, swapped atomically
+ *
+ * The launcher (current/bin/bivy) passes its unresolved `current` path as
+ * BIVY_ARCHIVE_ROOT, so a service unit or shim written through it keeps
+ * working after `current` moves to a new version.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+
+export const RELEASES_URL = "https://github.com/bivysh/bivy/releases";
+export const ARCHIVE_INFO = "bivy-archive.json";
+/** Versions kept on disk: the active one and the one before it, for rollback. */
+const KEEP = 2;
+
+/** "linux-x64" etc.: the archive target for this machine, or undefined. */
+export function archiveTarget(platform = process.platform, arch = process.arch) {
+  return ["linux", "darwin"].includes(platform) && ["x64", "arm64"].includes(arch) ? `${platform}-${arch}` : undefined;
+}
+
+/** Where a channel's manifest and archives live. `latest` is the newest stable release. */
+export function channelUrls(channel, base = process.env.BIVY_RELEASES_URL || RELEASES_URL) {
+  const dir = channel === "latest" ? `${base}/latest/download` : `${base}/download/${encodeURIComponent(channel)}`;
+  return {
+    manifest: `${dir}/manifest.json`,
+    // Stable archives are fetched from their own tag, so a release published
+    // mid-update can't swap the file under a manifest read a moment earlier.
+    archive: (manifest, file) => (channel === "latest" ? `${base}/download/v${manifest.version}/${file}` : `${dir}/${file}`),
+  };
+}
+
+/**
+ * The archive install this CLI runs from, or null. `archiveRoot` is the
+ * launcher's BIVY_ARCHIVE_ROOT; it only counts when it really is the install
+ * holding `appRoot`, so a value inherited into some other checkout is ignored.
+ */
+export function archiveInstall(archiveRoot, appRoot) {
+  if (!archiveRoot) return null;
+  try {
+    if (fs.realpathSync(path.join(archiveRoot, "app")) !== fs.realpathSync(appRoot)) return null;
+    const info = JSON.parse(fs.readFileSync(path.join(archiveRoot, ARCHIVE_INFO), "utf8"));
+    // Run as current/bin/bivy or as versions/<v>/bin/bivy, the install root is
+    // the same, and `current` is the path worth writing down.
+    const parent = path.dirname(archiveRoot);
+    const installRoot = path.basename(archiveRoot) === "current" ? parent : path.basename(parent) === "versions" ? path.dirname(parent) : undefined;
+    // An archive unpacked anywhere else runs, but has no install to update.
+    const current = path.join(installRoot ?? "", "current");
+    if (!installRoot || !fs.existsSync(current)) return null;
+    // Run through `current`, write `current`; a specific version (say, a new one
+    // being checked before the swap) stays itself.
+    const root = fs.realpathSync(archiveRoot) === fs.realpathSync(current) ? current : archiveRoot;
+    return { root, installRoot, version: info.version, target: info.target };
+  } catch {
+    return null;
+  }
+}
+
+export async function fetchManifest(url, fetchImpl = fetch) {
+  const res = await fetchImpl(url, { signal: AbortSignal.timeout(15_000) });
+  if (!res.ok) throw new Error(`Could not read the release manifest (${res.status} from ${url})`);
+  const manifest = await res.json();
+  if (typeof manifest?.version !== "string" || !manifest.archives) throw new Error(`${url} is not a Bivy release manifest`);
+  return manifest;
+}
+
+/**
+ * Fetch a large file with curl. Node's fetch can abort the process on an
+ * assertion when a server closes the connection while the body is paused
+ * for backpressure; curl is on every machine install.sh runs on.
+ */
+export function curlDownload(url, dest) {
+  const res = spawnSync("curl", ["-fsSL", "--retry", "2", "-o", dest, url], { encoding: "utf8" });
+  if (res.status !== 0) throw new Error(`Could not download ${url}: ${(res.stderr || "").trim() || `curl exit ${res.status}`}`);
+}
+
+/**
+ * Download, verify and extract one archive into versions/. Returns its
+ * directory. Nothing outside versions/ changes, so a failure here leaves the
+ * running install untouched.
+ */
+export async function stageArchive({ installRoot, manifest, target, archiveUrl, download = curlDownload }) {
+  const entry = manifest.archives[target];
+  if (!entry) throw new Error(`Bivy ${manifest.version} has no archive for ${target}`);
+  const versions = path.join(installRoot, "versions");
+  fs.mkdirSync(versions, { recursive: true });
+  const work = fs.mkdtempSync(path.join(versions, ".stage-"));
+  try {
+    const tarball = path.join(work, entry.file);
+    await download(archiveUrl(manifest, entry.file), tarball);
+    const sha256 = crypto.createHash("sha256").update(fs.readFileSync(tarball)).digest("hex");
+    if (sha256 !== entry.sha256) throw new Error(`${entry.file} failed verification: sha256 ${sha256}, the manifest says ${entry.sha256}`);
+
+    const tar = spawnSync("tar", ["-xzf", tarball, "-C", work], { encoding: "utf8" });
+    if (tar.status !== 0) throw new Error(`Could not extract ${entry.file}: ${tar.stderr}`);
+    const extracted = path.join(work, entry.file.replace(/\.tar\.gz$/, ""));
+    const info = JSON.parse(fs.readFileSync(path.join(extracted, ARCHIVE_INFO), "utf8"));
+    if (info.version !== manifest.version || info.target !== target) throw new Error(`${entry.file} holds ${info.version} ${info.target}, not ${manifest.version} ${target}`);
+
+    const dest = path.join(versions, `${manifest.version}-${target}`);
+    // Re-staging a version (a reinstall) must not replace the directory `current`
+    // points at while it runs; move it aside first and drop it afterwards.
+    const aside = fs.existsSync(dest) ? `${dest}.old-${process.pid}` : undefined;
+    if (aside) fs.renameSync(dest, aside);
+    fs.renameSync(extracted, dest);
+    if (aside) fs.rmSync(aside, { recursive: true, force: true });
+    return dest;
+  } finally {
+    fs.rmSync(work, { recursive: true, force: true });
+  }
+}
+
+/** The version directory `current` points at, or undefined. */
+export function activeVersion(installRoot) {
+  try {
+    return path.resolve(installRoot, fs.readlinkSync(path.join(installRoot, "current")));
+  } catch {
+    return undefined;
+  }
+}
+
+/** Point `current` at a version directory atomically. Returns what it pointed at before. */
+export function activate(installRoot, versionDir) {
+  const previous = activeVersion(installRoot);
+  const link = path.join(installRoot, "current");
+  const next = `${link}.next-${process.pid}`;
+  fs.rmSync(next, { force: true });
+  fs.symlinkSync(path.relative(installRoot, versionDir), next);
+  fs.renameSync(next, link);
+  return previous;
+}
+
+/** Remove version directories other than the newest KEEP, never the active one. */
+export function prune(installRoot, keep = []) {
+  const versions = path.join(installRoot, "versions");
+  const active = activeVersion(installRoot);
+  const kept = new Set([...new Set([active, ...keep].filter(Boolean).map((p) => path.resolve(p)))].slice(0, KEEP));
+  for (const name of fs.readdirSync(versions)) {
+    const dir = path.join(versions, name);
+    if (!kept.has(dir)) fs.rmSync(dir, { recursive: true, force: true });
+  }
+}

package/bin/bivy.mjs

@@ -45,11 +45,16 @@ import { parseTailscaleStatus, serveConflict, serveFailureHint, serveOffArgs, se
 import { resolveAttachSessionId } from "./attach-session-id.mjs";
 import { detectInstallKind as classifyInstallKind, managedInstall, npmGlobalPrefix } from "./install-kind.mjs";
 import { hasConfiguredService as configuredServiceExists } from "./service-state.mjs";
+import { activate, activeVersion, archiveInstall, archiveTarget, channelUrls, fetchManifest, prune, stageArchive } from "./archive-install.mjs";
 import { COMMANDS, EXIT, cliError, completionWords, describeCli, describeCommand, describeTools, renderHelp, resolveCommand, subcommandTable, suggestCommands, toolArgv, wantsJson } from "./cli-commands.mjs";
 
-const selfScript = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(selfScript);
-const repoRoot = path.resolve(__dirname, "..");
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// A GitHub release archive install runs through its launcher, which names the
+// install's `current` path. Paths written to disk (service unit, shims) use it,
+// so they stay valid when an update points `current` at a new version.
+const archive = archiveInstall(process.env.BIVY_ARCHIVE_ROOT, path.resolve(__dirname, ".."));
+const repoRoot = archive ? path.join(archive.root, "app") : path.resolve(__dirname, "..");
+const selfScript = path.join(repoRoot, "bin", "bivy.mjs");
 // Mutable node state (config, relay E2E keys, sessions, logs) must live in a
 // stable, user-owned directory that survives reinstalls. Pick it by install type:
 //   - BIVY_DATA_DIR set                         -> honor it (explicit override)
@@ -77,10 +82,11 @@ process.env.BIVY_DATA_DIR = appDir;
 //   - "git"        dev checkout (has .git)
 //   - "npx"        ephemeral `npx bivy` run (repoRoot under an npm _npx cache)
 //   - "npm-global" `npm i -g @bivy/bivy` (repoRoot is below node_modules/@bivy)
+//   - "archive"    a GitHub release archive under ~/.local/share/bivy (install.sh)
 //   - "packaged"   install.sh tarball tree (user-owned, self-preserving)
 //   - "managed"    a system package (the AUR's `bivy`), updated by its manager
 function detectInstallKind() {
-  return classifyInstallKind(repoRoot);
+  return archive ? "archive" : classifyInstallKind(repoRoot);
 }
 const cliConfigPath = path.join(appDir, "cli.json");
 const canonicalConfigPath = path.join(appDir, "config.yaml");
@@ -185,7 +191,7 @@ const mcpProxyEntry = path.join(repoRoot, packaged ? "dist/harness/mcp-proxy-cli
 const mcpServeEntry = path.join(repoRoot, packaged ? "dist/harness/mcp-serve-cli.js" : "src/harness/mcp-serve-cli.ts");
 const qrEntry = path.join(repoRoot, "public", "qr.js");
 const tsxCli = packaged ? "" : path.join(repoRoot, "node_modules", "tsx", "dist", "cli.mjs");
-const nodeBin = process.execPath;
+const nodeBin = archive ? path.join(archive.root, "runtime", "bin", "node") : process.execPath;
 const nodeScriptArgs = (entry) => (tsxCli ? [tsxCli, entry] : [entry]);
 
 // Resolve the baked-in hosted endpoints (app/relay/client URLs). Imported lazily
@@ -230,7 +236,7 @@ function commandPath(extraPath = "") {
     process.env.PATH || "",
     // npm global executables normally live beside the Node binary (including
     // nvm/fnm installs). Services need this even without shell initialization.
-    path.dirname(process.execPath),
+    path.dirname(nodeBin),
   ].filter(Boolean);
   return [...new Set(parts.flatMap((part) => String(part).split(path.delimiter)).filter(Boolean))].join(path.delimiter);
 }
@@ -4065,6 +4071,7 @@ function plistContent(config) {
     PORT: String(config.port),
     BIVY_WORKSPACE: config.workspace,
     BIVY_DATA_DIR: appDir,
+    ...(archive ? { BIVY_ARCHIVE_ROOT: archive.root } : {}),
     ...config.env,
     PATH: commandPath(config.env?.PATH),
   })
@@ -4109,6 +4116,7 @@ function systemdContent(config) {
     PORT: String(config.port),
     BIVY_WORKSPACE: config.workspace,
     BIVY_DATA_DIR: appDir,
+    ...(archive ? { BIVY_ARCHIVE_ROOT: archive.root } : {}),
     ...config.env,
     PATH: commandPath(config.env?.PATH),
   })
@@ -4301,7 +4309,9 @@ async function restartServiceReconciled(config) {
   // A typed config edit may change workspace, port, or environment without
   // touching the old unit. Reinstall on content drift so `bivy restart` really
   // applies the canonical file instead of reviving stale baked-in values.
-  if (portChanged || configChanged) return await installService(config);
+  // installService only *starts* the unit (`enable --now`, `launchctl load`),
+  // which leaves an already-running node on its old code; restart it as well.
+  if (portChanged || configChanged) return (await installService(config)) && restartService();
   return restartService();
 }
 
@@ -5515,6 +5525,49 @@ async function cmdUpdate(args = []) {
   await runUpdate(args);
 }
 
+/**
+ * Update a GitHub release archive install: stage the channel's archive beside
+ * the running one, point `current` at it, restart, and point `current` back if
+ * the node doesn't come up. The version before stays on disk for that.
+ */
+async function updateArchiveInstall(channel, { skipWait, force }) {
+  const urls = channelUrls(channel);
+  const target = archiveTarget();
+  console.log(c.dim(`Checking ${urls.manifest} (channel: ${channel})…`));
+  const manifest = await fetchManifest(urls.manifest);
+  if (manifest.version === archive.version && !force) {
+    console.log(c.green(`Bivy ${archive.version} is the newest on ${channel}.`));
+    return;
+  }
+  console.log(c.dim(`Downloading Bivy ${manifest.version} for ${target}…`));
+  const staged = await stageArchive({ installRoot: archive.installRoot, manifest, target, archiveUrl: urls.archive });
+  const probe = runQuiet(path.join(staged, "bin", "bivy"), ["--version"]);
+  if (probe.code !== 0 || probe.stdout.trim() !== manifest.version) {
+    throw new Error(`The downloaded Bivy ${manifest.version} does not run here (${(probe.stderr || probe.stdout).trim() || `exit ${probe.code}`}); kept ${archive.version}.`);
+  }
+  const config = loadConfig();
+  await waitForIdleSessions(config, { skip: skipWait });
+  const previous = activate(archive.installRoot, staged);
+  if (!hasConfiguredService(config)) {
+    prune(archive.installRoot, [staged, previous]);
+    console.log(c.green(`Updated to ${manifest.version}. Run 'bivy start' to use it.`));
+    return;
+  }
+  if ((await restartServiceReconciled(config)) && (await verifyNodeCameUp(config))) {
+    prune(archive.installRoot, [staged, previous]);
+    console.log(c.green(`Updated ${archive.version} → ${manifest.version} and restarted the background service.`));
+    return;
+  }
+  if (previous && previous !== activeVersion(archive.installRoot)) {
+    activate(archive.installRoot, previous);
+    await restartServiceReconciled(config);
+    console.log(c.red(`⚠ Bivy ${manifest.version} did not come up, so ${archive.version} is back in place.`));
+  } else {
+    reportNodeDidNotStart();
+  }
+  process.exitCode = 1;
+}
+
 async function runUpdate(args = []) {
   const skipWait = args.includes("--force") || args.includes("--no-wait");
   const kind = detectInstallKind();
@@ -5564,6 +5617,12 @@ async function runUpdate(args = []) {
     return;
   }
 
+  if (kind === "archive") {
+    await updateArchiveInstall(channel, { skipWait, force: args.includes("--force") });
+    console.log(c.dim(`=== bivy update finished ${new Date().toISOString()} ===`));
+    return;
+  }
+
   if (kind === "packaged") {
     console.log(c.dim(`Updating packaged Bivy install (channel: ${channel})…`));
     // The actual restart happens inside install.sh, which shells out to

package/bin/cli-commands.mjs

@@ -129,7 +129,7 @@ export const COMMANDS = [
 
   // Help and discovery
   { name: "guide", group: "help", scope: "node", json: true, usage: "guide [topic] [--json]", summary: "Short playbooks for agents: show the user, talk to them, long work, more hands, automate",
-    tools: [{ name: "bivy_guide", description: "Short playbooks for working in Bivy. Without a topic, lists them.", input: { topic: { type: "string", description: "show-the-user, talk-to-the-user, long-work, more-hands or automate." } }, argv: ["guide", { arg: "topic" }] }] },
+    tools: [{ name: "bivy_guide", description: "Short playbooks for working in Bivy. Without a topic, lists them.", input: { topic: { type: "string", description: "show-the-user, talk-to-the-user, long-work, more-hands, automate or add-an-agent." } }, argv: ["guide", { arg: "topic" }] }] },
   { name: "help", aliases: ["-h", "--help"], group: "help", scope: "node", json: true, usage: "help [command] [--json]", summary: "Show this help, one command's row, or every command as JSON" },
   { name: "version", aliases: ["--version", "-v"], group: "help", scope: "node", usage: "version", summary: "Print the installed Bivy version" },
 

package/bin/guides/add-an-agent.md

@@ -0,0 +1,39 @@
+# Add an agent: any ACP agent or CLI
+
+Summary: Make another coding agent available in Bivy, writing a small adapter when its CLI needs one.
+
+An agent with an ACP mode needs only its command:
+
+    bivy agent add gemini-acp --command gemini --args '["--experimental-acp"]'
+
+Any other CLI that takes a prompt on stdin (or as its last argument with
+`--prompt-mode argv`):
+
+    bivy agent add review-bot --transport process --command review-bot --args '["run"]'
+
+It is in the picker at once. Check it with one real turn, which prints the answer:
+
+    bivy exec -a gemini-acp "Say hello"
+
+When the CLI's output needs translating, write an adapter: a program Bivy runs
+once per turn with the prompt on stdin. It prints one JSON event per line:
+
+    {"type":"session.started","sessionId":"abc"}     # passed back as {id} to resume
+    {"type":"message.reasoning","text":"…"}
+    {"type":"tool.call","toolCallId":"t1","name":"bash","input":{"command":"ls"}}
+    {"type":"tool.result","toolCallId":"t1","result":"…"}
+    {"type":"message.delta","text":"The answer…"}
+    {"type":"usage","tokens":{"input_tokens":10,"output_tokens":20}}
+    {"type":"session.done"}                          # or {"type":"session.error","error":"…"}
+
+Start from examples/agents/jsonl-adapter/adapter.mjs in the Bivy repo, then:
+
+    bivy agent add my-agent --transport process --parser bivy-protocol \
+      --command "$PWD/adapter.mjs" --resume-args '["--resume","{id}"]'
+    bivy exec -a my-agent "List the files here"
+
+These events report what the agent did; they cannot ask before a tool runs. For
+approvals, the adapter must speak ACP (`--transport acp`).
+
+The entry lives under `agents:` in the node's config.yaml (`bivy agent list`,
+`bivy agent remove <id>`). The full format is in docs/add-an-agent.md.

package/bin/prune-sessions.mjs

@@ -68,23 +68,55 @@ export function linkSessionWorktrees({ sessions, staleSessions, staleWorktrees,
   return { sessions: sorted, worktrees: [...removeWorktrees] };
 }
 
-// Removal set for sessions. Live ("working") sessions are never touched. The
-// newest `keep` NON-EMPTY sessions (across every agent) survive; empty/untitled
-// sessions are always beyond the keep window. An item is removed only when it is
-// BOTH beyond the keep window AND older than `ageMs` — the same safe intersection
-// as the file-based selectStale, so keep-only and age-only both behave sensibly.
-// `keep`/`ageMs` of null disable that half of the test.
+// Delegated child sessions (sub-agents, `delegatedFrom`) belong to the session
+// that started them, as the sidebar nests them. Groups sessions into families
+// keyed by the top-most listed ancestor; a child whose parent isn't listed is
+// its own root.
+function sessionFamilies(sessions) {
+  const byId = new Map(sessions.map((s) => [s.id, s]));
+  const rootOf = (s) => {
+    const seen = new Set([s.id]);
+    let cur = s;
+    for (;;) {
+      const parent = byId.get(cur.delegatedFrom?.sessionId);
+      if (!parent || seen.has(parent.id)) return cur.id;
+      seen.add(parent.id);
+      cur = parent;
+    }
+  };
+  const families = new Map();
+  for (const s of sessions) {
+    const root = rootOf(s);
+    families.set(root, [...(families.get(root) ?? []), s]);
+  }
+  return [...families.values()];
+}
+
+// Removal set for sessions. A parent and its sub-agent sessions are judged as one
+// unit: the family's activity is its newest member's, it is live if any member is
+// working, and it is empty only if every member is. So sub-agents never take
+// keep slots from real sessions, and a recent child keeps its parent (and vice
+// versa). Live families are never touched. The newest `keep` NON-EMPTY families
+// survive; empty ones are always beyond the keep window. A family is removed only
+// when it is BOTH beyond the keep window AND older than `ageMs` — the same safe
+// intersection as the file-based selectStale. `keep`/`ageMs` of null disable that
+// half of the test.
 export function selectStaleSessions(sessions, keep, ageMs, now) {
-  const eligible = sessions.filter((s) => s.status !== "working");
-  const nonEmptyDesc = eligible
-    .filter((s) => !isEmptySession(s))
-    .sort((a, b) => sessionActivityMs(b) - sessionActivityMs(a));
-  const rank = new Map(nonEmptyDesc.map((s, i) => [s.id, i]));
+  const eligible = sessionFamilies(sessions)
+    .filter((members) => !members.some((s) => s.status === "working"))
+    .map((members) => ({
+      members,
+      activity: Math.max(...members.map(sessionActivityMs)),
+      empty: members.every(isEmptySession),
+    }));
+  const nonEmptyDesc = eligible.filter((f) => !f.empty).sort((a, b) => b.activity - a.activity);
+  const rank = new Map(nonEmptyDesc.map((f, i) => [f, i]));
   return eligible
-    .filter((s) => {
-      const beyondKeep = keep === null ? true : (isEmptySession(s) ? true : (rank.get(s.id) ?? Infinity) >= keep);
-      const olderThan = ageMs === null ? true : now - sessionActivityMs(s) >= ageMs;
+    .filter((f) => {
+      const beyondKeep = keep === null ? true : (f.empty ? true : rank.get(f) >= keep);
+      const olderThan = ageMs === null ? true : now - f.activity >= ageMs;
       return beyondKeep && olderThan;
     })
+    .flatMap((f) => f.members)
     .sort((a, b) => sessionActivityMs(b) - sessionActivityMs(a));
 }

package/dist/agent-cli.js

@@ -1,21 +1,18 @@
 #!/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. */
+/** First-class bring-your-own-agent CLI: writes `agents:` in the node config.yaml. */
 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";
+import { mergeLegacyIntoNodeConfig, nodeConfigPath, readNodeConfig, writeNodeConfig } from "./node-config.js";
+import { 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 valued = new Set(["--command", "--transport", "--adapter", "--args", "--name", "--prompt-mode", "--parser", "--resume-args", "--data-dir"]);
     const out = [];
     for (let index = 0; index < args.length; index += 1) {
         if (valued.has(args[index])) {
@@ -42,17 +39,35 @@ function parseArgs(value) {
         parsed = JSON.parse(value);
     }
     catch {
-        throw new Error("--args must be a JSON string array");
+        throw new Error("--args and --resume-args must be JSON string arrays");
     }
     if (!Array.isArray(parsed) || !parsed.every((item) => typeof item === "string")) {
-        throw new Error("--args must be a JSON string array");
+        throw new Error("--args and --resume-args must be JSON string arrays");
     }
     return parsed;
 }
-function localManifest(args) {
+function readJson(dataDir, name) {
+    try {
+        const value = JSON.parse(fs.readFileSync(path.join(dataDir, name), "utf8"));
+        return value && typeof value === "object" ? value : {};
+    }
+    catch {
+        return {};
+    }
+}
+/** The node's config.yaml, or the one the daemon would create from legacy files
+ *  — never a bare file that would skip that migration. */
+function nodeConfig(dataDir) {
+    return readNodeConfig(dataDir) ?? mergeLegacyIntoNodeConfig(readJson(dataDir, "cli.json"), readJson(dataDir, "settings.json"));
+}
+function agentId(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");
+    return id;
+}
+/** `bivy agent add` flags → the `adapter` block config.yaml and plugins share. */
+function agentConfig(args, id) {
     const command = option(args, "--command")?.trim();
     if (!command)
         throw new Error("--command is required");
@@ -61,29 +76,26 @@ function localManifest(args) {
         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")
+    if (transport === "acp") {
+        for (const flag of ["--prompt-mode", "--parser", "--resume-args"])
+            if (option(args, flag))
+                throw new Error(`${flag} applies to --transport process only`);
+        return { name, adapter: { kind: "acp", command, ...(adapterArgs.length ? { args: adapterArgs } : {}) } };
+    }
+    const promptMode = option(args, "--prompt-mode") ?? "stdin";
+    if (promptMode !== "stdin" && promptMode !== "argv")
         throw new Error("--prompt-mode must be stdin or argv");
-    const promptMode = promptModeValue;
+    const parser = option(args, "--parser");
+    const resumeArgs = option(args, "--resume-args");
     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 },
-                }],
+        name,
+        adapter: {
+            kind: "process",
+            command,
+            ...(adapterArgs.length ? { args: adapterArgs } : {}),
+            promptMode,
+            ...(parser ? { structured: { args: adapterArgs, parser } } : {}),
+            ...(resumeArgs ? { resume: { args: parseArgs(resumeArgs) } } : {}),
         },
     };
 }
@@ -94,64 +106,80 @@ async function main() {
     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 add <id> --command <command> [--args '["..."]'] [--name <name>] [--force]
+      ACP agent (default):  --transport acp
+      Any other CLI:        --transport process [--prompt-mode stdin|argv]
+                            [--parser <id>] [--resume-args '["...","{id}"]']
   bivy agent list [--json]
-  bivy agent remove <integration-id>
+  bivy agent remove <id>
 
-Adds an existing user-owned agent through the same declarative package contract used by every external integration.`);
+Agents are saved under agents: in <data-dir>/config.yaml and appear in the
+picker right away. Edit that file directly for every adapter option.`);
         return;
     }
     try {
         if (command === "add") {
-            const manifest = localManifest(args);
-            const existingPackage = listInstalledPlugins(dataDir).some((plugin) => plugin.id === manifest.metadata.id);
-            if (!existingPackage) {
+            const id = agentId(args);
+            const spec = agentConfig(args, id);
+            const config = nodeConfig(dataDir);
+            const replaced = Boolean(config.agents?.[id]);
+            if (replaced && !args.includes("--force"))
+                throw new Error(`Agent ${id} is already configured; pass --force to replace it`);
+            if (!replaced) {
                 const runtimeModule = await import("./runtime/index.js");
-                const retained = runtimeModule.canonicalAgentId(manifest.contributes.agents[0].id);
+                const retained = runtimeModule.canonicalAgentId(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 });
+                    throw new Error(`Agent id ${id} conflicts with ${retained}; choose a unique id`);
             }
+            writeNodeConfig(dataDir, { ...config, agents: { ...config.agents, [id]: spec } });
+            const body = { ok: true, id, path: nodeConfigPath(dataDir), replaced };
+            if (json)
+                console.log(JSON.stringify(body, null, 2));
+            else
+                console.log(`${replaced ? "Updated" : "Added"} ${"name" in spec ? spec.name : id} (${id}). It is in the agent picker now.`);
             return;
         }
         if (command === "list" || command === "ls") {
-            const rows = listInstalledPlugins(dataDir).flatMap((plugin) => plugin.manifest?.contributes.agents.map((agent) => ({
+            const configured = Object.entries(readNodeConfig(dataDir)?.agents ?? {}).map(([id, spec]) => ({
+                id,
+                name: "adapter" in spec ? spec.name ?? id : spec.label ?? id,
+                source: "config",
+                transport: "adapter" in spec ? spec.adapter.kind : `extends ${spec.extends}`,
+                command: "adapter" in spec ? spec.adapter.command : spec.command ?? spec.extends,
+            }));
+            const packaged = listInstalledPlugins(dataDir).flatMap((plugin) => plugin.manifest?.contributes.agents.map((agent) => ({
                 id: agent.id,
                 name: agent.name,
-                package: plugin.id,
-                version: plugin.manifest.metadata.version,
+                source: `${plugin.id}@${plugin.manifest.metadata.version}`,
                 transport: agent.adapter.kind,
                 command: agent.adapter.command,
-                status: plugin.errors.length ? "invalid" : "installed",
+                ...(plugin.errors.length ? { status: "invalid" } : {}),
             })) ?? []);
+            const rows = [...configured, ...packaged];
             if (json)
                 console.log(JSON.stringify({ ok: true, agents: rows }, null, 2));
             else if (!rows.length)
-                console.log("No installed agent integration packages.");
+                console.log("No agents added on this machine. Add one with: bivy agent add <id> --command <command>");
             else
                 for (const row of rows)
-                    console.log(`${row.id}\t${row.transport}\t${row.command}\t${row.package}@${row.version}`);
+                    console.log(`${row.id}\t${row.transport}\t${row.command}\t${row.source}`);
             return;
         }
         if (command === "remove" || command === "rm") {
             const id = positional(args)[1];
             if (!id)
-                fail("Usage: bivy agent remove <integration-id>", json);
+                fail("Usage: bivy agent remove <id>", json);
+            const config = readNodeConfig(dataDir);
+            if (config?.agents?.[id]) {
+                const { [id]: _removed, ...agents } = config.agents;
+                writeNodeConfig(dataDir, { ...config, agents });
+                if (json)
+                    console.log(JSON.stringify({ ok: true, id, removed: true }));
+                else
+                    console.log(`Removed ${id}.`);
+                return;
+            }
+            // Agents added before config.yaml held them were single-agent plugin packages.
             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));
@@ -162,7 +190,7 @@ Adds an existing user-owned agent through the same declarative package contract
             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.`);
+                console.log(removed ? `Removed ${id} (${packageId}).` : `Agent ${id} is not configured.`);
             return;
         }
         fail(`Unknown agent command: ${command}`, json);