@bivy/bivy 0.21.2-staging.1 → 0.21.2-staging.2

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/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);

package/dist/node-config.js

@@ -4,6 +4,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { parseAgentAdapter } from "./plugin-sdk/manifest.js";
 export const NODE_CONFIG_FILE = "config.yaml";
 export const NODE_CONFIG_VERSION = 1;
 const ROOT_KEYS = ["version", "node", "defaults", "safety", "sessions", "github", "automation", "agents", "environment"];
@@ -170,6 +171,23 @@ export function validateNodeConfig(value) {
             errors.push(`${at} must be an object`);
             continue;
         }
+        if (spec.adapter !== undefined) {
+            unknownKeys(spec, ["name", "description", "hidden", "authOwner", "adapter"], at, errors);
+            const adapter = parseAgentAdapter(spec.adapter, `${at}.adapter`, errors);
+            const authOwner = spec.authOwner;
+            if (authOwner !== undefined && authOwner !== "agent" && authOwner !== "bivy" && authOwner !== "mixed")
+                errors.push(`${at}.authOwner must be agent, bivy, or mixed`);
+            const name = optionalString(spec.name, `${at}.name`, errors, 120);
+            const description = optionalString(spec.description, `${at}.description`, errors, 500);
+            const hidden = optionalBoolean(spec.hidden, `${at}.hidden`, errors);
+            if (adapter)
+                agents[id] = { name, description, hidden, authOwner, adapter };
+            continue;
+        }
+        if (spec.extends === undefined) {
+            errors.push(`${at} needs an adapter (any ACP or CLI command) or extends (a maintained agent id)`);
+            continue;
+        }
         unknownKeys(spec, ["extends", "label", "command", "args", "jsonArgs", "parserId", "promptMode", "hidden"], at, errors);
         const extend = optionalString(spec.extends, `${at}.extends`, errors, 80);
         const list = (value, key) => {

package/dist/plugin-cli.js

@@ -247,13 +247,13 @@ export async function main(argv = process.argv.slice(2)) {
             if (!input)
                 fail("Usage: bivy plugin install <path> [--force]", json);
             const result = installPlugin(input, { dataDir, force: args.includes("--force") });
-            const body = { ok: true, installed: result.manifest.metadata.id, version: result.manifest.metadata.version, path: result.path, replaced: result.replaced, restartRequired: true };
+            const body = { ok: true, installed: result.manifest.metadata.id, version: result.manifest.metadata.version, path: result.path, replaced: result.replaced };
             if (json)
                 outputJson(body);
             else {
                 console.log(`${result.replaced ? "Updated" : "Installed"} ${result.manifest.metadata.name} (${result.manifest.metadata.id}@${result.manifest.metadata.version}).`);
                 console.log(`Stored at ${result.path}`);
-                console.log("Restart Bivy to activate it: bivy restart");
+                console.log("It is in the agent picker now.");
             }
             return;
         }
@@ -300,12 +300,11 @@ export async function main(argv = process.argv.slice(2)) {
             const removed = removePlugin(id, dataDir);
             if (!removed)
                 fail(`Plugin ${id} is not installed`, json);
-            const body = { ok: true, removed: id, restartRequired: true };
+            const body = { ok: true, removed: id };
             if (json)
                 outputJson(body);
             else {
                 console.log(`Removed plugin ${id}.`);
-                console.log("Restart Bivy to unload it: bivy restart");
             }
             return;
         }

package/dist/plugin-sdk/manifest.js

@@ -179,6 +179,21 @@ function parseAcpAdapter(raw, at, errors) {
     const args = stringList(raw.args, `${at}.args`, errors);
     return command ? { kind: "acp", command, ...(args ? { args } : {}) } : undefined;
 }
+/** Validate one `adapter` block. Plugin manifests and node `config.yaml` agents
+ *  share it, so an agent is described the same way wherever it is declared. */
+export function parseAgentAdapter(value, at, errors) {
+    const raw = object(value);
+    if (!raw) {
+        errors.push(`${at} must be an object`);
+        return undefined;
+    }
+    if (raw.kind === "process")
+        return parseProcessAdapter(raw, at, errors);
+    if (raw.kind === "acp")
+        return parseAcpAdapter(raw, at, errors);
+    errors.push(`${at}.kind must be process or acp`);
+    return undefined;
+}
 function parseAgent(value, index, errors) {
     const at = `contributes.agents[${index}]`;
     const raw = object(value);
@@ -198,16 +213,7 @@ function parseAgent(value, index, errors) {
     if (authOwner !== undefined && authOwner !== "agent" && authOwner !== "bivy" && authOwner !== "mixed") {
         errors.push(`${at}.authOwner must be agent, bivy, or mixed`);
     }
-    const adapterRaw = object(raw.adapter);
-    let adapter;
-    if (!adapterRaw)
-        errors.push(`${at}.adapter must be an object`);
-    else if (adapterRaw.kind === "process")
-        adapter = parseProcessAdapter(adapterRaw, `${at}.adapter`, errors);
-    else if (adapterRaw.kind === "acp")
-        adapter = parseAcpAdapter(adapterRaw, `${at}.adapter`, errors);
-    else
-        errors.push(`${at}.adapter.kind must be process or acp`);
+    const adapter = parseAgentAdapter(raw.adapter, `${at}.adapter`, errors);
     if (!id || !name || !adapter)
         return undefined;
     return {
@@ -351,5 +357,7 @@ export function recommendedBivyRange(currentVersion) {
     const parsed = parseSemver(currentVersion);
     if (!parsed)
         throw new Error(`Cannot generate a compatibility range from invalid Bivy version ${currentVersion}`);
-    return `>=${parsed.major}.${parsed.minor}.${parsed.patch} <${parsed.major}.${parsed.minor + 1}.0`;
+    // The manifest contract is versioned by apiVersion, so a plugin keeps working
+    // across Bivy minor releases; only a major release may break it.
+    return `>=${parsed.major}.${parsed.minor}.${parsed.patch} <${parsed.major + 1}.0.0`;
 }

package/dist/runtime/cli-parsers.js

@@ -241,6 +241,7 @@ export function bivyProtocolParser() {
     // appended verbatim (a shim emits an explicit break when it wants one), so it
     // opts out of inferred segment boundaries.
     const acc = new TurnAccumulator({ provider: "bivy-protocol", protocol: "protocol" }, false);
+    let sessionRef;
     return {
         onLine(line) {
             const events = [];
@@ -255,9 +256,23 @@ export function bivyProtocolParser() {
                 return events; // ignore non-JSON noise (banners etc.)
             }
             const type = String(msg.type ?? "");
-            if (type === "message.delta") {
+            if (type === "session.started") {
+                // The adapter's own conversation id; `resume.args` gets it back as {id}.
+                if (typeof msg.sessionId === "string" && msg.sessionId.trim())
+                    sessionRef = msg.sessionId.trim();
+            }
+            else if (type === "message.delta") {
                 acc.appendText(String(msg.text ?? ""), events);
             }
+            else if (type === "message.reasoning") {
+                acc.appendReasoning(String(msg.text ?? ""), events);
+            }
+            else if (type === "usage") {
+                const tokens = extractTokenUsage(msg.tokens ?? msg);
+                const costUsd = typeof msg.costUsd === "number" ? { costUsd: msg.costUsd } : {};
+                if (tokens || costUsd.costUsd !== undefined)
+                    acc.addUsage({ ...tokens, ...costUsd });
+            }
             else if (type === "session.status") {
                 const status = String(msg.status ?? "");
                 if (status === "working")
@@ -288,6 +303,8 @@ export function bivyProtocolParser() {
             return events;
         },
         messages: () => acc.history(),
+        usage: () => acc.usageSnapshot,
+        sessionRef: () => sessionRef,
     };
 }
 /** Parser for Claude Code CLI `--output-format stream-json`. */

package/dist/runtime/index.js

@@ -55,6 +55,8 @@ import { ProtocolRuntime, protocolRuntimeFromEnv, protocolCommandsFromEnv } from
 import { codexSlashCommands, opencodeSlashCommands } from "./slash-commands.js";
 import { withExactCapabilitySurface } from "./types.js";
 import { installedAgentContributions } from "../plugins/store.js";
+import { readNodeConfig } from "../node-config.js";
+import { defaultDataDir } from "../data-dir.js";
 import { forkCapsFromInfo } from "../session/fork-matrix.js";
 import { currentBivyVersion } from "../app-version.js";
 const PREFLIGHT_BEHAVIORS = {
@@ -116,54 +118,81 @@ function genericCliInfo() {
             : "Set BIVY_AGENT_COMMAND to enable this universal CLI runtime.",
     };
 }
-function customAgentSpecs() {
-    const out = new Map();
+/**
+ * The node's own agents, read from `<data-dir>/config.yaml` on every registry
+ * build so an edit or `bivy agent add` shows up without a restart. The legacy
+ * BIVY_CUSTOM_AGENTS projection is used only on a node with no config.yaml.
+ */
+function configuredAgents(dataDir = defaultDataDir()) {
+    try {
+        const config = readNodeConfig(dataDir);
+        if (config)
+            return { agents: Object.entries(config.agents ?? {}) };
+    }
+    catch (error) {
+        return { agents: [], error: error instanceof Error ? error.message : String(error) };
+    }
     const raw = process.env.BIVY_CUSTOM_AGENTS?.trim();
     if (!raw)
-        return out;
+        return { agents: [] };
     try {
         const parsed = JSON.parse(raw);
         if (!Array.isArray(parsed))
-            return out;
-        for (const value of parsed) {
-            if (!value || typeof value !== "object")
-                continue;
-            const item = value;
-            const id = typeof item.id === "string" ? item.id.trim().toLowerCase() : "";
-            if (!/^[a-z][a-z0-9-]{1,47}$/.test(id) || out.has(id))
-                continue;
-            if (typeof item.extends !== "string" || !isAgentProfileId(item.extends))
-                continue;
-            const base = AGENT_PROFILES[item.extends];
-            const strings = (v) => Array.isArray(v) && v.every((x) => typeof x === "string") ? v : undefined;
-            out.set(id, {
-                ...base,
-                displayName: typeof item.label === "string" && item.label.trim() ? item.label.trim() : id,
-                command: typeof item.command === "string" && item.command.trim() ? item.command.trim() : base.command,
-                ...(strings(item.args) ? { args: strings(item.args) } : {}),
-                ...(strings(item.jsonArgs) ? { jsonArgs: strings(item.jsonArgs) } : {}),
-                ...(typeof item.parserId === "string" ? { parserId: item.parserId } : {}),
-                ...(item.promptMode === "stdin" || item.promptMode === "argv" ? { promptMode: item.promptMode } : {}),
-                hidden: item.hidden === true,
-                supportTier: "experimental",
-                testedVersion: undefined,
-                install: undefined,
-                // `extends` reuses declarative launch syntax, never maintained host code.
-                // A different executable must not inherit Codex/OpenCode/Grok credential,
-                // store, slash-command, or native-discovery behavior by accident.
-                behaviors: undefined,
-                ...(base.resume ? { resume: { template: base.resume.template, ...(base.resume.newTemplate ? { newTemplate: base.resume.newTemplate } : {}) } } : {}),
-            });
-        }
+            return { agents: [] };
+        return {
+            agents: parsed
+                .filter((item) => Boolean(item) && typeof item.id === "string")
+                .map(({ id, ...spec }) => [id.trim().toLowerCase(), spec]),
+        };
     }
     catch {
         // Invalid operator configuration is ignored; packaged integrations remain usable.
+        return { agents: [] };
+    }
+}
+function extendsAgentSpec(id, item) {
+    if (!isAgentProfileId(item.extends))
+        return undefined;
+    const base = AGENT_PROFILES[item.extends];
+    const strings = (v) => Array.isArray(v) && v.every((x) => typeof x === "string") ? v : undefined;
+    return {
+        ...base,
+        displayName: typeof item.label === "string" && item.label.trim() ? item.label.trim() : id,
+        command: typeof item.command === "string" && item.command.trim() ? item.command.trim() : base.command,
+        ...(strings(item.args) ? { args: strings(item.args) } : {}),
+        ...(strings(item.jsonArgs) ? { jsonArgs: strings(item.jsonArgs) } : {}),
+        ...(typeof item.parserId === "string" ? { parserId: item.parserId } : {}),
+        ...(item.promptMode === "stdin" || item.promptMode === "argv" ? { promptMode: item.promptMode } : {}),
+        hidden: item.hidden === true,
+        supportTier: "experimental",
+        testedVersion: undefined,
+        install: undefined,
+        // `extends` reuses declarative launch syntax, never maintained host code.
+        // A different executable must not inherit Codex/OpenCode/Grok credential,
+        // store, slash-command, or native-discovery behavior by accident.
+        behaviors: undefined,
+        ...(base.resume ? { resume: { template: base.resume.template, ...(base.resume.newTemplate ? { newTemplate: base.resume.newTemplate } : {}) } } : {}),
+    };
+}
+function customAgentSpecs(dataDir) {
+    const out = new Map();
+    for (const [id, item] of configuredAgents(dataDir).agents) {
+        if (!/^[a-z][a-z0-9-]{1,47}$/.test(id) || out.has(id) || !item || typeof item !== "object")
+            continue;
+        const spec = "adapter" in item
+            ? adapterAgentSpec({ name: item.name || id, ...item }, "Configured on this machine")
+            : extendsAgentSpec(id, item);
+        if (spec)
+            out.set(id, spec);
     }
     return out;
 }
 export function pluginAgentConflictDiagnostics(dataDir) {
     const installed = installedAgentContributions(dataDir);
     const errors = [...installed.errors];
+    const configError = configuredAgents(dataDir).error;
+    if (configError)
+        errors.push(configError);
     for (const conflict of agentRegistry(dataDir).diagnostics()) {
         if (conflict.rejectedOrigin.kind !== "package" || conflict.rejectedOrigin.location !== "installed")
             continue;
@@ -171,18 +200,18 @@ export function pluginAgentConflictDiagnostics(dataDir) {
     }
     return errors;
 }
-/** Translate a public manifest contribution into the shared CLI adapter shape. */
-function pluginAgentSpec(contribution) {
-    const { agent } = contribution;
+/** Translate one `adapter` declaration (plugin manifest or config.yaml) into
+ *  the shared CLI/ACP launch shape. */
+function adapterAgentSpec(agent, packageName) {
     const common = {
         displayName: agent.name,
         command: agent.adapter.command,
-        packageName: `${contribution.pluginName} plugin`,
+        packageName,
         promptMode: "stdin",
         hidden: agent.hidden === true,
         supportTier: "experimental",
         authOwner: agent.authOwner ?? "agent",
-        blurb: agent.description ?? `Agent contributed by ${contribution.pluginName}.`,
+        blurb: agent.description ?? `${packageName}.`,
         install: undefined,
     };
     if (agent.adapter.kind === "acp") {
@@ -982,10 +1011,11 @@ function agentRegistry(pluginDataDir) {
     }
     // Machine configuration and installed packages use the exact same lifecycle.
     // Earlier registrations win, and every retained/rejected origin remains explicit.
-    for (const [id, spec] of customAgentSpecs())
+    for (const [id, spec] of customAgentSpecs(pluginDataDir))
         registry.register(cliRegistration(id, spec, { kind: "config" }));
     for (const contribution of installedAgentContributions(pluginDataDir).agents) {
-        registry.register(cliRegistration(contribution.agent.id, pluginAgentSpec(contribution), {
+        const { agent, pluginName } = contribution;
+        registry.register(cliRegistration(agent.id, adapterAgentSpec({ ...agent, description: agent.description ?? `Agent contributed by ${pluginName}.` }, `${pluginName} plugin`), {
             kind: "package",
             packageId: contribution.pluginId,
             packageVersion: contribution.pluginVersion,

package/dist/server.js

@@ -240,9 +240,6 @@ try {
         if (process.env[key] === undefined)
             process.env[key] = value;
     }
-    if (canonicalNodeConfig.agents && process.env.BIVY_CUSTOM_AGENTS === undefined) {
-        process.env.BIVY_CUSTOM_AGENTS = JSON.stringify(Object.entries(canonicalNodeConfig.agents).map(([id, spec]) => ({ id, ...spec })));
-    }
     if (canonicalNodeConfig.automation?.checks && process.env.BIVY_AUTOMATION_CHECKS === undefined) {
         process.env.BIVY_AUTOMATION_CHECKS = JSON.stringify(canonicalNodeConfig.automation.checks);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bivy/bivy",
-  "version": "0.21.2-staging.1",
+  "version": "0.21.2-staging.2",
   "type": "module",
   "license": "AGPL-3.0-only",
   "description": "Run coding agents on machines you own. Open-source, self-hostable agent workspace.",