forge-delegate 1.0.7 → 1.0.9

package/README.md

@@ -27,7 +27,7 @@ so you're picking from actual available models rather than guessing.
 **npx (recommended — works everywhere, no bash needed):**
 
 ```bash
-npx -y forge-delegate setup --model "opencode/mimo-v2.5-free" --targets "claude,codex,opencode"
+npx -y forge-delegate setup --model "opencode/deepseek-v4.1-flash-free" --targets "claude,codex,opencode"
 ```
 
 That's it — npx pulls the latest package and `setup` registers the MCP server with the agents
@@ -56,8 +56,11 @@ Then restart your agent and confirm the server is connected: `/mcp` in Claude Co
 
 ### What you need
 
-- **Node.js ≥ 18** and **opencode** installed (the installer can fetch opencode for you).
-- **Free `opencode/*` models** (e.g. `opencode/mimo-v2.5-free`) need no auth — zero setup.
+- **Node.js ≥ 18** and **opencode v2 or newer** installed (the installer can fetch opencode for you).
+  v2 removed the CLI flags older versions relied on for working directories and variants, and an
+  unknown flag makes `opencode run` print help and exit successfully — so a pre-v2 binary fails
+  silently. The server checks at startup and warns instead.
+- **Free `opencode/*` models** (e.g. `opencode/deepseek-v4.1-flash-free`) need no auth — zero setup.
 - **Any other provider** (deepseek, openai, google, ollama, …) must be logged into **your**
   opencode first — that's a step *you* do in your own opencode, not something forge-delegate
   handles: `opencode auth login <provider>`. forge-delegate reuses your opencode's credentials
@@ -80,10 +83,10 @@ Use the `npx` route — no bash needed (works in cmd/PowerShell). Drop `codex` f
 opencode ships free no-auth models under `opencode/`:
 
 ```bash
-npx -y forge-delegate setup --model "opencode/mimo-v2.5-free" --targets "claude,codex"
+npx -y forge-delegate setup --model "opencode/deepseek-v4.1-flash-free" --targets "claude,codex"
 ```
 
-Other free options: `opencode/hy3-free`, `opencode/nemotron-3.5-lightning-free`. Free tiers are
+Other free options: `opencode/mimo-v2.6-flash-free`, `opencode/nemotron-3.5-lightning-free`. Free tiers are
 rate-limited; switch anytime with `forge-delegate config set --model <m>`.
 
 ## Tools
@@ -152,7 +155,7 @@ Every delegation tool also accepts per-call `model`, `directory`, `agent`, `auto
 
 ## Models
 
-- **opencode provider** — free no-auth models (`opencode/mimo-v2.5-free`, ...) plus
+- **opencode provider** — free no-auth models (`opencode/deepseek-v4.1-flash-free`, ...) plus
   anything you have logged in via `opencode auth login <provider>`.
 - **Direct API from opencode logins** — `provider/model` for OpenAI-compatible providers.
 - **Custom providers** — OpenAI-compatible providers defined in `opencode.json`

package/cli.mjs

@@ -5,7 +5,7 @@ import { join, dirname } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { execSync } from "node:child_process";
-import { loadConfig, saveConfig, configPath } from "./lib.mjs";
+import { loadConfig, saveConfig, configPath, detectOpencode, loadOpencodeAuth } from "./lib.mjs";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -121,8 +121,20 @@ async function setup() {
   console.log("\n=== forge-delegate setup ===\n");
   if (interactive) console.log("Press Enter to accept the suggested [default], or type a value.\n");
 
+  const oc = await detectOpencode();
+  if (!oc.found) {
+    console.log("  ✗ opencode not found on PATH — install it from https://opencode.ai, then re-run setup.\n");
+  } else if (!oc.supported) {
+    console.log(
+      `  ✗ opencode ${oc.version?.raw ?? "(unknown version)"} is too old — forge-delegate requires opencode 2 or newer.\n` +
+        "    Run: opencode upgrade\n"
+    );
+  } else {
+    console.log(`  ✓ opencode ${oc.version.raw}\n`);
+  }
+
   if (!model) {
-    const def = current.defaultModel ?? "opencode/mimo-v2.5-free";
+    const def = current.defaultModel ?? "opencode/deepseek-v4.1-flash-free";
     model = interactive ? ((await ask(`Default model [${def}]: `)) ?? "").trim() || def : def;
   }
   if (!targets) targets = "claude,codex,opencode";
@@ -158,8 +170,7 @@ async function setup() {
   // 3. Check opencode logins
   let authCount = 0;
   try {
-    const authPath = join(homedir(), ".local/share/opencode/auth.json");
-    authCount = Object.keys(JSON.parse(readFileSync(authPath, "utf8"))).length;
+    authCount = Object.keys(await loadOpencodeAuth()).length;
   } catch {}
   if (authCount > 0) {
     console.log(`Found ${authCount} opencode provider login(s) — ready to use.`);
@@ -199,12 +210,14 @@ function configCmd(argv) {
 }
 
 async function status() {
+  const oc = await detectOpencode();
+  console.log(
+    `\nopencode: ${oc.found ? (oc.version?.raw ?? "unknown version") : "not found on PATH"}` +
+      `${oc.found && !oc.supported ? "  (too old — requires v2 or newer)" : ""}`
+  );
   let providers = [];
   try {
-    const authPath = join(homedir(), ".local/share/opencode/auth.json");
-    const { listAuthDirectProviders } = await import("./lib.mjs");
-    const auth = JSON.parse(readFileSync(authPath, "utf8"));
-    providers = Object.keys(auth);
+    providers = Object.keys(await loadOpencodeAuth());
   } catch {}
   console.log(`\nopencode logins: ${providers.length ? providers.join(", ") : "none (run 'opencode auth login <provider>')"}\n`);
   try {

package/docs/index.html

@@ -96,7 +96,7 @@
 
     <div class="field picker">
       <label for="model">Default model (provider/model)</label>
-      <input type="text" id="model" placeholder="type to search, e.g. opencode/mimo-v2.5-free" autocomplete="off">
+      <input type="text" id="model" placeholder="type to search, e.g. opencode/deepseek-v4.1-flash-free" autocomplete="off">
       <div class="filters">
         <select id="provider" title="Provider">
           <option value="">all providers</option>
@@ -330,7 +330,7 @@
     var cmd = command();
     var modelLine = model
       ? 'Use "' + model + '" as the default model unless I say otherwise.'
-      : 'Use a cheap/free default model (e.g. opencode/mimo-v2.5-free) unless I say otherwise.';
+      : 'Use a cheap/free default model (e.g. opencode/deepseek-v4.1-flash-free) unless I say otherwise.';
     return [
       "Install and register the forge-delegate MCP server for me. " + modelLine +
       " Register it with " + targets + ", and use \"" + scope + "\" scope.",

package/lib.mjs

@@ -1,18 +1,82 @@
-import { spawn } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 
 export const OPENCODE_TIMEOUT = Number(process.env.FORGE_OPENCODE_TIMEOUT ?? 900_000);
+
+// forge-delegate targets opencode v2+. v2 removed the `--dir` and `--variant`
+// flags from `run` — and treats an unknown flag as a help request, exiting 0 —
+// so an older binary fails silently. Detecting the version is the only way to
+// tell the user instead of returning empty results.
+export function parseOpencodeVersion(text) {
+  const m = String(text ?? "").match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return null;
+  return { major: +m[1], minor: +m[2], patch: +m[3], raw: m[0] };
+}
+
+export function detectOpencode() {
+  return new Promise((resolve) => {
+    execFile("opencode", ["--version"], { timeout: 10_000 }, (err, stdout, stderr) => {
+      if (err) return resolve({ found: false, version: null, supported: false });
+      const version = parseOpencodeVersion(`${stdout}\n${stderr}`);
+      resolve({ found: true, version, supported: Boolean(version) && version.major >= 2 });
+    });
+  });
+}
+
+// The startup warning on stderr is easy for an MCP client to swallow, and a v1
+// binary does not fail loudly: `run` reads the v2 flags as a help request and
+// exits 0. Check once per process, then refuse to spawn instead of returning
+// "(no output)" and letting it look like the model had nothing to say.
+let opencodeGate;
+function requireOpencodeV2() {
+  opencodeGate ??= detectOpencode();
+  return opencodeGate.then((oc) => {
+    if (!oc.found)
+      throw new Error("opencode not found on PATH — install it from https://opencode.ai");
+    if (!oc.supported)
+      throw new Error(
+        `opencode ${oc.version?.raw ?? "(unknown version)"} is too old — forge-delegate requires opencode 2 or newer ` +
+          `(v2 removed the CLI flags it uses). Run: opencode upgrade`
+      );
+    return oc;
+  });
+}
+
 const CONFIG_DIR = join(homedir(), ".forge-delegate");
 const AUTH_PATH = join(homedir(), ".local/share/opencode/auth.json");
 const OPENCODE_CONFIG_PATH = join(homedir(), ".config/opencode/opencode.json");
 const CATALOG_CACHE = join(CONFIG_DIR, "models-dev.json");
 const CATALOG_TTL = 24 * 3600 * 1000;
-const VARIANTS_CACHE = join(CONFIG_DIR, "variants.json");
 const OLLAMA_BASE = process.env.OLLAMA_URL ?? "http://localhost:11434";
 
-function loadOpencodeAuth() {
+function execFileText(cmd, args, opts = {}) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: 15_000, maxBuffer: 4 * 1024 * 1024, ...opts }, (err, stdout) => {
+      if (err) reject(err);
+      else resolve(stdout);
+    });
+  });
+}
+
+// opencode v2 moved credentials into its own store; auth.json is frozen at
+// whatever v1 last wrote there. Reading the file on v2 therefore hands back
+// stale keys, which surface as 401s that look like the user's fault. Ask v2
+// for its credentials instead, and fall back to the file on v1 (where the
+// `auth export` command does not exist).
+export async function loadOpencodeAuth() {
+  try {
+    const entries = JSON.parse(await execFileText("opencode", ["auth", "export"]));
+    if (Array.isArray(entries)) {
+      const auth = {};
+      for (const e of entries) {
+        if (e?.integrationID && e?.value?.type === "key" && e.value.key)
+          auth[e.integrationID] = { type: "api", key: e.value.key };
+      }
+      return auth;
+    }
+  } catch {}
   try {
     return JSON.parse(readFileSync(AUTH_PATH, "utf8"));
   } catch {
@@ -91,83 +155,43 @@ export function resolveConfig(overrides = {}) {
   };
 }
 
-export function opencodeArgs(model, prompt, { files, sessionId, variant, directory, agent, autoApprove } = {}) {
+// opencode v2 selects the run directory via the child's cwd (there is no `--dir`)
+// and the reasoning variant inline as `provider/model#variant` (there is no
+// `--variant`). Passing the old flags makes `run` print its help and exit 0 —
+// a silent no-op, so do not reintroduce them.
+export function opencodeArgs(model, prompt, { files, sessionId, variant, agent, autoApprove } = {}) {
   const args = ["run", "--format", "json"];
   if (autoApprove) args.push("--auto");
   if (sessionId) args.push("-s", sessionId);
-  if (directory) args.push("--dir", directory);
   if (agent) args.push("--agent", agent);
-  args.push("-m", model);
-  if (variant) args.push("--variant", variant);
+  const ref = variant && !model.includes("#") ? `${model}#${variant}` : model;
+  args.push("-m", ref);
   for (const f of files ?? []) args.push("-f", f);
   args.push(prompt);
   return args;
 }
 
+// Variant (reasoning effort) names come from the model catalog's
+// `reasoning_options`. opencode v2 no longer exposes them over the server API.
 export async function pickVariant(model) {
-  const [provider, ...rest] = model.split("/");
-  const id = rest.join("/");
-  if (!provider || !id || model.startsWith("ollama:")) return undefined;
-  let variants = {};
+  if (model.includes("#") || model.startsWith("ollama:")) return undefined;
+  const slash = model.indexOf("/");
+  if (slash <= 0) return undefined;
+  const provider = model.slice(0, slash);
+  const id = model.slice(slash + 1);
+  let catalog;
   try {
-    variants = await loadVariantMap();
+    catalog = await loadCatalog();
   } catch {
     return undefined;
   }
-  const list = variants[`${provider}/${id}`];
+  const options = catalog?.[provider]?.models?.[id]?.reasoning_options;
+  const effort = Array.isArray(options) ? options.find((o) => o?.type === "effort") : null;
+  const list = effort?.values;
   if (!Array.isArray(list) || list.length === 0) return undefined;
   return list.length === 1 ? list[0] : list[list.length - 2];
 }
 
-// Variant names per provider/model, discovered from `GET /config/providers`
-// on a short-lived local opencode server. Cached on disk for 24h.
-async function loadVariantMap() {
-  try {
-    const cached = JSON.parse(readFileSync(VARIANTS_CACHE, "utf8"));
-    if (Date.now() - cached.fetchedAt < CATALOG_TTL && cached.data) return cached.data;
-  } catch {}
-  const child = spawn("opencode", ["serve", "--port", "0"], { stdio: ["ignore", "pipe", "pipe"] });
-  try {
-    const baseUrl = await new Promise((resolvePromise, rejectPromise) => {
-      let out = "";
-      const timer = setTimeout(() => rejectPromise(new Error("opencode serve timed out")), 20_000);
-      child.stdout.on("data", (d) => {
-        out += d;
-        const m = out.match(/listening on (https?:\/\/\S+)/);
-        if (m) {
-          clearTimeout(timer);
-          resolvePromise(m[1]);
-        }
-      });
-      child.on("error", (e) => {
-        clearTimeout(timer);
-        rejectPromise(e);
-      });
-      child.on("exit", () => {
-        clearTimeout(timer);
-        rejectPromise(new Error("opencode serve exited before listening"));
-      });
-    });
-    const res = await fetch(`${baseUrl.replace(/\/+$/, "")}/config/providers`, { signal: AbortSignal.timeout(15_000) });
-    if (!res.ok) throw new Error(`config/providers ${res.status}`);
-    const body = await res.json();
-    const providers = body.providers ?? body;
-    const map = {};
-    for (const p of Array.isArray(providers) ? providers : Object.values(providers)) {
-      for (const [mid, m] of Object.entries(p.models ?? {})) {
-        if (m?.variants) map[`${p.id}/${mid}`] = Object.keys(m.variants);
-      }
-    }
-    try {
-      mkdirSync(CONFIG_DIR, { recursive: true });
-      writeFileSync(VARIANTS_CACHE, JSON.stringify({ fetchedAt: Date.now(), data: map }));
-    } catch {}
-    return map;
-  } finally {
-    child.kill("SIGKILL");
-  }
-}
-
 export function parseEvents(stdout) {
   let text = "";
   let sessionId = null;
@@ -186,13 +210,19 @@ export function parseEvents(stdout) {
 }
 
 export async function opencodeRun(model, prompt, opts = {}) {
+  await requireOpencodeV2();
   const started = Date.now();
   const variant = opts.variant ?? (await pickVariant(model));
   const timeoutMs = opts.timeoutMs ?? OPENCODE_TIMEOUT;
   const cwd = opts.directory ?? process.cwd();
+  // opencode v2 picks the project from the PWD environment variable, not from the
+  // child's cwd — so a delegation with `directory` set would otherwise run against
+  // the server's directory while looking like it honoured the option.
+  const env = opts.directory ? { ...process.env, PWD: opts.directory } : process.env;
   const stdout = await new Promise((resolvePromise, rejectPromise) => {
     const child = spawn("opencode", opencodeArgs(model, prompt, { ...opts, variant }), {
       cwd,
+      env,
       stdio: ["ignore", "pipe", "pipe"],
     });
     let out = "";
@@ -232,7 +262,7 @@ export async function callDirect(baseUrl, model, messages, apiKey, extraBody = {
 }
 
 export async function listAuthDirectProviders() {
-  const auth = loadOpencodeAuth();
+  const auth = await loadOpencodeAuth();
   let catalog = {};
   try {
     catalog = await loadCatalog();
@@ -302,9 +332,18 @@ export async function runAuthDirect(model, prompt) {
   if (slashIdx <= 0) throw new Error(`expected provider/model format, got '${model}'`);
   const prov = model.slice(0, slashIdx);
   const id = model.slice(slashIdx + 1);
-  const auth = loadOpencodeAuth();
-  if (!auth[prov]?.key)
+  const auth = await loadOpencodeAuth();
+  if (!auth[prov]?.key) {
+    // opencode's own free tier rejects direct HTTP ("can only be used from within
+    // OpenCode"), so these models are reachable only through the CLI.
+    if (prov === "opencode" || prov === "opencode-go")
+      throw new Error(
+        `'${model}' is hosted by opencode, whose free tier only works from inside opencode — ` +
+          `ask_model cannot call it directly. Use the delegate tool instead, or prefix the model ` +
+          `with 'opencode:' to route it through the CLI.`
+      );
     throw new Error(`no opencode login for '${prov}' — run: opencode auth login ${prov}`);
+  }
   const catalog = await loadCatalog();
   const info = catalog[prov];
   if (!info?.api || info.npm !== "@ai-sdk/openai-compatible")

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "forge-delegate",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "MCP server that relays coding work to other AI models (DeepSeek, Gemini, OpenAI, Ollama) so Claude Code saves tokens",
   "type": "module",
   "bin": {
-    "forge-delegate": "./cli.mjs"
+    "forge-delegate": "cli.mjs"
   },
   "scripts": {
     "setup": "node cli.mjs setup",
@@ -20,7 +20,16 @@
     "docs/",
     "README.md"
   ],
-  "keywords": ["mcp", "claude", "claude-code", "ai", "deepseek", "gemini", "ollama", "delegation"],
+  "keywords": [
+    "mcp",
+    "claude",
+    "claude-code",
+    "ai",
+    "deepseek",
+    "gemini",
+    "ollama",
+    "delegation"
+  ],
   "license": "MIT",
   "engines": {
     "node": ">=18"

package/server.mjs

@@ -14,6 +14,7 @@ import {
   opencodeArgs,
   parseEvents,
   pickVariant,
+  detectOpencode,
   listAuthDirectProviders,
   listLocalProviders,
   loadConfig,
@@ -54,6 +55,24 @@ if (SKILL_STATUS && SKILL_STATUS.state !== "ok") {
   );
 }
 
+// Same channel rule. Non-blocking so a slow or missing `opencode` can never delay
+// the MCP handshake; if the binary is absent or pre-v2 the user hears about it
+// instead of getting silent empty delegations later.
+detectOpencode()
+  .then((oc) => {
+    if (!oc.found) {
+      process.stderr.write(
+        "forge-delegate: opencode not found on PATH — delegations will fail. Install: https://opencode.ai\n"
+      );
+    } else if (!oc.supported) {
+      process.stderr.write(
+        `forge-delegate: opencode ${oc.version?.raw ?? "(unknown version)"} is too old — requires opencode 2 or newer ` +
+          `(v2 removed the CLI flags forge-delegate uses). Run: opencode upgrade\n`
+      );
+    }
+  })
+  .catch(() => {});
+
 const INSTRUCTIONS = `forge-delegate hands coding work to cheap external models running as full agents. They read the project and write the code in their own loop, so the work never passes through your context. Spend your context on judgment; delegate the typing.
 
 DELEGATE BY DEFAULT — do not hand-write these yourself:
@@ -111,8 +130,11 @@ async function startBackgroundJob(model, task, opts = {}) {
   const logPath = join(RUNS_DIR, `${id}.log`);
   const out = openSync(logPath, "w");
   const cwd = opts.directory ?? process.cwd();
+  // opencode v2 resolves the project from PWD, not the child's cwd (see lib.mjs).
+  const env = opts.directory ? { ...process.env, PWD: opts.directory } : process.env;
   const child = spawn("opencode", opencodeArgs(model, task, { ...opts, variant }), {
     cwd,
+    env,
     detached: true,
     stdio: ["ignore", out, out],
   });
@@ -147,7 +169,7 @@ server.tool(
       if (local.ollama.length) lines.push(`  ollama: ${local.ollama.slice(0, 12).join(", ")}`);
       else lines.push("  ollama: not running");
       for (const [name, p] of Object.entries(local.config))
-        lines.push(`  ${name} (opencode.json): ${p.models.join(", ") || "(models defined ad hoc)"}`);
+        lines.push(`  ${name} (opencode.json): ${Object.keys(p.models).join(", ") || "(models defined ad hoc)"}`);
 
       lines.push("\n== direct via opencode logins (ask_model, provider/model) ==");
       try {
@@ -192,7 +214,7 @@ server.tool(
   "delegate",
   "USE THIS INSTEAD OF WRITING THE CODE YOURSELF when the task is: tests for code that already exists; a mechanical refactor (rename, signature change, import rewrite, API migration); fixing lint/type/build errors; boilerplate or scaffolding (CRUD endpoints, config, schemas, adapters, fixtures); a port between languages or frameworks; the same edit repeated across 3 or more files; reading a large file/directory to answer one narrow question; or the survey half of an audit (delegate the gathering, keep the verdict — demand a file path behind every claim). Hands the task to another AI model running as a full agent via local opencode: it reads your project, explores, and writes concrete code in its own tool loop — none of which enters your context. Keep architecture, unknown-root-cause debugging, and security-sensitive code for yourself, and always review what comes back. Runs INLINE by default (result returned when done; Claude Code auto-backgrounds calls past 2 minutes). Pass background:true to run detached and get a job id instantly, then poll check_delegation — use that for parallel fan-out or hosts that block on long calls. Pass continue_session (returned by a previous delegation) to keep the same agent session instead of re-exploring. Never paste file contents into task: name the paths and let the agent read them. model/directory/agent/autoApprove default from config — omit them.",
   {
-    model: z.string().optional().describe("provider/model format, e.g. opencode/mimo-v2.5-free (defaults to config defaultModel)"),
+    model: z.string().optional().describe("provider/model format, e.g. opencode/deepseek-v4.1-flash-free (defaults to config defaultModel)"),
     task: z.string(),
     files: z.array(z.string()).optional().describe("specific files to attach (inline mode)"),
     background: z.boolean().optional().describe("run detached and return a job id (default false)"),