regent-code 3.0.2 → 3.0.3

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.1 install
+npx -y regent-code@3.0.3 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.1"],
+  "plugins": ["regent-code@git+https://github.com/nathwn12/regent-code.git#v3.0.3"],
 }
 ```
 
@@ -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.1` 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.3` git tag must be pushed to GitHub before the pinned spec resolves.
 
 ## Single-source rule (duplicate plugin ID)
 

package/.opencode/package.json

@@ -1,6 +1,6 @@
 {
   "type": "module",
   "dependencies": {
-    "@opencode-ai/plugin": "^0.0.0-beta-18414"
+    "@opencode-ai/plugin": "beta"
   }
 }

package/README.md

@@ -51,26 +51,26 @@ 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.2"],
+  "plugins": ["regent-code@git+https://github.com/nathwn12/regent-code.git#v3.0.3"],
 }
 ```
 
 ### Version compatibility (dynamic, not pinned)
 
-Since v3.0.2 regent-code does **not** pin a specific OpenCode beta. Both the
-plugin and the MCP server depend on `@opencode-ai/client` and
-`@opencode-ai/plugin` through a floating beta range
-(`>=0.0.0-beta-18314 <0.0.0-beta-99999`) that resolves the newest beta on every
-install — matching whatever service version that machine runs, no manual pin
-updates. The dispatch code is *runtime-adaptive* on top: generation results
+Since v3.0.3 regent-code resolves `@opencode-ai/client` and
+`@opencode-ai/plugin` through the OpenCode **`beta` dist-tag** (`"beta"` in
+`package.json`), which always points at the current beta build — the same
+channel the CLI ships on. Every install resolves automatically to the newest
+beta; no version chasing, no manual pin updates. (Avoid `npm install
+pkg@<version>` in this repo: npm silently rewrites dependency ranges in the
+manifest when given explicit versions — use plain `npm install` or `npm
+update`.) The dispatch code is *runtime-adaptive* on top: generation results
 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). If the beta track ever renumbers
-(e.g. `0.1.0`), raise the range's upper bound in `package.json` and
-`.opencode/package.json`.
-The `v3.0.2` git tag must be pushed to GitHub before this pinned spec resolves.
+known worker sessions stays hard-blocked). The `v3.0.3` 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,16 +79,18 @@ The `v3.0.2` git tag must be pushed 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.2 install
+npx -y regent-code@3.0.3 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 `["npx", "-y", "regent-code@3.0.2"]`
-- **Plugin**: `plugins` → `regent-code@3.0.2`
+- **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`
 
 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
@@ -114,7 +116,14 @@ 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, so anyone can add it to their `opencode.jsonc` directly:
+**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
 {
@@ -123,14 +132,14 @@ Configure it in OpenCode by adding a local MCP server:
     "servers": {
       "regent": {
         "type": "local",
-        "command": ["npx", "-y", "regent-code@3.0.2"]
+        "command": ["node", "<NPM_GLOBAL>/regent-code/mcp/cli.js"]
       }
     }
   }
 }
 ```
 
-`npx` downloads the package on first run and starts the server; nothing is pinned to a local path. Dispatch tools still require a local OpenCode service to be running (see below), so the server behaves identically to a local install.
+`<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.
 
 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/index.js

@@ -42,8 +42,7 @@ import {
 } from './shared.js';
 
 import { readPackagePrompts, renderPrompt } from './prompts.js';
-
-const version = '3.0.1';
+import { version } from './version.js';
 
 // ── OpenCode client (lazy singleton) ─────────────────────────
 let clientPromise = null;

package/mcp/install.js

@@ -8,20 +8,30 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { homedir } from 'node:os';
-import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
 import { parseTree, findNodeAtLocation, getNodeValue, modify, applyEdits } from 'jsonc-parser';
-
-const require = createRequire(import.meta.url);
-const { version } = require('../package.json');
+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));
+
 export const SERVER_CONFIG = Object.freeze({
   type: 'local',
-  command: ['npx', '-y', `regent-code@${version}`],
+  command: ['node', CLI_PATH],
   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 {}
@@ -198,7 +208,15 @@ export function install(options = {}) {
   const existingText = existsSync(target.path) ? readFileSync(target.path, 'utf8') : null;
   const base = existingText ?? `{\n}\n`;
   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);
@@ -206,6 +224,7 @@ export function install(options = {}) {
 
   return {
     ...report,
+    ...(warnings.length ? { warnings } : {}),
     path: target.path,
     scope: target.scope,
     created: existingText === null,

package/mcp/version.js

@@ -0,0 +1,9 @@
+// Single dynamic source for the package version: read from the installed
+// package.json at runtime, never hardcoded. Both the installer (plugin/MCP
+// spec pins) and the MCP server (serverInfo) import from here, so a version
+// bump in package.json propagates everywhere without touching code.
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export const version = require('../package.json').version;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "regent-code",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "Agent orchestration for OpenCode. From idea to shipped — zero ceremony. Plugin + MCP server.",
   "type": "module",
   "main": ".opencode/plugins/regent.js",
@@ -15,8 +15,8 @@
   "author": "nathwn12",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.0",
-    "@opencode-ai/client": "^0.0.0-beta-18414",
-    "@opencode-ai/plugin": "^0.0.0-beta-18414",
+    "@opencode-ai/client": "beta",
+    "@opencode-ai/plugin": "beta",
     "jsonc-parser": "3.3.1"
   },
   "repository": {