@jakedowns/progress-tool-opencode-plugin 2.14.0 → 2.14.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -15,6 +15,15 @@ composer. The plugin also installs and registers the MCP server
15
15
  (`@jakedowns/progress-tool-mcp`) automatically, and ships four skills
16
16
  (`progress-tool`, `delegation`, `osc-demo`, `tree-demo`).
17
17
 
18
+ The MCP entrypoint is spawned with a real JavaScript runtime (`node`, then
19
+ `bun`, then `npx -y @jakedowns/progress-tool-mcp`). It deliberately never uses
20
+ `process.execPath`, which is the `opencode` binary in OpenCode Desktop. If no
21
+ runtime is found, auto-registration is skipped with a warning, and the progress
22
+ rules / strict-mode nudges stay off until the `progress` tool is actually
23
+ available to the model. Pin a runtime with
24
+ `{ "options": { "mcpRuntime": "/absolute/path/to/node" } }` if detection picks
25
+ the wrong one.
26
+
18
27
  Prefer manual configuration? Add to `opencode.json`:
19
28
 
20
29
  ```jsonc
@@ -54,6 +63,7 @@ Pass under the plugin entry's `options` in `opencode.json`:
54
63
  | `injectInstructions` | `true` | inject progress/relay rules into every session |
55
64
  | `registerSkills` | `true` | register the bundled skills |
56
65
  | `autoRegisterMcp` | `true` | register `@jakedowns/progress-tool-mcp` automatically |
66
+ | `mcpRuntime` | auto | absolute path to the `node`/`bun` used to spawn the MCP server (auto-detected; set this if detection picks wrong) |
57
67
  | `strictMode` | `"nudge"` | `"nudge"` / `"force"` / `"off"` tool-call monitor |
58
68
  | `wallClockMs` | `120000` | wall-clock nudge threshold (`0` disables) |
59
69
  | `idleReminder` | `true` | turn-end nudge when open tasks remain |
@@ -1,4 +1,4 @@
1
- "use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const r=require("solid-js/web"),B=require("@opencode/plugin/gui"),v=require("solid-js"),Y=require("@opencode/plugin/rpc"),Z="2.14.0",F={version:Z},K=Y.Rpc.define({id:"opencode-progress",methods:{list:{input:{},output:{type:"object",properties:{entries:{type:"object",additionalProperties:!0},updatedAt:{type:"number"}},required:["entries","updatedAt"],additionalProperties:!1}},dismiss:{input:{type:"object",properties:{key:{type:"string"},status:{type:"string"}},required:["key","status"],additionalProperties:!1},output:{type:"object",properties:{ok:{type:"boolean"}},required:["ok"],additionalProperties:!1}}},events:{updated:{schema:{type:"object",properties:{updatedAt:{type:"number"}},required:["updatedAt"],additionalProperties:!1}}}}),N={error:4,running:3,waiting:2,done:1};function E(e){if(e==null)return"";let t=String(e);return t=t.replace(/\r\n?/g,`
1
+ "use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const r=require("solid-js/web"),B=require("@opencode/plugin/gui"),v=require("solid-js"),Y=require("@opencode/plugin/rpc"),Z="2.14.1",F={version:Z},K=Y.Rpc.define({id:"opencode-progress",methods:{list:{input:{},output:{type:"object",properties:{entries:{type:"object",additionalProperties:!0},updatedAt:{type:"number"}},required:["entries","updatedAt"],additionalProperties:!1}},dismiss:{input:{type:"object",properties:{key:{type:"string"},status:{type:"string"}},required:["key","status"],additionalProperties:!1},output:{type:"object",properties:{ok:{type:"boolean"}},required:["ok"],additionalProperties:!1}}},events:{updated:{schema:{type:"object",properties:{updatedAt:{type:"number"}},required:["updatedAt"],additionalProperties:!1}}}}),N={error:4,running:3,waiting:2,done:1};function E(e){if(e==null)return"";let t=String(e);return t=t.replace(/\r\n?/g,`
2
2
  `),t=t.replace(/\\u000[ad]/gi,`
3
3
  `),t=t.replace(/\\r\\n|\\n|\\r/gi,`
4
4
  `),t=t.replace(/<br\s*\/?>/gi,`
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jakedowns/progress-tool-opencode-plugin",
3
- "version": "2.14.0",
3
+ "version": "2.14.1",
4
4
  "description": "OpenCode plugin: native progress indicators for the TUI and desktop GUI, with an out-of-band relay for zero-token long-running command telemetry",
5
5
  "type": "module",
6
6
  "exports": {
@@ -18,7 +18,7 @@
18
18
  "scripts": {
19
19
  "build": "vite build",
20
20
  "dev": "vite build --watch",
21
- "test": "node --test test/dismissal.test.cjs test/instructions.test.cjs test/monitor.test.cjs test/skills.test.cjs test/telemetry.test.cjs",
21
+ "test": "node --test test/dismissal.test.cjs test/instructions.test.cjs test/mcp.test.cjs test/monitor.test.cjs test/skills.test.cjs test/telemetry.test.cjs",
22
22
  "prepublishOnly": "npm test && npm run build"
23
23
  },
24
24
  "dependencies": {
package/src/index.ts CHANGED
@@ -30,6 +30,7 @@ import {
30
30
  type WallClockState,
31
31
  } from "./monitor.js";
32
32
  import { logNudge, nudgeLoggingEnabled, diffStatuses, type StatusSnapshot } from "./telemetry.js";
33
+ import { resolveMcpLaunch } from "./mcp.js";
33
34
 
34
35
  /**
35
36
  * The plugin's own version, read at runtime so a running server part can be
@@ -93,24 +94,61 @@ export default Plugin.define({
93
94
  // single `opencode plugin add` installs everything. A dev checkout that
94
95
  // loads this plugin by path won't resolve the package — skip silently.
95
96
  // Opt out with { options: { autoRegisterMcp: false } }.
97
+ //
98
+ // The interpreter must be a real JS runtime: `process.execPath` is the
99
+ // `opencode` binary under OpenCode Desktop, and handing it the MCP
100
+ // entrypoint makes it chdir into the `.js` file (ENOTDIR). Resolve
101
+ // node/bun/npx instead; see src/mcp.ts and issue #1.
96
102
  if (ctx.options?.autoRegisterMcp !== false) {
97
103
  try {
98
104
  const requireFromHere = createRequire(import.meta.url);
99
105
  const mcpEntry = requireFromHere.resolve("@jakedowns/progress-tool-mcp");
100
- await ctx.mcp.transform((editor) => {
101
- if (!editor.get("progress-server")) {
106
+ const launch = resolveMcpLaunch(mcpEntry, {
107
+ runtime: typeof ctx.options?.mcpRuntime === "string" ? ctx.options.mcpRuntime : undefined,
108
+ });
109
+ if (!launch) {
110
+ console.warn(
111
+ `[opencode-progress] v${pluginVersion} progress-server NOT registered: no node/bun/npx found. ` +
112
+ `Set { "options": { "mcpRuntime": "/absolute/path/to/node" } } or configure ` +
113
+ `mcp.servers.progress-server manually with command ["npx", "-y", "@jakedowns/progress-tool-mcp"]`
114
+ );
115
+ } else {
116
+ let registered = false;
117
+ await ctx.mcp.transform((editor) => {
118
+ if (editor.get("progress-server")) return;
102
119
  editor.set("progress-server", {
103
120
  type: "local",
104
- command: [process.execPath, mcpEntry],
121
+ command: launch.command,
105
122
  });
123
+ registered = true;
124
+ });
125
+ if (registered) {
126
+ console.log(
127
+ `[opencode-progress] v${pluginVersion} registered progress-server (${launch.source}): ${launch.command.join(" ")}`
128
+ );
129
+ } else {
130
+ console.log(
131
+ `[opencode-progress] v${pluginVersion} progress-server already configured — leaving it as is`
132
+ );
106
133
  }
107
- });
108
- console.log(`[opencode-progress] registered MCP server from ${mcpEntry}`);
109
- } catch {
134
+ }
135
+ } catch (error) {
110
136
  // Companion package not installed (local dev) — keep the existing config.
137
+ if ((error as { code?: string } | undefined)?.code !== "MODULE_NOT_FOUND") {
138
+ console.warn(`[opencode-progress] v${pluginVersion} progress-server auto-registration skipped: ${String(error)}`);
139
+ }
111
140
  }
112
141
  }
113
142
 
143
+ // Whether the `progress` tool is actually present in the outgoing request.
144
+ // A config entry is not proof the MCP server connected, and MCP connects
145
+ // asynchronously, so inspect the model's tool set on every context hook.
146
+ // This keeps guidance honest: no "call the progress tool" nudges when the
147
+ // tool is unavailable (issue #1, related UX).
148
+ const progressTool = { available: false, warned: false };
149
+ const hasProgressTool = (tools: Record<string, unknown> | undefined): boolean =>
150
+ Boolean(tools) && Object.keys(tools ?? {}).some((name) => /progress/i.test(name));
151
+
114
152
  let signature = JSON.stringify(readProgressState().entries ?? {});
115
153
 
116
154
  const registration = await ctx.rpc.register(ProgressRpc, {
@@ -138,12 +176,56 @@ export default Plugin.define({
138
176
  // instructions so agents know about the out-of-band relay BEFORE their
139
177
  // first long-running command, not only from the `progress` tool response.
140
178
  // Opt out per project with `{ "options": { "injectInstructions": false } }`.
179
+ //
180
+ // Rules are only injected while the `progress` tool is actually in the
181
+ // model's tool set: if the MCP server failed to start, telling the agent to
182
+ // call a tool that doesn't exist just produces phantom tool calls.
183
+ const strictMode = normalizeStrictMode(ctx.options);
184
+ const staleAfterMs = normalizeStaleAfterMs(ctx.options);
185
+ const strictThreshold =
186
+ typeof ctx.options?.strictThreshold === 'number' && ctx.options.strictThreshold >= 2
187
+ ? ctx.options.strictThreshold
188
+ : 3;
189
+ const verbose = nudgeLoggingEnabled(ctx.options);
190
+
141
191
  let rulesRegistration: Awaited<ReturnType<typeof ctx.session.hook>> | undefined;
142
- if (instructionsEnabled(ctx.options)) {
143
- rulesRegistration = await ctx.session.hook("context", (event) => {
192
+ if (instructionsEnabled(ctx.options) || strictMode !== 'off') {
193
+ const injectRules = instructionsEnabled(ctx.options);
194
+ rulesRegistration = await ctx.session.hook("context", async (event) => {
195
+ let available = hasProgressTool(
196
+ (event as unknown as { tools?: Record<string, unknown> }).tools
197
+ );
198
+
199
+ // Code Mode may expose MCP tools only through the `tools` namespace in
200
+ // the prompt instead of as direct entries. Fall back to the registry,
201
+ // which lists every registered tool regardless of how it is surfaced.
202
+ if (!available) {
203
+ try {
204
+ available = (await ctx.tool.list()).some((tool) => /progress/i.test(tool.id));
205
+ } catch {
206
+ // Registry unavailable — treat the request's tool set as truth.
207
+ }
208
+ }
209
+ progressTool.available = available;
210
+
211
+ if (!progressTool.available) {
212
+ if (!progressTool.warned) {
213
+ progressTool.warned = true;
214
+ console.warn(
215
+ `[opencode-progress] v${pluginVersion} progress tool not available — skipping rule injection and strict nudges until progress-server connects`
216
+ );
217
+ }
218
+ return;
219
+ }
220
+
221
+ if (progressTool.warned) {
222
+ progressTool.warned = false;
223
+ console.log(`[opencode-progress] v${pluginVersion} progress tool available — guidance enabled`);
224
+ }
225
+ if (!injectRules) return;
144
226
  event.system.push({ type: "text", text: PROGRESS_RULES });
145
227
  });
146
- console.log("[opencode-progress] progress rules injected into system instructions");
228
+ if (injectRules) console.log("[opencode-progress] progress rules injected into system instructions");
147
229
  }
148
230
 
149
231
  // Ship the usage + demo skills with the package so installing the plugin
@@ -167,14 +249,7 @@ export default Plugin.define({
167
249
 
168
250
  // Strict mode: watch tool calls and nudge when the agent works silently
169
251
  // (no task entry) or leaves pending tasks' progress unchanged.
170
- const strictMode = normalizeStrictMode(ctx.options);
171
- const staleAfterMs = normalizeStaleAfterMs(ctx.options);
172
- const strictThreshold =
173
- typeof ctx.options?.strictThreshold === 'number' && ctx.options.strictThreshold >= 2
174
- ? ctx.options.strictThreshold
175
- : 3;
176
252
  const monitors = new Map<string, MonitorState>();
177
- const verbose = nudgeLoggingEnabled(ctx.options);
178
253
 
179
254
  // Behaviour telemetry: compare every observed store snapshot against the
180
255
  // previous one so we can measure how agents drive the lifecycle
@@ -207,6 +282,9 @@ export default Plugin.define({
207
282
  if (strictMode !== 'off') {
208
283
  toolHook = await ctx.tool.hook('execute.after', (event) => {
209
284
  try {
285
+ // Guidance is only meaningful when the progress tool exists; the
286
+ // context hook flips this on once the MCP server has connected.
287
+ if (!progressTool.available) return;
210
288
  const isProgressCall = /(^|_)progress$/.test(event.tool);
211
289
  const entries = Object.values(readProgressState().entries ?? {}).filter(
212
290
  (entry) => entry && entry.sessionId === event.sessionID
@@ -293,7 +371,7 @@ export default Plugin.define({
293
371
  console.error('[opencode-progress] strict-mode monitor failed', String(error));
294
372
  }
295
373
  });
296
- console.log(`[opencode-progress] v${pluginVersion} strict mode: ${strictMode} (threshold ${strictThreshold})`);
374
+ console.log(`[opencode-progress] v${pluginVersion} strict mode: ${strictMode} (threshold ${strictThreshold}, gated on progress tool availability)`);
297
375
  if (verbose) {
298
376
  logNudge({ event: "config", strictMode, strictThreshold, wallClockMs: normalizeWallClockMs(ctx.options), idleReminder: ctx.options?.idleReminder !== false, unhinged: ctx.options?.unhinged === true });
299
377
  }
package/src/mcp.ts ADDED
@@ -0,0 +1,169 @@
1
+ /**
2
+ * Companion MCP launch resolution.
3
+ *
4
+ * The plugin auto-registers `@jakedowns/progress-tool-mcp`, but it cannot use
5
+ * `process.execPath` as the interpreter. In OpenCode Desktop (and in
6
+ * bun-compiled CLI builds) `process.execPath` is the `opencode` executable,
7
+ * not a JavaScript runtime. OpenCode then receives the MCP entrypoint as a
8
+ * positional project path, tries to `chdir` into the `.js` file, and the
9
+ * server dies with `ENOTDIR` — so `progress`/`list` never register.
10
+ * See https://github.com/jakedowns/progress-tool/issues/1.
11
+ *
12
+ * Resolution order:
13
+ * 1. an explicit `mcpRuntime` plugin option
14
+ * 2. `process.execPath`, only when it really is node/bun/deno
15
+ * 3. node, then bun — on PATH, then in well-known install locations
16
+ * 4. `npx -y @jakedowns/progress-tool-mcp` as a last resort
17
+ */
18
+
19
+ import { existsSync, readdirSync } from "node:fs";
20
+ import os from "node:os";
21
+ import path from "node:path";
22
+
23
+ /** Published companion package, used by the `npx` fallback. */
24
+ export const MCP_PACKAGE = "@jakedowns/progress-tool-mcp";
25
+
26
+ /** Basenames that really are JavaScript runtimes. */
27
+ const RUNTIME_NAMES = new Set(["node", "nodejs", "bun", "deno"]);
28
+
29
+ /**
30
+ * Everything the resolver touches from the outside world is injectable so the
31
+ * launch order can be tested without the host's real PATH or install layout.
32
+ */
33
+ export interface RuntimeProbe {
34
+ /** Explicit runtime from `options.mcpRuntime`. */
35
+ runtime?: string;
36
+ /** Override for `process.execPath` (the OpenCode binary, usually). */
37
+ execPath?: string;
38
+ env?: Record<string, string | undefined>;
39
+ platform?: string;
40
+ home?: string;
41
+ exists?: (candidate: string) => boolean;
42
+ readdir?: (directory: string) => string[];
43
+ }
44
+
45
+ export interface McpLaunch {
46
+ command: string[];
47
+ /** Human-readable explanation for the startup log. */
48
+ source: string;
49
+ }
50
+
51
+ /** True when `execPath` names a JS runtime rather than an application binary. */
52
+ export function isJsRuntime(execPath: string | undefined | null): boolean {
53
+ if (typeof execPath !== "string" || execPath.length === 0) return false;
54
+ // Split on both separators so the check also recognizes Windows paths when
55
+ // inspected from another platform in tests.
56
+ const base = execPath.split(/[\\/]/).pop()?.toLowerCase().replace(/\.(exe|cmd|bat)$/, "") ?? "";
57
+ return RUNTIME_NAMES.has(base);
58
+ }
59
+
60
+ function executableNames(name: string, platform: string): string[] {
61
+ if (platform !== "win32") return [name];
62
+ return [`${name}.exe`, `${name}.cmd`, `${name}.bat`, name];
63
+ }
64
+
65
+ function lookup(
66
+ name: string,
67
+ directories: readonly string[],
68
+ platform: string,
69
+ exists: (candidate: string) => boolean
70
+ ): string | undefined {
71
+ for (const directory of directories) {
72
+ if (!directory) continue;
73
+ for (const file of executableNames(name, platform)) {
74
+ const candidate = path.join(directory, file);
75
+ if (exists(candidate)) return candidate;
76
+ }
77
+ }
78
+ return undefined;
79
+ }
80
+
81
+ /** Search the process PATH for an executable. */
82
+ export function findExecutable(name: string, probe: RuntimeProbe = {}): string | undefined {
83
+ const env = probe.env ?? process.env;
84
+ const platform = probe.platform ?? process.platform;
85
+ const exists = probe.exists ?? existsSync;
86
+ const separator = platform === "win32" ? ";" : ":";
87
+ const rawPath = env.PATH ?? env.Path ?? env.path ?? "";
88
+ const directories = String(rawPath)
89
+ .split(separator)
90
+ .map((entry) => entry.trim())
91
+ .filter(Boolean);
92
+ return lookup(name, directories, platform, exists);
93
+ }
94
+
95
+ /**
96
+ * Install locations worth checking when PATH is minimal — as it is for GUI
97
+ * apps on macOS, where Desktop's server may inherit only
98
+ * `/usr/bin:/bin:/usr/sbin:/sbin`.
99
+ */
100
+ export function knownInstallDirs(probe: RuntimeProbe = {}): string[] {
101
+ const home = probe.home ?? os.homedir();
102
+ const platform = probe.platform ?? process.platform;
103
+ const readdir =
104
+ probe.readdir ??
105
+ ((directory: string): string[] => {
106
+ try {
107
+ return readdirSync(directory);
108
+ } catch {
109
+ return [];
110
+ }
111
+ });
112
+
113
+ const dirs = [
114
+ path.join(home, ".bun", "bin"),
115
+ path.join(home, ".volta", "bin"),
116
+ path.join(home, ".local", "bin"),
117
+ ];
118
+
119
+ if (platform === "win32") {
120
+ dirs.push(path.join(home, "AppData", "Roaming", "npm"));
121
+ } else {
122
+ dirs.push("/opt/homebrew/bin", "/usr/local/bin", "/usr/bin", "/bin");
123
+ }
124
+
125
+ // nvm keeps one directory per installed Node version.
126
+ const nvmRoot = path.join(home, ".nvm", "versions", "node");
127
+ for (const version of readdir(nvmRoot)) {
128
+ dirs.push(path.join(nvmRoot, version, "bin"));
129
+ }
130
+
131
+ return dirs;
132
+ }
133
+
134
+ /** Find an executable on PATH, then in the well-known install locations. */
135
+ export function findRuntime(name: string, probe: RuntimeProbe = {}): string | undefined {
136
+ const onPath = findExecutable(name, probe);
137
+ if (onPath) return onPath;
138
+ const platform = probe.platform ?? process.platform;
139
+ const exists = probe.exists ?? existsSync;
140
+ return lookup(name, knownInstallDirs(probe), platform, exists);
141
+ }
142
+
143
+ /**
144
+ * Build the command OpenCode should spawn for the companion MCP server.
145
+ * Returns `null` when no runtime and no `npx` can be found — the caller should
146
+ * then skip auto-registration and tell the user how to configure it manually.
147
+ */
148
+ export function resolveMcpLaunch(entry: string, probe: RuntimeProbe = {}): McpLaunch | null {
149
+ const configured = typeof probe.runtime === "string" ? probe.runtime.trim() : "";
150
+ if (configured) return { command: [configured, entry], source: "options.mcpRuntime" };
151
+
152
+ // Prefer the host runtime when the plugin really runs on a JS runtime
153
+ // (plain `node`/`bun` dev runs). Under Desktop this is the `opencode`
154
+ // binary and is deliberately rejected.
155
+ const execPath = probe.execPath ?? process.execPath;
156
+ if (isJsRuntime(execPath)) {
157
+ return { command: [execPath as string, entry], source: "process.execPath" };
158
+ }
159
+
160
+ for (const name of ["node", "bun"]) {
161
+ const found = findRuntime(name, probe);
162
+ if (found) return { command: [found, entry], source: `${name} (PATH or known install dir)` };
163
+ }
164
+
165
+ const npx = findRuntime("npx", probe);
166
+ if (npx) return { command: [npx, "-y", MCP_PACKAGE], source: "npx fallback" };
167
+
168
+ return null;
169
+ }