opencode-worker 0.1.3 → 0.1.5

package/README.md

@@ -14,7 +14,7 @@ A set-but-empty `--opencode-bin`/`OPENCODE_WORKER_BIN` fails with `BIN_EMPTY` in
 - `HOME` and `XDG_{CONFIG,DATA,CACHE,STATE}_HOME` point into `<dir>/.opencode-worker/`.
 - Generated config: `model` = `small_model` = requested model, `enabled_providers: ["opencode"]`, `permission.external_directory: "deny"`.
 - Models outside the `opencode` provider are rejected (`PROVIDER_NOT_ALLOWED`); there is no fallback.
-- Timeout (default 180 s): SIGTERM, then SIGKILL after 5 s.
+- Job timeout: default 900 s (15 min). Set it once per install with `OPENCODE_WORKER_TIMEOUT_SEC` (CLI and MCP server), or per job with `--timeout` / `worker_start.timeoutSec`. On expiry: SIGTERM, then SIGKILL after 5 s; an `alarm()` 10 s later also kills the worker if this process itself died.
 - Fixed flags: `run --pure --auto --format json --agent <agent> --model <model> --variant <variant>`.
 
 Defaults: model `opencode/deepseek-v4.1-flash-free`, variant `low`, agent `build`.
@@ -22,8 +22,9 @@ Defaults: model `opencode/deepseek-v4.1-flash-free`, variant `low`, agent `build
 ## CLI
 
 ```sh
-opencode-worker run --dir ./task --timeout 180 "Fix add() in calculator.py and run the tests"
-opencode-worker run --dir ./task -f prompt.md --variant high
+opencode-worker run --dir ./task "Fix add() in calculator.py and run the tests"
+opencode-worker run --dir ./task --timeout 1800 -f prompt.md --variant high
+OPENCODE_WORKER_TIMEOUT_SEC=1800 opencode-worker run --dir ./task "…"
 ```
 
 Exit codes: `0` ok, `1` worker failed (timeout, nonzero exit, error event, model mismatch), `2` usage/setup error.
@@ -48,8 +49,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
 {
@@ -57,19 +59,21 @@ Async by design so long runs never hit client request timeouts.
     "opencode-worker": {
       "command": "npx",
       "args": ["-y", "opencode-worker", "mcp"],
-      "env": { "OPENCODE_WORKER_BIN": "/path/to/opencode" }
+      "env": { "OPENCODE_WORKER_BIN": "/path/to/opencode", "OPENCODE_WORKER_TIMEOUT_SEC": "1800" }
     }
   }
 }
 ```
 
+`OPENCODE_WORKER_TIMEOUT_SEC` is optional (default 900); it is the job limit, independent of the per-call `worker_wait` limit.
+
 ### Client setup
 
 Claude Code (tools must be allowed in `-p` mode; put the prompt right after `-p`, because `--allowedTools` and `--mcp-config` are variadic and swallow trailing arguments):
 
 ```sh
-claude mcp add opencode-worker -e OPENCODE_WORKER_BIN=/path/to/opencode -- npx -y opencode-worker mcp
-claude -p "…" --allowedTools "mcp__opencode-worker__worker_start,mcp__opencode-worker__worker_status,mcp__opencode-worker__worker_result"
+claude mcp add opencode-worker -e OPENCODE_WORKER_BIN=/path/to/opencode -e OPENCODE_WORKER_TIMEOUT_SEC=1800 -- npx -y opencode-worker mcp
+claude -p "…" --allowedTools "mcp__opencode-worker__worker_start,mcp__opencode-worker__worker_wait,mcp__opencode-worker__worker_status,mcp__opencode-worker__worker_result"
 ```
 
 Codex (`~/.codex/config.toml`); without the approval mode, `codex exec` rejects MCP calls under `approval: never`:
@@ -78,7 +82,7 @@ Codex (`~/.codex/config.toml`); without the approval mode, `codex exec` rejects
 [mcp_servers.opencode-worker]
 command = "npx"
 args = ["-y", "opencode-worker", "mcp"]
-env = { OPENCODE_WORKER_BIN = "/path/to/opencode" }
+env = { OPENCODE_WORKER_BIN = "/path/to/opencode", OPENCODE_WORKER_TIMEOUT_SEC = "1800" }
 default_tools_approval_mode = "approve"
 ```
 

package/bin/opencode-worker.mjs

@@ -13,7 +13,7 @@ Options (run):
   --model <id>           default ${DEFAULTS.model} (provider must be one of ${DEFAULTS.providers.join(",")})
   --variant <v>          default ${DEFAULTS.variant}
   --agent <name>         default ${DEFAULTS.agent}
-  --timeout <sec>        default ${DEFAULTS.timeoutSec}
+  --timeout <sec>        default $OPENCODE_WORKER_TIMEOUT_SEC, else ${DEFAULTS.timeoutSec}
   --opencode-bin <path>  default $OPENCODE_WORKER_BIN, then PATH
   -f, --prompt-file <f>  Read prompt from file
 

package/lib/mcp.mjs

@@ -45,24 +45,57 @@ const runSchema = {
     model: { type: "string", description: `default ${DEFAULTS.model}` },
     variant: { type: "string", description: `default ${DEFAULTS.variant}` },
     agent: { type: "string", description: `default ${DEFAULTS.agent}` },
-    timeoutSec: { type: "number", description: `default ${DEFAULTS.timeoutSec}` },
+    timeoutSec: { type: "number", description: `Job time limit in seconds; omit to use the server default ($OPENCODE_WORKER_TIMEOUT_SEC, else ${DEFAULTS.timeoutSec})` },
   },
   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

@@ -7,7 +7,7 @@ export const DEFAULTS = {
   model: "opencode/deepseek-v4.1-flash-free",
   variant: "low",
   agent: "build",
-  timeoutSec: 180,
+  timeoutSec: 900,
   providers: ["opencode"],
 };
 const STATE_DIR = ".opencode-worker";
@@ -132,6 +132,16 @@ function actualModels(stateRoot, sessionID) {
   });
 }
 
+/** Job timeout default: OPENCODE_WORKER_TIMEOUT_SEC if set, else DEFAULTS.timeoutSec. */
+export function defaultTimeoutSec() {
+  const raw = process.env.OPENCODE_WORKER_TIMEOUT_SEC;
+  if (raw === undefined) return DEFAULTS.timeoutSec;
+  const n = Number(raw);
+  if (raw.trim() === "" || !(Number.isFinite(n) && n > 0))
+    throw new WorkerError("BAD_CONFIG", `OPENCODE_WORKER_TIMEOUT_SEC must be a positive number of seconds, got '${raw}'`);
+  return n;
+}
+
 /**
  * Run one OpenCode worker task.
  * @param {{dir:string,prompt:string,model?:string,variant?:string,agent?:string,timeoutSec?:number,opencodeBin?:string,signal?:AbortSignal}} o
@@ -143,7 +153,8 @@ export async function runWorker(o) {
   const model = o.model ?? DEFAULTS.model;
   const variant = o.variant ?? DEFAULTS.variant;
   const agent = o.agent ?? DEFAULTS.agent;
-  const timeoutSec = o.timeoutSec ?? DEFAULTS.timeoutSec;
+  const timeoutSec = o.timeoutSec ?? defaultTimeoutSec();
+  if (!(Number.isFinite(timeoutSec) && timeoutSec > 0)) throw new WorkerError("BAD_ARGS", `timeoutSec must be a positive number, got ${o.timeoutSec}`);
   const provider = model.split("/")[0];
   if (!DEFAULTS.providers.includes(provider))
     throw new WorkerError("PROVIDER_NOT_ALLOWED", `provider '${provider}' not in ${JSON.stringify(DEFAULTS.providers)}`);

package/package.json

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