opencode-worker 0.1.7 → 0.1.9

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"]`.
 - Project config is ignored: `opencode.json`, `.opencode/` agents, plugins and MCP in the task dir are not loaded (`OPENCODE_DISABLE_PROJECT_CONFIG=1`, private `OPENCODE_CONFIG_DIR`). `AGENTS.md` still applies.
-- Tools are default-deny: only `read`, `list`, `glob`, `grep`, `edit` (incl. write/patch), `bash`, `todowrite`, `todoread` are allowed; `external_directory` is denied. No web fetch, no sub-agents.
+- Tools are default-deny and set by `role` (below); `external_directory` is always denied. No web fetch, no sub-agents.
 - Models outside the `opencode` provider are rejected (`PROVIDER_NOT_ALLOWED`); there is no fallback.
 - No job time limit by default: a job runs until it finishes, `worker_cancel`, or the MCP session closes — like a subagent. Opt in to a limit with `OPENCODE_WORKER_TIMEOUT_SEC` (per install) or `--timeout` / `worker_start.timeoutSec` (per job); on expiry: SIGTERM, then SIGKILL after 5 s, plus an `alarm()` 10 s later that fires even if this process died.
 - Cancel and timeout stop the whole process tree: opencode plus every command it spawned (tool shells run in their own process groups, so the tree is walked by parent pid).
@@ -36,6 +36,20 @@ Defaults: model `opencode/deepseek-v4.1-flash-free`, variant `low`, agent `build
 Unknown values (e.g. `medium`, which this model does not define) fail with `BAD_VARIANT` instead of silently using the provider default.
 On short tasks the difference is small: in our runs `low`/`high`/`max` averaged roughly 30/45/70 reasoning tokens and `none` produced 0, with the same answers.
 
+## Roles
+
+`--role` / `worker_start.role`:
+
+| role | allowed tools | dir sharing |
+|---|---|---|
+| `implementer` (default) | read, list, glob, grep, edit (incl. write/patch), bash, todo | exclusive |
+| `tester` | read, list, glob, grep, bash, todo — no edit tool | exclusive |
+| `reviewer` | read, list, glob, grep, todo — no edit, no bash | shared with other reviewers |
+
+`tester` and `reviewer` also get a one-line role brief prepended to the prompt. A tester can still write files through `bash`; this is a tool policy, not a sandbox — check `diff`.
+
+One `implementer`/`tester` job per `dir` at a time; any number of reviewers may share a dir, but not with an exclusive job. A conflicting start fails immediately with `DIR_BUSY` (MCP `worker_start` returns it directly). An orphaned worker keeps holding its dir until `worker_cancel` stops it.
+
 ## CLI
 
 ```sh
@@ -58,7 +72,7 @@ Exit codes: `0` ok, `1` worker failed (timeout, nonzero exit, error event, model
 | `text` | worker's final text |
 | `tools[]` | `{tool, status, input, exit, output, error}` per tool call; `exit` is the bash exit code (else `null`), `output` capped at 4000 chars |
 | `cost`, `tokens` | summed from `step_finish` events |
-| `diff` | `diff -ruN` of `<dir>` before vs after (excludes `.opencode-worker/`) |
+| `diff` | unified diff of `<dir>` before vs after. Excludes `.opencode-worker/` and tool caches (`__pycache__`, `*.pyc`, `.pytest_cache`, `.mypy_cache`, `.ruff_cache`, `.cache`); the worker also runs with `PYTHONDONTWRITEBYTECODE=1`, so test runs don't show up as changes |
 | `errors[]` | `timeout`, `cancelled`, `nonzero_exit`, `event_error`, `model_mismatch`, `diff_failed`, `unparsed_line` |
 | `artifacts` | raw `events.jsonl` and `stderr.txt` under `<dir>/.opencode-worker/runs/<id>/` |
 
@@ -103,6 +117,8 @@ env = { OPENCODE_WORKER_BIN = "/path/to/opencode" }
 default_tools_approval_mode = "approve"
 ```
 
+Codex does not read a project-level `.codex/config.toml`. To enable the worker only when needed, put the same block in a profile file `~/.codex/ocw.config.toml` and start Codex with `codex -p ocw`.
+
 OMP (`.omp/mcp.json` or `~/.omp/agent/mcp.json`): the JSON above with `"type": "stdio"`. Non-interactive: `omp -p --auto-approve "…"`.
 
 Job records are written to `$OPENCODE_WORKER_STATE_DIR` (default `$XDG_STATE_HOME/opencode-worker/jobs`, else `~/.local/state/opencode-worker/jobs`), so `worker_status`/`worker_result` work after a server or client restart.
@@ -113,7 +129,7 @@ Closing stdin or SIGINT/SIGTERM/SIGHUP cancels running jobs and records them as
 - `<dir>/.opencode-worker/` holds state, snapshots and logs per run; delete it when done.
 - The before-snapshot copies the whole directory: use small, task-scoped directories.
 - Parallel jobs are allowed but share the free endpoint and your CPU: with 6 concurrent jobs a ~10 s task took up to ~30 s. Run a few at a time.
-- Two jobs writing the same `dir` at once will overwrite each other's files and snapshots; give each job its own directory.
+- Give each parallel implementer its own `dir` (e.g. a git worktree per task); same-dir starts get `DIR_BUSY`.
 
 ## Releasing
 

package/bin/opencode-worker.mjs

@@ -11,7 +11,8 @@ const USAGE = `Usage:
 Options (run):
   --dir <dir>            Working directory; the worker is confined to it (required)
   --model <id>           default ${DEFAULTS.model} (provider must be one of ${DEFAULTS.providers.join(",")})
-  --variant <v>          default ${DEFAULTS.variant}
+  --variant <v>          reasoning: none | low | high | max (default ${DEFAULTS.variant})
+  --role <role>          implementer (default) | tester | reviewer
   --agent <name>         default ${DEFAULTS.agent}
   --timeout <sec>        optional job time limit (default $OPENCODE_WORKER_TIMEOUT_SEC, else none)
   --opencode-bin <path>  default $OPENCODE_WORKER_BIN, then PATH
@@ -27,7 +28,7 @@ try {
       allowPositionals: true,
       options: {
         dir: { type: "string" }, model: { type: "string" }, variant: { type: "string" },
-        agent: { type: "string" }, timeout: { type: "string" }, "opencode-bin": { type: "string" },
+        agent: { type: "string" }, role: { type: "string" }, timeout: { type: "string" }, "opencode-bin": { type: "string" },
         "prompt-file": { type: "string", short: "f" },
       },
     });
@@ -36,7 +37,7 @@ try {
     const timeoutSec = values.timeout === undefined ? undefined : Number(values.timeout);
     if (timeoutSec !== undefined && !(timeoutSec > 0)) throw new WorkerError("BAD_ARGS", "--timeout must be a positive number");
     const result = await runWorker({
-      dir: values.dir, prompt, model: values.model, variant: values.variant, agent: values.agent,
+      dir: values.dir, prompt, model: values.model, variant: values.variant, agent: values.agent, role: values.role,
       timeoutSec, opencodeBin: values["opencode-bin"],
     });
     process.stdout.write(JSON.stringify(result, null, 2) + "\n");

package/lib/mcp.mjs

@@ -6,7 +6,7 @@ import os from "node:os";
 import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
-import { runWorker, killTree, DEFAULTS } from "./worker.mjs";
+import { runWorker, killTree, alive, ROLES, DEFAULTS } from "./worker.mjs";
 
 const PROTOCOL = "2025-06-18";
 const jobs = new Map(); // live jobs of this server: id -> { record, controller, done }
@@ -23,10 +23,6 @@ function save(record) {
   fs.renameSync(file + ".tmp", file);
 }
 
-function alive(pid) {
-  try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
-}
-
 // The recorded pid is ours only if it is still that opencode binary (guards against pid reuse).
 function isOurWorker(record) {
   if (!record.workerPid || !record.workerBin || !alive(record.workerPid)) return false;
@@ -61,7 +57,12 @@ const runSchema = {
     dir: { type: "string", description: "Absolute working directory; the worker is confined to it" },
     prompt: { type: "string", description: "Task for the OpenCode worker" },
     model: { type: "string", description: `default ${DEFAULTS.model}` },
-    variant: { type: "string", description: `default ${DEFAULTS.variant}` },
+    variant: { type: "string", description: "Reasoning effort: none | low | high | max (model-defined set; default low)" },
+    role: {
+      type: "string",
+      enum: Object.keys(ROLES),
+      description: "implementer (default): edit + bash. tester: bash, no edits. reviewer: read/search only; several reviewers may share a dir. Only one implementer/tester job per dir at a time.",
+    },
     agent: { type: "string", description: `default ${DEFAULTS.agent}` },
     timeoutSec: { type: "number", description: "Optional job time limit in seconds. Default: $OPENCODE_WORKER_TIMEOUT_SEC if set, else no limit (runs until done or worker_cancel)." },
   },
@@ -122,7 +123,9 @@ async function callTool(name, args, opts) {
     };
     const controller = new AbortController();
     save(record);
-    const onSpawn = ({ pid, bin, runDir }) => { Object.assign(record, { workerPid: pid, workerBin: bin, runDir }); save(record); };
+    let spawned;
+    const started = new Promise((r) => { spawned = r; });
+    const onSpawn = ({ pid, bin, runDir }) => { Object.assign(record, { workerPid: pid, workerBin: bin, runDir }); save(record); spawned(); };
     const done = runWorker({ ...args, opencodeBin: opts.opencodeBin, signal: controller.signal, onSpawn }).then(
       (r) => { record.result = r; record.status = r.errors.some((e) => e.type === "cancelled") ? "cancelled" : r.ok ? "done" : "failed"; },
       (e) => { record.error = { type: e.code ?? "SETUP_ERROR", detail: e.message }; record.status = "failed"; },
@@ -132,6 +135,10 @@ async function callTool(name, args, opts) {
       jobs.delete(record.jobId);
     });
     jobs.set(record.jobId, { record, controller, done });
+    // Setup failures (bad variant, DIR_BUSY, missing binary) surface here instead of on the first wait.
+    await Promise.race([started, done]);
+    if (record.status === "failed" && record.error)
+      return textResult({ jobId: record.jobId, status: "failed", ok: false, errors: [record.error] }, true);
     return textResult({ jobId: record.jobId, status: "running" });
   }
   if (name === "worker_wait") return waitFor(args?.jobId, args?.timeoutSec);

package/lib/worker.mjs

@@ -7,6 +7,7 @@ export const DEFAULTS = {
   model: "opencode/deepseek-v4.1-flash-free",
   variant: "low",
   agent: "build",
+  role: "implementer",
   timeoutSec: null, // no job time limit by default; stop via cancel or session close
   providers: ["opencode"],
 };
@@ -59,6 +60,8 @@ function isolatedEnv(stateRoot, configPath) {
     OPENCODE_CONFIG_DIR: path.join(stateRoot, "xdg/config/opencode"),
     OPENCODE_DISABLE_PROJECT_CONFIG: "1",
     TERM: "dumb",
+    // Test runs must not show up as file changes in the diff.
+    PYTHONDONTWRITEBYTECODE: "1",
   };
   for (const k of ["LANG", "LC_ALL", "TMPDIR"]) if (process.env[k]) env[k] = process.env[k];
   for (const k of ["HOME", "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_CACHE_HOME", "XDG_STATE_HOME", "OPENCODE_CONFIG_DIR"])
@@ -94,15 +97,20 @@ function snapshot(dir, dest) {
   }
 }
 
+// Tool caches that commands write as a side effect; never meaningful in a worker diff.
+export const DIFF_EXCLUDES = [STATE_DIR, "__pycache__", "*.pyc", ".pytest_cache", ".mypy_cache", ".ruff_cache", ".cache"];
+
 function unifiedDiff(before, dir) {
-  const r = spawnSync("diff", ["-ruN", `--exclude=${STATE_DIR}`, "before", dir], {
+  const r = spawnSync("diff", ["-ruN", ...DIFF_EXCLUDES.map((p) => `--exclude=${p}`), "before", dir], {
     cwd: path.dirname(before),
     encoding: "utf8",
     maxBuffer: 32 * 1024 * 1024,
   });
   // diff exit: 0 same, 1 different, 2 trouble
   if (r.status === 2) return { diff: null, error: r.stderr.trim() };
-  return { diff: r.stdout.replaceAll(dir + "/", "after/"), error: null };
+  // Drop the per-file "diff -ruN --exclude=…" command lines; ---/+++ headers already name each file.
+  const body = r.stdout.split("\n").filter((l) => !l.startsWith("diff -ruN ")).join("\n");
+  return { diff: body.replaceAll(dir + "/", "after/"), error: null };
 }
 
 function parseEvents(stdout) {
@@ -199,9 +207,52 @@ export function killTree(root, graceMs = 5000) {
   }, graceMs).unref());
 }
 
+export function alive(pid) {
+  if (!pid) return false;
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === "EPERM"; }
+}
+
+const READ_TOOLS = ["read", "list", "glob", "grep", "todowrite", "todoread"];
+/**
+ * Roles = tool allowlist + a one-line brief prepended to the prompt.
+ * `exclusive` roles may change files (tester via bash), so they need the dir to themselves.
+ */
+export const ROLES = {
+  implementer: { tools: ALLOWED_TOOLS, exclusive: true, brief: null },
+  tester: { tools: [...READ_TOOLS, "bash"], exclusive: true, brief: "Role: tester. Run commands to test and verify. Do not modify source files; report what passed and what failed." },
+  reviewer: { tools: READ_TOOLS, exclusive: false, brief: "Role: reviewer. You can only read and search; you cannot edit files or run commands. Report findings with file and line references." },
+};
+
+/**
+ * One exclusive job per dir, or any number of reviewers. A lock is live while its
+ * owner process or its worker is alive, so an orphaned worker still holds the dir.
+ */
+function acquireDirLock(stateRoot, runId, role) {
+  const locksDir = path.join(stateRoot, "locks");
+  fs.mkdirSync(locksDir, { recursive: true });
+  const live = [];
+  for (const name of fs.readdirSync(locksDir)) {
+    const file = path.join(locksDir, name);
+    let lock;
+    try { lock = JSON.parse(fs.readFileSync(file, "utf8")); } catch { continue; }
+    if (alive(lock.pid) || alive(lock.workerPid)) live.push(lock);
+    else fs.rmSync(file, { force: true });
+  }
+  const conflict = ROLES[role].exclusive ? live : live.filter((l) => ROLES[l.role]?.exclusive !== false);
+  if (conflict.length)
+    throw new WorkerError("DIR_BUSY", `dir already has a running ${conflict.map((l) => l.role).join(", ")} job (run ${conflict.map((l) => l.runId).join(", ")}); wait for it, cancel it, or use another dir`);
+  const file = path.join(locksDir, `${runId}.json`);
+  const lock = { runId, role, pid: process.pid, workerPid: null };
+  fs.writeFileSync(file, JSON.stringify(lock));
+  return {
+    setWorker(pid) { lock.workerPid = pid; fs.writeFileSync(file, JSON.stringify(lock)); },
+    release() { fs.rmSync(file, { force: true }); },
+  };
+}
+
 /**
  * Run one OpenCode worker task.
- * @param {{dir:string,prompt:string,model?:string,variant?:string,agent?:string,timeoutSec?:number|null,opencodeBin?:string,signal?:AbortSignal,onSpawn?:(info:{pid:number,bin:string,runDir:string})=>void}} o
+ * @param {{dir:string,prompt:string,role?:"implementer"|"tester"|"reviewer",model?:string,variant?:string,agent?:string,timeoutSec?:number|null,opencodeBin?:string,signal?:AbortSignal,onSpawn?:(info:{pid:number,bin:string,runDir:string})=>void}} o
  */
 export async function runWorker(o) {
   if (!o.dir || !o.prompt) throw new WorkerError("BAD_ARGS", "dir and prompt are required");
@@ -210,6 +261,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 role = o.role ?? DEFAULTS.role;
+  if (!Object.hasOwn(ROLES, role)) throw new WorkerError("BAD_ROLE", `role must be one of ${Object.keys(ROLES).join(", ")}, got '${role}'`);
   const timeoutSec = o.timeoutSec ?? defaultTimeoutSec();
   if (timeoutSec !== null && !(Number.isFinite(timeoutSec) && timeoutSec > 0))
     throw new WorkerError("BAD_ARGS", `timeoutSec must be a positive number, got ${o.timeoutSec}`);
@@ -220,13 +273,13 @@ export async function runWorker(o) {
   const bin = resolveOpencodeBin(o.opencodeBin);
   const version = opencodeVersion(bin);
 
-  const runId = new Date().toISOString().replace(/[:.]/g, "-");
+  const runId = new Date().toISOString().replace(/[:.]/g, "-") + "-" + Math.random().toString(36).slice(2, 6);
   const stateRoot = path.join(dir, STATE_DIR);
   const runDir = path.join(stateRoot, "runs", runId);
   fs.mkdirSync(runDir, { recursive: true });
-  const configPath = path.join(stateRoot, "opencode.json");
+  const configPath = path.join(runDir, "opencode.json"); // per run: concurrent reviewers may differ in variant
   const modelId = model.split("/").slice(1).join("/");
-  const permission = Object.fromEntries([["*", "deny"], ...ALLOWED_TOOLS.map((t) => [t, "allow"]), ["external_directory", "deny"]]);
+  const permission = Object.fromEntries([["*", "deny"], ...ROLES[role].tools.map((t) => [t, "allow"]), ["external_directory", "deny"]]);
   const config = {
     $schema: "https://opencode.ai/config.json",
     model,
@@ -241,10 +294,21 @@ export async function runWorker(o) {
   const variants = modelVariants(bin, env, model);
   if (!variants.includes(variant))
     throw new WorkerError("BAD_VARIANT", `variant '${variant}' is not defined for ${model}; available: ${variants.join(", ")}`);
+  const lock = acquireDirLock(stateRoot, runId, role);
+  try {
+    return await collect({ o, dir, stateRoot, runDir, role, agent, model, modelId, provider, variant, timeoutSec, env, bin, version, lock });
+  } finally {
+    lock.release();
+  }
+}
+
+/** Snapshot, spawn opencode, gather events and diff. Runs while the dir lock is held. */
+async function collect({ o, dir, stateRoot, runDir, role, agent, model, modelId, provider, variant, timeoutSec, env, bin, version, lock }) {
   const before = path.join(runDir, "before");
   snapshot(dir, before);
 
-  const args = ["run", "--pure", "--auto", "--format", "json", "--agent", agent, "--model", model, "--variant", variant, o.prompt];
+  const prompt = ROLES[role].brief ? `${ROLES[role].brief}\n\n${o.prompt}` : o.prompt;
+  const args = ["run", "--pure", "--auto", "--format", "json", "--agent", agent, "--model", model, "--variant", variant, prompt];
   const started = Date.now();
   const eventsPath = path.join(runDir, "events.jsonl");
   const stderrPath = path.join(runDir, "stderr.txt");
@@ -259,7 +323,10 @@ export async function runWorker(o) {
     // Streamed to disk so a run stays inspectable even if this process dies mid-run.
     child.stdout.on("data", (d) => { stdout += d; fs.appendFileSync(eventsPath, d); });
     child.stderr.on("data", (d) => { stderr += d; fs.appendFileSync(stderrPath, d); });
-    if (child.pid) o.onSpawn?.({ pid: child.pid, bin, runDir });
+    if (child.pid) {
+      lock.setWorker(child.pid);
+      o.onSpawn?.({ pid: child.pid, bin, runDir });
+    }
     const kill = () => killTree(child.pid);
     const timer = timeoutSec === null ? null : setTimeout(() => { timedOut = true; kill(); }, timeoutSec * 1000);
     o.signal?.addEventListener("abort", () => { cancelled = true; kill(); }, { once: true });
@@ -286,7 +353,7 @@ export async function runWorker(o) {
     ok: exit === 0 && errors.length === 0,
     exit, signal, durationSec,
     opencode: { bin, version },
-    requested: { model, variant, agent, timeoutSec },
+    requested: { model, variant, agent, role, timeoutSec },
     actual,
     sessionID: ev.sessionID,
     text: ev.text,

package/package.json

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