{"_id":"pi-deltabox","_rev":"3-f77b624aac2537eae9581e5547061a8a","name":"pi-deltabox","dist-tags":{"latest":"0.1.1"},"versions":{"0.0.0-stage":{"name":"pi-deltabox","version":"0.0.0-stage","_id":"pi-deltabox@0.0.0-stage","stub":true,"maintainers":[{"name":"xeonliu","email":"5bxtqrabi@mozmail.com"}],"dist":{"shasum":"9ccf5883a269a62635b8b0b2aa2db1cbabf90f4c","tarball":"https://registry.npmjs.org/pi-deltabox/-/pi-deltabox-0.0.0-stage.tgz","fileCount":2,"integrity":"sha512-14+5pwVYK72XHRTM8592Y54WyLC73nHcz8ych5ZWYqaO+12bbrW6M6CvXb5wvjQa8PuWWBKJH4WqnonCsiin4w==","signatures":[{"sig":"MEUCIQCBJLIGhr4bXu9H77XDu8Ws58YpsmDM8KaJk674BdUV9wIgFVUD0kkLLKUJlDf54jBjSLofy9GCdWLvHhKjIccIgSY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":333},"_npmUser":{"name":"xeonliu","email":"5bxtqrabi@mozmail.com"},"description":"Temporary package placeholder for staged publishing","directories":{}},"0.1.0":{"name":"pi-deltabox","version":"0.1.0","keywords":["pi","pi-package","sandbox","deltabox"],"license":"Apache-2.0","_id":"pi-deltabox@0.1.0","maintainers":[{"name":"xeonliu","email":"5bxtqrabi@mozmail.com"}],"pi":{"extensions":["./dist/extension.js"]},"dist":{"shasum":"a078b73eeaaea2c595eb6b58c5c59fffcf8b847f","tarball":"https://registry.npmjs.org/pi-deltabox/-/pi-deltabox-0.1.0.tgz","fileCount":10,"integrity":"sha512-/IzgF/o+eEmSJmalRQY7hjILn+1NccrbL2d0bceDoP/jt+C2vflZCCcvc+j52Oqzn5c3IpDtYDrttjXrj6BxOw==","signatures":[{"sig":"MEQCIF80/nHDYWHDvefVfXJf0EFzqxIcI2ZktKConK70IAcHAiAhmZjFx13ZSHOomYPXBmkGyNqzTkBAdaqpO2Ul5WyeYQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"sig":"MEYCIQDEkv6kPLNxKa3Zad7W23IW0/s1/WKfHk0J2DCPTFRKnAIhALm2V70c4kCFlcDSMJ0V5xcOzaxcDfMSp3lNEkBmwV8S","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":61735},"main":"dist/extension.js","type":"module","_from":"file:/home/runner/work/pi-deltabox/pi-deltabox/dist/pi-deltabox-0.1.0.tgz","scripts":{"test":"npm run build && tsc -p tsconfig.tests.json && node --test dist-test/tests/client.test.js dist-test/tests/commands.test.js dist-test/tests/config.test.js dist-test/tests/extension.test.js dist-test/tests/tools.test.js","build":"tsc -p tsconfig.json","bench:native":"npm run build && node perf/native-fastpath-bench.mjs"},"_npmUser":{"name":"xeonliu","email":"5bxtqrabi@mozmail.com"},"_resolved":"/home/runner/work/pi-deltabox/pi-deltabox/dist/pi-deltabox-0.1.0.tgz","_integrity":"sha512-/IzgF/o+eEmSJmalRQY7hjILn+1NccrbL2d0bceDoP/jt+C2vflZCCcvc+j52Oqzn5c3IpDtYDrttjXrj6BxOw==","_npmVersion":"11.19.0","description":"Pi extension: agent-native sandbox sessions with diff/commit/abort, powered by deltabox-lite","directories":{},"_nodeVersion":"24.21.0","dependencies":{"typebox":"^1.3.10"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.5.0","@types/node":"^22.0.0","@earendil-works/pi-coding-agent":"^0.79.3"},"optionalDependencies":{"deltabox-lite-linux-x64":"0.1.0","deltabox-lite-darwin-x64":"0.1.0","deltabox-lite-linux-arm64":"0.1.0","deltabox-lite-darwin-arm64":"0.1.0"},"_npmOperationalInternal":{"tmp":"tmp/pi-deltabox_0.1.0_1791963279834_0.953623900507077","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"pi":{"extensions":["./dist/extension.js"]},"_id":"pi-deltabox@0.1.1","dist":{"shasum":"3dec99e21a6d553d76bbf14081e465d9c198a490","tarball":"https://registry.npmjs.org/pi-deltabox/-/pi-deltabox-0.1.1.tgz","fileCount":10,"integrity":"sha512-hml4XmSVJuXVBcKk2o3ZjqlQO0MEkHNOe9C89c5iUKNopgmKbEIWbhHTxsUn2gevbxkDT4EDeP+9t3yHGvOnJA==","signatures":[{"sig":"MEQCIGpgeoBO0haKr9Lhf28LdDE0d56iUBeYdTpuRZ1dvmzFAiB25ooGMffO3glv5LYoOpxh1kB32y/pqP2zg6KooPJHtw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIALe9wI5JMaQNtHT4VUhUep8qPNxuKKmKHtNpgyjYUdlAiAwFLVAuVv5CyPTGlwtKkg7vhtgamxnLVNAuvAlW+SVVw=="}],"unpackedSize":61735},"main":"dist/extension.js","name":"pi-deltabox","type":"module","_from":"file:/home/runner/work/pi-deltabox/pi-deltabox/dist/pi-deltabox-0.1.1.tgz","license":"Apache-2.0","scripts":{"test":"npm run build && tsc -p tsconfig.tests.json && node --test dist-test/tests/client.test.js dist-test/tests/commands.test.js dist-test/tests/config.test.js dist-test/tests/extension.test.js dist-test/tests/tools.test.js","build":"tsc -p tsconfig.json","bench:native":"npm run build && node perf/native-fastpath-bench.mjs"},"version":"0.1.1","_npmUser":{"name":"xeonliu","email":"5bxtqrabi@mozmail.com"},"keywords":["pi","pi-package","sandbox","deltabox"],"_resolved":"/home/runner/work/pi-deltabox/pi-deltabox/dist/pi-deltabox-0.1.1.tgz","_integrity":"sha512-hml4XmSVJuXVBcKk2o3ZjqlQO0MEkHNOe9C89c5iUKNopgmKbEIWbhHTxsUn2gevbxkDT4EDeP+9t3yHGvOnJA==","_npmVersion":"11.19.0","description":"Pi extension: agent-native sandbox sessions with diff/commit/abort, powered by deltabox-lite","directories":{},"maintainers":[{"name":"xeonliu","email":"5bxtqrabi@mozmail.com"}],"_nodeVersion":"24.21.0","dependencies":{"typebox":"^1.3.10"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.5.0","@types/node":"^22.0.0","@earendil-works/pi-coding-agent":"^0.79.3"},"optionalDependencies":{"deltabox-lite-linux-x64":"0.1.1","deltabox-lite-darwin-x64":"0.1.1","deltabox-lite-linux-arm64":"0.1.1","deltabox-lite-darwin-arm64":"0.1.1"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-deltabox_0.1.1_1791966948265_0.5732300406736779"}}},"time":{"created":"2026-10-14T07:33:44.532Z","modified":"2026-10-14T08:35:48.536Z","0.0.0-stage":"2026-10-14T07:33:44.532Z","0.1.0":"2026-10-14T07:34:39.984Z","0.1.1":"2026-10-14T08:35:48.360Z"},"license":"Apache-2.0","keywords":["pi","pi-package","sandbox","deltabox"],"description":"Pi extension: agent-native sandbox sessions with diff/commit/abort, powered by deltabox-lite","maintainers":[{"name":"xeonliu","email":"5bxtqrabi@mozmail.com"}],"readme":"<div align=\"center\">\n\n# pi-deltabox\n\n**Sandboxed tools for Pi, with review / commit / abort — powered by deltabox-lite.**\n\nEvery filesystem change remains reviewable, committable, and abortable.\n\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](#license)\n[![Pi](https://img.shields.io/badge/pi-0.79+-black.svg)](https://github.com/earendil-works/pi)\n[![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macOS-lightgrey.svg)](#)\n[![Core](https://img.shields.io/badge/deltabox-lite-4e8cff.svg)](https://github.com/Ddnirvana/deltabox-lite)\n\n</div>\n\npi-deltabox is a [Pi](https://github.com/earendil-works/pi) extension that\nembeds a durable deltabox-lite session directly in the Pi Node process. `read`,\n`write`, `edit`, `bash`, `grep`, `find`, and `ls` execute inside the selected\nconfined filesystem mode. The default `none` native path keeps coordinator\nstate and an isolated Bash worker hot, shares Pi's process environment, and\nuses the live mount directly for low-latency byte I/O.\n\n## Demo\n\n![pi agent creating a file, reviewing the diff, and committing it](assets/pi-deltabox.gif)\n\n## Features\n\n- **Tool-level overrides** — the seven tools above run through the sandbox\n  using Pi's official tool-override API.\n- **Durable review scopes** — task/tool rollback points are owned by the core;\n  skipped reviews keep the earliest rollback point across tool calls.\n- **In-process by default** — a Node-API addon owns one resident coordinator\n  for the Pi session; no per-tool process or JSON-RPC round trip is required.\n- **Persistent command worker** — `none`-isolation `bash -c` calls reuse one Bash\n  process while isolating shell state and refreshing Pi's ambient environment.\n- **Direct mount I/O** — `none`-isolation native reads and writes use the validated\n  session mount, register exact paths in one batch, and avoid Base64 copies.\n- **Native filesystem selection** — select exact `cbcow-through`,\n  `cbcow-private`, `copy-private`, or Git storage with an explicit command\n  isolation profile. Pi stores no filesystem state.\n- **Bundled native runtime** — npm installs the matching Linux or macOS binary\n  and Node-API prebuild. CLI and persistent JSON-RPC transports remain available\n  as compatibility fallbacks.\n- **Three review modes** — review everything at the end of a task, after every\n  tool call, or only after risky calls.\n- **Slash commands** — `/sandbox-status`, `/sandbox-review`,\n  `/sandbox-commit`, `/sandbox-abort`, `/sandbox-skip`, `/sandbox-diff`,\n  `/sandbox-mode`.\n- **End-of-task nudge** — when a task finishes with pending changes, Pi tells\n  you to review, commit, or abort them.\n\n## Install\n\n```bash\npi install npm:pi-deltabox          # once published\npi install ./pi-deltabox            # from a checkout\n```\n\nThe npm package selects a native prebuild for Linux and macOS on x64 and arm64.\nFor a source checkout, build [deltabox-lite](https://github.com/Ddnirvana/deltabox-lite),\ncopy the addon to a `.node` path, and point the extension at both artifacts:\n\n```bash\ncargo build --release\ncp target/release/libdeltabox_node.dylib /tmp/deltabox.node  # macOS\n```\n\n## Configure\n\nCreate `deltabox.json` in the project, in `~/.pi/agent` for user-wide defaults,\nor both. Project values are merged over user-wide values, including nested\n`review` settings:\n\n```json\n{\n  \"transport\": \"native\",\n  \"timeoutMs\": 30000,\n  \"isolation\": \"none\",\n  \"policy\": \"policy.toml\",\n  \"bin\": \"/path/to/deltabox-lite/target/release/deltabox\",\n  \"nativeAddon\": \"/tmp/deltabox.node\",\n  \"stateDir\": null,\n  \"runtimeDir\": null,\n  \"filesystem\": {\n    \"mode\": \"cbcow-through\",\n    \"durability\": \"fast\",\n    \"groupCommitMs\": null\n  },\n  \"review\": {\n    \"mode\": \"task\"\n  }\n}\n```\n\nInstalled prebuilds do not need explicit `bin` or `nativeAddon` values. Paths\nin source-checkout configuration may be absolute or relative to the project.\nConfiguration is snapshotted when the Pi session creates its native\ncoordinator. `stateDir` and `runtimeDir` can pin the engine locations; `null`\nuses Deltabox defaults.\n\nNative `filesystem.mode` accepts the exact modes `cbcow-through`,\n`cbcow-private`, `copy-private`, or Linux-only `git`. Select `isolation` as\n`deltabox` or `none` for CB-CoW/copy-private, and as `bubblewrap` or `docker`\nfor Git. Native startup never changes the requested mode; select\n`copy-private` explicitly when CB-CoW is unavailable. Strict durability\nrequires a CB-CoW mode; `groupCommitMs` is available only where the selected\nprovider supports it.\n\nThe extension reports the requested mode, resolved mode, provider, visibility,\ndurability, rollback guarantee, fallback reason, and taint state through\n`/sandbox-status`. Fallback and unsafe rollback conditions are also shown as Pi\nnotifications.\n\n### Review modes\n\n| Mode | Behavior |\n|---|---|\n| `task` (default) | No per-tool prompts; review / commit / abort at the end of a task |\n| `tool` | Prompt after every mutating tool call |\n| `risky` | Prompt after `bash`, `write`, and `edit` |\n\n`timeoutMs` bounds CLI and JSON-RPC requests. A `timeout` supplied to Pi's bash\ntool overrides it for those compatibility transports. `none`-isolation commands\nuse the resident executor's fixed 600-second deadline.\n\n## Commands\n\n| Command | Description |\n|---|---|\n| `/sandbox-status` | Show session status and pending change count |\n| `/sandbox-review` | Show the pending diff |\n| `/sandbox-commit` | Apply pending changes to the real project |\n| `/sandbox-abort` | Discard changes back to the active review scope |\n| `/sandbox-skip` | Keep changes pending and preserve the current rollback point |\n| `/sandbox-diff [from] [to]` | Diff between checkpoints |\n| `/sandbox-mode task\\|tool\\|risky` | Switch review mode at runtime |\n\n## How it works\n\n1. On session start, the extension loads the Node-API addon in Pi, snapshots\n   policy and runtime configuration, and starts one resident coordinator.\n2. Native operations run on the addon's Tokio blocking runtime. The route,\n   policy, journal, filesystem state, active review, and unsandboxed Bash worker\n   stay resident for the session lifetime. Repeated starts reuse the live\n   client rather than creating another backend session.\n3. `none`-isolation project reads and writes use the controlled mount directly; native\n   Buffer methods handle fallback paths without JSON or Base64.\n4. `/sandbox-commit` accepts the current view; `/sandbox-abort` restores the\n   active review scope. In through mode, host visibility is immediate. In\n   private modes, publication happens at commit.\n5. Set `\"transport\": \"serve\"` or `\"cli\"` only when native loading is not\n   available. These transports preserve the durable on-disk protocol.\n\n## Performance benchmark\n\nThe included benchmark compares native, `serve`, CLI, and an unsandboxed\nheadless reference over the same review/write/read/exec/diff/abort lifecycle:\n\n```bash\nnpm run bench:native -- --binary /path/to/deltabox \\\n  --native-addon /path/to/deltabox.node --warmups 5 --runs 30\n```\n\n## License\n\nApache-2.0.\n\nMaintainers: see [RELEASING.md](RELEASING.md) for the npm release process.\n\n**⭐ Star this repo if you find it is helpful!**\n","readmeFilename":"README.md"}