opencode-worker 0.1.2 → 0.1.4

package/README.md

@@ -5,7 +5,8 @@ Run the official OpenCode CLI as an isolated, time-boxed worker. One package, tw
 - `opencode-worker run` — CLI, prints one JSON result
 - `opencode-worker mcp` — MCP stdio server (async jobs)
 
-No dependencies. Node ≥ 20. OpenCode is **not** bundled: pass `--opencode-bin`, set `OPENCODE_WORKER_BIN`, or have `opencode` on `PATH`.
+No dependencies. Node ≥ 20. OpenCode is **not** bundled: pass `--opencode-bin`, set `OPENCODE_WORKER_BIN`, or have `opencode` on `PATH` (checked in that order).
+A set-but-empty `--opencode-bin`/`OPENCODE_WORKER_BIN` fails with `BIN_EMPTY` instead of falling back to `PATH`; this usually means a shell variable was not expanded in your MCP config.
 
 ## Safety defaults
 
@@ -47,8 +48,9 @@ The worker's report is not proof: verify `diff` and rerun your own checks.
 
 ## MCP
 
-Tools: `worker_start` (returns `jobId` immediately), `worker_status`, `worker_result`, `worker_cancel`.
-Async by design so long runs never hit client request timeouts.
+Tools: `worker_start` (returns `jobId` immediately), `worker_wait`, `worker_status`, `worker_result`, `worker_cancel`.
+
+Recommended flow: `worker_start` → `worker_wait` (repeat while it returns `status: "running"`). `worker_wait` blocks up to `timeoutSec` (default 50 s, max 120 s) and returns the full result once the job finishes, so clients don't burn model turns polling `worker_status`. The 50 s default stays under common 60 s client tool timeouts (e.g. Codex `tool_timeout_sec`).
 
 ```json
 {

package/lib/mcp.mjs

@@ -50,19 +50,52 @@ const runSchema = {
   required: ["dir", "prompt"],
 };
 const idSchema = { type: "object", properties: { jobId: { type: "string" } }, required: ["jobId"] };
+const WAIT_DEFAULT_SEC = 50; // under common 60 s client tool timeouts (e.g. Codex)
+const WAIT_MAX_SEC = 120;
+const waitSchema = {
+  type: "object",
+  properties: {
+    jobId: { type: "string" },
+    timeoutSec: { type: "number", description: `Max seconds to block (default ${WAIT_DEFAULT_SEC}, max ${WAIT_MAX_SEC})` },
+  },
+  required: ["jobId"],
+};
 
 const TOOLS = [
-  { name: "worker_start", description: "Start an isolated OpenCode worker job (free model by default). Returns jobId immediately.", inputSchema: runSchema },
-  { name: "worker_status", description: "Get job status: running | done | failed | cancelled | lost (server died mid-run). Works across server restarts.", inputSchema: idSchema },
-  { name: "worker_result", description: "Get the JSON result (diff, tests text, cost, tokens, actual model) of a finished job. Works across server restarts.", inputSchema: idSchema },
+  { name: "worker_start", description: "Start an isolated OpenCode worker job (free model by default). Returns jobId immediately. Then call worker_wait.", inputSchema: runSchema },
+  { name: "worker_wait", description: "Block until the job finishes or timeoutSec elapses. Finished: returns the full result (same as worker_result). Still running: returns {status: \"running\"}; call worker_wait again. Prefer this over polling worker_status.", inputSchema: waitSchema },
+  { name: "worker_status", description: "Get job status without waiting: running | done | failed | cancelled | lost (server died mid-run). Works across server restarts.", inputSchema: idSchema },
+  { name: "worker_result", description: "Get the JSON result (diff, tool outputs, cost, tokens, actual model) of a finished job. Works across server restarts.", inputSchema: idSchema },
   { name: "worker_cancel", description: "Cancel a running job owned by this server (SIGTERM, then SIGKILL).", inputSchema: idSchema },
 ];
 
+function resultOf(job) {
+  if (job.status === "running") return textResult({ jobId: job.jobId, status: "running" }, true);
+  if (job.status === "lost") return textResult({ ok: false, errors: [{ type: "lost", detail: "server exited before the job finished; inspect <dir>/.opencode-worker/runs" }] }, true);
+  return textResult({ jobId: job.jobId, status: job.status, ...(job.result ?? { ok: false, errors: [job.error] }) }, !job.result?.ok);
+}
+
+async function waitFor(jobId, timeoutSec) {
+  const sec = Math.min(Math.max(Number(timeoutSec) || WAIT_DEFAULT_SEC, 1), WAIT_MAX_SEC);
+  const deadline = Date.now() + sec * 1000;
+  const live = jobs.get(jobId);
+  if (live) await Promise.race([live.done, new Promise((r) => setTimeout(r, sec * 1000).unref())]);
+  // Jobs owned by another server process: watch the persisted record.
+  let job = load(jobId);
+  while (job?.status === "running" && !live && Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 500));
+    job = load(jobId);
+  }
+  if (!job) return textResult({ error: "unknown jobId" }, true);
+  if (job.status === "running") return textResult({ jobId, status: "running", waitedSec: sec, hint: "call worker_wait again" });
+  return resultOf(job);
+}
+
 function textResult(obj, isError = false) {
   return { content: [{ type: "text", text: JSON.stringify(obj, null, 2) }], isError };
 }
 
-function callTool(name, args, opts) {
+async function callTool(name, args, opts) {
   if (name === "worker_start") {
     const record = {
       jobId: randomUUID(), status: "running", serverPid: process.pid,
@@ -81,15 +114,12 @@ function callTool(name, args, opts) {
     jobs.set(record.jobId, { record, controller, done });
     return textResult({ jobId: record.jobId, status: "running" });
   }
+  if (name === "worker_wait") return waitFor(args?.jobId, args?.timeoutSec);
   const job = load(args?.jobId);
   if (!job) return textResult({ error: "unknown jobId" }, true);
   const { jobId, status, startedAt, finishedAt, dir } = job;
   if (name === "worker_status") return textResult({ jobId, status, startedAt, finishedAt, dir });
-  if (name === "worker_result") {
-    if (status === "running") return textResult({ jobId, status }, true);
-    if (status === "lost") return textResult({ ok: false, errors: [{ type: "lost", detail: "server exited before the job finished; inspect <dir>/.opencode-worker/runs" }] }, true);
-    return textResult(job.result ?? { ok: false, errors: [job.error] }, !job.result?.ok);
-  }
+  if (name === "worker_result") return resultOf(job);
   if (name === "worker_cancel") {
     const live = jobs.get(jobId);
     live?.controller.abort();
@@ -121,8 +151,10 @@ export function serveMcp(opts = {}) {
     if (method === "ping") return reply({});
     if (method === "tools/list") return reply({ tools: TOOLS });
     if (method === "tools/call") {
-      const r = callTool(params?.name, params?.arguments ?? {}, opts);
-      return r ? reply(r) : fail(-32602, `unknown tool: ${params?.name}`);
+      return callTool(params?.name, params?.arguments ?? {}, opts).then(
+        (r) => (r ? reply(r) : fail(-32602, `unknown tool: ${params?.name}`)),
+        (e) => fail(-32603, e.message),
+      );
     }
     fail(-32601, `method not found: ${method}`);
   });

package/lib/worker.mjs

@@ -22,14 +22,20 @@ export class WorkerError extends Error {
 }
 
 export function resolveOpencodeBin(explicit) {
-  const candidates = [explicit, process.env.OPENCODE_WORKER_BIN].filter(Boolean);
-  for (const c of candidates) {
-    if (fs.existsSync(c)) return path.resolve(c);
-    throw new WorkerError("BIN_NOT_FOUND", `opencode binary not found: ${c}`);
+  const sources = [
+    ["--opencode-bin", explicit],
+    ["OPENCODE_WORKER_BIN", process.env.OPENCODE_WORKER_BIN],
+  ];
+  for (const [name, value] of sources) {
+    if (value === undefined || value === null) continue;
+    // A set-but-empty value is almost always an unexpanded shell variable; never fall back to PATH silently.
+    if (value.trim() === "") throw new WorkerError("BIN_EMPTY", `${name} is set but empty; give the absolute path to the opencode binary`);
+    if (!fs.existsSync(value)) throw new WorkerError("BIN_NOT_FOUND", `opencode binary not found at ${name}=${value}`);
+    return path.resolve(value);
   }
   const which = spawnSync("/usr/bin/env", ["which", "opencode"], { encoding: "utf8" });
   if (which.status === 0 && which.stdout.trim()) return which.stdout.trim();
-  throw new WorkerError("BIN_NOT_FOUND", "opencode not found (use --opencode-bin or OPENCODE_WORKER_BIN)");
+  throw new WorkerError("BIN_NOT_FOUND", "opencode not found on PATH (set OPENCODE_WORKER_BIN or --opencode-bin)");
 }
 
 function opencodeVersion(bin) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-worker",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Run the official OpenCode CLI as an isolated, time-boxed worker. CLI + MCP stdio server.",
   "repository": {
     "type": "git",