@brutalsystems/muster 0.7.1 → 0.7.3

package/CONTRACT_PROVENANCE.md

@@ -79,6 +79,115 @@ the same codename remediation via a history rewrite (`git filter-repo
 whose content or ancestry it touched. This is a historical acquisition
 record, not a claim that the commit is still reachable.
 
+## Contract baseline moved to 0.6.0 — 2026-09-20
+
+Tin Can 0.6.0 changes the endpoint it delivers to on the opencode leg, from the
+v2 `/api/session/{id}/prompt` to the v1 `/session/{id}/prompt_async`, and the
+change resolves the failure described in the 0.5.9 entry below. It is a minor
+rather than a patch because `urgent` was removed as a capability: the v1 route
+has no equivalent of v2's steer/queue distinction, so rather than accept it and
+ignore it, Tin Can now reports urgent as unsupported on every runtime. Muster
+never referenced that capability, so nothing here changes.
+
+Muster's contract suite was run against a real installed
+`@brutalsystems/tincan@0.6.0` and passed all four cases. Naming is untouched:
+0.6.0's `canonical-id.json` was compared case by case with Muster's frozen copy
+and every pre-existing case is present with an unchanged expectation, with the
+same four additive opencode-specific cases introduced in 0.5.7.
+
+Verified end to end rather than by the suite alone: a Muster-launched OpenCode
+session in a terminal received a Tin Can message, ran the turn, and replied to
+the sending Claude Code session. The OpenCode log for that session shows a
+started loop and a resolved model with no `Failed to drain` line, which is the
+signature the 0.5.9 entry documents as the failure.
+
+One operational trap worth recording, because it makes a working setup look
+broken: the OpenCode plugin is a **copy on disk** under
+`~/.config/opencode/plugin/`. Updating the npm package does not update it, and
+a stale plugin keeps posting to the old v2 route. The peer registry records
+`plugin_version`; confirm it matches the installed package before trusting a
+delivery result.
+
+## Contract baseline moved to 0.5.9 — 2026-09-20
+
+Re-pinned from `0.5.7`, skipping a separate `0.5.8` pass, because the `notice`
+text moved twice in one afternoon while the underlying mechanism was being
+isolated: 0.5.7 described it as never scheduled, 0.5.8 as a warmth problem,
+0.5.9 states what was actually observed. Both earlier descriptions were wrong.
+
+Muster's contract suite was run against a real installed
+`@brutalsystems/tincan@0.5.9` and passed all four cases.
+
+0.5.9 changes the `notice` text on `send_peer` results and widens it from idle
+opencode peers to all opencode peers. It does not touch naming: 0.5.9's
+`canonical-id.json` was compared case by case with Muster's frozen copy, and
+every pre-existing case in `slugify`, `suffix`, `assign` and `resolve` is
+present with an unchanged expectation, with the same four additive
+opencode-specific cases 0.5.7 introduced.
+
+The reason for the churn is worth recording, because Muster's own evidence
+caused it. Muster reported that inbound Tin Can delivery to an idle
+TUI-hosted opencode session was admitted but never scheduled, and 0.5.7's
+notice encoded that mechanism. The opencode log disproves it: a session idle
+since 20:00:13 was woken 68ms after admission at 20:01:13 and ran the drain,
+which then failed with `ModelUnavailableError` on a local model. Fourteen of
+the seventeen `Failed to drain` lines in that log name the same local model.
+Admission does schedule execution, exactly as the endpoint documents; the
+turn died afterwards. Muster's `opencode serve` control did not separate host
+type from model resolution, because it used different credentials and failed on
+an unrelated 401.
+
+The mechanism was subsequently isolated, and it is neither scheduling nor model
+warmth. In every TUI-hosted opencode session observed, the drain path failed to
+resolve the session's model, while the TUI path resolved the same model in the
+same process seconds either side of it:
+
+    20:42:30  stream providerID=fireworks-ai modelID=...qwen3p8-max   (TUI turn)
+    20:42:54  ERROR Failed to drain Session
+              ModelUnavailableError: fireworks-ai/...qwen3p8-max      (delivered)
+
+That run was stock opencode 1.18.31 with no Muster involvement, no overlay, and
+a globally authenticated provider, so it is not a Muster defect and not
+specific to Muster-supplied providers.
+
+Observed across 14 distinct TUI-hosted sessions and 20 failures, under two
+unrelated providers (`muster-local` and `fireworks-ai`). No TUI-hosted drain
+was observed to succeed. The contrasting case is an `opencode serve` session,
+whose drain resolved its model and reached the provider, failing only on an
+unrelated HTTP 401 — the model resolution itself worked there. That is what
+localises this to TUI-hosted sessions. It is a consistent observation on
+1.18.31, not a proof about every configuration.
+
+What remains true for callers is narrower: a caller cannot confirm that an
+opencode peer acted on a message, because a turn that dies after admission is
+indistinguishable from outside from one that succeeded.
+
+## Contract baseline moved to 0.5.7 — 2026-09-20
+
+Re-pinned from `0.5.2` to `@brutalsystems/tincan@0.5.7`, deliberately rather
+than by drift: 0.5.2 was three releases behind and no longer what anyone runs.
+
+Muster's contract suite was run against a real installed
+`@brutalsystems/tincan@0.5.7` and passed all four cases.
+
+The intervening releases are additive on this contract. 0.5.6 added a `notes`
+array to the `peers` result and changed tool description text; 0.5.7 added a
+`notice` field on `send_peer` results for idle opencode peers, reporting that a
+message is durably admitted but that execution cannot be confirmed on that leg.
+Neither touches naming.
+
+Verified against the artifact rather than assumed: 0.5.7's
+`test/fixtures/canonical-id.json` was compared case by case with Muster's
+frozen copy. Every pre-existing case in `slugify`, `suffix`, `assign` and
+`resolve` is present with an unchanged expectation. 0.5.7 adds four cases, all
+opencode-specific — one `suffix` case for opencode session ids, three `assign`
+cases for opencode peers and slug collisions between them. Nothing was modified
+or removed.
+
+Muster's own fixture stays frozen at `tincan_version: 0.1.0` with its 31 cases.
+That is the point of the design: frozen expectations are checked against a live
+installed binary, so the suite detects drift rather than absorbing it.
+
 ## Contract baseline moved to 0.5.2 — 2026-09-20
 
 `@brutalsystems/tincan@0.2.0`, this document's verified baseline, was
@@ -112,8 +221,8 @@ withdrawn npm artifact actually contained.
 The upstream release notes report that 0.3.0 expands
 Codex-hosted listings to both runtimes and 0.3.1 corrects Codex status decoding.
 These releases have not been verified by Muster's contract suite. The tested
-baseline remains exactly 0.2.0; README installation instructions pin it outside
-Muster's dependency tree.
+baseline is 0.5.7; README installation instructions pin it outside Muster's
+dependency tree.
 
 Inspection confirms the contract test does not assert total peer counts,
 same-runtime exclusion, or Tin Can state. Its count assertion applies only to

package/README.md

@@ -12,6 +12,29 @@ loopback API and local-provider protocol checks. Claude requires a directory
 already trusted by the operator. The automated suite uses fake runtimes, not
 real models.
 
+## Install
+
+```sh
+npm install -g @brutalsystems/muster
+muster --version
+```
+
+Publishing a release does not touch an installed copy: `muster --version` keeps
+reporting the old version until you update it.
+
+```sh
+npm update -g @brutalsystems/muster
+```
+
+If `which muster` resolves to a version-manager shim (for example
+`~/.asdf/shims/muster`), run that update under the Node the shim resolves to and
+reshim afterwards — `asdf reshim nodejs` — or the shim keeps pointing at the old
+binary.
+
+An MCP server starts once at session startup, so an agent session that already
+has Muster loaded keeps running the old binary until that session restarts.
+Updating on disk is not enough; restart the session too.
+
 ## Build and run locally
 
 Requires Node 22.12+ (tested with 24.16), TypeScript 5, Codex 0.155.1, Claude
@@ -231,8 +254,14 @@ arrive after startup; this v1 is not an enterprise policy-enforcement layer.
 Claude permissions and its command sandbox are different mechanisms; neither
 claim implies that every external tool is OS-sandboxed.
 
-OpenCode keeps normal provider/model configuration but launches with `--pure`,
-which disables inherited external plugins. Before launch, Muster inspects the
+OpenCode keeps normal provider/model configuration and launches with `--pure`
+unless plugins are selected, which disables inherited external plugins.
+Providers declared under `[opencode.provider]` and a model named by
+`[opencode] model` or `--model` are supplied in the same verified overlay, so a
+launch does not depend on the operator's own OpenCode configuration; provider
+definitions merge with any the child resolves for itself rather than replacing
+them. Secrets belong in `api_key_env_var`, read from the launching environment,
+not in `config.toml`. Before launch, Muster inspects the
 effective OpenCode configuration, disables every inherited MCP server and tool
 family, enables only the selected Muster definitions, and fails closed if a
 higher-precedence managed policy prevents that isolation from being proven.
@@ -240,8 +269,10 @@ higher-precedence managed policy prevents that isolation from being proven.
 These child restrictions prevent automatically propagating spawn authority.
 External tools are enabled only through the operator configuration and launch
 selection described below. Codex and Claude runtime inboxes remain reachable
-from an external Tin Can even when they have no MCP tools of their own. OpenCode
-delivery remains deferred as documented under Tin Can compatibility.
+from an external Tin Can even when they have no MCP tools of their own. An
+OpenCode session is reachable as a Tin Can peer only when the Tin Can plugin is
+selected with `--plugin`; the plugin, not the MCP server, is what advertises the
+session to other runtimes.
 No user-level runtime configuration is rewritten, and workspace-trust dialogs
 are never accepted automatically.
 
@@ -308,8 +339,18 @@ server has the same name, and its native tool allowlist. Claude receives a priva
 Muster stdio connection that filters both tool discovery and calls; newly added
 upstream tools cannot bypass the selection. Only selected tools are preapproved.
 OpenCode disables inherited definitions and tool families in its verified
-per-launch overlay, then enables only selected definitions. It also uses
-`--pure`, so inherited plugins do not enter the child process.
+per-launch overlay, then enables only selected definitions. A launch that
+selects MCP servers omits the wildcard `*` permission entry and names the
+built-in tools it denies instead: in OpenCode a `*` entry suppresses MCP tools
+outright, and an explicit allow for the tool does not restore them. The
+built-in list is fixed, so a tool added by a future OpenCode release would not
+be denied by it; launches that select no MCP server keep the wildcard. With no plugins
+selected it also uses `--pure` and pins an empty plugin list, so inherited
+plugins do not enter the child process. Selecting a plugin with `--plugin`
+necessarily relaxes that: OpenCode merges project-local `.opencode/plugin`
+discovery into any non-empty plugin list, so the child also loads whatever
+plugins the target repository ships. Select plugins only for repositories
+trusted with that.
 Claude connection specifications are stored with owner-only permissions under
 `~/.muster/mcp`, removed on stop, task completion, or when `list` observes an ended
 session. MCP server access is separate from filesystem sandbox permissions: a
@@ -372,18 +413,18 @@ The ordinary suite requires tmux, node-pty, POSIX `ps`/`lsof`, and Python 3 for
 real file locks in the fake Codex executable. It uses isolated runtime homes and
 no model APIs. It skips the four explicitly invoked compatibility cases.
 
-The verified contract baseline is **Tin Can 0.2.0**. The suite spawns an installed binary as an MCP
+The verified contract baseline is **Tin Can 0.6.0**. The suite spawns an installed binary as an MCP
 subprocess, compares durable IDs, and verifies delivery to fake runtimes through
 both terminal hosts. A missing binary or missing durable field fails the test.
 For reproducible verification, install that exact release outside Muster:
 
 ```sh
 contract_dir=$(mktemp -d)
-npm install --prefix "$contract_dir" --no-save @brutalsystems/tincan@0.5.2
+npm install --prefix "$contract_dir" --no-save @brutalsystems/tincan@0.6.0
 MUSTER_TINCAN_BIN="$contract_dir/node_modules/.bin/tincan" npm run test:contract
 ```
 
-Verification uses the published 0.2.0 release installed in an isolated
+Verification uses the published 0.6.0 release installed in an isolated
 temporary directory. No Tin Can source edits are made.
 Fixture version metadata alone does not indicate address-format drift: compare
 the case arrays. Those arrays cover naming only, not peer-list membership or
@@ -403,6 +444,23 @@ real models.
 MIT © 2026 Mike Williams. See [LICENSE](./LICENSE). Vendored Tin Can code
 retains source attribution and its [MIT notice](./TINCAN_LICENSE).
 
+Publishing is tag-driven and runs in GitHub Actions over OIDC trusted
+publishing, with no stored npm token. A bare `git push` publishes nothing; a
+version tag is what triggers `publish.yml`. That workflow validates a [RELEASE_NOTES.md](./RELEASE_NOTES.md) section for
+the version being published, so write the notes under `## Unreleased` as you do
+the work and commit them normally. Cutting the release is then one command:
+
+```sh
+git commit -am "<the change, including its notes under ## Unreleased>"
+npm version patch -m "%s — <what changed>"
+```
+
+`npm version` runs the `version` hook, which stamps `## Unreleased` into
+`## <version> — <date>` and stages it, then bumps, commits and tags; the
+`postversion` hook pushes the commit and tag together. If there is no
+`## Unreleased` section, or it is empty, the stamp refuses — before a tag
+exists, rather than in CI after one has been pushed.
+
 [RELEASING.md](./RELEASING.md) covers versioning, package inspection, publication,
-and release notes. Changes to the shared address format require an explicit
+and release notes in full. Changes to the shared address format require an explicit
 contract update; Muster never independently fixes the frozen naming behavior.

package/dist/config.js

@@ -4,6 +4,8 @@ import { join } from "node:path";
 import TOML from "@iarna/toml";
 import { z } from "zod";
 import { mcpName, mcpServerSchema } from "./mcp.js";
+import { pluginName, pluginSchema } from "./plugins.js";
+import { openCodeSectionSchema } from "./providers.js";
 export const configSchema = z
     .object({
     host: z.enum(["auto", "tmux", "pty", "macos-terminal"]).default("auto"),
@@ -20,6 +22,9 @@ export const configSchema = z
         .default("read-only"),
     default_mcp: z.array(mcpName).default([]),
     mcp_servers: z.record(mcpName, mcpServerSchema).default({}),
+    default_plugins: z.array(pluginName).default([]),
+    plugins: z.record(pluginName, pluginSchema).default({}),
+    opencode: openCodeSectionSchema,
     allow_dangerous_flags: z.boolean().default(false),
 })
     .strict();

package/dist/guard.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { resolve } from "node:path";
 import { mcpName, claudeMcpConfig } from "./mcp.js";
+import { pluginName } from "./plugins.js";
 export const runSchema = z
     .object({
     runtime: z.enum(["codex", "claude", "opencode"]),
@@ -19,6 +20,8 @@ export const runSchema = z
     permissions: z.enum(["auto", "deny", "bypass"]).optional(),
     sandbox: z.enum(["read-only", "workspace-write", "full-access"]).optional(),
     mcp: z.array(mcpName).optional(),
+    plugin: z.array(pluginName).optional(),
+    model: z.string().min(1).optional(),
     args: z.array(z.string()).default([]),
 })
     .strict();

package/dist/muster.js

@@ -28,6 +28,12 @@ and --sandbox read-only|workspace-write|full-access before -- RUNTIME_OPTIONS.
 terminal, iterm2, or ghostty, and requires --open.
 --mcp NAME is repeatable and replaces configured session defaults; --no-mcp
 clears them. Tasks use no MCP defaults; select servers explicitly.
+--plugin NAME is repeatable and replaces configured session defaults;
+--no-plugin clears them. OpenCode only: selected plugins load in the child,
+which also admits any plugin the target repository ships.
+--model PROVIDER/MODEL selects the OpenCode model, overriding the configured
+[opencode] model. Providers defined under [opencode.provider] are supplied to
+the child, so launches do not depend on the user's own OpenCode config.
 run, list and stop default to JSON. output prints raw task text.
 
 pty launches print their record and keep this process running. Ctrl-C stops the
@@ -199,15 +205,24 @@ async function main() {
                 sandbox: { type: "string" },
                 mcp: { type: "string", multiple: true },
                 "no-mcp": { type: "boolean" },
+                plugin: { type: "string", multiple: true },
+                model: { type: "string" },
+                "no-plugin": { type: "boolean" },
             },
         });
-        const { format = "json", "no-mcp": noMcp, ...values } = parsed;
+        const { format = "json", "no-mcp": noMcp, "no-plugin": noPlugin, ...values } = parsed;
         if (noMcp !== undefined && command !== "run")
             throw new Error("--no-mcp applies only to run");
         if (noMcp && values.mcp)
             throw new Error("--mcp and --no-mcp cannot be combined");
         if (noMcp)
             values.mcp = [];
+        if (noPlugin !== undefined && command !== "run")
+            throw new Error("--no-plugin applies only to run");
+        if (noPlugin && values.plugin)
+            throw new Error("--plugin and --no-plugin cannot be combined");
+        if (noPlugin)
+            values.plugin = [];
         if (format !== "json" && format !== "human")
             throw new Error("format must be json or human");
         if (command === "output" && parsed.format !== undefined)

package/dist/opencode-policy.js

@@ -1,6 +1,7 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { resolvePermissions, runtimeArgs } from "./guard.js";
+import { openCodeModel, openCodeProviders } from "./providers.js";
 const exec = promisify(execFile);
 const DEBUG_CONFIG_ERROR = "Cannot verify effective OpenCode MCP configuration";
 const ISOLATION_ERROR = "OpenCode MCP isolation could not be verified; refusing launch";
@@ -96,15 +97,48 @@ function mcpPolicy(selected, inheritedMcpNames) {
     }
     return { effective, mcp, tools };
 }
+/**
+ * OpenCode's built-in tool ids, as reported by its own tool listing. Needed
+ * because a wildcard `*` permission entry suppresses MCP tools outright — an
+ * explicit allow for the tool does not rescue it — so a launch that selects
+ * MCP servers has to name the built-ins it denies instead of leaning on `*`.
+ * A built-in added by a future OpenCode release is not in this list and would
+ * not be denied by it; see the isolation note in the README.
+ */
+const OPENCODE_BUILTIN_TOOLS = [
+    "invalid",
+    "question",
+    "bash",
+    "read",
+    "glob",
+    "grep",
+    "edit",
+    "write",
+    "task",
+    "webfetch",
+    "todowrite",
+    "todoread",
+    "websearch",
+    "skill",
+    "apply_patch",
+    "patch",
+    "list",
+    "lsp",
+    "external_directory",
+];
 function permissions(req, config, tools) {
     const policy = resolvePermissions(req, config);
-    const permission = {
-        "*": policy.permissions === "bypass"
-            ? "allow"
-            : policy.permissions === "auto"
-                ? "ask"
-                : "deny",
-    };
+    // A selected MCP server cannot coexist with a wildcard entry, so the
+    // built-ins are enumerated instead. Without one, `*` still backstops.
+    const selectsMcp = Object.values(tools).some((enabled) => enabled);
+    const fallback = policy.permissions === "bypass"
+        ? "allow"
+        : policy.permissions === "auto"
+            ? "ask"
+            : "deny";
+    const permission = selectsMcp && policy.permissions !== "bypass"
+        ? Object.fromEntries(OPENCODE_BUILTIN_TOOLS.map((name) => [name, fallback]))
+        : { "*": fallback };
     if (policy.permissions !== "bypass") {
         for (const name of [
             "read",
@@ -137,14 +171,27 @@ function permissions(req, config, tools) {
         permission[pattern] = enabled ? "allow" : "deny";
     return permission;
 }
-export function openCodeConfig(req, config, selected, inheritedMcpNames) {
+export function openCodeConfig(req, config, selected, inheritedMcpNames, plugins = [], source = {}) {
     const { mcp, tools } = mcpPolicy(selected, inheritedMcpNames);
+    const model = openCodeModel(req.model, config);
+    const provider = openCodeProviders(config, source);
     return {
         share: "disabled",
+        // Providers merge with whatever the child resolves for itself, so naming
+        // one here adds a definition rather than displacing the operator's.
+        ...(Object.keys(provider).length > 0 && { provider }),
+        ...(model !== undefined && { model }),
         server: { hostname: "127.0.0.1" },
         permission: permissions(req, config, tools),
         tools,
         mcp,
+        // Absent, OpenCode discovers plugins from the user and project plugin
+        // directories; `--pure` is what suppresses them. A non-empty array names
+        // the operator's selection but does NOT displace project-local discovery,
+        // so selecting any plugin also admits whatever the target repository
+        // ships under .opencode/plugin. An empty array is the isolated case and
+        // is paired with `--pure` at launch.
+        plugin: plugins.map((plugin) => plugin.url),
     };
 }
 function mergeRecords(base, override) {
@@ -290,18 +337,18 @@ export async function openCodeMcpNames(env, cwd, deadline) {
         throw new Error(DEBUG_CONFIG_ERROR);
     return Object.keys(config.mcp);
 }
-export async function openCodeSessionLaunch(req, config, selected, inheritedMcpNames, port, env, cwd, deadline) {
+export async function openCodeSessionLaunch(req, config, selected, inheritedMcpNames, port, env, cwd, deadline, plugins = [], source = {}) {
     const extra = runtimeArgs(req);
     const policy = resolvePermissions(req, config);
     const overlay = {
-        ...openCodeConfig(req, config, selected, inheritedMcpNames),
+        ...openCodeConfig(req, config, selected, inheritedMcpNames, plugins, source),
         server: { hostname: "127.0.0.1", port },
     };
     const patch = await verifyOverlay(overlay, selected, inheritedMcpNames, env, cwd, deadline);
     return {
         argv: [
             "opencode",
-            "--pure",
+            ...(plugins.length === 0 ? ["--pure"] : []),
             "--hostname",
             "127.0.0.1",
             "--port",
@@ -316,10 +363,10 @@ export async function openCodeSessionLaunch(req, config, selected, inheritedMcpN
         serverUrl: `http://127.0.0.1:${port}`,
     };
 }
-export async function openCodeTaskLaunch(req, config, selected, inheritedMcpNames, env, cwd, deadline) {
+export async function openCodeTaskLaunch(req, config, selected, inheritedMcpNames, env, cwd, deadline, plugins = [], source = {}) {
     const extra = runtimeArgs(req);
     const policy = resolvePermissions(req, config);
-    const overlay = openCodeConfig(req, config, selected, inheritedMcpNames);
+    const overlay = openCodeConfig(req, config, selected, inheritedMcpNames, plugins, source);
     const patch = await verifyOverlay(overlay, selected, inheritedMcpNames, env, cwd, deadline);
     return {
         argv: [
@@ -327,7 +374,7 @@ export async function openCodeTaskLaunch(req, config, selected, inheritedMcpName
             "run",
             "--format",
             "json",
-            "--pure",
+            ...(plugins.length === 0 ? ["--pure"] : []),
             ...(policy.permissions === "auto" ? ["--auto"] : []),
             ...extra,
             "--",

package/dist/plugins.js

@@ -0,0 +1,34 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { z } from "zod";
+export const pluginName = z.string().regex(/^[a-zA-Z0-9_-]+$/);
+export const pluginSchema = z
+    .object({
+    path: z.string().min(1),
+})
+    .strict();
+/**
+ * OpenCode wants plugins as file URLs. Operator definitions are written as
+ * ordinary paths, so `~` and relative paths resolve here rather than in the
+ * launch path, where a wrong answer would be harder to see.
+ */
+function pluginUrl(path) {
+    const expanded = path.startsWith("~/")
+        ? join(homedir(), path.slice(2))
+        : path;
+    return pathToFileURL(resolve(expanded)).href;
+}
+export function selectPlugins(req, config) {
+    // Personal defaults apply to sessions, not unattended one-shot tasks —
+    // the same rule selectMcp uses.
+    const names = req.plugin ?? (req.kind === "session" ? config.default_plugins : []);
+    return [...new Set(names)].map((name) => {
+        const plugin = Object.hasOwn(config.plugins, name)
+            ? config.plugins[name]
+            : undefined;
+        if (!plugin)
+            throw new Error(`Unknown plugin: ${name}`);
+        return { name, url: pluginUrl(plugin.path) };
+    });
+}

package/dist/providers.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+export const providerName = z.string().regex(/^[a-zA-Z0-9_-]+$/);
+const environmentName = z.string().regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/);
+const modelId = z.string().min(1);
+/**
+ * Deliberately thin. OpenCode's provider schema is far larger; Muster carries
+ * only what a launch needs to stand on its own, so the operator does not have
+ * to keep a matching definition in ~/.config/opencode. Per-model options are
+ * passed through verbatim because model capability flags (tool_call, limit)
+ * decide whether an agent can use tools at all.
+ */
+export const providerSchema = z
+    .object({
+    npm: z.string().min(1).optional(),
+    name: z.string().min(1).optional(),
+    base_url: z.string().url().optional(),
+    api_key: z.string().min(1).optional(),
+    api_key_env_var: environmentName.optional(),
+    models: z
+        .union([
+        z.array(modelId),
+        z.record(modelId, z.record(z.string(), z.unknown())),
+    ])
+        .default({}),
+})
+    .strict()
+    .refine((p) => !(p.api_key !== undefined && p.api_key_env_var !== undefined), "api_key and api_key_env_var cannot be combined");
+export const openCodeSectionSchema = z
+    .object({
+    model: z.string().min(1).optional(),
+    provider: z.record(providerName, providerSchema).default({}),
+})
+    .strict()
+    .default({});
+function models(definition) {
+    return Array.isArray(definition.models)
+        ? Object.fromEntries(definition.models.map((id) => [id, {}]))
+        : definition.models;
+}
+function apiKey(name, definition, source) {
+    if (definition.api_key !== undefined)
+        return definition.api_key;
+    if (definition.api_key_env_var === undefined)
+        return undefined;
+    const value = source[definition.api_key_env_var];
+    // Failing here beats launching a session whose every turn dies on a 401.
+    if (value === undefined || value === "")
+        throw new Error(`Provider ${name} needs ${definition.api_key_env_var} in the environment`);
+    return value;
+}
+/**
+ * The provider/model half of the OpenCode overlay. Providers merge with any
+ * the child resolves for itself, so these definitions add to the operator's
+ * own configuration rather than replacing it.
+ */
+export function openCodeProviders(config, source) {
+    const entries = Object.entries(config.opencode.provider);
+    if (entries.length === 0)
+        return {};
+    return Object.fromEntries(entries.map(([name, definition]) => {
+        const key = apiKey(name, definition, source);
+        const options = {};
+        if (definition.base_url !== undefined)
+            options.baseURL = definition.base_url;
+        if (key !== undefined)
+            options.apiKey = key;
+        return [
+            name,
+            {
+                ...(definition.npm !== undefined && { npm: definition.npm }),
+                ...(definition.name !== undefined && { name: definition.name }),
+                ...(Object.keys(options).length > 0 && { options }),
+                models: models(definition),
+            },
+        ];
+    }));
+}
+/** `--model` beats the configured default; OpenCode decides when neither is set. */
+export function openCodeModel(requested, config) {
+    return requested ?? config.opencode.model;
+}

package/dist/run.js

@@ -22,6 +22,7 @@ import { allocateLoopbackPort, OpenCodeHttp } from "./opencode-http.js";
 import { assertOpenCodeVersion, openCodeMcpNames, openCodeSessionLaunch, openCodeTaskLaunch, } from "./opencode-policy.js";
 import { assignNames, resolvePeer, runtimeName, } from "./naming.js";
 import { selectMcp, prepareMcp, mcpEnvironment } from "./mcp.js";
+import { selectPlugins } from "./plugins.js";
 export class Muster {
     config;
     home;
@@ -68,6 +69,7 @@ export class Muster {
             throw new Error("--open requires a tmux session on macOS");
         const permissions = resolvePermissions(req, this.config);
         const selectedMcp = selectMcp(req, this.config);
+        const selectedPlugins = req.runtime === "opencode" ? selectPlugins(req, this.config) : [];
         let argv = [];
         if (req.runtime === "opencode")
             runtimeArgs(req);
@@ -103,6 +105,9 @@ export class Muster {
                 ...(req.open ? { open: true, terminal } : {}),
                 args: req.args,
                 mcp: selectedMcp.map((s) => s.name),
+                ...(selectedPlugins.length
+                    ? { plugins: selectedPlugins.map((p) => p.name) }
+                    : {}),
                 ...permissions,
             });
             const prepared = await prepareMcp(selectedMcp, mcpEnvironment(selectedMcp, this.env, this.sourceEnv), req.cwd, deadline);
@@ -127,7 +132,7 @@ export class Muster {
             else if (req.runtime === "opencode" && req.kind === "session") {
                 const port = await allocateLoopbackPort();
                 const inheritedMcpNames = await openCodeMcpNames(runtimeEnv, req.cwd, deadline);
-                const launch = await openCodeSessionLaunch(req, this.config, prepared.servers, inheritedMcpNames, port, runtimeEnv, req.cwd, deadline);
+                const launch = await openCodeSessionLaunch(req, this.config, prepared.servers, inheritedMcpNames, port, runtimeEnv, req.cwd, deadline, selectedPlugins, this.sourceEnv);
                 argv = launch.argv;
                 runtimeEnv = { ...runtimeEnv, ...launch.envPatch };
                 entry = await this.registry.update(entry.launchId, {
@@ -137,7 +142,7 @@ export class Muster {
             }
             else if (req.runtime === "opencode" && req.kind === "task") {
                 const inheritedMcpNames = await openCodeMcpNames(runtimeEnv, req.cwd, deadline);
-                const launch = await openCodeTaskLaunch(req, this.config, prepared.servers, inheritedMcpNames, runtimeEnv, req.cwd, deadline);
+                const launch = await openCodeTaskLaunch(req, this.config, prepared.servers, inheritedMcpNames, runtimeEnv, req.cwd, deadline, selectedPlugins, this.sourceEnv);
                 argv = launch.argv;
                 runtimeEnv = { ...runtimeEnv, ...launch.envPatch };
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brutalsystems/muster",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {
@@ -18,7 +18,9 @@
     "pretest:contract": "npm run build",
     "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
     "prepack": "npm run build",
-    "prepublishOnly": "npm test"
+    "prepublishOnly": "npm test",
+    "version": "node scripts/stamp-release-notes.mjs && git add RELEASE_NOTES.md",
+    "postversion": "git push origin HEAD --follow-tags"
   },
   "dependencies": {
     "@iarna/toml": "^2.2.5",