@bivy/bivy 0.0.0 → 0.1.0-staging.2

package/dist/harness/net-proxy.js

@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Universal Agent Harness — network effect boundary (egress broker).
+//
+// Third pillar of "govern the substrate, not the agent". Almost every CLI agent
+// (and the tools it spawns) honors the conventional HTTP_PROXY / HTTPS_PROXY /
+// ALL_PROXY environment variables, so a single local proxy the daemon injects
+// into the agent's env sees — and can allow/deny/log — all of its outbound
+// network traffic, with zero agent-specific code.
+//
+// It handles both proxy modes:
+//   * plain HTTP   → an ordinary forward proxy (absolute-URI requests),
+//   * HTTPS/TLS    → the CONNECT method (we see host:port and tunnel bytes; TLS
+//                    stays end-to-end so we log the destination, not content).
+//
+// Per the locked decision this ships as observe-and-log first (default allow),
+// but the decider can deny by host now (e.g. block a data-exfil domain). Pure
+// networking, unit-tested in test/harness-net-proxy.test.ts.
+import http from "node:http";
+import net from "node:net";
+/** Split "host:port" (CONNECT target) into parts, defaulting the port. */
+export function parseHostPort(authority, defaultPort) {
+    // IPv6 literal like [::1]:443
+    const m = /^\[([^\]]+)\]:?(\d+)?$/.exec(authority);
+    if (m)
+        return { host: m[1], port: m[2] ? Number(m[2]) : defaultPort };
+    const idx = authority.lastIndexOf(":");
+    if (idx > 0 && /^\d+$/.test(authority.slice(idx + 1))) {
+        return { host: authority.slice(0, idx), port: Number(authority.slice(idx + 1)) };
+    }
+    return { host: authority, port: defaultPort };
+}
+/**
+ * A running egress proxy. Construct via `EgressProxy.start()`; inject its
+ * `env()` into an agent subprocess so all its traffic flows through it.
+ */
+export class EgressProxy {
+    server;
+    port;
+    host;
+    constructor(server, port, host) {
+        this.server = server;
+        this.port = port;
+        this.host = host;
+    }
+    static start(options = {}, listenHost = "127.0.0.1") {
+        const decide = options.decide ?? (() => ({ allow: true }));
+        const onEvent = options.onEvent ?? (() => { });
+        const server = http.createServer((clientReq, clientRes) => {
+            // Plain-HTTP forward proxy: the request line carries an absolute URI.
+            let target;
+            try {
+                target = new URL(clientReq.url ?? "");
+            }
+            catch {
+                clientRes.writeHead(400).end("Bad proxy request");
+                return;
+            }
+            const port = target.port ? Number(target.port) : 80;
+            void Promise.resolve(decide(target.hostname, port)).then((decision) => {
+                onEvent({ type: "http", host: target.hostname, port, method: clientReq.method ?? "GET", url: target.href, allowed: decision.allow, reason: decision.reason });
+                if (!decision.allow) {
+                    clientRes.writeHead(403).end(decision.reason || "Blocked by Bivy egress policy");
+                    return;
+                }
+                const proxyReq = http.request({ hostname: target.hostname, port, path: `${target.pathname}${target.search}`, method: clientReq.method, headers: clientReq.headers }, (proxyRes) => {
+                    clientRes.writeHead(proxyRes.statusCode ?? 502, proxyRes.headers);
+                    proxyRes.pipe(clientRes);
+                });
+                proxyReq.on("error", () => clientRes.writeHead(502).end("Upstream error"));
+                clientReq.pipe(proxyReq);
+            });
+        });
+        // HTTPS via CONNECT: we see host:port and tunnel raw bytes (TLS end-to-end).
+        server.on("connect", (req, clientSocket, head) => {
+            const { host, port } = parseHostPort(req.url ?? "", 443);
+            void Promise.resolve(decide(host, port)).then((decision) => {
+                onEvent({ type: "connect", host, port, allowed: decision.allow, reason: decision.reason });
+                if (!decision.allow) {
+                    clientSocket.write("HTTP/1.1 403 Forbidden\r\n\r\n");
+                    clientSocket.destroy();
+                    return;
+                }
+                const upstream = net.connect(port, host, () => {
+                    clientSocket.write("HTTP/1.1 200 Connection Established\r\n\r\n");
+                    if (head && head.length)
+                        upstream.write(head);
+                    upstream.pipe(clientSocket);
+                    clientSocket.pipe(upstream);
+                });
+                upstream.on("error", () => clientSocket.destroy());
+                clientSocket.on("error", () => upstream.destroy());
+            });
+        });
+        return new Promise((resolve) => {
+            server.listen(0, listenHost, () => {
+                const addr = server.address();
+                const port = typeof addr === "object" && addr ? addr.port : 0;
+                resolve(new EgressProxy(server, port, listenHost));
+            });
+        });
+    }
+    /** Proxy env to merge into an agent subprocess so its traffic is governed. */
+    env() {
+        const url = `http://${this.host}:${this.port}`;
+        return {
+            HTTP_PROXY: url,
+            HTTPS_PROXY: url,
+            http_proxy: url,
+            https_proxy: url,
+            ALL_PROXY: url,
+            // Never route node-local traffic (the daemon's own API, MCP proxy) through here.
+            NO_PROXY: "127.0.0.1,localhost,::1",
+            no_proxy: "127.0.0.1,localhost,::1",
+        };
+    }
+    stop() {
+        return new Promise((resolve) => this.server.close(() => resolve()));
+    }
+}

package/dist/harness/sandbox.js

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Universal Agent Harness — exec sandbox (configure the agent's own sandbox).
+//
+// Several agents ship their OWN sandbox, so Bivy just selects the right tier per
+// session from one policy knob and lets each agent enforce it natively. This gives
+// real, in-agent enforcement (a read-only session physically refuses writes) with
+// a single data mapping and no OS-specific code. Agents without a native sandbox
+// run under the filesystem, MCP, and network governance channels instead.
+//
+// Tiers use Codex's vocabulary because it's the clearest:
+//   read-only          — may read the workspace; no writes, no network.
+//   workspace-write    — may read/write the worktree; escapes need approval.
+//   danger-full-access — no in-agent limit (explicit opt-out).
+//
+// Chosen by BIVY_SANDBOX (default workspace-write — the safe, useful middle).
+// Agents without a native sandbox (Goose, OpenCode, Aider) return no flags and
+// remain governed by the filesystem, MCP, and network channels instead.
+const TIERS = ["read-only", "workspace-write", "danger-full-access"];
+/** Coerce an arbitrary value to a valid SandboxTier, or undefined if it isn't one. */
+export function normalizeSandboxTier(value) {
+    const raw = String(value ?? "").trim().toLowerCase().replace(/_/g, "-");
+    return TIERS.includes(raw) ? raw : undefined;
+}
+// The node's configured default tier (from settings.json), set on startup and
+// whenever node settings change. `BIVY_SANDBOX` still wins so an explicit env on
+// the process overrides the persisted setting; a per-session override (passed to
+// sandboxTier) wins over both.
+let configuredTier;
+export function setConfiguredSandboxTier(value) {
+    configuredTier = normalizeSandboxTier(value);
+}
+/**
+ * The sandbox tier to launch an agent at. Precedence:
+ *   per-session override (arg) > BIVY_SANDBOX env > node setting > workspace-write.
+ */
+export function sandboxTier(override) {
+    return (normalizeSandboxTier(override) ??
+        normalizeSandboxTier(process.env.BIVY_SANDBOX) ??
+        configuredTier ??
+        "workspace-write");
+}
+/** Gemini expresses containment through --approval-mode rather than a tier flag. */
+function geminiApprovalArgs(tier) {
+    switch (tier) {
+        case "read-only":
+            return ["--approval-mode", "plan"]; // plan mode = read-only
+        case "danger-full-access":
+            return ["--approval-mode", "yolo"]; // auto-approve everything
+        case "workspace-write":
+        default:
+            return ["--approval-mode", "auto_edit"]; // auto-approve edits, still bounded
+    }
+}
+/**
+ * Native sandbox/approval flags for an agent at a tier. Empty when the agent has
+ * no native sandbox. These are inserted by the runtime when composing the
+ * launch args (see CLI_AGENT_SPECS.composeArgs).
+ */
+export function sandboxArgsFor(agentId, tier) {
+    switch (agentId) {
+        case "codex":
+            return ["--sandbox", tier];
+        // Qwen Code is a Gemini-CLI fork and shares its `--approval-mode` flag.
+        case "gemini":
+        case "qwen":
+            return geminiApprovalArgs(tier);
+        default:
+            return [];
+    }
+}
+/** Claude Agent SDK permissionMode equivalent of a tier (used by the SDK adapter). */
+export function claudePermissionModeFor(tier) {
+    if (tier === "read-only")
+        return "plan";
+    if (tier === "danger-full-access")
+        return "bypassPermissions";
+    return "default"; // guardian's canUseTool still gates risky tools
+}
+/**
+ * Codex app-server containment for a tier (the governed "Codex approvals"
+ * runtime, whose shim drives `codex app-server`). Codex's `thread/start` takes
+ * two knobs: `sandbox` (its native OS jail — the tier values ARE Codex's
+ * `--sandbox` modes) and `approvalPolicy` (whether it escalates a proposed
+ * action before running it). The restrictive tiers stay on "untrusted" so every
+ * command/patch surfaces as a Bivy Approve/Deny card through the guardian, on
+ * top of the sandbox. "Full access" (danger-full-access) is an explicit opt-out:
+ * no sandbox AND "never" ask, so the agent runs unrestricted — otherwise
+ * "allow all" would still gate every action behind an approval card, which is
+ * exactly the mismatch this fixes.
+ */
+export function codexSandboxPolicy(tier) {
+    return tier === "danger-full-access"
+        ? { sandbox: tier, approvalPolicy: "never" }
+        : { sandbox: tier, approvalPolicy: "untrusted" };
+}

package/dist/history-sync.js

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import { createHash } from "node:crypto";
+function hashMessages(messages) {
+    return createHash("sha256").update(JSON.stringify(messages)).digest("hex");
+}
+/**
+ * Decide whether to send the whole transcript or just the new tail, given what
+ * the client says it already has.
+ */
+export function historyDelta(messages, cursor = {}) {
+    const count = messages.length;
+    const historyHash = hashMessages(messages);
+    const { have, haveToken } = cursor;
+    if (typeof have === "number" &&
+        Number.isInteger(have) &&
+        have > 0 &&
+        have <= count &&
+        typeof haveToken === "string" &&
+        haveToken.length > 0 &&
+        hashMessages(messages.slice(0, have)) === haveToken) {
+        // Prefix matches — send only what's new (possibly nothing, if have === count).
+        return { mode: "append", baseCount: have, messages: messages.slice(have), count, historyHash };
+    }
+    return { mode: "full", baseCount: 0, messages, count, historyHash };
+}

package/dist/hosted-endpoints.d.mts

@@ -0,0 +1,14 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+export declare const DEFAULT_HOSTED_DOMAIN: string;
+
+export interface HostedEndpoints {
+  domain: string;
+  controlPlane: string;
+  relay: string;
+  clientBaseUrl: string;
+}
+
+export declare function hostedEndpoints(
+  env?: Record<string, string | undefined>,
+): HostedEndpoints;

package/dist/hosted-endpoints.mjs

@@ -0,0 +1,35 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+/**
+ * Hosted endpoint defaults — single source of truth (step 1).
+ *
+ * The node derives its app/control-plane, relay, and remote-client URLs from ONE
+ * hosted domain, so a user never has to type or even know these URLs. Every
+ * value is overridable by environment variable for self-hosting / staging:
+ *
+ *   BIVY_HOSTED_DOMAIN      base domain (e.g. "bivy.sh")
+ *   BIVY_CONTROL_PLANE_URL  full app/control-plane URL override
+ *   BIVY_RELAY_URL          full relay ws(s):// URL override
+ *   BIVY_CLIENT_BASE_URL    remote web-client base URL override
+ *
+ * Imported by both bin/bivy.mjs (plain Node) and src/relay-setup.ts (via tsx),
+ * which is why this is a dependency-free .mjs module.
+ */
+
+// The hosted domain baked into builds. app.<domain> and relay.<domain> are
+// derived from it so users do not need to enter hosted URLs during setup.
+export const DEFAULT_HOSTED_DOMAIN = "bivy.sh";
+
+/**
+ * Resolve the hosted endpoints from env (falling back to the baked-in domain).
+ * @param {Record<string, string | undefined>} [env]
+ */
+export function hostedEndpoints(env = process.env) {
+  const domain = (env.BIVY_HOSTED_DOMAIN || DEFAULT_HOSTED_DOMAIN)
+    .replace(/^https?:\/\//, "")
+    .replace(/\/+$/, "");
+  const controlPlane = (env.BIVY_CONTROL_PLANE_URL || `https://app.${domain}`).replace(/\/+$/, "");
+  const relay = (env.BIVY_RELAY_URL || `wss://relay.${domain}`).replace(/\/+$/, "");
+  const clientBaseUrl = (env.BIVY_CLIENT_BASE_URL || controlPlane).replace(/\/+$/, "");
+  return { domain, controlPlane, relay, clientBaseUrl };
+}

package/dist/identity.js

@@ -0,0 +1,153 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { randomBytes, randomUUID, createHash, timingSafeEqual } from "node:crypto";
+function defaultNodeName() {
+    return os.hostname();
+}
+function migrateNodeName(name) {
+    return name.replace(/\s+local node$/i, "");
+}
+function hashToken(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+export class NodeIdentity {
+    configPath;
+    config;
+    constructor(configPath, config) {
+        this.configPath = configPath;
+        this.config = config;
+    }
+    static load(appDir) {
+        const configPath = path.join(appDir, "node.json");
+        fs.mkdirSync(appDir, { recursive: true, mode: 0o700 });
+        let raw;
+        try {
+            raw = fs.readFileSync(configPath, "utf8");
+        }
+        catch (error) {
+            // Only a missing file means "no identity yet". Any other read failure
+            // (permission denied, I/O error, etc.) must not mint a fresh identity.
+            if (error?.code !== "ENOENT")
+                throw error;
+        }
+        let config;
+        if (raw === undefined) {
+            config = {
+                nodeId: `node_${randomUUID()}`,
+                name: defaultNodeName(),
+                createdAt: new Date().toISOString(),
+                devices: [],
+            };
+        }
+        else {
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                // The file exists but is corrupt/truncated. Minting a fresh nodeId here
+                // would silently invalidate every device paired with this node, so fail
+                // loudly instead and let the operator decide how to recover.
+                throw new Error(`Node identity file at ${configPath} is corrupt and could not be parsed. Refusing to generate a ` +
+                    `new node identity (this would invalidate every paired device). Restore it from a backup, or ` +
+                    `remove the file manually if you intend to start fresh.`);
+            }
+            config = {
+                nodeId: typeof parsed.nodeId === "string" && parsed.nodeId ? parsed.nodeId : `node_${randomUUID()}`,
+                name: typeof parsed.name === "string" && parsed.name.trim()
+                    ? migrateNodeName(parsed.name.trim())
+                    : defaultNodeName(),
+                createdAt: typeof parsed.createdAt === "string" ? parsed.createdAt : new Date().toISOString(),
+                devices: Array.isArray(parsed.devices) ? parsed.devices : [],
+            };
+        }
+        const identity = new NodeIdentity(configPath, config);
+        identity.persist();
+        return identity;
+    }
+    persist() {
+        // Atomic write: write to a tmp file in the same directory, then rename over
+        // the target. This guarantees readers never observe a partially-written or
+        // truncated node.json, even if the process is killed mid-write.
+        const tmp = `${this.configPath}.tmp`;
+        fs.writeFileSync(tmp, `${JSON.stringify(this.config, null, 2)}\n`, { mode: 0o600 });
+        try {
+            fs.chmodSync(tmp, 0o600);
+        }
+        catch {
+            // Best effort on platforms without chmod.
+        }
+        fs.renameSync(tmp, this.configPath);
+        try {
+            fs.chmodSync(this.configPath, 0o600);
+        }
+        catch {
+            // Best effort on platforms without chmod.
+        }
+    }
+    get nodeId() {
+        return this.config.nodeId;
+    }
+    get name() {
+        return this.config.name;
+    }
+    setName(name) {
+        const clean = name.trim().replace(/\s+/g, " ").slice(0, 80);
+        if (!clean)
+            throw new Error("Node name cannot be empty");
+        this.config.name = clean;
+        this.persist();
+        return clean;
+    }
+    listDevices() {
+        return this.config.devices.map(({ tokenHash: _hash, ...rest }) => rest);
+    }
+    /**
+     * Create a new device token. Returns the raw token, which is shown to the
+     * user exactly once and never recoverable afterwards.
+     */
+    createDevice(name) {
+        const clean = name.trim().slice(0, 80) || "Unnamed device";
+        const token = `mesh_${randomBytes(32).toString("base64url")}`;
+        const record = {
+            id: `dev_${randomUUID()}`,
+            name: clean,
+            tokenHash: hashToken(token),
+            createdAt: new Date().toISOString(),
+            lastSeenAt: null,
+        };
+        this.config.devices.push(record);
+        this.persist();
+        const { tokenHash: _hash, ...device } = record;
+        return { device, token };
+    }
+    revokeDevice(id) {
+        const before = this.config.devices.length;
+        this.config.devices = this.config.devices.filter((device) => device.id !== id);
+        const removed = this.config.devices.length < before;
+        if (removed)
+            this.persist();
+        return removed;
+    }
+    /**
+     * Verify a raw token against stored hashes using a constant-time compare.
+     * Updates lastSeenAt on a match. Returns the matched device id, or null.
+     */
+    verifyToken(token) {
+        if (!token)
+            return null;
+        const candidateBuf = Buffer.from(hashToken(token), "hex");
+        for (const device of this.config.devices) {
+            const storedBuf = Buffer.from(device.tokenHash, "hex");
+            if (storedBuf.length === candidateBuf.length && timingSafeEqual(storedBuf, candidateBuf)) {
+                device.lastSeenAt = new Date().toISOString();
+                this.persist();
+                return device.id;
+            }
+        }
+        return null;
+    }
+}

package/dist/integrations/index.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+export { IntegrationManager } from "./manager.js";
+export { BUILT_IN_INTEGRATIONS } from "./registry.js";