@bivy/bivy 0.18.9-staging.3 → 0.18.9-staging.5

package/README.md

@@ -282,7 +282,7 @@ curl -fsSL https://bivy.sh/install.sh | bash
 
 Setup helps you choose an agent and configure remote access. Existing agents
 keep their command, login, and configuration. The installer may use `sudo` to
-install missing Node.js or Debian/Ubuntu build tools, but never for `npm install`. To inspect it first,
+install a missing Node.js, but never for `npm install`. To inspect it first,
 download it with `curl -fsSL https://bivy.sh/install.sh -o install.sh`.
 
 Already have Node.js and want to avoid sudo?

package/bin/bivy.mjs

@@ -160,6 +160,7 @@ const relaySetupEntry = path.join(repoRoot, packaged ? "dist/relay-setup.js" : "
 // artifact (src/ is not packaged), so resolve it the same packaged-aware way as
 // the runtime entries and import it dynamically at call time.
 const hostedEndpointsEntry = path.join(repoRoot, packaged ? "dist/hosted-endpoints.mjs" : "src/hosted-endpoints.mjs");
+const agentBridgesEntry = path.join(repoRoot, packaged ? "dist/agent-bridges.mjs" : "src/agent-bridges.mjs");
 const githubConnectEntry = path.join(repoRoot, packaged ? "dist/github-connect-repo.js" : "src/github-connect-repo.ts");
 const githubAppConnectEntry = path.join(repoRoot, packaged ? "dist/github-app-connect.js" : "src/github-app-connect.ts");
 const githubAppSyncEntry = path.join(repoRoot, packaged ? "dist/github-app-sync-cli.js" : "src/github-app-sync-cli.ts");
@@ -185,6 +186,27 @@ async function getHostedEndpoints() {
   return _hostedEndpoints();
 }
 
+// Agent SDK bridges (Claude, Pi) install on demand into the data dir, not with
+// Bivy — the daemon and this CLI share src/agent-bridges.mjs for it.
+function loadAgentBridges() {
+  return import(pathToFileURL(agentBridgesEntry).href);
+}
+
+/** Install any bridge packages the given agents need. True when all are present. */
+async function ensureAgentBridges(agentIds) {
+  const bridges = await loadAgentBridges();
+  const missing = [...new Set(agentIds.flatMap((id) => bridges.missingBridges(id)))];
+  if (!missing.length) return true;
+  console.log(c.dim(`Installing agent bridge ${missing.join(", ")} into ${bridges.bridgesDir()}…`));
+  try {
+    await bridges.installBridges(missing, { stdio: "inherit" });
+    return true;
+  } catch (error) {
+    console.error(c.red(error instanceof Error ? error.message : String(error)));
+    return false;
+  }
+}
+
 const SERVICE_LABEL = "dev.bivy";
 const SERVICE_UNIT = "bivy.service";
 
@@ -587,14 +609,10 @@ async function ensureDeps() {
     ));
     return false;
   }
-  if (process.platform === "linux" && (!commandExists("make") || !commandExists("g++") || !commandExists("python3"))) {
-    console.error(c.yellow("Build tools are missing. On Ubuntu/Debian run: sudo apt-get update && sudo apt-get install -y build-essential python3"));
-    console.error(c.dim("The node-pty terminal dependency needs these tools if no prebuilt binary matches this machine."));
-  }
   console.log(c.dim(`Installing dependencies (${cmd} ${args.join(" ")})…`));
   const code = await run(cmd, args, { cwd: repoRoot });
   if (code !== 0 || !fs.existsSync(dependencyMarker)) {
-    console.error(c.red(`${cmd} install failed. Install Node.js 20+ and, if native dependencies failed, build tools (make/g++/python3), then try again.`));
+    console.error(c.red(`${cmd} install failed. Install Node.js 20+, then try again.`));
     return false;
   }
   return true;
@@ -628,28 +646,6 @@ function nodePackageLoadable(packageName) {
   return runQuiet(nodeBin, ["-e", "require(require.resolve(process.argv[1], { paths: [process.argv[2]] }))", packageName, repoRoot]).code === 0;
 }
 
-async function ensureNodePackage(packageName) {
-  if (nodePackageInstalled(packageName)) {
-    console.log(c.green(`  ✓ Found Bivy bridge package ${packageName}`));
-    return true;
-  }
-  // Add with the package manager that owns this tree. Running `npm install` in a
-  // pnpm workspace would write a competing package-lock.json and a hoisted
-  // node_modules over pnpm's symlink layout, leaving the checkout in a state
-  // neither tool resolves correctly.
-  const usesPnpm = fs.existsSync(path.join(repoRoot, "pnpm-lock.yaml"));
-  const [cmd, baseArgs] = usesPnpm
-    ? [commandExists("pnpm") ? "pnpm" : "corepack", commandExists("pnpm") ? ["add"] : ["pnpm", "add"]]
-    : ["npm", ["install", "--no-audit", "--no-fund"]];
-  if (!commandExists(cmd)) {
-    console.error(c.red(`${cmd} is required to install ${packageName}.`));
-    return false;
-  }
-  console.log(c.dim(`Installing Bivy bridge package ${packageName}…`));
-  const code = await run(cmd, [...baseArgs, packageName], { cwd: repoRoot });
-  return code === 0 && nodePackageInstalled(packageName);
-}
-
 const userLocalPrefix = process.env.BIVY_NPM_GLOBAL_PREFIX || path.join(os.homedir(), ".local");
 
 async function ensureNpmCommand(command, packageName, label) {
@@ -689,10 +685,13 @@ const KNOWN_AGENT_INSTALLS = [
   { command: "gemini", npmPackage: "@google/gemini-cli", label: "Gemini CLI" },
 ];
 
-async function ensureKnownAgents() {
+async function ensureKnownAgents({ bridgesOnly = false } = {}) {
   if (process.env.BIVY_SKIP_AGENT_PREINSTALL === "1") return true;
+  const { AGENT_BRIDGES } = await loadAgentBridges();
+  const bridges = await ensureAgentBridges(Object.keys(AGENT_BRIDGES));
+  if (bridgesOnly) return bridges;
   console.log(c.dim("Ensuring known agent integrations are installed…"));
-  const results = [await ensureNodePackage("@anthropic-ai/claude-agent-sdk")];
+  const results = [bridges];
   for (const agent of KNOWN_AGENT_INSTALLS) {
     results.push(
       agent.pythonPackage
@@ -707,11 +706,15 @@ async function ensureKnownAgents() {
 
 async function ensureSetupAgent(choice) {
   if (!choice) return true;
-  if (choice.runtimeId === "pi") return ensureNpmCommand("pi", "@earendil-works/pi-coding-agent", "Pi");
+  if (choice.runtimeId === "pi") {
+    const bridge = await ensureAgentBridges(["pi"]);
+    const cli = await ensureNpmCommand("pi", "@earendil-works/pi-coding-agent", "Pi");
+    return bridge && cli;
+  }
   if (choice.runtimeId === "claude-code-sdk") {
-    const sdk = await ensureNodePackage("@anthropic-ai/claude-agent-sdk");
+    const bridge = await ensureAgentBridges(["claude-code-sdk"]);
     const cli = await ensureNpmCommand("claude", "@anthropic-ai/claude-code", "Claude Code");
-    return sdk && cli;
+    return bridge && cli;
   }
   if (choice.runtimeId === "codex-approvals") return ensureNpmCommand("codex", "@openai/codex", "Codex");
   if (choice.runtimeId === "opencode") return ensureNpmCommand("opencode", "opencode-ai/opencode", "OpenCode");
@@ -4462,12 +4465,13 @@ async function cmdDoctor(args = []) {
 
   console.log(c.bold("\n  Bivy doctor\n"));
   console.log(`  ${mark(hasSupportedNode())} Node ${process.version}${hasSupportedNode() ? "" : c.dim("  (needs >= 20.0.0)")}`);
-  const ptyInstalled = nodePackageInstalled("node-pty");
-  const ptyUsable = ptyInstalled && nodePackageLoadable("node-pty");
-  console.log(`  ${mark(ptyUsable, true)} terminal PTY ${ptyUsable ? c.green("available") : ptyInstalled ? c.yellow("installed but not loadable — reinstall after installing build tools") : c.yellow("dependency missing — reinstall Bivy; interactive terminals unavailable")}`);
-  const claudeBridge = nodePackageInstalled("@anthropic-ai/claude-agent-sdk");
+  const ptyInstalled = nodePackageInstalled("@lydell/node-pty");
+  const ptyUsable = ptyInstalled && nodePackageLoadable("@lydell/node-pty");
+  console.log(`  ${mark(ptyUsable, true)} terminal PTY ${ptyUsable ? c.green("available") : ptyInstalled ? c.yellow(`installed but not loadable — no prebuilt binary for ${process.platform}-${process.arch}, or npm ran with --omit=optional`) : c.yellow("dependency missing — reinstall Bivy; interactive terminals unavailable")}`);
+  const { bridgeInstalled } = await loadAgentBridges();
+  const claudeBridge = bridgeInstalled("@anthropic-ai/claude-agent-sdk");
   console.log(`  ${mark(claudeBridge, true)} Claude bridge ${claudeBridge ? c.green("installed") : c.dim("optional — installed on first Claude setup/use")}`);
-  const piBridge = nodePackageInstalled("@earendil-works/pi-coding-agent");
+  const piBridge = bridgeInstalled("@earendil-works/pi-coding-agent");
   const piNodeOk = nodeAtLeast(22, 19);
   console.log(`  ${mark(piBridge && piNodeOk, true)} Pi bridge ${piBridge ? (piNodeOk ? c.green("installed") : c.yellow("installed but needs Node >=22.19")) : c.dim("optional — installed only if you choose Pi")}`);
   console.log(`  ${mark(commandExists("git"), true)} git${commandExists("git") ? "" : c.dim("  (recommended for repo-backed sessions)")}`);
@@ -5549,11 +5553,11 @@ Unlike 'bivy run', these commands operate on governed background Runs with check
     case "agents:install":
     case "runtimes:install":
       if (args.includes("-h") || args.includes("--help")) {
-        console.log(`Usage: bivy agents:install\n\nInstall known agent integrations (${KNOWN_AGENT_INSTALLS.map((a) => a.label).join(", ")}).`);
+        console.log(`Usage: bivy agents:install [--bridges]\n\nInstall known agent integrations (${KNOWN_AGENT_INSTALLS.map((a) => a.label).join(", ")}).\n\n  --bridges   only install the SDK bridges Bivy loads for Claude Code and Pi\n              (they otherwise install on first use)`);
         break;
       }
       if (!(await ensureDeps())) process.exit(1);
-      await ensureKnownAgents();
+      if (!(await ensureKnownAgents({ bridgesOnly: args.includes("--bridges") })) && args.includes("--bridges")) process.exit(1);
       break;
     case "open": {
       if (args.includes("-h") || args.includes("--help")) {

package/bin/codex-app-server-shim.mjs

@@ -478,6 +478,9 @@ function threadParams(msg, extra = {}) {
     approvalPolicy: APPROVAL_POLICY,
     sandbox: SANDBOX_MODE,
     ...(selectedModel ? { model: selectedModel } : {}),
+    // The user's account-wide Bivy instructions ride as developer instructions,
+    // alongside (not instead of) the AGENTS.md files Codex loads itself.
+    ...(typeof msg.instructions === "string" && msg.instructions ? { developerInstructions: msg.instructions } : {}),
     ...extra,
   };
 }

package/dist/agent-bridges.d.mts

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+export interface AgentBridge {
+  command: string;
+  packages: string[];
+}
+
+export declare const AGENT_BRIDGES: Record<string, AgentBridge>;
+
+export interface ResolvedBridge {
+  dir: string;
+  version: string;
+  source: "bivy" | "bridges";
+}
+
+export declare function bridgeVersions(): Record<string, string>;
+export declare function bridgesDir(env?: Record<string, string | undefined>): string;
+export declare function resolveBridge(name: string, dir?: string): ResolvedBridge | undefined;
+export declare function bridgeInstalled(name: string, dir?: string): boolean;
+export declare function missingBridges(agentId: string, dir?: string): string[];
+export declare function bridgesToSync(options?: { dir?: string; commandExists?: (command: string) => boolean }): string[];
+export declare function installBridges(
+  names: string[],
+  options?: { dir?: string; stdio?: "inherit" | "pipe" },
+): Promise<{ installed: string[]; output: string }>;
+export declare function enableBridgeResolution(dir?: string): void;

package/dist/agent-bridges.mjs

@@ -0,0 +1,271 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+// Agent bridges: the SDK packages Bivy loads in-process to drive an agent
+// (Claude's Agent SDK, Pi's coding-agent library).
+//
+// They are large (hundreds of MB together) and a node usually needs one, so
+// they are not installed with Bivy. They install on first use into a directory
+// next to the node's state, which survives `bivy update` replacing the package
+// directory, and resolve from there whenever Bivy's own node_modules lacks
+// them. In a dev checkout the workspace installs them as optionalDependencies,
+// so normal resolution finds them first and the bridge directory is unused.
+//
+// Plain JS (with a .d.mts) so the CLI in bin/ and the daemon share one copy.
+import fs from "node:fs";
+import module from "node:module";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// src/ in a checkout, dist/ in a release: either way the parent is the package root.
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * Which bridge packages each agent loads, and the CLI whose presence means the
+ * agent is in use on this node. Adding a bridge is a row here plus a pinned
+ * entry in package.json's optionalDependencies (published as `agentBridges`).
+ */
+export const AGENT_BRIDGES = {
+  "claude-code-sdk": { command: "claude", packages: ["@anthropic-ai/claude-agent-sdk"] },
+  pi: { command: "pi", packages: ["@earendil-works/pi-coding-agent", "@earendil-works/pi-ai"] },
+};
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+function bivyManifest() {
+  return readJson(path.join(packageRoot, "package.json")) ?? {};
+}
+
+/** Pinned bridge versions: `agentBridges` in a release, optionalDependencies in a checkout. */
+export function bridgeVersions() {
+  const pkg = bivyManifest();
+  return { ...(pkg.agentBridges ?? pkg.optionalDependencies ?? {}) };
+}
+
+/** Where bridges install: $BIVY_BRIDGES_DIR, else `bridges/` in the node's data dir. */
+export function bridgesDir(env = process.env) {
+  if (env.BIVY_BRIDGES_DIR) return path.resolve(env.BIVY_BRIDGES_DIR);
+  const dataDir = env.BIVY_DATA_DIR ? path.resolve(env.BIVY_DATA_DIR) : path.join(packageRoot, ".bivy");
+  return path.join(dataDir, "bridges");
+}
+
+/** "@scope/name/sub" -> "@scope/name"; "name/sub" -> "name". */
+function packageNameOf(specifier) {
+  const parts = specifier.split("/");
+  return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+
+function packageAt(dir) {
+  const manifest = readJson(path.join(dir, "package.json"));
+  return manifest ? { dir, version: manifest.version } : undefined;
+}
+
+/** Find `name` the way Node's resolver walks node_modules upward from `from`. */
+function findUpward(name, from) {
+  for (let dir = from; ; dir = path.dirname(dir)) {
+    const found = packageAt(path.join(dir, "node_modules", name));
+    if (found) return found;
+    if (path.dirname(dir) === dir) return undefined;
+  }
+}
+
+/**
+ * npm writes node_modules/.package-lock.json when an install finishes, and we
+ * write package.json just before starting one. An interrupted install (the
+ * daemon stopped mid-way) leaves half-extracted packages, so trust the
+ * directory only when that lockfile is newer than the manifest.
+ */
+function installComplete(dir) {
+  try {
+    return fs.statSync(path.join(dir, "node_modules", ".package-lock.json")).mtimeMs >= fs.statSync(path.join(dir, "package.json")).mtimeMs;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Where a bridge package resolves from, if anywhere: Bivy's own dependency
+ * tree first (a checkout), then the bridge directory.
+ */
+export function resolveBridge(name, dir = bridgesDir()) {
+  const own = findUpward(name, packageRoot);
+  if (own) return { ...own, source: "bivy" };
+  if (!installComplete(dir)) return undefined;
+  const bridged = packageAt(path.join(dir, "node_modules", name));
+  return bridged ? { ...bridged, source: "bridges" } : undefined;
+}
+
+export function bridgeInstalled(name, dir) {
+  return resolveBridge(name, dir) !== undefined;
+}
+
+/** Bridge packages `agentId` needs that are not resolvable yet (none for agents without a bridge). */
+export function missingBridges(agentId, dir) {
+  return (AGENT_BRIDGES[agentId]?.packages ?? []).filter((name) => !bridgeInstalled(name, dir));
+}
+
+function onPath(command, env = process.env) {
+  const exts = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD").split(";") : [""];
+  for (const dir of (env.PATH ?? "").split(path.delimiter)) {
+    for (const ext of exts) {
+      try {
+        fs.accessSync(path.join(dir, command + ext), fs.constants.X_OK);
+        return true;
+      } catch {}
+    }
+  }
+  return false;
+}
+
+/**
+ * Bridge packages that should be (re)installed now: every package already in
+ * the bridge directory or belonging to an agent whose CLI is on PATH, that is
+ * either missing or not at Bivy's pinned version. Empty means nothing to do,
+ * and computing it touches no network.
+ */
+export function bridgesToSync({ dir = bridgesDir(), commandExists = onPath } = {}) {
+  const versions = bridgeVersions();
+  const wanted = new Set(Object.keys(readJson(path.join(dir, "package.json"))?.dependencies ?? {}));
+  for (const bridge of Object.values(AGENT_BRIDGES)) {
+    if (commandExists(bridge.command)) bridge.packages.forEach((name) => wanted.add(name));
+  }
+  return [...wanted].filter((name) => {
+    if (!versions[name]) return false;
+    const found = resolveBridge(name, dir);
+    return !found || (found.source === "bridges" && found.version !== versions[name]);
+  });
+}
+
+/**
+ * Replace nested copies that a bridge's own npm-shrinkwrap pins, which npm
+ * `overrides` cannot reach. Driven by the nested overrides in package.json
+ * (`"parent": { "child": "version" }`), so a new pin is data, not code.
+ */
+function applyNestedOverrides(dir) {
+  for (const [parent, pins] of Object.entries(bivyManifest().overrides ?? {})) {
+    if (!pins || typeof pins !== "object") continue;
+    const parentDir = path.join(dir, "node_modules", parent);
+    for (const [child, version] of Object.entries(pins)) {
+      const target = path.join(parentDir, "node_modules", child);
+      const nested = packageAt(target);
+      if (!nested || nested.version === version) continue;
+      const source = [packageAt(path.join(dir, "node_modules", child)), findUpward(child, packageRoot)]
+        .find((candidate) => candidate?.version === version);
+      if (!source) throw new Error(`Security patch source ${child}@${version} is missing`);
+      fs.rmSync(target, { recursive: true, force: true });
+      fs.cpSync(source.dir, target, { recursive: true });
+    }
+  }
+}
+
+/**
+ * Install `names` (at Bivy's pinned versions) into the bridge directory. The
+ * directory is an ordinary npm project that keeps earlier bridges and carries
+ * Bivy's security overrides. Optional dependencies are omitted: bridges run as
+ * libraries against the operator's own agent CLI, never their bundled binaries.
+ *
+ * `stdio: "inherit"` streams npm's output (CLI); otherwise it is captured.
+ * Installs in one process run one at a time, since they share a directory.
+ */
+let installQueue = Promise.resolve();
+export function installBridges(names, options = {}) {
+  const run = installQueue.then(() => installNow(names, options));
+  installQueue = run.catch(() => {});
+  return run;
+}
+
+function installNow(names, { dir = bridgesDir(), stdio = "pipe" } = {}) {
+  const versions = bridgeVersions();
+  const unknown = names.filter((name) => !versions[name]);
+  if (unknown.length) return Promise.reject(new Error(`Not an agent bridge: ${unknown.join(", ")}`));
+
+  fs.mkdirSync(dir, { recursive: true });
+  // npm does not repair half-extracted packages, so an interrupted earlier
+  // install is discarded rather than installed over.
+  if (!installComplete(dir)) fs.rmSync(path.join(dir, "node_modules"), { recursive: true, force: true });
+  const manifestPath = path.join(dir, "package.json");
+  const previous = readJson(manifestPath)?.dependencies ?? {};
+  const dependencies = { ...previous };
+  for (const name of names) dependencies[name] = versions[name];
+  const manifest = { name: "bivy-agent-bridges", private: true, dependencies, overrides: bivyManifest().overrides ?? {} };
+  fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+
+  return new Promise((resolve, reject) => {
+    const child = spawn("npm", ["install", "--omit=optional", "--no-audit", "--no-fund"], {
+      cwd: dir,
+      stdio: stdio === "inherit" ? "inherit" : ["ignore", "pipe", "pipe"],
+    });
+    let output = "";
+    const append = (chunk) => { output = (output + chunk.toString()).slice(-12000); };
+    child.stdout?.on("data", append);
+    child.stderr?.on("data", append);
+    child.on("error", reject);
+    child.on("close", (code) => {
+      if (code !== 0) {
+        reject(new Error(`npm could not install ${names.join(", ")} (exit ${code ?? "unknown"})${output ? `\n${output}` : ""}`));
+        return;
+      }
+      try {
+        applyNestedOverrides(dir);
+        resolve({ installed: names, output });
+      } catch (error) {
+        reject(error);
+      }
+    });
+  });
+}
+
+const NOT_FOUND = new Set(["ERR_MODULE_NOT_FOUND", "MODULE_NOT_FOUND"]);
+
+// Same fallback as the in-thread hook below, for Node versions that only have
+// module.register (off-thread, async hooks loaded from this data: URL).
+const ASYNC_HOOKS = `
+let parentURL, names;
+export function initialize(data) { parentURL = data.parentURL; names = new Set(data.names); }
+const nameOf = ${packageNameOf.toString()};
+export async function resolve(specifier, context, next) {
+  try { return await next(specifier, context); } catch (error) {
+    if (!${JSON.stringify([...NOT_FOUND])}.includes(error?.code) || !names.has(nameOf(specifier))) throw error;
+    try { return await next(specifier, { ...context, parentURL }); } catch { throw error; }
+  }
+}`;
+
+let resolutionEnabled = false;
+
+/**
+ * Let `import`/`require` of a bridge package fall back to the bridge directory
+ * when Bivy's own node_modules lacks it. Idempotent; call before loading a
+ * bridge. Only bridge package names are redirected, and only after normal
+ * resolution fails, so a checkout's workspace copies always win.
+ */
+export function enableBridgeResolution(dir = bridgesDir()) {
+  if (resolutionEnabled) return;
+  resolutionEnabled = true;
+  const parentURL = pathToFileURL(path.join(dir, "package.json")).href;
+  const names = Object.keys(bridgeVersions());
+  if (typeof module.registerHooks === "function") {
+    const bridges = new Set(names);
+    module.registerHooks({
+      resolve(specifier, context, next) {
+        try {
+          return next(specifier, context);
+        } catch (error) {
+          if (!NOT_FOUND.has(error?.code) || !bridges.has(packageNameOf(specifier))) throw error;
+          try {
+            return next(specifier, { ...context, parentURL });
+          } catch {
+            throw error;
+          }
+        }
+      },
+    });
+  } else if (typeof module.register === "function") {
+    module.register(`data:text/javascript,${encodeURIComponent(ASYNC_HOOKS)}`, { data: { parentURL, names } });
+  }
+}

package/dist/agent-instructions.js

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright (c) 2026 Petter André Sjulstad
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Account-wide agent instructions: one Markdown file of the user's global
+ * preferences, handed to every agent session IN ADDITION to the repo's own
+ * AGENTS.md/CLAUDE.md (which the agent keeps loading itself).
+ *
+ * The source of truth on a machine is `<appDir>/AGENTS.md` — plain Markdown the
+ * user can also edit by hand. Its mtime is the last-writer-wins clock: the
+ * account-wide copy rides in the E2E model-auth vault envelope (see server.ts),
+ * and a synced import stamps the file with the writer's timestamp so every
+ * machine compares like with like. Clearing is an empty file, not a delete, so
+ * the empty state carries a timestamp and propagates too.
+ *
+ * Delivery is the caller's business; this module only produces the composed
+ * text (and a file holding it, for agents that take a path).
+ */
+/** Cap on the editable text. It rides on every turn of every session. */
+export const MAX_AGENT_INSTRUCTIONS_BYTES = 16 * 1024;
+const PREAMBLE = "The user's global Bivy instructions follow. They apply to every workspace; where they conflict with " +
+    "instructions from the current repository (AGENTS.md, CLAUDE.md, …), the repository's instructions win.";
+export function agentInstructionsPath(appDir) {
+    return path.join(appDir, "AGENTS.md");
+}
+function composedPath(appDir) {
+    return path.join(appDir, "agent-instructions.composed.md");
+}
+export function readAgentInstructions(appDir) {
+    try {
+        const file = agentInstructionsPath(appDir);
+        return { text: fs.readFileSync(file, "utf8"), updatedAt: Math.trunc(fs.statSync(file).mtimeMs) };
+    }
+    catch {
+        return { text: "", updatedAt: 0 };
+    }
+}
+export function writeAgentInstructions(appDir, text, updatedAt = Date.now()) {
+    if (Buffer.byteLength(text, "utf8") > MAX_AGENT_INSTRUCTIONS_BYTES) {
+        throw new Error(`Agent instructions are limited to ${MAX_AGENT_INSTRUCTIONS_BYTES / 1024} KB.`);
+    }
+    const file = agentInstructionsPath(appDir);
+    fs.mkdirSync(appDir, { recursive: true });
+    fs.writeFileSync(file, text);
+    fs.utimesSync(file, new Date(updatedAt), new Date(updatedAt));
+    return readAgentInstructions(appDir);
+}
+/**
+ * Reconcile a synced copy with the local file (last writer wins).
+ * - "imported": the synced copy was newer and is now the local file.
+ * - "local-newer": this machine holds a newer copy the account should get.
+ * - "unchanged": nothing to do.
+ */
+export function mergeSyncedAgentInstructions(appDir, incoming) {
+    const local = readAgentInstructions(appDir);
+    const synced = incoming && typeof incoming === "object" ? incoming : undefined;
+    if (typeof synced?.text !== "string" || typeof synced.updatedAt !== "number") {
+        return local.updatedAt > 0 ? "local-newer" : "unchanged";
+    }
+    if (synced.text === local.text)
+        return "unchanged";
+    if (synced.updatedAt > local.updatedAt) {
+        writeAgentInstructions(appDir, synced.text, synced.updatedAt);
+        return "imported";
+    }
+    return "local-newer";
+}
+/** Wrap the user's text in the precedence preamble; "" when there is nothing to send. */
+export function composeAgentInstructions(text) {
+    const body = text.trim();
+    return body ? `${PREAMBLE}\n\n${body}\n` : "";
+}
+/**
+ * The instructions for a session starting now, or undefined when the user has
+ * none. Keeps a composed copy on disk (rewritten only when it changes) for
+ * agents that take a file path rather than text.
+ */
+export function sessionInstructions(appDir) {
+    const text = composeAgentInstructions(readAgentInstructions(appDir).text);
+    const file = composedPath(appDir);
+    try {
+        if (!text) {
+            // An MCP server spec injected earlier may still point here; don't let it
+            // serve instructions the user has since cleared.
+            fs.rmSync(file, { force: true });
+            return undefined;
+        }
+        let current;
+        try {
+            current = fs.readFileSync(file, "utf8");
+        }
+        catch { /* not written yet */ }
+        if (current !== text)
+            fs.writeFileSync(file, text);
+        return { text, file };
+    }
+    catch (error) {
+        // Never block a session on this; it just starts without them.
+        console.warn("[agent-instructions] could not prepare instructions:", error.message);
+        return undefined;
+    }
+}

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

@@ -55,7 +55,7 @@ export function claudeCodeIntegration(origin) {
                 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."
+                        ? "The Claude Code agent is installed; Bivy installs its SDK bridge when you start the first Claude session (or run 'bivy agents:install --bridges')."
                         : "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",

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

@@ -13,7 +13,6 @@
 //   * The SDK is loaded with a dynamic import so it stays an *optional*
 //     dependency: a Bivy install only needs it when this runtime is selected.
 import { withSessionCredentials, credentialEnvFallback } from "../../credentials/session.js";
-import { createRequire } from "node:module";
 import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
 import { withExactCapabilitySurface } from "../../runtime/types.js";
@@ -30,6 +29,7 @@ import { anthropicCredentialPreflight, describeAnthropicError, isAnthropicAuthEr
 import { toModelInfo as sharedToModelInfo } from "../../runtime/normalize.js";
 import { hasLiveProcessForCwd } from "../../runtime/native-process-scan.js";
 import { bivySessionEnv } from "../../runtime/session-env.js";
+import { bridgeInstalled, enableBridgeResolution } from "../../agent-bridges.mjs";
 /** Binary names a live Claude Code process could be running under (see
  *  native-process-scan.ts's best-effort cwd match). */
 const CLAUDE_BIN_NAMES = ["claude"];
@@ -190,20 +190,15 @@ export function claudeRuntimeFromEnv() {
 }
 /** True when `@anthropic-ai/claude-agent-sdk` is resolvable in this install. */
 export function claudeSdkInstalled() {
-    try {
-        createRequire(import.meta.url).resolve(SDK_PACKAGE);
-        return true;
-    }
-    catch {
-        return false;
-    }
+    return bridgeInstalled(SDK_PACKAGE);
 }
 async function loadSdk() {
+    enableBridgeResolution();
     try {
         return await import(SDK_PACKAGE);
     }
     catch {
-        throw new Error(`The claude-code-sdk runtime requires the "${SDK_PACKAGE}" package. Install it with: npm install ${SDK_PACKAGE}`);
+        throw new Error(`The claude-code-sdk runtime requires the "${SDK_PACKAGE}" bridge. Install it with: bivy agents:install --bridges`);
     }
 }
 /**
@@ -885,7 +880,9 @@ class ClaudeSession {
             // Kept even when the native tool below is also registered: it's a cheap,
             // harmless fallback for a shell/subprocess the agent spawns that can't
             // reach the in-process MCP tool directly.
-            systemPrompt: { type: "preset", preset: "claude_code", append: BIVY_ATTACH_SYSTEM_PROMPT },
+            // The user's account-wide instructions follow it; the repo's CLAUDE.md
+            // still loads through the preset as usual.
+            systemPrompt: { type: "preset", preset: "claude_code", append: [BIVY_ATTACH_SYSTEM_PROMPT, this.runtimeOptions.instructions].filter(Boolean).join("\n\n") },
             ...(this.runtimeOptions.executablePath ? { pathToClaudeCodeExecutable: this.runtimeOptions.executablePath } : {}),
         };
         if (resumeId)
@@ -1516,12 +1513,12 @@ export class ClaudeCodeRuntime {
         return [{ id: "anthropic", name: "Anthropic", oauth: true, models: FALLBACK_MODELS }];
     }
     async createSession(options) {
-        const session = new ClaudeSession(await withSessionCredentials(this.options, options.credentialLabels), options.workspace, options.toolInterceptor, options.toolProvider);
+        const session = new ClaudeSession({ ...(await withSessionCredentials(this.options, options.credentialLabels)), instructions: options.instructions?.text }, options.workspace, options.toolInterceptor, options.toolProvider);
         this.sessions.push(session);
         return { session };
     }
     async openSession(options) {
-        const session = new ClaudeSession(await withSessionCredentials(this.options, options.credentialLabels), options.workspace, options.toolInterceptor, options.toolProvider, options.sessionFile);
+        const session = new ClaudeSession({ ...(await withSessionCredentials(this.options, options.credentialLabels)), instructions: options.instructions?.text }, options.workspace, options.toolInterceptor, options.toolProvider, options.sessionFile);
         this.sessions.push(session);
         return {
             session,