dsh-deltabox

dsh-deltabox supplies Agent-owned Deltabox sessions, foreground Bash and filesystem providers, and a turn-stopping review policy for DeepSeek Harness Web and Desktop (0.2.x, including prereleases). It contains no browser code or dsh.client entry. Harness still owns Host, API, Mux, session, Agent, Shell, FS, permission, and approval services; this bundle fixes the execution providers to Deltabox.

News

• 2026-10-30 — v0.1.6: Update to deltabox-lite 0.1.5 for faster macOS session startup.

• 2026-10-25 — v0.1.5: Accept every DSH 0.2.x runtime, including 0.2.1-rc.3 and later patch releases, without a per-version exemption.

• 2026-10-21 — v0.1.4: Windows x64 runtime packages via deltabox-lite 0.1.4, with PowerShell execution, UTF-8 output, and Desktop workspace previews. CB-CoW uses WinFsp; isolated commands require MXC. Linux and macOS integrations remain available.

Install

npm package (Web)

After the first npm release, install the package into the Harness Web profile with the dsh plugin CLI:

dsh plugin --profile web add dsh-deltabox

The CLI resolves dsh-deltabox from npm and installs its matching deltabox-lite runtime and platform package dependencies. See RELEASING.md for this repository's independent plugin release workflow.

Install a pinned commit into a Harness profile:

dsh plugin --profile web add github:delta-box/dsh-deltabox#<commit>

A local checkout installs from its path instead: dsh plugin --profile web add /path/to/dsh-deltabox. Git dependencies run this package's prepare script. The default native transport also requires the matching deltabox-lite npm package, which supplies both the Node-API addon and the companion deltabox helper. CB-CoW uses FUSE on Linux (/dev/fuse plus fusermount3 or fusermount), APFS/FSEvents on macOS, and WinFsp on Windows. Windows isolated commands also require MXC process security support. Linux Git mode instead requires Git and Bubblewrap. Set transport: stdio only for compatibility with an installation that has the executable but no native addon.

Desktop (app mode)

Open Desktop, go to Plugins → Add plugin, enter dsh-deltabox, and install it.

Environment

| Variable | Role | Meaning | |---|---|---| | DELTABOX_BINARY | user | Optional helper executable override. Native mode otherwise resolves the matching helper from deltabox-lite; stdio mode uses the value directly. | | DEEPSEEK_API_KEY | user | Harness model credential required to run agents; the repo root .env is also read. | | DEEPSEEK_BASE_URL | user | Optional non-default model endpoint. | | DSH_HOME | user | Harness home, default ~/.dsh; the default stateRoot is <DSH_HOME>/deltabox/v1. | | DELTABOX_STATE_DIR | stdio runtime | State root for the compatibility deltabox serve child. | | DELTABOX_RUNTIME_DIR | stdio runtime | Ephemeral root for the compatibility deltabox serve child. |

Native options are frozen once and the Rust coordinator is shared through an immutable Arc, so hot operations do not take a configuration lock. deltabox isolation uses the platform worker, bubblewrap scrubs the environment and denies network, and none inherits the complete DSH process environment. Native state and runtime roots are passed directly to the addon; the two environment variables above apply only to stdio compatibility mode.

cd /path/to/deepseek-harness
export DELTABOX_BINARY=/path/to/deltabox
export DEEPSEEK_API_KEY=...
dsh plugin --profile web add github:delta-box/dsh-deltabox#<commit>
dsh --profile web "your task"

Composition

The bundle patch follows dsh-base and dsh-web-app. It disables Agent presets, local subprocess and sandbox runners, PowerShell, the background-job registry and tools, and filesystem-search tools, and the local Bash/FS providers. Disabled rows mount no effects; a later profile or home patch can explicitly replace a row and enable it. The bundle leaves Harness approval, the sandbox-policy home, the permission-preset selector, Host, API, Mux, session, Agent, Shell, FS, the Web approval panel, and other unrelated Web UI rows available.

sandbox-policy stays enabled while every enforcing runner (sandbox, bash-sandbox, pwsh-sandbox, fs-sandbox) stays disabled. Deltabox owns confinement, so mounting a second runner would stack two isolators; the policy home is only the vocabulary. tool-bash reads ctx.shell.sandboxMode from the Deltabox executor, advertises sandbox_permissions from it, and routes an approved escalation through ctx.sandboxPolicy and ctx.approval before the command reaches Deltabox.

| Entry | Role | |---|---| | deltabox-runtime | Owns lightweight Agent handles and hands off one warm native project session after idle or disposal. | | deltabox-bash | Implements foreground ctx.shell calls through session.exec. | | deltabox-fs | Implements ctx.fs; isolated native modes use zero-Base64 Buffer I/O and none may use the controlled mount directly. | | deltabox-review-policy | Checks active reviews at agent/turn-stopping and uses Harness approval to commit or abort them. | | deltabox-view | Contributes the project-view path guidance the model reads before it picks a path. |

tool-bash is configured with enableRunInBackground: false, and the jobs registry is disabled so the current Bash tool uses its foreground path. The preset registry and each shipped preset declaration are disabled. The retired Harness invariant registry and companion entry are no longer installed; the runtime registers Agent handles through the awaited agent/created event. No dsh.client or extra transport row is installed.

Runtime

ctx.deltabox.sessionFor(agent) returns one handle for the exact Agent instance. agent.session.header.cwd selects the project root; a missing cwd uses projectRoot. Agent creation registers only a lightweight handle. The first filesystem or Bash operation constructs the native coordinator with one validated storage/isolation pair. Defaults are cbcow-through+deltabox with fast durability; git+bubblewrap is the zero-FUSE alternative and cbcow-through+none is the explicit unsandboxed path. An Agent becoming idle is not disposed: after agent.whenIdle() confirms that no follow-up slipped in, its queue drains and any open review aborts before the live project session is parked. The next Agent for the same project receives a fresh handle and identity backed by those warm resources, eliminating another native coordinator and session.start; stale handles and filesystem targets remain invalid.

The handle serializes Deltabox operations. Blocking Rust work runs on the addon's Tokio blocking runtime instead of Node's libuv worker pool. The embedded coordinator retains its route, policy, journal, filesystem state, and active review in memory for the session lifetime. Reads start a session without opening a review. Mutations call review.begin before a write or command. review.commit and review.abort increment the target generation, so targets obtained before either operation fail with FS_STALE_VERSION. Idle or disposed Agents may park reusable sessions; runtime unload stops active, parking, and warm sessions after admitted work settles. Handoff is guaranteed only inside one DSH/Web process; another process cannot reattach and reports the project as busy. Filesystem targets from before a handoff must always be resolved again.

Each session still receives the standing file/review policy for provider operations; a Bash command may additionally request a wider per-command profile (see below). deltabox isolation applies the platform policy worker. Bubblewrap commands receive a scrubbed environment, deny network, and can access the whole project bind mount; policy deny paths still apply to native byte reads/writes but are not translated into Bubblewrap submounts. Select none only when inherited credentials, ambient variables, and unrestricted network are intentional.

Runtime configuration

| Field | Default | Meaning | |---|---:|---| | transport | native | native embeds the coordinator; stdio starts deltabox serve. | | binary | deltabox | Helper override; native mode resolves the packaged helper when this stays at its default. | | projectRoot | process.cwd() | Fallback project root for Agents without a session cwd. | | stateRoot | <DSH_HOME>/deltabox/v1 | Private state and per-session directory root. | | stopGraceMs | 2000 | Grace before TERM and again before KILL during teardown. | | fsMode | cbcow-through | cbcow-through or the Linux-only zero-FUSE git engine. | | isolation | from fsMode | deltabox for CB-CoW, bubblewrap for Git, or explicit none with native CB-CoW. | | durability | fast | fast avoids strict persistence barriers; strict retains them. | | projectSessionReuse | native mode | Keep one idle or disposed session warm per project for the next Agent; set false to retain eager teardown on disposal and disable idle parking. |

Providers

The Bash provider runs bash -c in the initiating Agent's Deltabox session on Linux and macOS. On Windows it runs PowerShell. none mode keeps one Bash worker alive on Linux and macOS and executes every command in an isolated subshell; the isolated modes use their respective command providers. It rejects stdin and background execution. The current Shell execute() interface returns a settled handle after the batch RPC completes, with result and output readers; it does not provide live streaming or mid-command cancellation. The command deadline is fixed at 600 seconds; each captured stream is bounded at 8 MiB.

The bundle also contributes one runtime-context line (deltabox:view, order 115) so the model addresses paths the way the providers do. It names the view the Agent's commands start in, states that the host project directory is deliberately unreachable from those commands and is not escalatable, gives the path form each tool family takes (relative or view paths for shell commands; the project path, the view path, or a relative path for the file tools, all naming the same reviewed copy), and states that a path outside the project is read from the host directly but written only under danger-full-access and never rolled back. The mount point is quoted once the Agent has opened a session, because the core assigns it at session.start.

Per-command filesystem profiles

sandboxMode reports workspace-write, so the Harness Bash tool advertises sandbox_permissions and runs the pre-execution approval. The approved mode is translated into a Deltabox execution profile for that one command:

| Harness mode | Deltabox profile | Effect | |---|---|---| | workspace-write (standing) | workspace-write | Writes stay inside the session workspace | | danger-full-access (approved) | read-write | Writes also reach the rest of the host filesystem |

The same mode is selectable without a per-command denial, through the Harness permission-preset surfaces (permission + ui-permission): the composer permission chip and the General-settings default each write the session's sandbox/mode knob, so a session parked on danger-full-access runs every command under read-write. Both presets keep approval: ask; the stock danger-full-access bundle pins never, and never auto-rejects every ask, which would silently roll back the turn-stopping Deltabox review instead of prompting.

Escalation is a one-shot retry: after a denial the model may repeat the exact command with sandbox_permissions: "danger-full-access" and a justification, and Harness asks the user before anything runs. A rejection is final for that command and no Deltabox session is touched.

The profile widens access, not the deny set. The workspace still routes through Deltabox, so its changes remain visible to diff, checkpoint, commit, and abort, while engine state and helper endpoints stay denied. Linux FUSE and private-workspace modes also deny direct backing-project access; macOS through mode tracks writes directly in the real project. Host writes outside the workspace are outside DeltaFS and cannot be rolled back. Linux FUSE and private-workspace modes require their working view outside the denied backing project for read-write. macOS cbcow-through supports read-write in the real project while protecting its rollback baseline, metadata, tokens, and helper endpoints.

The two approvals are complementary: the sandbox escalation decides whether a command may acquire wider access before it runs, and the review policy decides after the turn whether the workspace changes it produced are kept.

Filesystem writes and the execution level

ctx.fs.sandboxMode reports workspace-write too, so tool-fs (and tool-str-replace-editor) advertise sandbox_permissions for write and edit and resolve the same per-call policy, approved one-shot escalation included. The provider then fences the mutation against the target's path space:

| Target | workspace-write (standing) | danger-full-access (approved or session preset) | |---|---|---| | Project file, named by the project path, the mount path, or a relative path | Allowed; the write stays on the DeltaFS view, so it is versioned, reviewed, and rollback-able | Same | | A path outside the project | Denied with FS_SANDBOX_DENIED, which tool-fs renders as the shared [sandbox: …] marker plus the escalation hint | Written straight to the host filesystem |

Resolution never refuses an outside path: it maps to the host path space and the fence decides at mutation time, so a refusal carries the model-facing escalation marker instead of failing during resolve (which the tool layer cannot map). Both accepted forms of a project file canonicalize to the same view target, so a model that names the absolute project path still gets the reviewed copy rather than an unreviewed host write. read is unfenced at every level, matching the Harness convention that the sandbox governs writes.

Host writes are deliberately outside DeltaFS: they land on the host immediately, never enter a review, and cannot be rolled back, so a turn whose only changes are host writes auto-commits with no review card. Nothing outside the project is exempt from this: danger-full-access reaches the engine's own state and the backing project tree as well, which is the price of the level being a true full access.

read-only is deliberately not a Deltabox profile. Deltabox's unit of work is a writable, rollback-able workspace, so a session narrowed to read-only still runs workspace-write; a deployment that needs read-only command execution should keep a Harness sandbox runner mounted for that session instead.

The filesystem provider keeps display paths under the logical project root for view targets and uses the host path for host targets. Targets encode Agent/session identity, generation, path space, display path, and process path. resolve, stat, lstat, and listDir use canonical local metadata; Git mode uses the project root because it has no mount. Isolated native reads and writes use Node Buffer without Base64 or an extra JS-to-Rust copy. none uses the validated mount directly and registers exact changed paths; stdio retains the Base64 protocol.

The profile does not provide glob, grep, terminal, Code Runtime, or background jobs. It also does not add cumulative diff UI or another transport.

Review policy

At agent/turn-stopping, Agents without a started session or without an active review are ignored. An active review calls review.diff and reads pending_changes and the change-file summary. Empty reviews commit silently. A non-empty review asks:

Deltabox 检测到尚未处置的文件改动（5 个文件）：src/index.ts（修改 +2 -1）、README.md（新增 +18）、docs/old.md（删除 -12）、assets/logo.png（修改，二进制）、empty.txt（新增）。Allow once 保留自本次 review 开始以来的全部改动；Reject 撤回这些改动。

The request uses toolName: 'deltabox-review' and the existing ctx.approval.request() service. allowed-once commits and rejected aborts. cancelled and unavailable leave the review active for a later turn or session disposal. Approval and Deltabox errors propagate through the existing turn-stopping error path; the policy does not guess after an ambiguous commit or abort. 完整 diff 文本留在 Node 插件内；仅每文件摘要（路径、类型、行数）进入 approval reason，由 Web 审批面板展示并记录在 session log。

Model Experience

The model sees the existing Bash and filesystem tool schemas and their normal foreground results, plus one runtime-context line naming the view the Agent's commands start in. 完整 diff 文本、RPC 字段、审批传输细节不进入模型视野；approval reason 只携带改动文件摘要。

KV Cache effect

None directly. The Harness tool packages own their schemas and prompt sections; review runs after the turn's tool work has settled.

Known Limitations and Deferred Work

• Foreground execution only - No background jobs, PTY, stdin channel, persistent terminal, incremental output, or per-command cancellation RPC is exposed.
• Fixed command deadline - Deltabox does not accept a shorter tool timeout, so the provider uses its fixed 600-second deadline.
• Whole-file reads - streamText yields one complete bounded native read; there is no streaming file API yet.
• Platform provider required - CB-CoW needs FUSE on Linux or APFS/FSEvents on macOS; Git mode needs Linux, Git, and Bubblewrap.
• Explicit none is unsandboxed - It shares credentials, network, and process environment with executed commands.
• Git ignores ignored files - .gitignore matches are outside GitGhost diff and rollback coverage.
• Bubblewrap policy gap - Command isolation covers the whole project bind mount; deny paths are enforced only by native byte operations in v1.
• No search provider - glob and grep are unavailable until a Deltabox search provider is added.

Development

The development dependencies use Harness 0.2.1-alpha.2. The overrides in pnpm-workspace.yaml pin transitive Harness and Cordis packages as well as auto-installed peers; npm's top-level package.json.overrides does not apply to this pnpm workspace. Update the workspace pins and lockfile together. The plugin uses host peers when installed, rather than bundling a second Harness runtime.

Byte-range reads preserve target generations and the coordinator's deny policy. Host and none reads use bounded file windows. Isolated native and stdio reads use the existing coordinator read API, then slice the result: its 16 MiB whole-file limit still applies, even when the requested window is smaller. Large-file range streaming requires a future Deltabox protocol extension.

pnpm install
pnpm run typecheck
pnpm test
pnpm run build
pnpm run bench:native -- --binary /path/to/deltabox --warmups 5 --runs 30
pnpm run bench:native:commit -- --binary /path/to/deltabox --warmups 5 --runs 30
pnpm run bench:batch -- --binary /path/to/deltabox --files 100 --bytes 1024 --warmups 1 --runs 5
pnpm run pack:release

After building the matching addon and helper, verify the providers and Harness approval service under Desktop's actual Electron runtime (temporary projects only):

pnpm run prepare
ELECTRON_RUN_AS_NODE=1 "/Applications/DeepSeek Harness.app/Contents/MacOS/DeepSeek Harness" \
  tests/desktop/native-smoke.mjs /path/to/deltabox /path/to/deltabox.node

The smoke test exercises both deltabox and none isolation: native module and helper resolution, filesystem reads/writes, byte windows, Bash, approval commit, approval rollback, stale targets, and native deny-policy preservation. macOS requires FSEvents access, so a restricted test runner may need to execute it outside its own sandbox. Use a matching rebuilt helper and addon: fast none execution needs the post-command FSEvents marker barrier to include newly created files in an immediate rollback.

bench:native defaults to the abort lifecycle. bench:native:commit measures the same native phases while repeatedly committing updates to one fixed 1 KiB file, so the project size remains constant across warm-ups and measured runs.

prepare uses tsdown.prepare.config.ts directly and does not depend on a DeepSeek Harness TypeScript project reference.

Desktop tool activation check

Run pnpm run test:desktop to boot the composed execution-plane rows and verify that the model-facing bash, read, write, and edit tools register. No model or credentials are required. The tool rows explicitly inject sandboxPolicy and approval: without this dependency, Desktop can activate confined tools before the policy service is ready, leaving them absent from the model catalog even though the plugin is enabled.

One-execution command network approval

On macOS and Linux, deltabox isolation defaults to an empty network allowlist with one-command approval enabled. Configure standing destinations or override the network mode in the deltabox-runtime row of your profile:

- id: deltabox-runtime
  name: dsh-deltabox/runtime
  config:
    network:
      mode: allowlist
      approval: true
      allow: [registry.npmjs.org:443]
      deny: [blocked.example:443]
      allowPrivate: false

Ordinary bash can reach only standing destinations. The plugin also registers network_bash, a foreground tool with description, command, targets, justification, and optional workdir. Targets are exact host:port values, at most 32 per request. Destinations outside allow require an existing Harness approval answerer to return Allow once before session acquisition or execution. Reject, cancellation, missing answerers, and approval policy never all stop the command. Standing destinations need no extra ask; deny takes precedence and cannot be overridden by approval. Each prompt names the command, working directory, requested destinations, reason, and file mode.

The approved targets travel only with that execution. They are not written to session policy or passed through model-controlled environment variables. The executor consumes an Agent-bound grant once; reusing a command spec, handing it to another Agent, or handing off a warm project session cannot reuse the grant. The core closes the approval-enabled command runtime and its proxy connections after every execution, including executions without extra grants. The existing Bash deadline still applies; this batch transport does not interrupt a running command on caller cancellation. Cancellation before execution prevents startup.

File access stays under the session's file mode; network approval does not grant host filesystem writes. Configure the existing permission preset separately when host writes are needed. Network requests and remote changes cannot be undone by Deltabox review/abort. A denied destination is reported in command stderr as a [network: ...] marker. Direct OS-level denials do not have a proxy destination record; DNS, TLS, and transport errors remain ordinary command failures. No path automatically retries the complete command after a denial or lost response.

Approval enforcement supports deltabox isolation on macOS and Linux, using an authenticated HTTP/CONNECT proxy plus OS restrictions on direct connections. Only proxy-aware HTTP/HTTPS clients are supported by this path; raw SSH, UDP, QUIC, and clients ignoring proxy variables remain blocked. Redirects and package registries may require additional exact destinations. Destinations resolving to local/private addresses are denied by default, even if their names are approved; allowPrivate: true explicitly enables those addresses within the destination allowlist. Domain approval is a destination permission, not content inspection.

none cannot enforce restricted networking; bubblewrap keeps its existing network-disabled behavior and cannot provide approval/allowlist mode. Windows retains allow_audit by default because its sandbox cannot enforce network policy. Unsupported combinations are rejected. The runtime probes network protocol v1 before opening an approval-enabled session: install matching addon and helper builds from the companion deltabox-lite change. An older runtime fails closed. This policy covers command subprocesses only; model API traffic, Web tools, MCP, and browsers have separate transports and permissions.

File-review approval prompts provide English and Chinese displayReason text, selected by the Harness UI language. Their audit reason uses English. Network approval prompts show only the Agent-provided justification in the user’s language; the Harness tool detail already displays the command. The tool asks the Agent to name the requested destinations in that short justification.