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.
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.
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.
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 FalseConfiguration 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 |
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 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.
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.
- 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
nodeonPATHfor a script binary. flutter/dart,git, and whichever package manager your project names.- A Rust toolchain —
cargoonPATH, as rustup installs it — when you runcargo. 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_HOMEpointing at a JDK when you rungradlew— the wrapper's JVM comes from there and never fromPATH.- A harness on the
@deepseek-ai/*0.2 line. The peers are caret ranges (^0.2.0-rc.2, and^4.0.4for@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.3satisfies neither^0.2.0-rc.2nor 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.devDependenciespin0.2.0-rc.2, the build the types and the suite are read against.
pnpm install
pnpm typecheck # host, client and test programs
pnpm build # both halves: lib/index.js and lib/client.js
pnpm test # vitestlib/ 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:
vitestloads its config through esbuild's service, which spawns with piped stdio and dies withspawn EPERMunder the sandbox. Outside a sandbox, or through the plugin's ownbridge_run, it runs normally. --pool=threadskeeps vitest portable between the two: its default forks pool uses an IPC pipe, and pipes are what the sandbox forbids.
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.
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).
MIT — see LICENSE.