pti/wraptool
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages 3 Wiki Activity Actions

docs: design a shared harness descriptor registry #13

Merged
pti merged 1 commit from design-harness-descriptor into main 2026-07-07 16:13:45 +02:00
Conversation 0 Commits 1 Files changed 1 +207
pti commented 2026-07-07 15:49:21 +02:00
Owner
Copy link

Design doc for scaling to N coding harnesses (opencode, pi, agy, …).

Problem

The "point harness X at wraptool over MCP" logic exists three times, diverging: init.go (7 harnesses, no auth), guixcontainer.go's writeMCPConfig (claude + auth), connect.sh (claude + auth). The registry that knows all harnesses can't emit a token; the two that can are claude-only.

Proposal

Extract init.go's harnessGenerators into internal/harness — a Descriptor{Name, Auth, Render(Params)} registry — shared by init, up (both runtimes), and eventually connect.sh (shells out to wraptool init, retiring the shell reimpl). Per-harness AuthMode makes "can this harness carry a bearer token to a remote MCP server?" explicit and fails loudly instead of writing a config that 401s. Adding a harness = one descriptor row + one auth check.

§7 — provisioning decision (decoupled)

The harness is the developer's toolbox, not the project: binaries live in a shared, developer-scoped pool ($XDG_DATA_HOME/wraptool/harnesses/) mounted into every container (install once across all projects), never in manifest.scm, never packaged by wraptool. Includes the three-tier isolation table (project toolchain / developer toolbox / host secrets) and the "curate the pool, never mount $HOME" rule (a harness's own API key is a dev cred that belongs in the box; project/host secrets stay out, via MCP).

Proposal only — no code. Grounded in the existing init.go registry.

🤖 Generated with Claude Code

Design doc for scaling to N coding harnesses (opencode, pi, agy, …). ## Problem The "point harness X at wraptool over MCP" logic exists **three times, diverging**: `init.go` (7 harnesses, no auth), `guixcontainer.go`'s `writeMCPConfig` (claude + auth), `connect.sh` (claude + auth). The registry that knows all harnesses can't emit a token; the two that can are claude-only. ## Proposal Extract `init.go`'s `harnessGenerators` into `internal/harness` — a `Descriptor{Name, Auth, Render(Params)}` registry — shared by `init`, `up` (both runtimes), and eventually `connect.sh` (shells out to `wraptool init`, retiring the shell reimpl). Per-harness `AuthMode` makes "can this harness carry a bearer token to a remote MCP server?" explicit and fails loudly instead of writing a config that 401s. Adding a harness = one descriptor row + one auth check. ## §7 — provisioning decision (decoupled) The harness is the **developer's toolbox, not the project**: binaries live in a shared, developer-scoped **pool** (`$XDG_DATA_HOME/wraptool/harnesses/`) mounted into every container (install once across all projects), never in `manifest.scm`, never packaged by wraptool. Includes the three-tier isolation table (project toolchain / developer toolbox / host secrets) and the "curate the pool, never mount `$HOME`" rule (a harness's own API key is a dev cred that belongs in the box; project/host secrets stay out, via MCP). Proposal only — no code. Grounded in the existing `init.go` registry. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
docs: design a shared harness descriptor registry
All checks were successful
Lint / lint (pull_request) Successful in 18s
Details
a526ee31a4 
Add design/harness-descriptor.md: unify the "wire harness X -> wraptool MCP"
logic that today lives three times, diverging — cmd/init.go (7 harnesses, no
auth), cmd/guixcontainer.go writeMCPConfig (claude + auth), and connect.sh
(claude + auth). Proposes extracting init.go's harnessGenerators into an
internal/harness Descriptor registry shared by init, up (both runtimes), and
eventually connect.sh, with a first-class per-harness AuthMode so a networked
container fails loudly when a harness can't carry a bearer token.

§7 records the decoupled provisioning decision: the harness is the developer's
toolbox, not the project — so binaries live in a shared, developer-scoped pool
mounted into every container (install once across all projects), never in
manifest.scm and never packaged by wraptool. Includes the project-toolchain /
developer-toolbox / host-secret three-tier isolation table.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
pti merged commit dfa1aa4509 into main 2026-07-07 16:13:45 +02:00
pti deleted branch design-harness-descriptor 2026-07-07 16:13:46 +02:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
pti/wraptool!13
No description provided.