@bivy/bivy 0.0.0 → 0.1.0-staging.10

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Petter André Sjulstad
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -1,8 +1,268 @@
-# @bivy/bivy
+# Bivy
 
-Placeholder package reserving the `@bivy/bivy` name on npm.
+Route coding-agent work to infrastructure you own.
 
-This package does not contain any functionality yet. It is intended to eventually
-hold the distributable parts of the [Bivy](https://github.com/) project.
+Bivy turns GitHub issues, Slack requests, signed webhooks, schedules, and live
+prompts into governed agent runs on your laptop, server, or cloud account. Choose
+the node, agent, and model; burst onto a short-lived runner in your own cloud;
+then watch, steer, and approve from a phone, browser, or terminal.
 
-Stay tuned.
+Agents run with your repository, keys, and toolchain. Bivy's relay and control
+plane do not receive repository contents, prompts, transcripts, or model keys.
+Bivy adds routing, durable sessions, approvals, fallback rules, and outcome
+reports around agents you already use.
+
+- **Website:** [bivy.sh](https://bivy.sh)
+- **Documentation:** [`docs/`](docs/README.md) — start with the [quickstart](docs/quickstart.md)
+- **License:** [FSL-1.1-ALv2](LICENSE) (source-available; converts to Apache-2.0 two years after each release)
+
+> Bivy is 0.x software. The core loop is solid and used daily, but interfaces
+> and behaviour can change between releases.
+
+## Install
+
+```bash
+curl -fsSL https://bivy.sh/install.sh | bash
+```
+
+macOS and Linux. Requires Node 22.19 or newer; the installer sets it up if
+missing. It installs the [`@bivy/bivy`](https://www.npmjs.com/package/@bivy/bivy) package
+from npm, then runs the guided `bivy setup` wizard — workspace, relay/control-
+plane sign-in, and an auto-start background service (launchd on macOS, systemd
+on Linux).
+
+Already have Node? The installer is optional:
+
+```bash
+npm install -g @bivy/bivy
+bivy setup
+```
+
+Releases are published from CI with provenance attestations; verify with
+`npm audit signatures`. See [`docs/releasing.md`](docs/releasing.md).
+
+Already have the repository checked out:
+
+```bash
+npm install
+npm run setup
+```
+
+See [`docs/install.md`](docs/install.md) for service management and uninstall.
+
+## Architecture
+
+Bivy has three parts. Only the first one holds your data.
+
+```text
+  your machine                     hosted or self-hosted
+
+  ┌──────────────┐               ┌─────────┐        ┌───────────────┐
+  │ node daemon  │  ──dials──▶   │  relay  │ ◀────▶ │ control plane │
+  │ agents, keys │    outbound   │ opaque  │        │ accounts, web │
+  │ repo, tools  │               │ frames  │        │ app, metadata │
+  └──────────────┘               └─────────┘        └───────────────┘
+         ▲                                                  ▲
+         └────────── end-to-end encrypted session ───────────┘
+                     phone · browser · another terminal
+```
+
+- **Node** — a daemon on your machine. Owns the workspace, credentials, and agent
+  processes. Serves an API and WebSocket on `http://localhost:4317` plus a
+  `/healthz` probe. **It hosts no web UI.**
+- **Relay** — forwards encrypted frames between your node and your devices. Your
+  node dials out, so no inbound port is opened. The relay cannot read the frames.
+- **Control plane** — holds your account, node registry, and session index, and
+  serves the web/PWA client. Use the hosted one or run your own.
+
+Because the node serves no UI, a browser or phone needs a control plane — hosted
+at `app.bivy.sh`, or one you deploy yourself. The terminal CLI needs neither.
+
+See [`docs/remote-access.md`](docs/remote-access.md) and
+[`docs/security-model.md`](docs/security-model.md).
+
+## Supported agents
+
+Nineteen agents are available in the picker, each driven through its native interface:
+
+| Agent | Command | Notes |
+|---|---|---|
+| Pi | `bivy run pi` | Default; bundled |
+| Claude Code | `bivy run claude` | Bundled SDK |
+| Codex | `bivy run codex` | Installs `@openai/codex` |
+| OpenCode | `bivy run opencode` | Installs `opencode-ai/opencode` |
+| Gemini CLI | `bivy run gemini` | Installs `@google/gemini-cli` |
+| Qwen Code | `bivy run qwen` | Installs `@qwen-code/qwen-code` |
+| Goose | `bivy run goose` | Requires `goose` on PATH |
+| Aider | `bivy run aider` | No session resume (upstream gap) |
+| Cline | `bivy run cline` | Installs `cline` |
+| Crush | `bivy run crush` | No session resume (upstream gap) |
+| Cursor | `bivy run cursor` | ACP-capable |
+| GitHub Copilot | `bivy run copilot` | ACP-capable |
+| Grok | `bivy run grok` | Model selection |
+| Amp | `bivy run amp` | Native thread resume |
+| Auggie | `bivy run auggie` | Headless CLI |
+| Droid | `bivy run droid` | Model selection |
+| Continue | `bivy run continue` | Headless CLI |
+| Kilo Code | `bivy run kilocode` | ACP-capable |
+| Rovo Dev | `bivy run rovodev` | Installed out of band |
+
+Any other command works via `bivy run -- ./your-agent --flags`. ACP-capable
+agents can be promoted to Bivy's governed protocol path for per-tool approvals
+and native resume.
+
+[`docs/runtime-support-matrix.md`](docs/runtime-support-matrix.md) lists exactly
+what each agent supports — resume, model selection, approvals, sandboxing.
+
+## Common commands
+
+```bash
+bivy                  # launch the default agent as a durable session
+bivy run claude       # run a specific agent
+bivy sessions         # list live and saved sessions
+bivy resume           # resume the most recent session
+bivy open             # open the web app (requires relay setup)
+bivy status           # config summary and node reachability
+bivy doctor           # health check
+bivy logs -f          # tail node logs
+bivy update           # update Bivy and restart the service
+```
+
+Full command list, flags, and examples: [`docs/cli-reference.md`](docs/cli-reference.md).
+
+## Configuration
+
+The common knobs:
+
+```bash
+BIVY_WORKSPACE=/path/to/repo    # default workspace
+BIVY_SANDBOX=read-only          # read-only | workspace-write (default) | danger-full-access
+BIVY_APPROVAL_MODE=risky        # never | risky | always | autonomous (default)
+```
+
+Every environment variable, config file, and precedence rule:
+[`docs/configuration.md`](docs/configuration.md).
+
+## Approvals and sandboxing
+
+The default approval mode is **`autonomous`**: agents act without per-action
+prompts. Safety comes from a floor that applies in *every* mode — catastrophic
+commands and writes outside the workspace are refused outright, and a backstop
+set (force-push, publish, deploy, sudo) always pauses for a human.
+
+If you want to be asked about more, set the mode explicitly:
+
+```bash
+BIVY_APPROVAL_MODE=risky    # prompt on risky shell commands and file edits
+BIVY_APPROVAL_MODE=always   # prompt on every tool call
+BIVY_APPROVAL_MODE=never    # no prompts beyond the hard floor
+```
+
+Approve from the terminal, browser, or phone.
+
+Sandbox tiers (`read-only`, `workspace-write`, `danger-full-access`) are enforced
+natively by agents that support them — Codex, Claude Code, Gemini CLI, Qwen Code.
+Agents without a native sandbox are governed at the filesystem, MCP, and network
+layer. **Bivy does not ship its own OS-level jail in 0.1.**
+
+## Credentials
+
+Provider credentials stay on the node or in a vault you control. Bivy Cloud does
+not receive model keys, GitHub repository tokens, OAuth refresh tokens, prompts,
+transcripts, or workspace files.
+
+```bash
+bivy secrets list
+bivy secrets set github.repo-token
+bivy secrets ref github.repo-token op://Bivy/GitHub/repo-token
+bivy secrets doctor
+```
+
+`secret://`, `env://`, and `op://` (1Password) references are resolved before the
+daemon starts. See [`docs/key-management.md`](docs/key-management.md).
+
+## GitHub work queue
+
+Label an issue `bivy` (or `bivy/<node>` to target a machine), or mention the Bivy
+GitHub App in a comment. A node you own claims the work, runs the agent in an
+isolated worktree, and the agent opens the pull request itself.
+
+Available on every plan: interactive CLI/app sessions are unlimited. Free
+accounts also get 10 unattended automations per rolling 7-day window across
+GitHub, Slack, webhooks, and schedules; Pro removes the automation cap.
+Self-hosted stacks are unlimited.
+
+A private GitHub App only installs on the account that owns it, so connect one
+app per GitHub account — one for your personal repos, one per organization
+(`bivy github:app-create --org <org>`). A node can serve several at once, each
+with its own key and `@`-mention handle.
+
+See [`docs/github-work-queue.md`](docs/github-work-queue.md).
+
+## Linear work queue
+
+Apply `bivy` or `bivy/<node>` to a Linear issue to dispatch it to the same hosted queue. The node fetches issue content directly from Linear, works in an isolated GitHub worktree, and asks the agent to open a pull request. See [`docs/linear-work-queue.md`](docs/linear-work-queue.md).
+
+## Development
+
+```bash
+npm install
+npm run dev          # node daemon on http://localhost:4317
+npm run dev:web      # web client dev server (proxies /api and /ws to the node)
+```
+
+Checks — all of these run in CI:
+
+```bash
+npm run typecheck
+npm run typecheck:web
+npm run lint
+npm run test:unit
+npm run test:core
+npm run check:licenses
+npm run check:secrets
+```
+
+Repository layout:
+
+- `src/` — node daemon, runtime adapters, approvals, secrets, sessions
+- `bin/` — the `bivy` CLI
+- `packages/core` — shared protocol, pairing, wire format
+- `packages/web` — the React/Vite PWA client (`@bivy/web`)
+- `services/relay` — self-hostable relay
+- `services/control-plane` — self-hostable control plane
+- `deploy/` — self-host deployment examples
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Self-hosting
+
+Node, relay, and control plane are all in this repository, and the CLI accepts
+flags to point at your own deployment:
+
+```bash
+bivy relay:setup --relay wss://relay.example.com \
+                 --control-plane https://bivy.example.com
+```
+
+**Self-hosting is unsupported** — no SLA, community best-effort via GitHub
+issues. You own TLS, backups, upgrades, and hardening. See
+[`docs/self-host.md`](docs/self-host.md).
+
+## Security
+
+Report vulnerabilities through [GitHub private vulnerability reporting](https://github.com/bivysh/bivy/security/advisories/new).
+Please do not open a public issue. See [`SECURITY.md`](SECURITY.md) for scope,
+response times, and safe harbour, and [`docs/security-model.md`](docs/security-model.md)
+for the trust model and known limitations.
+
+## License
+
+Bivy Core is licensed under the Functional Source License (FSL-1.1-ALv2): you may
+use, modify, and self-host it for any purpose **except a Competing Use** —
+offering it to others as a product or service that substitutes for Bivy or Bivy
+Cloud. Two years after each release, that version converts to Apache-2.0.
+
+This is a source-available licence, not an OSI-approved open source licence.
+
+See [`LICENSE`](LICENSE), [`CORE.md`](CORE.md), and [`CLOUD.md`](CLOUD.md).

package/bin/acp-shim.mjs

@@ -0,0 +1,298 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// ACP ⇄ Bivy Agent Protocol shim — the GENERAL high-capability adapter.
+//
+// The Codex shim (codex-app-server-shim.mjs) proved that driving an agent's
+// bidirectional JSON-RPC app-server — instead of a one-shot stdout pipe — buys
+// per-tool approvals, streaming, and resume. Everything there is Codex-specific is
+// the *protocol*. ACP (Agent Client Protocol, https://agentclientprotocol.com) is
+// the open standard for exactly that surface, and a growing set of agents speak it
+// (Gemini CLI `--experimental-acp`, and others). This shim bridges ANY ACP agent to
+// the bivy-agent-protocol JSONL that ProtocolRuntime (src/runtime/protocol.ts)
+// speaks — so a new ACP agent becomes fully governed (Approve/Deny per tool),
+// streaming, and resumable as DATA (one catalog entry), never per-agent code.
+//
+// Usage (spawned by the daemon's `acp` runtime):
+//   node acp-shim.mjs --agent <cmd> [-- <agent args…>]
+//
+// ACP surface implemented (client side of the protocol):
+//   → initialize / session/new / session/load / session/prompt / session/cancel
+//   ← session/update  (agent_message_chunk, agent_thought_chunk, tool_call,
+//                       tool_call_update, plan) → streamed transcript
+//   ← session/request_permission → a bivy `tool.call` we block on until the human
+//                       taps Approve/Deny (answered as the ACP selected option)
+//   ← fs/read_text_file / fs/write_text_file → serviced against the workspace
+//
+// Transport is newline-delimited JSON-RPC 2.0 over the agent's stdio (as Gemini's
+// ACP mode emits). Experimental: validate against your ACP agent, then promote it
+// into the picker as data. Fail-closed on permission (deny if the human declines),
+// fail-safe elsewhere (surface errors as session.error rather than wedging).
+
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import fs from "node:fs";
+
+// --- arg parsing: --agent <cmd> [-- <args…>] --------------------------------
+const argv = process.argv.slice(2);
+let agentCmd = process.env.BIVY_ACP_COMMAND || "";
+let agentArgs = [];
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === "--agent") agentCmd = argv[++i] ?? "";
+  else if (argv[i] === "--") { agentArgs = argv.slice(i + 1); break; }
+}
+if (process.env.BIVY_ACP_ARGS && agentArgs.length === 0) {
+  try { const p = JSON.parse(process.env.BIVY_ACP_ARGS); if (Array.isArray(p)) agentArgs = p.map(String); } catch { /* ignore */ }
+}
+if (!agentCmd) {
+  process.stderr.write("acp-shim: no agent command (set --agent <cmd> or BIVY_ACP_COMMAND)\n");
+  process.exit(2);
+}
+
+// --- bivy-agent-protocol output (our stdout) --------------------------------
+function bivy(obj) {
+  process.stdout.write(`${JSON.stringify(obj)}\n`);
+}
+
+// --- ACP agent (child JSON-RPC over its stdio) ------------------------------
+const agent = spawn(agentCmd, agentArgs, { stdio: ["pipe", "pipe", "pipe"] });
+agent.stderr.on("data", (d) => process.stderr.write(`[acp-agent] ${d}`));
+agent.on("error", (e) => bivy({ type: "session.error", error: `acp agent spawn failed: ${e.message}` }));
+agent.on("exit", (code) => {
+  if (code && code !== 0) bivy({ type: "session.error", error: `acp agent exited (${code})` });
+});
+
+let nextId = 1;
+const pending = new Map(); // jsonrpc id -> {resolve, reject}
+function agentRequest(method, params) {
+  const id = nextId++;
+  agent.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+  return new Promise((resolve, reject) => pending.set(id, { resolve, reject }));
+}
+function agentReply(id, result) {
+  agent.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, result })}\n`);
+}
+function agentReplyError(id, code, message) {
+  agent.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } })}\n`);
+}
+function agentNotify(method, params) {
+  agent.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
+}
+
+// --- session state ----------------------------------------------------------
+let sessionId = null;
+let cwd = process.cwd();
+let initialized = false;
+// toolCallId -> { requestId, options } so a later bivy tool.decision answers the
+// right ACP permission request with a concrete optionId.
+const permissionRequests = new Map();
+
+async function ensureInitialized() {
+  if (initialized) return;
+  await agentRequest("initialize", {
+    protocolVersion: 1,
+    clientCapabilities: { fs: { readTextFile: true, writeTextFile: true } },
+  });
+  initialized = true;
+}
+
+// --- ACP → bivy: streamed session/update notifications ----------------------
+function onSessionUpdate(params) {
+  const u = params?.update;
+  if (!u || typeof u !== "object") return;
+  const kind = String(u.sessionUpdate || "");
+  const textOf = (content) => {
+    if (!content) return "";
+    if (typeof content === "string") return content;
+    if (Array.isArray(content)) return content.map(textOf).join("");
+    if (content.type === "text" && typeof content.text === "string") return content.text;
+    if (typeof content.text === "string") return content.text;
+    return "";
+  };
+  switch (kind) {
+    case "agent_message_chunk": {
+      const t = textOf(u.content);
+      if (t) bivy({ type: "message.delta", text: t });
+      break;
+    }
+    case "agent_thought_chunk": {
+      const t = textOf(u.content);
+      if (t) bivy({ type: "message.reasoning", text: t });
+      break;
+    }
+    case "tool_call": {
+      // An auto-run tool (no permission requested) — surface it so the transcript
+      // shows the action; the result arrives via tool_call_update.
+      const toolCallId = String(u.toolCallId ?? u.id ?? "");
+      bivy({ type: "tool.call", toolCallId, name: String(u.title || u.kind || "tool"), input: u.rawInput ?? u.input ?? {} });
+      break;
+    }
+    case "tool_call_update": {
+      const toolCallId = String(u.toolCallId ?? u.id ?? "");
+      const status = String(u.status || "");
+      if (status === "completed" || status === "failed") {
+        bivy({ type: "tool.result", toolCallId, name: String(u.title || "tool"), result: textOf(u.content) || status });
+      }
+      break;
+    }
+    case "plan":
+      // Optional planning stream — fold into reasoning so nothing is lost.
+      if (Array.isArray(u.entries)) bivy({ type: "message.reasoning", text: u.entries.map((e) => `• ${e.content ?? ""}`).join("\n") });
+      break;
+    default:
+      break;
+  }
+}
+
+// --- ACP → bivy: agent→client requests (permission, fs) ---------------------
+async function onAgentRequest(id, method, params) {
+  switch (method) {
+    case "session/request_permission": {
+      // Turn the ACP permission prompt into a bivy tool.call the daemon gates via
+      // guardianInterceptor; remember the options so the human's decision maps back
+      // to a concrete ACP optionId.
+      const tc = params?.toolCall ?? {};
+      const toolCallId = String(tc.toolCallId ?? tc.id ?? `perm-${id}`);
+      const options = Array.isArray(params?.options) ? params.options : [];
+      permissionRequests.set(toolCallId, { requestId: id, options });
+      bivy({ type: "tool.call", toolCallId, name: String(tc.title || tc.kind || "tool"), input: tc.rawInput ?? tc.input ?? {} });
+      return;
+    }
+    case "fs/read_text_file": {
+      try {
+        let text = fs.readFileSync(String(params?.path ?? ""), "utf8");
+        if (typeof params?.line === "number" || typeof params?.limit === "number") {
+          const lines = text.split("\n");
+          const start = Math.max(0, (params.line ?? 1) - 1);
+          text = lines.slice(start, params.limit ? start + params.limit : undefined).join("\n");
+        }
+        agentReply(id, { content: text });
+      } catch (e) {
+        agentReplyError(id, -32000, `read failed: ${e.message}`);
+      }
+      return;
+    }
+    case "fs/write_text_file": {
+      try {
+        fs.writeFileSync(String(params?.path ?? ""), String(params?.content ?? ""));
+        agentReply(id, {});
+      } catch (e) {
+        agentReplyError(id, -32000, `write failed: ${e.message}`);
+      }
+      return;
+    }
+    default:
+      // Unknown client method (e.g. terminal/*): decline so the agent can fall back
+      // instead of hanging on a request we don't implement.
+      agentReplyError(id, -32601, `unsupported client method: ${method}`);
+      return;
+  }
+}
+
+// --- read the ACP agent's stdout (JSON-RPC lines) ---------------------------
+createInterface({ input: agent.stdout }).on("line", (line) => {
+  const t = line.trim();
+  if (!t) return;
+  let msg;
+  try { msg = JSON.parse(t); } catch { return; }
+  // Response to one of our requests.
+  if (msg.id !== undefined && (msg.result !== undefined || msg.error !== undefined)) {
+    const p = pending.get(msg.id);
+    if (p) {
+      pending.delete(msg.id);
+      if (msg.error) p.reject(new Error(msg.error.message || "acp error"));
+      else p.resolve(msg.result);
+    }
+    return;
+  }
+  // Agent→client request (has id + method).
+  if (msg.id !== undefined && msg.method) { void onAgentRequest(msg.id, msg.method, msg.params); return; }
+  // Notification (method, no id).
+  if (msg.method === "session/update") onSessionUpdate(msg.params);
+});
+
+// --- bivy commands in (daemon → us) -----------------------------------------
+async function onBivyCommand(msg) {
+  const type = String(msg.type || "");
+  const id = msg.id;
+  try {
+    switch (type) {
+      case "hello.ack":
+        return;
+      case "session.create": {
+        await ensureInitialized();
+        cwd = String(msg.cwd || msg.workspace || cwd);
+        const res = await agentRequest("session/new", { cwd, mcpServers: [] });
+        sessionId = res?.sessionId ?? res?.session?.id ?? null;
+        bivy({ replyTo: id, ok: true, runtimeSessionRef: sessionId });
+        return;
+      }
+      case "session.resume": {
+        await ensureInitialized();
+        const ref = String(msg.runtimeSessionRef || msg.resumeRef || msg.sessionId || "");
+        cwd = String(msg.cwd || msg.workspace || cwd);
+        if (!ref) { bivy({ replyTo: id, ok: false, error: "missing resume ref" }); return; }
+        try {
+          const res = await agentRequest("session/load", { sessionId: ref, cwd, mcpServers: [] });
+          sessionId = res?.sessionId ?? ref;
+        } catch {
+          // Agent doesn't support session/load — start fresh so the chat still opens.
+          const res = await agentRequest("session/new", { cwd, mcpServers: [] });
+          sessionId = res?.sessionId ?? null;
+        }
+        bivy({ replyTo: id, ok: true, runtimeSessionRef: sessionId });
+        return;
+      }
+      case "chat.send": {
+        if (!sessionId) { bivy({ replyTo: id, ok: false, error: "no acp session" }); return; }
+        // Ack immediately; the turn streams via session/update and finishes when the
+        // session/prompt request resolves (approval cards can make a turn outlast
+        // ProtocolRuntime's command timeout, so we must not defer the ack).
+        bivy({ replyTo: id, ok: true });
+        bivy({ type: "session.status", status: "working" });
+        agentRequest("session/prompt", { sessionId, prompt: [{ type: "text", text: String(msg.text ?? "") }] })
+          .then(() => { bivy({ type: "session.status", status: "idle" }); bivy({ type: "session.done" }); })
+          .catch((e) => bivy({ type: "session.error", error: e instanceof Error ? e.message : String(e) }));
+        return;
+      }
+      case "tool.decision": {
+        const entry = permissionRequests.get(msg.toolCallId);
+        if (entry) {
+          permissionRequests.delete(msg.toolCallId);
+          const allow = msg.decision !== "deny";
+          // Pick an ACP option matching the human's choice by its `kind`
+          // (allow_once/allow_always vs reject_once/reject_always); fall back to the
+          // first option, or a cancelled outcome when nothing fits.
+          const want = allow ? /^allow/ : /^reject/;
+          const opt = entry.options.find((o) => want.test(String(o.kind || ""))) ?? entry.options[0];
+          if (opt && opt.optionId !== undefined) agentReply(entry.requestId, { outcome: { outcome: "selected", optionId: opt.optionId } });
+          else agentReply(entry.requestId, { outcome: { outcome: "cancelled" } });
+        }
+        return;
+      }
+      case "session.abort": {
+        if (sessionId) agentNotify("session/cancel", { sessionId });
+        if (id !== undefined) bivy({ replyTo: id, ok: true });
+        return;
+      }
+      default:
+        if (id !== undefined) bivy({ replyTo: id, ok: true });
+        return;
+    }
+  } catch (error) {
+    if (id !== undefined) bivy({ replyTo: id, ok: false, error: error instanceof Error ? error.message : String(error) });
+    else bivy({ type: "session.error", error: error instanceof Error ? error.message : String(error) });
+  }
+}
+
+// Announce capabilities: ACP agents are governed (per-tool permission) and
+// resumable (session/load). Models aren't part of the core ACP surface, so we
+// don't advertise a picker we can't drive.
+bivy({ type: "hello", runtime: { capabilities: { toolInterception: true, modelSelection: false, resume: true } } });
+
+createInterface({ input: process.stdin }).on("line", (line) => {
+  if (!line.trim()) return;
+  let msg;
+  try { msg = JSON.parse(line); } catch { return; }
+  void onBivyCommand(msg);
+});