Skip to content

About

One approval per session instead of one per command: a loopback-only toolchain server for file-sandboxed agent sessions.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

dsh-tool-bridge

CI

A DSH plugin that gives a file-sandboxed session the toolchain its sandbox denies — flutter/dart, the project's own Node tools, a guard-railed git, pnpm/npm, a verb-guarded cargo — as two native tools, one switch per conversation, and a sidebar panel. The browser half of a UI walkthrough (@playwright/mcp) is mounted the same way: per conversation, for the conversations that ask.

It is the successor of a Python HTTP server that did the same job beside the harness. docs/adr/0007-the-plugin-is-the-bridge.md records why the plugin is not just the nicer shape but the correct one, and what did not survive the move.

Why any of this is needed

Inside a workspace-write sandbox the Flutter/Dart toolchain cannot run at all — it fails writing the SDK lockfile — every git write is denied because the git directory lives outside the workspace, and a Node toolchain dies on spawn EPERM: the sandbox cannot create the named pipes libuv uses for child stdio, which is what takes down vite (its Windows net use probe), vitest's default forks pool and esbuild (docs/vite-vitest-sandbox-findings.md records the measurements).

cargo is the narrower case, and worth stating exactly: it builds inside the sandbox once its crates are on disk — measured, cargo build finished in 4.05 s in workspace-write, rustc children and all — and the one thing it cannot do there is reach crates.io: cargo fetch retried three times and died with schannel: AcquireCredentialsHandle failed: SEC_E_NO_CREDENTIALS, because a confined child runs under a low-integrity token that cannot acquire a TLS credential. So the bridge is where a Rust project resolves its dependencies (ADR-0015).

The sandbox is applied per capability call: ctx.sandbox.confine() wraps the argv a consumer is about to spawn. The harness process itself is not confined, and neither are its children — so this plugin, running in that process, starts the toolchain directly, and nothing has to be approved per session because nothing is confined per session. That is the whole mechanism, and it is also the whole trust story: see Installing it is the trust decision below.

What you get

Two tools. bridge_run runs one command and comes back with a job: status, exitCode, durationSec, the log tail, and — for a test run — the digest (summary, counts, the complete failures inventory) plus a baseline split against the project's .toolbridge/known-failures.json, whose newFailures names the failures your change introduced. bridge_arb_edit edits Flutter ARB localization files and runs flutter gen-l10n as one atomic operation, planning every file before writing any.

Background work needs no third tool: every run is a ctx.jobs job, so the harness's own job_output, job_list and job_kill read and stop it, it appears in the harness's job roster, and a finished background job wakes its conversation with a completion notice.

Two switches, per conversation. Toolchain (config default: on) and Browser (config default: off), as a row of labelled switches directly above the input box — the harness's own seat for entries above the composer card, so on a phone they get a row of their own instead of a fight with the conversation header. Turning a switch off removes that half's tool schemas from the conversation's prompts — for the browser half it also closes the MCP server, so a conversation that never looks at a page pays nothing for the ability to. State is durable per session: a resumed conversation keeps what it had. A new conversation starts from its directory's project default — the last flip a conversation made in that directory — so flipping Browser on once means later conversations in that project open with it on; a directory nothing was ever flipped in falls back to the configured defaults, and a directory with no record of its own inherits the first remembered directory with the same folder name. The switch row shows intent, and it says so when the fact differs — browser starting…, or the reason in red when the mount failed. The icon at the row's end opens the panel in the sidebar.

A sidebar panel showing the conversation's working directory, both lanes' depth, the formatter pin, the browser's flags, every job with its digest summary, and the selected job's log — the thing the old server opened a browser tab for, without the token in the address bar and without a page that goes stale. It answers for the conversation it is opened beside, whether it came from the row's icon or from the sidebar's own guide.

Install

dsh plugin --profile <profile> add <absolute path to this checkout>

Then restart the harness once. The plugin declares its own bundle layer (dsh.bundle.patch), so plugin add composes it; there is no profile patch row to hand-edit.

Install it by path (or from git), not with link:. @deepseek-ai/* are peer dependencies, and inside a profile they resolve to the harness's own single copies through ~/.dsh/profiles/node_modules. A link: install resolves them from this checkout instead, which puts a second physical copy of packages like @deepseek-ai/dsh-tools in the process — the failure that looks like every tool call dying with Cannot read properties of undefined (reading 'prepare'), and whose message never names the plugin. Verify after installing:

Test-Path "$env:USERPROFILE\.dsh\profiles\<profile>\node_modules\@deepseek-ai\dsh-tools"   # must be False

Configure it

Configuration lives in the plugin's config schema, so a machine-specific value is a patch override in the profile — and a patch replaces the targeted row's whole config, so restate every key you keep:

- id: toolbridge
  config:
    dartFormatExe: C:/Tools/dart-3.12.2/bin/dart.exe
    defaults:
      bridge: true
      browser: false
    playwright:
      browser: msedge
      caps: vision,devtools
      outputDir: C:/Users/me/AppData/Local/dsh-pw-mcp
      toolCallTimeoutMs: 120000
Field Default Meaning
stateDir $DSH_HOME/toolbridge Where the plugin keeps the per-session switch record, the per-directory project defaults and the job logs
defaults.bridge true Whether a new conversation starts with the toolchain tools — the fallback for a directory no conversation has flipped a switch in yet
defaults.browser false Whether a new conversation starts with Playwright MCP mounted — same fallback; the last flip in a directory takes precedence over it
dartFormatExe — The formatter pin: the dart.exe CI formats with (see below)
playwright.browser msedge The browser channel; msedge drives the Edge Windows already ships, so no download
playwright.caps vision,devtools Playwright MCP capabilities: vision adds the coordinate mouse tools a canvas needs, devtools the recorders. Measured: 44 tools with both, ~25 for core alone
playwright.outputDir — Where video, trace and PDF land — outside any workspace on purpose, for the human
playwright.toolCallTimeoutMs 120000 Per-call MCP timeout; a screenshot or a stopped video can exceed the 60 s default
defaultTimeoutSec 600 How long a foreground bridge_run waits inside the call before handing the job back still running

Using it

bridge_run is the front door. The accepted names are flutter, dart, git, pnpm, npm, npx, gradlew, cargo, and the project's own vite/vitest/ svelte-check/svelte-kit/tsc, resolved out of the job's working directory — the Node tools by reading the package's bin field, cargo straight off PATH (rustup installs a real cargo.exe, so there is no wrapper to unwrap) and gradlew through its gradle/wrapper/gradle-wrapper.jar — never through a .cmd/.bat wrapper, which would put cmd.exe in the middle of an argv that is supposed to have no shell.

Gradle builds go through the wrapper jar. gradlew runs as java -classpath <project>/gradle/wrapper/gradle-wrapper.jar org.gradle.wrapper.GradleWrapperMain (the classpath form rather than -jar, which needs a Main-Class attribute not every committed wrapper jar carries), with --no-daemon forced (a settled job leaves no resident JVM behind) and the JVM taken from JAVA_HOME only — never from PATH, because React Native's toolchain is strict about its JDK. The wrapper resolves in the working directory or in a relative -p <dir> inside it, which is what lets a session at the RN repo root build with gradlew -p android :app:assembleDebug; a directory without the wrapper jar is refused by name. Refused are the flags that redirect an anchor or open execution — -g/--gradle-user-home, --project-cache-dir, -I/--init-script, -c/--settings-file, -b/--build-file, every -D, --daemon, -t/--continuous, --stop/--status — plus -P/--project-prop keys under org.gradle., while project properties like -PreactNativeArchitectures=x86_64 pass through.

Cargo verbs are named, and dependency resolution is why it is here. cargo <name> looks for cargo-<name>.exe on PATH and runs it, so an unfiltered verb space would be general execution behind an allowlisted name — the reason pnpm exec is narrowed. Accepted: build, check, test, bench, doc, run, clean, fix, clippy, fmt, generate-lockfile, and the dependency verbs fetch, update, add, remove/rm, tree, metadata. clippy and fmt are themselves cargo-*.exe subcommands and are accepted by name because they ship with the toolchain — provenance cannot decide it: measured, rustup's shims and cargo install's binaries (cargo-binstall.exe, 26 MB) share the one directory on PATH. Refused: the verbs that touch machine state or crates.io (install/uninstall write %USERPROFILE%\.cargo\bin, publish/yank/owner/login/logout change a remote or store a token), scaffolding that can name a path outside the pinned cwd (new/init, vendor, package), the compiler reached around cargo (rustc/rustdoc), every unlisted name (cargo nextest), the anchor flags --target-dir/--config/-Z, the whole-workspace spellings --workspace/--all/--exclude, and cargo +<toolchain> — the toolchain is machine configuration (rustup default, RUSTUP_TOOLCHAIN), and every toolchain shares one target/. -p/--package is a Workspace selector (a path-shaped value is held to the literal-path rules), and --manifest-path is guarded the way gradlew -p is: a relative path inside the pinned cwd, which is also the only thing that stops cargo's own upward search for Cargo.toml. cargo clean is allowed because it removes target/ only. A cargo run that serves is not guessed onto the long lane — pass long: true.

Workspace scripts run on either side of the verb. pnpm --filter <pkg> run test and npm -w <pkg> run build are accepted, because a selector picks a member of the workspace the pinned cwd already belongs to rather than moving the job: the manager still starts in the session's directory, so the lane and its serialization are unchanged. A selector that names a directory is guarded by the same literal-path rules as the restore pathspecs (./packages/web yes, ../.. no, . because it is anchored at the cwd itself), the whole-workspace spellings — --workspaces, -ws, --include-workspace-root, and pnpm's -w/--workspace, which is --workspace-root there — are refused, and so is a ! exclusion, because it means every member except the one named. What it costs is in ADR-0002: a package name is resolved by the workspace, so it may land in a member the pinned cwd does not contain.

Git writes name what they touch. fetch, rebase, cherry-pick and a narrowed git push are accepted, because a fork kept in step with upstream needs all three in one loop and fetch is what makes a rebase mean anything. A push must carry a named remote and a named destination ref — git push origin feature, git push origin HEAD:refs/heads/feature — so a bare git push (which takes its destination from the upstream config), --force, --delete, --mirror, --all/--tags, a +refspec, a :refspec, a wildcard refspec and a path/file: remote are all refused. A rebase or cherry-pick is refused when it would block: a job has no terminal, so -i/--autosquash, -e/--edit and -x/--exec are out, while --abort/--continue/--skip are in, or a conflict would have no way out. merge and pull stay out — a pull hides whether it merged or rebased (ADR-0014).

Refusals are deliberate, and they are the only bound left (ADR-0001). dart takes any subcommand, so dart run <file>.dart executes arbitrary code with this plugin's access; what the narrow surface buys is recovery cost and surprise for a fallible caller. Refused on that reasoning: history that cannot be got back (reset --hard, clean, stash, checkout/switch), a push that would rewrite or delete a remote ref, an interactive rebase or an --edit cherry-pick, git restore . (a pathspec guard: literal, relative, non-wildcard paths only), the cwd-retargeting flags and the whole-workspace spellings on either package manager, and an exec form (pnpm exec, npm exec, npx) whose target is not one of the project's own script binaries — measured, they also run anything on PATH, and npx fetches what it cannot find.

Long jobs get their own lane. A command that runs until killed — vite dev, vitest in watch mode, a dev/start/serve/watch/storybook script, or long: true — is serialized against other long jobs instead of against the builds, because a dev server on the queue lane starves everything behind it. The guess exists because the two error directions are not symmetric; the flag overrides it either way.

Lanes are keyed by working directory. Concurrent Flutter runs corrupt build/ and two Vite builds share dist/, so all runs in one directory are serialized — across conversations too. The cost is honest: a long build in one conversation delays a build in another conversation on the same directory, which is what already happened within one conversation.

Formatting the way CI formats. dart format output changes between SDK releases, so formatting with a newer local dart is what turns CI's dart format --set-exit-if-changed check red. Point dartFormatExe at the standalone dart whose version matches the Flutter version the project's workflow pins, and only dart format uses it — dart analyze deliberately keeps the local SDK, because its verdict also depends on the Flutter framework version resolved through the package config, which a formatter pin cannot align.

Scoping to your uncommitted files. scope: "uncommitted" reads the working tree once, at submit time, and narrows the command to its uncommitted .dart files — the scope is Dart's by construction, and cargo fmt/clippy take no file list, so there is no Rust scope (ADR-0015). For dart format that is an Expansion — the files are appended to argv, so the formatter itself is narrowed, which is CI's changed-files check run locally. For analyze/fix no argv can name a file list (an analyzer takes at most one directory), so the same set narrows the returned lines instead and the exit code still covers the whole project: a Filter. Nothing uncommitted is a refusal, not a whole-tree format.

Timeouts never kill. timeoutSec bounds how long the call waits for queue time plus run time; when it expires the job is unchanged and still running. Read it on with job_output <id>, stop it with job_kill <id>.

The browser half, and looking at the UI

The split ADR-0005 drew is unchanged: this plugin runs the app under test, the browser drives it. Starting the app needs the toolchain (a Vite dev server dies inside the file sandbox), and driving is @playwright/mcp — reached as mcp__ui__browser_* tools. What changed is that the MCP client is no longer a resident profile row: turn the conversation's Browser switch on and the plugin mounts it into a scope minted for that conversation; turn it off (or end the conversation) and the connection and its server process go away.

The loop: bridge_run {cmd: "vite", args: ["dev"], long: true, background: true} → read the bound URL from the job's log → mcp__ui__browser_navigate, browser_snapshot (the accessibility tree as text — cheap, and the source of the element refs) → act by ref → browser_console_messages when the screen is blank → screenshot or video as the artifact. Sight arrives two ways, an image block in the tool result or the same file read with the harness's image tool; neither is privileged, and the one rule is the claim — never report having seen a page you only have a path to. Make the finding repeatable by writing it as a script-driven run through bridge_run.

Installing it is the trust decision

This plugin is not a sandbox and not a privilege boundary. Its children run with the harness's own access, unconfined, with no per-session approval — so the decision that used to be a danger-full-access escalation is now the decision to install it into a profile (ADR-0001, amended). That is a real trade: the refusal list described above is the only bound on what a conversation can do, and it bounds surprise and recovery cost rather than privilege.

What is unchanged: there is no privilege boundary here to lose, and no force push, remote ref deletion, reset --hard, clean, stash or whole-worktree wipe is reachable. What changed with ADR-0014 is the unnamed push: git push origin feature is accepted, and it authenticates through the machine's own git credential store — the plugin stores no token, reads none, and a job's stdin is ignore with GIT_TERMINAL_PROMPT=0, so a push that needs an answer fails with git's own message instead of hanging. The old sentence ("a GitHub token must never live in a long-running process") was never true of a plugin that is the harness process; what the refusal bought was one approval click per push. The callers are your own agent sessions on your own machine, and everything the plugin does per conversation is in the switch the human can see and turn off.

Requirements

  • Windows — CI-verified, and the platform the resolution logic is written for. The retired server carried a POSIX fallback nobody had exercised; this port states the platform instead of carrying an untested claim.
  • Node 22+ for the plugin, and node on PATH for a script binary.
  • flutter/dart, git, and whichever package manager your project names.
  • A Rust toolchain — cargo on PATH, as rustup installs it — when you run cargo. The bridge uses the machine's own %USERPROFILE%\.cargo: the registry cache and its credentials stay where your own builds keep them, which is also how a job reaches crates.io at all.
  • JAVA_HOME pointing at a JDK when you run gradlew — the wrapper's JVM comes from there and never from PATH.
  • A harness on the @deepseek-ai/* 0.2 line. The peers are caret ranges (^0.2.0-rc.2, and ^4.0.4 for @deepseek-ai/cordis), so any 0.2.x build satisfies them. What a caret does not buy is a prerelease of a later patch: measured with semver, 0.2.1-rc.3 satisfies neither ^0.2.0-rc.2 nor any wildcard, because a prerelease only matches a range carrying a comparator with its own version tuple — so that line needs the range widened by hand. devDependencies pin 0.2.0-rc.2, the build the types and the suite are read against.

Development

pnpm install
pnpm typecheck      # host, client and test programs
pnpm build          # both halves: lib/index.js and lib/client.js
pnpm test           # vitest

lib/ is committed — the two entry points, not their source maps. This package is installed into a profile from git (github:ds-hu/dsh-tool-bridge), and a git dependency unpacks the repository's tracked files and builds nothing, so an ignored lib/ ships a package whose main does not exist: the Loader answers 1 entry did not activate toolbridge … failed to import. So pnpm build and stage lib/ with the source change — tests/package.spec.ts fails if the entry points are missing or untracked. (A prepare script would be the alternative; it costs an allowBuilds entry per resolved commit in every consuming profile, which is why the sibling plugins commit lib/ instead.)

icon.svg is committed for the same reason and a smaller one: package.json#icon is what the plugin list renders, and app-boot reads that path out of the manifest's own directory. It is also in files, which is the list the pack applies — an icon the pack leaves out is a plugin card without a mark.

The engine under src/engine/ is pure logic ported from the retired server with its test suite — the digest parsers, the known-failure split, the command surface, the ARB editor, the resolvers. Its specs read the same fixtures the Python suite did (tests/fixtures/), and the ports were checked against the Python outcomes: validate.ts has a 135-case parity digest whose Python-vs-TypeScript output hashes identical.

Two sandbox facts shape the loop, both measured:

  • Run the suite through the toolchain bridge, not directly, in a confined session: vitest loads its config through esbuild's service, which spawns with piped stdio and dies with spawn EPERM under the sandbox. Outside a sandbox, or through the plugin's own bridge_run, it runs normally.
  • --pool=threads keeps vitest portable between the two: its default forks pool uses an IPC pipe, and pipes are what the sandbox forbids.

Where the rest lives

  • CONTEXT.md — the vocabulary the code and the docs are written in: tool bridge, engine, the two halves, switch, project default, scoped mount, job ledger, lane depth, working directory, guardrail, digest, format pin, uncommitted scope, sight — plus the terms this refactor retired and why.
  • docs/adr/ — the decisions: the allowlist is a guardrail (0001, amended for the trust decision); the working directory is pinned (0002, amended for the workspace selector); a sub-tool is a job (0003, amended); the Node surface and the long lane (0004); the browser belongs to Playwright MCP, now mounted per conversation (0005, amended); npm is a package manager on the same terms (0006); the plugin is the bridge (0007, amended for the peer range); the git surface carries fetch, rebase, cherry-pick and a named push (0014); cargo joins as a verb-guarded build tool, and dependency resolution is its reason (0015); a directory's last flip is its project default (0016).
  • docs/vite-vitest-sandbox-findings.md — the measurements behind the Node surface: which commands the sandbox kills, with what error, and why.
  • CHANGELOG.md — what each released version changed, and why; the entries are written from the commit messages, which carry the measurements.
  • src/engine/ — the pure logic and the reason each refusal exists.
  • src/host/ — the plugin half: tools, lanes, the job ledger, the switches, the scoped browser mount, the sidebar's transport.
  • src/client/ — the browser half: the switch row above the composer and the sidebar panel.

Deliberately absent

A force push or a remote ref deletion; merge/pull; git history that cannot be got back (reset --hard, clean); whole-worktree wipes (git restore .); stash; checkout/switch; a per-request cwd (the working directory is the session's, ADR-0002) and per-request worktrees; the whole-workspace runs (--workspaces, -ws, --include-workspace-root, pnpm's -w) and the unnarrowed package-manager forms (pnpm dlx, npm link/unlink/publish/ config/store) and an exec-form target that is not a project script binary; the cargo verbs that touch machine state or crates.io (install/uninstall, publish, yank, owner, login/logout), cargo scaffolding (new, init, vendor, package), the compiler reached around cargo (rustc/rustdoc), an unlisted cargo-<name> helper such as nextest, cargo's --target-dir/ --config/-Z/--workspace/--all/--exclude and cargo +<toolchain>, and a Rust uncommitted scope; guessing a project's package manager from its lockfile (the lockfile is advisory, the caller names the manager); any raw node or python executable name (the guardrail is a list of names, ADR-0001); a per-request formatter override (the pin is configuration); UI driving inside the plugin — the browser is Playwright MCP's, mounted per conversation (ADR-0005).

Licence

MIT — see LICENSE.

About

One approval per session instead of one per command: a loopback-only toolchain server for file-sandboxed agent sessions.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages