regent-code 3.0.3 → 3.0.4

package/.github/workflows/ci.yml

@@ -36,3 +36,6 @@ jobs:
       - name: Test
         working-directory: .opencode
         run: node --test tests/regent.test.js tests/regent.v2.test.js tests/regent.live-test.js tests/regent.hybrid.v2.6.1.test.js tests/regent.runtime.v2.6.1.test.js
+
+      - name: Test MCP suites (bin contract + installer + server)
+        run: node --test mcp/tests/bin.test.js mcp/tests/install.test.js mcp/tests/mcp.test.js

package/.opencode/INSTALL.md

@@ -6,7 +6,7 @@ If the package is published to npm, both the plugin and the MCP server install
 with a single command against any existing `opencode.json` / `opencode.jsonc`:
 
 ```bash
-npx -y regent-code@3.0.3 install
+npx -y regent-code@3.0.4 install
 ```
 
 Patches the project config (or the global `~/.config/opencode/` config) to add
@@ -19,7 +19,7 @@ Patches the project config (or the global `~/.config/opencode/` config) to add
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugins": ["regent-code@git+https://github.com/nathwn12/regent-code.git#v3.0.3"],
+  "plugins": ["regent-code@git+https://github.com/nathwn12/regent-code.git#v3.0.4"],
 }
 ```
 
@@ -32,7 +32,7 @@ Patches the project config (or the global `~/.config/opencode/` config) to add
 }
 ```
 
-The pinned version is recommended. Use the unpinned branch only when you intentionally want the latest changes. The `v3.0.3` git tag must be pushed to GitHub before the pinned spec resolves.
+The pinned version is recommended. Use the unpinned branch only when you intentionally want the latest changes. The `v3.0.4` git tag must be pushed to GitHub before the pinned spec resolves.
 
 ## Single-source rule (duplicate plugin ID)
 

package/AGENTS.md

@@ -28,6 +28,12 @@ All 108 tests across the five suites must pass before committing.
 - Error paths produce structured JSON, never throw
 - `context.directory` → `process.cwd()` fallback
 
+## Bin targets
+
+- Every `package.json` `bin` file MUST start with `#!/usr/bin/env node`. Without it, npm generates a passthrough `.cmd` shim on Windows that ShellExecutes the file through its extension association (opens an editor) instead of running it under node. Enforced by `mcp/tests/bin.test.js`.
+- The MCP launch contract is the single command `npx -y regent-code` - no absolute paths, no global installs, no hand-written `.cmd`/`.ps1` shims. Enforced by the same test.
+- `npm run prepublishOnly` (wired to `npm run verify`) gates every `npm publish`; CI runs the MCP suites too.
+
 ## Verdict gates
 
 Before committing:

package/README.md

@@ -51,7 +51,7 @@ Add Regent to your OpenCode configuration:
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "plugins": ["regent-code@git+https://github.com/nathwn12/regent-code.git#v3.0.3"],
+  "plugins": ["regent-code@git+https://github.com/nathwn12/regent-code.git#v3.0.4"],
 }
 ```
 
@@ -69,7 +69,7 @@ are read from the persisted transcript when the service stores turns, otherwise
 from the synchronous `session.generate` text; agent catalogs are queried with
 and without an explicit location scope; and the caller-authorization guardrail
 degrades OPEN when the runtime agent API is unresolvable (only recursion from
-known worker sessions stays hard-blocked). The `v3.0.3` git tag must be pushed
+known worker sessions stays hard-blocked). The `v3.0.4` git tag must be pushed
 to GitHub before this pinned spec resolves.
 
 > **Windows dev-machine warning (single-source rule):** when this repository is open as an OpenCode project, its own `.opencode/plugins/regent.js` is auto-loaded as a project plugin. Do NOT also pin regent in `opencode.jsonc` on the same machine — two active sources make host plugin reloads fail with `Duplicate plugin ID: regent`, leaving sessions with a torn tool surface and blocking live skill/plugin edits. Either develop unpinned (project plugin only) or pin the repo file directly: `"plugins": ["file:///Q:/PROJECTS/PERSONAL/regent-code/.opencode/plugins/regent.js"]`. One source of truth, always.
@@ -79,25 +79,23 @@ to GitHub before this pinned spec resolves.
 The fastest way to get **both** the plugin and the MCP server on any machine — no cloning, no manual config edits, no local files:
 
 ```bash
-npx -y regent-code@3.0.3 install
+npx -y regent-code@3.0.4 install
 ```
 
 The installer finds an existing `opencode.json` / `opencode.jsonc` (project config in the current directory first, then the global `~/.config/opencode/` config) and adds both entries:
 
-- **MCP server**: `mcp.servers.regent` → runs `node <absolute path to this package's mcp/cli.js>` directly. No per-connection npx bootstrap: `npx -y regent-code` re-resolves against the npm registry on every OpenCode session start and can re-provision the npx cache, which makes MCP connects flaky (handshake timeouts / connection-closed). Launching the installed file with `node` is deterministic and offline.
-- **Plugin**: `plugins` → `regent-code@3.0.3`
+- **MCP server**: `mcp.servers.regent` → runs `["npx", "-y", "regent-code"]`. That single command spawns the server through the package's `bin` — no absolute paths, no global install, no per-machine shims.
+- **Plugin**: `plugins` → `regent-code@3.0.4`
 
 It is **idempotent and non-destructive** — it only adds or updates regent entries, preserving comments, trailing commas, and every unrelated setting in the file. Re-run it to upgrade the pinned version. Flags: `--global` forces the user config, `--file <path>` targets an exact file, `--help` explains all options. Restart the OpenCode session afterwards — plugin load and MCP connection happen on config load.
 
-> When the installer is invoked from npm's ephemeral npx cache, it prints a warning: the absolute path it wrote can be pruned by npm. Run `npm install -g regent-code@3.0.3` once and re-run the installer so the entry points at the persistent global install.
-
 > On the machine that develops regent-code itself, respect the single-source rule above: do not add a second pin when the repo is open as a project.
 
 ## MCP Server
 
 Since v3.0.0, regent-code ships a second distribution alongside the plugin: a Model Context Protocol (MCP) server that exposes the same six tools (`delegate`, `delegate_many`, `research`, `explore`, `changed-files`, `verify`) plus the Regent command and skill corpus as MCP prompts. It is out-of-process and works from any MCP client (Claude Desktop, Cursor, or OpenCode).
 
-Configure it in OpenCode by adding a local MCP server:
+Configure it in OpenCode by adding a local MCP server — the exact entry the installer writes:
 
 ```jsonc
 {
@@ -106,7 +104,7 @@ Configure it in OpenCode by adding a local MCP server:
     "servers": {
       "regent": {
         "type": "local",
-        "command": ["node", "<REPO>/regent-code/mcp/index.js"],
+        "command": ["npx", "-y", "regent-code"],
         "cwd": "."
       }
     }
@@ -114,32 +112,9 @@ Configure it in OpenCode by adding a local MCP server:
 }
 ```
 
-`<REPO>` is the path to where the repo is cloned; `cwd: "."` makes the server operate on the workspace directory, which is what the `explore` tool and subagent dispatch use as the working directory.
-
-**Other machines / people — no local clone needed.** The package is published to npm. Recommended: install globally once, then let the installer write the entry (see "One-command install" above):
-
-```bash
-npm install -g regent-code@3.0.3
-npx -y regent-code@3.0.3 install --global
-```
-
-Or add the server to `opencode.jsonc` manually with a direct node launch:
-
-```jsonc
-{
-  "$schema": "https://opencode.ai/config.json",
-  "mcp": {
-    "servers": {
-      "regent": {
-        "type": "local",
-        "command": ["node", "<NPM_GLOBAL>/regent-code/mcp/cli.js"]
-      }
-    }
-  }
-}
-```
+`npx -y regent-code` is the single, canonical launch command — it runs on any machine with Node/npm installed, from the npm registry or the npx cache. No cloning, no global install, no absolute path, no shims. `cwd: "."` makes the server operate on the workspace directory, which is what the `explore` tool and subagent dispatch use as the working directory.
 
-`<NPM_GLOBAL>` is the npm global install directory (`npm root -g`). Launching the installed file with `node` means every OpenCode session start spawns the server directly — no per-connection npx registry resolution, so connection is deterministic and works offline. Dispatch tools still require a local OpenCode service to be running (see below), so the server behaves identically to a local install.
+**Other machines / people — no local clone needed.** The package is published to npm. On any machine, either hand-write the entry above or run the one-command installer (see "One-command install" above).
 
 Tool names surface in OpenCode as `<server>_<tool>`, so `regent_delegate`, `regent_delegate_many`, `regent_research`, `regent_explore`, `regent_changed-files`, `regent_verify`. Prompts surface as commands named `<server>:<prompt>`; the prompts are namespaced `command.<name>` (e.g. `/regent:command.orchestrate`, `/regent:command.tdd`) and `skill.<id>` (e.g. `/regent:skill.using-regent`).
 

package/mcp/cli.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 // Regent CLI entry (package `bin`).
 //   no arguments  -> run the MCP server over stdio (that is what a local
 //                    `mcp.servers` entry in OpenCode invokes)

package/mcp/install.js

@@ -8,30 +8,22 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { homedir } from 'node:os';
-import { fileURLToPath } from 'node:url';
 import { parseTree, findNodeAtLocation, getNodeValue, modify, applyEdits } from 'jsonc-parser';
 import { version } from './version.js';
 
 export const PLUGIN_SPEC = `regent-code@${version}`;
 export const SERVER_NAME = 'regent';
 
-// Launch the MCP server straight from the installed package. A per-connection
-// `npx -y regent-code` bootstraps npm resolution against the registry and can
-// re-provision the npx cache on every OpenCode session start, which makes MCP
-// connects flaky (handshake timeouts / connection-closed). `node <path>` is
-// deterministic and offline.
-const CLI_PATH = fileURLToPath(new URL('./cli.js', import.meta.url));
-
+// The MCP server launches with a single portable command. `npx -y regent-code`
+// runs the package's `bin` (mcp/cli.js) from the npm registry or npx cache —
+// no absolute paths, no global install, no per-machine shims. This is the only
+// supported launch path; the installer writes exactly this entry.
 export const SERVER_CONFIG = Object.freeze({
   type: 'local',
-  command: ['node', CLI_PATH],
+  command: ['npx', '-y', 'regent-code'],
   cwd: '.',
 });
 
-// npm's ephemeral npx cache (`_npx/<hash>/...`) can be pruned by npm; warn the
-// user to install globally so the config's absolute path keeps resolving.
-const EPHEMERAL_NPX_CACHE = '_npx';
-
 const CONFIG_NAMES = ['opencode.jsonc', 'opencode.json'];
 
 export class InstallError extends Error {}
@@ -210,13 +202,6 @@ export function install(options = {}) {
   const { text, report } = patchText(base);
   const warnings = [...report.warnings];
 
-  if (CLI_PATH.includes(EPHEMERAL_NPX_CACHE)) {
-    warnings.push(
-      `MCP entry points into npm's ephemeral npx cache (${CLI_PATH}); npm can prune it. ` +
-        `Run "npm install -g ${PLUGIN_SPEC}" once, then re-run "npx -y ${PLUGIN_SPEC} install" ` +
-        `so the config points at the persistent global install.`,
-    );
-  }
   if (text !== existingText) {
     mkdirSync(dirname(target.path), { recursive: true });
     writeFileSync(target.path, text);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "regent-code",
-  "version": "3.0.3",
+  "version": "3.0.4",
   "description": "Agent orchestration for OpenCode. From idea to shipped — zero ceremony. Plugin + MCP server.",
   "type": "module",
   "main": ".opencode/plugins/regent.js",
@@ -30,8 +30,9 @@
     "format": "prettier --write .opencode/plugins/ skills/ mcp/ --no-error-on-unmatched-pattern",
     "format:check": "prettier --check .opencode/plugins/ skills/ mcp/ --no-error-on-unmatched-pattern",
     "typecheck": "tsc --noEmit",
-    "test": "node --test .opencode/tests/regent.test.js .opencode/tests/regent.live-test.js .opencode/tests/regent.v2.test.js .opencode/tests/regent.hybrid.v2.6.1.test.js .opencode/tests/regent.runtime.v2.6.1.test.js mcp/tests/mcp.test.js mcp/tests/install.test.js",
-    "verify": "npm run format:check && npm run lint && npm run typecheck && npm test"
+    "test": "node --test .opencode/tests/regent.test.js .opencode/tests/regent.live-test.js .opencode/tests/regent.v2.test.js .opencode/tests/regent.hybrid.v2.6.1.test.js .opencode/tests/regent.runtime.v2.6.1.test.js mcp/tests/mcp.test.js mcp/tests/install.test.js mcp/tests/bin.test.js",
+    "verify": "npm run format:check && npm run lint && npm run typecheck && npm test",
+    "prepublishOnly": "npm run verify"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",