@bivy/bivy 0.0.0 → 0.1.0-staging.2

package/dist/guard.js

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import path from "node:path";
+export function bashCommand(input) {
+    if (!input || typeof input !== "object")
+        return "";
+    const command = input.command;
+    return typeof command === "string" ? command : "";
+}
+/** Heuristic for the legacy "risky" mode (prompt-heavy). */
+export function looksRiskyBash(command) {
+    const normalized = command.trim().toLowerCase();
+    if (!normalized)
+        return false;
+    return (/(^|[;&|()\s])(rm|rmdir|mv|cp|chmod|chown|dd|mkfs|sudo|su|kill|pkill|curl|wget|git\s+(commit|push|reset|clean|checkout|switch|merge|rebase)|npm\s+(install|update|publish)|pnpm\s+(install|update|publish)|yarn\s+(add|install|upgrade|publish))([;&|()\s]|$)/.test(normalized) ||
+        /(^|\s)(>|>>|2>|&>|tee\s+)/.test(normalized));
+}
+/**
+ * Catastrophic, irreversible, system-wide actions. Blocked OUTRIGHT in every mode
+ * — the boundary that makes unattended autonomy safe rather than reckless.
+ */
+export function looksCatastrophic(command) {
+    const c = command.trim().toLowerCase();
+    if (!c)
+        return false;
+    return (/\brm\s+(-\S*[rf]\S*\s+)+(\/|~|\$home|\/\*)(\s|$|\/)/.test(c) || // rm -rf / | ~ | /*
+        /\bmkfs(\.\w+)?\b/.test(c) ||
+        /\bdd\b[^\n]*\bof=\/dev\/(sd|nvme|hd|disk)/.test(c) ||
+        />\s*\/dev\/(sd|nvme|hd|disk)/.test(c) ||
+        /:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/.test(c) || // fork bomb
+        /\bchmod\s+-\S*r\S*\s+777\s+\/(\s|$)/.test(c) ||
+        /(^|[;&|]\s*)(shutdown|reboot|halt|poweroff)\b/.test(c));
+}
+/**
+ * Irreversible / outward-facing actions that pause for a human even in autonomous
+ * mode (the "backstop"): publishing, deploying, force-pushing, pushing to the
+ * default branch, privilege escalation.
+ */
+export function looksBackstop(command) {
+    const c = command.trim().toLowerCase();
+    if (!c)
+        return false;
+    return (/\bgit\s+push\b[^\n]*(--force|--force-with-lease|\s-f\b)/.test(c) ||
+        /\bgit\s+push\b[^\n]*\b(main|master)\b/.test(c) ||
+        /\bnpm\s+publish\b/.test(c) ||
+        /\b(kubectl\s+apply|terraform\s+apply|docker\s+push|fly\s+deploy|vercel\s+(deploy|--prod)|netlify\s+deploy|gh\s+release\s+create)\b/.test(c) ||
+        /(^|[;&|]\s*)(mail|mailx|sendmail|ssmtp)\b/.test(c) || // send email from the shell
+        /(^|[;&|]\s*)sudo\b/.test(c));
+}
+/** Extract a filesystem path from a write/edit tool input, if present. */
+export function toolPath(input) {
+    if (!input || typeof input !== "object")
+        return undefined;
+    const o = input;
+    for (const key of ["path", "file_path", "filePath", "file"]) {
+        if (typeof o[key] === "string" && o[key])
+            return o[key];
+    }
+    return undefined;
+}
+/** True if `p` resolves outside `workspace` (so a write there escapes the boundary). */
+export function pathEscapesWorkspace(workspace, p) {
+    const root = path.resolve(workspace);
+    const abs = path.resolve(root, p);
+    return abs !== root && !abs.startsWith(root + path.sep);
+}
+/**
+ * Decide what to do with a tool call. The hard floor (catastrophic commands,
+ * writes outside the session workspace) applies in every mode. Above that floor,
+ * `mode` decides how often to prompt.
+ */
+export function guardToolCall(workspace, toolName, input, mode, isRiskyIntegration) {
+    // Built-in tool names arrive with runtime-specific casing: the Claude Code SDK
+    // sends `Bash`/`Write`/`Edit` verbatim, while Pi/others send lowercase. Match
+    // case-insensitively so the hard floor below fires for every runtime — a
+    // case-sensitive compare silently disabled it for claude-code. Integration
+    // tool names (MCP, etc.) keep their original casing via `isRiskyIntegration`.
+    const tool = toolName.toLowerCase();
+    // Tools that write to the filesystem and so must respect the workspace
+    // boundary. MultiEdit/NotebookEdit also take a `file_path` (see toolPath).
+    const isWrite = tool === "write" || tool === "edit" || tool === "multiedit" || tool === "notebookedit";
+    // --- Hard floor: blocked in every mode ---
+    if (tool === "bash" && looksCatastrophic(bashCommand(input))) {
+        return { decision: "deny", reason: "Blocked: catastrophic command (outside the safety boundary)" };
+    }
+    if (isWrite) {
+        const p = toolPath(input);
+        if (p && pathEscapesWorkspace(workspace, p)) {
+            return { decision: "deny", reason: "Blocked: write outside the workspace boundary" };
+        }
+    }
+    if (mode === "never")
+        return { decision: "allow" };
+    // Integration tools flagged risky (send email, upload, ...) always confirm.
+    if (isRiskyIntegration(toolName))
+        return { decision: "ask" };
+    if (mode === "autonomous") {
+        if (tool === "bash" && looksBackstop(bashCommand(input)))
+            return { decision: "ask" };
+        return { decision: "allow" };
+    }
+    if (mode === "always") {
+        return { decision: tool === "bash" || isWrite ? "ask" : "allow" };
+    }
+    // "risky"
+    if (tool === "bash")
+        return { decision: looksRiskyBash(bashCommand(input)) ? "ask" : "allow" };
+    return { decision: isWrite ? "ask" : "allow" };
+}

package/dist/harness/cache-evict.js

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Size-capped LRU eviction for regenerable caches (e.g. the shared dep cache).
+//
+// The shared package-manager cache (BIVY_SHARED_DEP_CACHE) grows without bound
+// as sessions pull dependencies. These caches are content-addressed and
+// self-healing — a package manager simply re-downloads anything missing — so it
+// is safe to evict least-recently-used files to hold the cache under a byte cap.
+// Best-effort: a locked/racing file is skipped, not fatal.
+import fs from "node:fs";
+import path from "node:path";
+/** Recursive total size of the files under `dir` (symlinks not followed). */
+export function dirSizeBytes(dir) {
+    let total = 0;
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    for (const e of entries) {
+        const p = path.join(dir, e.name);
+        try {
+            if (e.isDirectory())
+                total += dirSizeBytes(p);
+            else if (e.isFile())
+                total += fs.statSync(p).size;
+        }
+        catch {
+            // unreadable entry — skip
+        }
+    }
+    return total;
+}
+/**
+ * Evict least-recently-modified files under `root` until the total size is at or
+ * below `maxBytes`. No-op when already under the cap or `maxBytes <= 0`.
+ */
+export function evictToCap(root, maxBytes) {
+    const files = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            const p = path.join(dir, e.name);
+            try {
+                if (e.isDirectory())
+                    walk(p);
+                else if (e.isFile()) {
+                    const st = fs.statSync(p);
+                    files.push({ path: p, size: st.size, mtimeMs: st.mtimeMs });
+                }
+            }
+            catch {
+                // skip
+            }
+        }
+    };
+    walk(root);
+    const before = files.reduce((n, f) => n + f.size, 0);
+    if (maxBytes <= 0 || before <= maxBytes) {
+        return { before, after: before, removedFiles: 0, removedBytes: 0 };
+    }
+    files.sort((a, b) => a.mtimeMs - b.mtimeMs); // oldest first = least recently used
+    let total = before;
+    let removedFiles = 0;
+    let removedBytes = 0;
+    for (const f of files) {
+        if (total <= maxBytes)
+            break;
+        try {
+            fs.rmSync(f.path, { force: true });
+            total -= f.size;
+            removedFiles += 1;
+            removedBytes += f.size;
+        }
+        catch {
+            // locked / racing with an install — leave it
+        }
+    }
+    return { before, after: total, removedFiles, removedBytes };
+}

package/dist/harness/cow-clone.js

@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Copy-on-write directory clone primitive.
+//
+// The foundation for installed-tree dedup across session worktrees: cloning a
+// directory (e.g. a populated node_modules / target) so the copy shares blocks
+// with the source until written, making the marginal disk cost of a second
+// worktree ≈ its diff instead of a full duplicate.
+//
+// CoW is filesystem-specific and NOT portable, so we detect capability at
+// runtime and ALWAYS fall back to a plain recursive copy — correct everywhere,
+// just without block sharing:
+//   - macOS (APFS, the default)      → clonefile via `cp -c`
+//   - Linux (btrfs / XFS reflink=1 / ZFS) → reflink via `cp --reflink=always`
+//   - Linux ext4, Windows NTFS, unknown   → recursive copy (no CoW)
+//   - Windows ReFS/Dev Drive              → not reachable via `cp`; copy for now
+//
+// Detection probes the REAL mechanism on a throwaway file rather than trusting
+// the filesystem name, because CoW depends on the mount, not just the OS.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const strategyByDir = new Map();
+function tryCp(args) {
+    try {
+        return spawnSync("cp", args, { stdio: "ignore" }).status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Determine, once per directory, the best copy-on-write strategy the filesystem
+ * backing `dir` supports. Cached per resolved directory. Falls back to "copy".
+ */
+export function detectCloneStrategy(dir = os.tmpdir()) {
+    const key = path.resolve(dir);
+    const cached = strategyByDir.get(key);
+    if (cached)
+        return cached;
+    const strategy = probeCloneStrategy(key);
+    strategyByDir.set(key, strategy);
+    return strategy;
+}
+function probeCloneStrategy(dir) {
+    const src = path.join(dir, `.bivy-cow-probe-${process.pid}-${process.hrtime.bigint()}`);
+    const dst = `${src}.clone`;
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(src, "probe");
+        if (process.platform === "darwin" && tryCp(["-c", src, dst]))
+            return "apple-clonefile";
+        if (process.platform === "linux" && tryCp(["--reflink=always", src, dst]))
+            return "reflink";
+        return "copy";
+    }
+    catch {
+        return "copy";
+    }
+    finally {
+        fs.rmSync(src, { force: true });
+        fs.rmSync(dst, { force: true });
+    }
+}
+/**
+ * Clone directory `src` to `dst`, using copy-on-write where the destination's
+ * filesystem supports it and falling back to a plain recursive copy otherwise.
+ * `dst` must not already exist. Returns the strategy actually used.
+ */
+export function cloneDir(src, dst) {
+    const strategy = detectCloneStrategy(path.dirname(dst));
+    if (strategy === "apple-clonefile" && tryCp(["-c", "-R", src, dst]))
+        return "apple-clonefile";
+    if (strategy === "reflink" && tryCp(["--reflink=always", "-R", src, dst]))
+        return "reflink";
+    // Universal fallback — correct on every OS/FS, no block sharing.
+    fs.cpSync(src, dst, { recursive: true });
+    return "copy";
+}
+/** Test-only: forget cached probe results. */
+export function __resetCloneStrategyForTests() {
+    strategyByDir.clear();
+}

package/dist/harness/dep-cache.js

@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Universal Agent Harness — shared dependency-cache singleton.
+//
+// Bivy creates a git worktree per session and is NOT in the dependency-install
+// path: the agent (or user) runs `npm install` / `pip install` / `cargo build`
+// ad-hoc inside the worktree. Without intervention, every worktree re-downloads
+// the same packages into its own tree, so N sessions of the same repo multiply
+// both disk and network.
+//
+// When BIVY_SHARED_DEP_CACHE is set, point every package manager at ONE shared
+// cache/registry directory via env, so downloads dedup across all sessions.
+// These are cache/registry knobs only — they never change a project's lockfile
+// or where its dependencies actually install, so the user's project tooling is
+// unaffected. Opt-in, mirroring the egress-proxy singleton (see egress.ts).
+//
+// Note: this dedups DOWNLOADS, not the installed trees themselves (each worktree
+// still gets its own node_modules/target/...). Installed-tree dedup needs either
+// copy-on-write worktrees or a base-provisioning step Bivy does not have today —
+// see docs/worktree-disk-strategy.md.
+import fs from "node:fs";
+import path from "node:path";
+let cacheRoot;
+/**
+ * Enable the shared dep cache if BIVY_SHARED_DEP_CACHE is set. Idempotent.
+ * Value "1"/"true" → a default location under the Bivy data dir; any other
+ * value is treated as an explicit cache-root path. Returns the resolved root,
+ * or undefined when disabled (or the root could not be created).
+ */
+export function initSharedDepCache(dataDir) {
+    if (cacheRoot)
+        return cacheRoot;
+    const flag = process.env.BIVY_SHARED_DEP_CACHE;
+    if (!flag)
+        return undefined;
+    const root = flag === "1" || flag.toLowerCase() === "true" ? path.join(dataDir, "dep-cache") : flag;
+    try {
+        fs.mkdirSync(root, { recursive: true });
+    }
+    catch {
+        // If we can't create the shared root, stay disabled rather than point every
+        // package manager at an unwritable path (which would break installs).
+        return undefined;
+    }
+    cacheRoot = root;
+    return cacheRoot;
+}
+/**
+ * Env to merge into an agent/terminal subprocess so its package managers share
+ * one cache, or {} when disabled. Cache/registry locations only.
+ */
+export function depCacheEnv() {
+    return cacheRoot ? sharedCacheEnvFor(cacheRoot) : {};
+}
+/**
+ * Pure mapping of a cache root → per-tool cache env. Exported for tests and so
+ * the mapping stays reviewable in one place. Add ecosystems here as needed
+ * (Ruby GEM/bundler and Gradle change install/config location, not just cache,
+ * so they are intentionally left out until validated — see the strategy doc).
+ */
+export function sharedCacheEnvFor(root) {
+    return {
+        npm_config_cache: path.join(root, "npm"), // npm + npx download cache
+        YARN_CACHE_FOLDER: path.join(root, "yarn"), // yarn (classic) cache
+        PIP_CACHE_DIR: path.join(root, "pip"), // pip wheel/download cache
+        CARGO_HOME: path.join(root, "cargo"), // cargo registry + git cache
+        GOMODCACHE: path.join(root, "go", "mod"), // go module cache
+        GOCACHE: path.join(root, "go", "build"), // go build cache
+    };
+}
+/** The resolved shared cache root, or undefined when disabled. */
+export function sharedDepCacheRoot() {
+    return cacheRoot;
+}
+/** Test-only: forget the resolved root so a fresh init can run. */
+export function __resetSharedDepCacheForTests() {
+    cacheRoot = undefined;
+}

package/dist/harness/disk-admission.js

@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Disk admission control.
+//
+// The safe form of a hard disk cap: rather than deleting a live worktree that
+// may hold uncommitted work (destructive), refuse to PROVISION new
+// disk-consuming work — a fresh session worktree — when the filesystem is
+// already low on free space. Bivy therefore never fills the user's device; the
+// user frees space (or closes a session) and the next attempt succeeds.
+//
+// Opt-in via BIVY_MIN_FREE_DISK_BYTES (0/unset disables). Best-effort: if free
+// space cannot be measured we ALLOW — real work must never be blocked by a
+// measurement error.
+import fs from "node:fs";
+const mib = (n) => Math.round(n / (1024 * 1024));
+function defaultStatfs(p) {
+    const st = fs.statfsSync(p);
+    return { bavail: Number(st.bavail), bsize: Number(st.bsize) };
+}
+/**
+ * Decide whether new disk-consuming work may be admitted on the filesystem
+ * backing `pathOnFs`. `minFreeBytes` defaults to BIVY_MIN_FREE_DISK_BYTES;
+ * <= 0 disables the guard (always allowed). `statfs` is injectable for tests.
+ */
+export function checkDiskAdmission(pathOnFs, opts = {}) {
+    const minFreeBytes = opts.minFreeBytes ?? Number(process.env.BIVY_MIN_FREE_DISK_BYTES ?? 0);
+    if (!Number.isFinite(minFreeBytes) || minFreeBytes <= 0)
+        return { allowed: true };
+    let freeBytes;
+    try {
+        const st = (opts.statfs ?? defaultStatfs)(pathOnFs);
+        freeBytes = st.bavail * st.bsize;
+    }
+    catch {
+        return { allowed: true }; // cannot measure → do not block real work
+    }
+    if (freeBytes < minFreeBytes) {
+        return {
+            allowed: false,
+            freeBytes,
+            minFreeBytes,
+            reason: `only ${mib(freeBytes)} MiB free (need ${mib(minFreeBytes)} MiB) — free up disk, close a session, or lower BIVY_MIN_FREE_DISK_BYTES`,
+        };
+    }
+    return { allowed: true, freeBytes, minFreeBytes };
+}

package/dist/harness/egress.js

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Universal Agent Harness — egress-proxy singleton.
+//
+// A tiny shared holder so the daemon (server.ts) can start one EgressProxy at
+// boot and the runtime layer (process.ts) can inject its env into every agent
+// subprocess — without process.ts importing the server. Opt-in via the
+// BIVY_EGRESS_PROXY env var, so routing all agent traffic through the broker is
+// an explicit choice (it adds a hop and logs destinations).
+import { EgressProxy } from "./net-proxy.js";
+let proxy;
+/** Start the egress proxy if BIVY_EGRESS_PROXY is set. Idempotent. */
+export async function startEgressProxyIfEnabled(onEvent) {
+    if (proxy)
+        return proxy;
+    if (!process.env.BIVY_EGRESS_PROXY)
+        return undefined;
+    proxy = await EgressProxy.start({ onEvent });
+    return proxy;
+}
+/** Proxy env to merge into an agent subprocess, or {} when disabled. */
+export function egressEnv() {
+    return proxy ? proxy.env() : {};
+}
+export async function stopEgressProxy() {
+    if (!proxy)
+        return;
+    await proxy.stop();
+    proxy = undefined;
+}

package/dist/harness/manager.js

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+// Universal Agent Harness — per-session checkpoint lifecycle.
+//
+// Thin, runtime-agnostic coordinator the daemon calls around a turn, regardless
+// of which agent runtime backs the session. It owns one CheckpointStore per live
+// session and turns the raw git primitives into the three events the product
+// needs: a snapshot before a turn, the structured diff a turn produced, and a
+// rewind. If a session's workspace is not a git repo, the harness disables itself
+// for that session (every method becomes a safe no-op) so non-repo sessions keep
+// working exactly as before.
+//
+// Deliberately holds no transport/UI types: the daemon maps TurnChanges onto its
+// own `session.changes` broadcast and the `session.rewind` command. Unit-tested
+// in test/harness-manager.test.ts.
+import { CheckpointStore, NotAGitRepoError } from "./checkpoint.js";
+export class HarnessManager {
+    stores = new Map();
+    /** Checkpoint captured at the start of the currently-running turn, per session. */
+    turnBase = new Map();
+    /**
+     * Begin tracking a session's workspace. Returns true when checkpointing is
+     * available (the workspace is inside a git repo), false otherwise — the caller
+     * can surface a "rewind unavailable" hint but must not treat false as an error.
+     */
+    async attach(sessionId, worktree) {
+        if (this.stores.has(sessionId))
+            return true;
+        try {
+            const store = await CheckpointStore.open(worktree, sessionId);
+            this.stores.set(sessionId, store);
+            return true;
+        }
+        catch (error) {
+            if (error instanceof NotAGitRepoError)
+                return false;
+            throw error;
+        }
+    }
+    detach(sessionId) {
+        this.stores.delete(sessionId);
+        this.turnBase.delete(sessionId);
+    }
+    isTracking(sessionId) {
+        return this.stores.has(sessionId);
+    }
+    /**
+     * Snapshot the workspace at the start of a turn. Safe no-op for untracked
+     * (non-repo) sessions. Idempotent within a turn: a second call before endTurn
+     * keeps the original base so a mid-turn re-prompt doesn't lose the diff origin.
+     */
+    async beginTurn(sessionId, label) {
+        const store = this.stores.get(sessionId);
+        if (!store)
+            return;
+        if (this.turnBase.has(sessionId))
+            return;
+        this.turnBase.set(sessionId, await store.snapshot(label));
+    }
+    /**
+     * Snapshot the workspace at the end of a turn and return the structured diff
+     * against the turn's base. Returns undefined for untracked sessions or when
+     * beginTurn was never called. Returns an empty `changes` array when the turn
+     * touched no files.
+     */
+    async endTurn(sessionId, label) {
+        const store = this.stores.get(sessionId);
+        if (!store)
+            return undefined;
+        if (!this.turnBase.has(sessionId))
+            return undefined;
+        const before = this.turnBase.get(sessionId);
+        this.turnBase.delete(sessionId);
+        const after = await store.snapshot(label);
+        const changes = before ? await store.changesBetween(before, after) : [];
+        return { before, after, changes };
+    }
+    /** The full checkpoint chain for a session, newest first. */
+    async checkpoints(sessionId) {
+        const store = this.stores.get(sessionId);
+        if (!store)
+            return [];
+        return await store.list();
+    }
+    /**
+     * Restore a session's workspace to a checkpoint. Throws if the session isn't
+     * tracked or the id is unknown to git. Any in-flight turn base is cleared so
+     * the next turn re-snapshots from the restored state.
+     */
+    async rewind(sessionId, checkpointId) {
+        const store = this.stores.get(sessionId);
+        if (!store)
+            throw new Error(`Session ${sessionId} is not tracked by the harness.`);
+        await store.rewindTo(checkpointId);
+        this.turnBase.delete(sessionId);
+    }
+}