msb-tool-bundles

Agent tool bundles: ~/.config/msb/tools/<name>/ with bundle.toml (description, hosts, [env], pi_package — a pi package installed by pi in the guest via plan_pi_packages()/sync_pi_packages(), validated

SKILL.md

GitHub

Agent Tool Bundles

Detail carved out of AGENTS.md, which keeps only what has to hold in every session. Repo-specific throughout; the facts here are verified against msb 0.7.6 and re-checked on 0.7.7.

A bundle is one capability this machine owns and a project never names: a folder under TOOLS_DIR (~/.config/msb/tools/<name>/) holding bundle.toml (TOOL_KEYS: description, hosts, [env]), pi.ts (PI_BUNDLE_FILE) and claude/SKILL.md (CLAUDE_BUNDLE_FILE), the last two optional. Nothing is shipped: a bundle points at endpoints the operator runs, so shipping one would aim every clone at someone else's server — the same reasoning as machine_only_groups, and the reason Sandbox.bundles_pinned reads tools from the registry entry only, falling back to [defaults] tools, and never from a project's sandbox.toml. available_bundles() parses every folder but never dies — a bundle that does not parse is ({}, "does not parse: …") — so a half-written draft stops only the sandboxes that name it. bundle_status() / Sandbox.bundle_status give each named bundle's problem (unknown name, parse error, bundle_problem()) with the file named; Sandbox.bundles dies on the first one and is what every path that APPLIES a bundle reads (rules, env, adapters), at every start. show/show --json read bundle_status and flag the problem instead (a problem key per tools row). Both are functools.cached_property: one start reads them half a dozen times.

bundle_problem() is the whole validation: slug folder name, no unknown keys, one-line description (it is what the agent is told it has), non-empty hosts parsed by bundle_host() (HOST, HOST:PORT, [IPv6]:PORT, never a scheme or rule syntax, never port 80, then rule_problem()), and [env] whose names are shell identifiers, are not is_reserved_var(), and do not start MSB_ (msb's placeholder for a bound secret is the literal $MSB_<VAR> — spike 13 — and a bundle's env reaches the guest VERBATIM, so a mention in a body the interceptor cannot substitute is a refused request). An env value that parses as a URL must be https and its host:port must be in hosts (compared lowercased, as urlsplit().hostname is), or the tool would be handed a call egress denies — which from inside the guest reads as an outage, not as a rule.

Everything is derived from those three keys. net_rules() appends one source per bundle (tools:<name>, so a refusal names which bundle.toml), after the groups and the [llm] rules and before extra_rules; its non-443 ports join the --tls-intercept-port union with the model endpoints' (443 always restated); bundle_env() is merged FIRST in env_vars(), under every [env], and like every variable is fixed at create — so hosts, [env] and attaching/detaching a bundle are rebuilds, while adapter files and the description refresh on the next start. Sandbox.bundles returns [] for a Kandev sandbox: kandev_provision() builds its own argv with its own egress and runs none of the per-boot seeding, so a bundle there would be rules with no tool.

Delivery is host-side, into mounts that already exist — no new mount, no npm install, nothing runs in the guest to install it. apply_pi_bundles(box, agent) copies each adapter to STATE_DIR/pi/<name>/agent/extensions/msb-<name>.ts (BUNDLE_PREFIX), which pi discovers as ~/.pi/agent/extensions/; apply_claude_bundles(box) (from ensure_profile(), secret mode only) copies each Claude skill to STATE_DIR/claude/<name>/skills/msb-<name>/SKILL.md, the guest's ~/.claude. The prefix on both keeps a bundle off a skill or extension the operator has under the bundle's own name. A stale adapter whose removal fails stays in the marker and is retried next start. Which ones msbctl wrote is recorded in STATE_DIR/tools/<name>.json (bundles_applied()/bundles_record()), so a disable deletes exactly those and leaves an extension or skill the operator put there by hand; rename_sandbox() moves that marker and purge unlinks it. sandbox_profile_section(box, harness) announces each bundle's description — only to the harness it ships an adapter for — because an agent that does not know a bundle exists reaches for the built-in web tools and hits the deny.

A pi.ts adapter is one self-contained file: msbctl copies it and nothing beside it, so a relative import dangles, and only pi's aliased imports (@earendil-works/pi-coding-agent, which pi also aliases under the @mariozechner name it used to have, and typebox), node builtins and globals are available. Endpoints come from [env] at call time, never written into the adapter, so the same copy serves every sandbox and a URL in the file cannot hide from the rule list.

pi_package (pi_package_problem(): a bare npm name, optionally @<exact version>; no range, tag or npm:/git:/path source) is the one exception to "nothing runs in the guest". plan_pi_packages() merges npm:<spec> into settings.json's packages (marker key pi_packages lists the npm names msbctl declared, so a pi install of the operator's is never touched) and drops a detached one HERE, so pi stops loading it whatever the guest does. sync_pi_packages() then msb execs only for real work: PI_OFFLINE=0 pi install npm:<spec> for one missing or off its pin, npm uninstall --prefix ~/.pi/agent/npm for a detached one still there (not pi remove, which exits 1 once the settings entry is gone). Installed-or-not is read from the mount (pi_package_installed(): agent/npm/node_modules/<name>/package.json, pi 1.4's getNpmInstallRoot()), never from an exit status; a miss warns and the start carries on. The guest step runs only when ensure_running() actually starts the sandbox or is msbctl start (ensure_pi(box, packages)), so a failing install never delays a shell/exec into a running one; the marker is kept either way. An entry the operator already has for the same npm name is never adopted (it would be uninstalled on a detach): the bundle's is left out with a warning. Two bundles naming one package die in Sandbox.bundles. PI_OFFLINE=1 stays in [agent_env.pi] — it is exactly what stops pi's own installMissing() and updateConfiguredSources() — so the install and UPDATERS["pi"]'s pi update --extensions lift it for one command. A pi_package counts as a pi adapter (bundle_adapters(folder, spec)), so the bundle is announced to pi only, and hosts may be omitted for it. msbctl names no package, fetches none on the host and resolves no dependency: that is the line that keeps this from becoming a plugin manager. Package-specific switches belong in the bundle's [env] (bili: ACP_AUTO_UPDATE=0, read by its checkForUpdate() in 0.1.83).

UI: setup section "Agent tools" (section_tools, _summary_tools, BUNDLE_SKELETON when TOOLS_DIR is empty — there is no TOML writer and no picker can guess an endpoint) writes [defaults] tools; edit section "Agent tools" (section_agent_tools) writes the registry's tools and asks for a rebuild. show prints one tool line per bundle and show --json a tools list (names of env variables only, never a reason to worry about values). Tests: tests/test_bundles.py. spikes/19-agent-tool-bundle.sh checks what a unit test cannot — the adapter under pi's own loader on the host (SPIKE_LIVE=1 also calls the endpoints), and with SPIKE_SANDBOX=<name> the emitted rules, both adapter files and a search called from inside the guest, where only the emitted rules apply.