opencode-usage-coach 0.13.1 → 0.13.3

package/README.md

@@ -25,32 +25,52 @@ See **[docs/architecture.md](docs/architecture.md)** for the full design.
 
 ## Quick Start
 
+### 3 steps to get running
+
+**Step 1 — Install globally (provides the `usage-coach` CLI):**
+
+```bash
+npm install -g opencode-usage-coach
+```
+
+**Step 2 — Add the server plugin to opencode:**
+
 ```jsonc
-// ~/.config/opencode/opencode.json  — server plugin
+// ~/.config/opencode/opencode.json
 { "plugin": ["opencode-usage-coach"] }
-
-// ~/.config/opencode/tui.json        — sidebar panel (point at built dist/tui.js)
-{ "$schema": "https://opencode.ai/tui.json", "plugin": ["opencode-usage-coach/tui"] }
 ```
 
-Then run setup:
+**Step 3 — Run setup (auto-configures everything else):**
 
 ```bash
-usage-coach setup          # auto-generates harness.config.json + copies agent file
-usage-coach setup --json   # machine-readable output (for scripts/CI)
+usage-coach setup
 ```
 
-This creates `~/.config/opencode-usage-coach/harness.config.json` (edit `generator`/`grader` or use `/coach-config` at runtime) and copies `agents/usage-coach-harness.md` to `~/.config/opencode/agents/`.
+This single command:
+- Creates `~/.config/opencode-usage-coach/harness.config.json` (model config)
+- Copies the harness agent file to `~/.config/opencode/agents/`
+- **Auto-configures `~/.config/opencode/tui.json`** with the correct TUI plugin path
+- Detects whether `codexbar` is installed
 
-If you use `codexbar` for quota sensing:
+Restart opencode — you're done. The sidebar panel appears (toggle with `Alt+H`).
+
+> **Without `npm install -g`:** The server plugin still works (opencode auto-installs it from npm), but `usage-coach setup` and the `usage-coach` CLI won't be available. You'd need to manually create `harness.config.json` and configure `tui.json` yourself.
+
+### Quota sensing (optional but recommended)
+
+The plugin works in **GO-only mode** out of the box (no quota sensing). To enable real-time quota monitoring, install [codexbar](https://github.com/nicepkg/codexbar):
 
 ```bash
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/nicepkg/codexbar/main/install.sh | bash
+
+# Then configure your provider API key:
 printf '%s' "$YOUR_PROVIDER_API_KEY" | codexbar config set-api-key --provider <id> --stdin
 ```
 
-Without codexbar, the plugin runs in GO-only mode (no quota sensing).
+codexbar supports any provider with a usage API (OpenAI, Anthropic, Google, z.ai, etc.). Check `codexbar providers` for the full list.
 
-For local dev without npm: `bun install && bun run build`, then point both configs at the `dist/` files.
+Without codexbar, the plugin simply doesn't sense quota — all other features (harness loop, learning, domain knowledge) work normally.
 
 ## Configuration
 
@@ -89,7 +109,13 @@ See **[docs/architecture.md](docs/architecture.md)** for details on the loop, NE
 
 ## Troubleshooting
 
-Common issues: TUI panel missing (check `tui.json` points at `dist/tui.js`, never install `solid-js` in the config dir), model selection errors (`generator` is required), and tool-abort timeouts (platform limit — split large tasks).
+**opencode crashes on startup after adding the plugin** — Make sure you're on v0.13.1 or later. Earlier versions had a bug where opencode would crash due to named exports. Run `npm install -g opencode-usage-coach@latest`.
+
+**TUI sidebar not showing** — Run `usage-coach setup` again. It auto-detects the TUI path and writes `tui.json`. If you installed via `npm install -g`, the path is `$(npm root -g)/opencode-usage-coach/dist/tui.js`. Never install `solid-js` in the opencode config directory.
+
+**`usage-coach: command not found`** — You need `npm install -g opencode-usage-coach` for the CLI. The server plugin works without it, but setup and status commands require the global install.
+
+**Model selection errors** — `generator` is required in `harness.config.json`. Run `usage-coach setup` to create it, then edit the model or use `/coach-config` at runtime.
 
 See **[docs/troubleshooting.md](docs/troubleshooting.md)** for full diagnoses and fixes.
 

package/dist/cli.js

@@ -345,6 +345,7 @@ function formatDomain(r) {
 }
 var GLOBAL_CONFIG_DIR = join(homedir(), ".config", "opencode-usage-coach");
 var OPENCODE_AGENTS_DIR = join(homedir(), ".config", "opencode", "agents");
+var OPENCODE_TUI_CONFIG = join(homedir(), ".config", "opencode", "tui.json");
 var DEFAULT_HARNESS_CONFIG = {
   generator: "opencode/deepseek-v4-flash-free",
   grader: "opencode/mimo-v2.5-free",
@@ -355,6 +356,42 @@ function resolveAgentSourceFile() {
   const scriptDir = dirname(fileURLToPath(import.meta.url));
   return join(scriptDir, "..", "agents", "usage-coach-harness.md");
 }
+function resolveTuiPath(scriptDir) {
+  const dir = scriptDir ?? dirname(fileURLToPath(import.meta.url));
+  return join(dir, "tui.js");
+}
+function configureTui(tuiPath, tuiConfigPath) {
+  if (!existsSync(tuiPath)) {
+    return { action: "not-found", path: tuiPath };
+  }
+  let config = {};
+  if (existsSync(tuiConfigPath)) {
+    try {
+      config = JSON.parse(readFileSync(tuiConfigPath, "utf8"));
+    } catch {
+      config = {};
+    }
+  }
+  const plugins = Array.isArray(config["plugin"]) ? config["plugin"] : [];
+  if (plugins.includes(tuiPath)) {
+    return { action: "exists", path: tuiConfigPath };
+  }
+  const filtered = plugins.filter(
+    (p) => !p.includes("opencode-usage-coach")
+  );
+  filtered.push(tuiPath);
+  config["plugin"] = filtered;
+  if (!config["$schema"]) {
+    config["$schema"] = "https://opencode.ai/tui.json";
+  }
+  try {
+    mkdirSync(dirname(tuiConfigPath), { recursive: true });
+    writeFileSync(tuiConfigPath, JSON.stringify(config, null, 2) + "\n");
+    return { action: "configured", path: tuiConfigPath };
+  } catch {
+    return { action: "write-error", path: tuiConfigPath };
+  }
+}
 function detectCodexbar() {
   try {
     const r = spawnSync("codexbar", ["--version"], { timeout: 5e3 });
@@ -370,6 +407,7 @@ function doSetup(opts = {}) {
   const configDir = opts.configDir ?? GLOBAL_CONFIG_DIR;
   const agentsDir = opts.agentsDir ?? OPENCODE_AGENTS_DIR;
   const agentSource = opts.agentSourceFile ?? resolveAgentSourceFile();
+  const tuiConfigPath = opts.tuiConfigPath ?? OPENCODE_TUI_CONFIG;
   const configPath = join(configDir, "harness.config.json");
   let configAction;
   if (existsSync(configPath)) {
@@ -394,10 +432,13 @@ function doSetup(opts = {}) {
     copyFileSync(agentSource, agentDestPath);
     agentAction = "copied";
   }
+  const tuiPath = resolveTuiPath(opts.scriptDir);
+  const tuiResult = configureTui(tuiPath, tuiConfigPath);
   return {
     harnessConfig: { action: configAction, path: configPath },
     codexbar,
-    agentFile: { action: agentAction, path: agentDestPath }
+    agentFile: { action: agentAction, path: agentDestPath },
+    tuiConfig: tuiResult
   };
 }
 function formatSetup(r) {
@@ -433,6 +474,20 @@ function formatSetup(r) {
     lines.push(`     Expected: ${r.agentFile.path}`);
   }
   lines.push("");
+  if (r.tuiConfig.action === "configured") {
+    lines.push(`  \u2705 TUI plugin configured`);
+    lines.push(`     ${r.tuiConfig.path}`);
+  } else if (r.tuiConfig.action === "exists") {
+    lines.push(`  \u2705 TUI plugin already configured`);
+    lines.push(`     ${r.tuiConfig.path}`);
+  } else if (r.tuiConfig.action === "not-found") {
+    lines.push(`  \u26A0\uFE0F  TUI plugin (dist/tui.js) not found`);
+    lines.push(`     Run: npm install -g opencode-usage-coach`);
+  } else {
+    lines.push(`  \u26A0\uFE0F  Could not write TUI config`);
+    lines.push(`     Manually add to ${r.tuiConfig.path}`);
+  }
+  lines.push("");
   lines.push("Setup complete. Restart opencode to apply changes.");
   return lines.join("\n");
 }
@@ -551,6 +606,7 @@ if (isDirectRun) {
   main();
 }
 export {
+  configureTui,
   doSetup,
   parseArgs,
   projectStateDir,
@@ -560,5 +616,6 @@ export {
   readRules,
   readStatus,
   resolveAgentSourceFile,
-  resolveStateDir
+  resolveStateDir,
+  resolveTuiPath
 };

package/dist/index.js

@@ -1821,7 +1821,7 @@ async function UsageCoachPlugin(input) {
         const agent = await resolveAgent(input.client, _input.sessionID);
         currentAgent = agent;
         refreshBackground();
-        const harnessTools = ["unknown_scan", "question", "generate", "generate_batch", "grade", "investigate", "verify_diagnosis", "generalize", "harness_start", "task_update", "harness_done", "record_failure", "reverse_interview"];
+        const harnessTools = ["unknown_scan", "question", "generate", "generate_batch", "grade", "grade_batch", "investigate", "verify_diagnosis", "generalize", "harness_start", "task_update", "harness_done", "record_failure", "reverse_interview"];
         if (!harnessTools.includes(_input.tool)) return;
         if (!isHarnessAgent(agent)) {
           throw new Error(`[${PLUGIN_NAME}] '${_input.tool}' is restricted to agent mode ${JSON.stringify(HARNESS_AGENTS)} (current: ${JSON.stringify(agent || "unknown")}). Switch to that agent mode to use it.`);
@@ -1885,13 +1885,16 @@ DETERMINISTIC LOOP \u2014 first classify the tasks:
   INDEPENDENT = task B does NOT need task A's output  ->  use PATH A (parallel, faster)
   DEPENDENT   = task B needs task A's output          ->  use PATH B (sequential)
 
-PATH A \u2014 INDEPENDENT (parallel via generate_batch):
+PATH A \u2014 INDEPENDENT (parallel via generate_batch + grade_batch):
   1. task_update(1..${args.total}, title, "generating")
   2. generate_batch({tasks: [{id:1, prompt:"Task: <title1>. Perform it."}, ...]})  -> all results + NEXT
-  3. for each i: task_update(i, title, "grading") + grade({prompt:"Evaluate... PASS/FAIL first line. Task: <title>"})  -> verdict + NEXT
-  4. for each i: PASS -> task_update(i, title, "completed", "PASS"); FAIL -> revise (up to 2x) or task_update(i, title, "failed", "FAIL")
+  3. task_update(1..${args.total}, title, "grading")
+  4. grade_batch({tasks: [{id:1, prompt:"Evaluate... PASS/FAIL first line. Task: <title1>"}, ...]})  -> all verdicts + per-task NEXT
+  5. for each i: PASS -> task_update(i, title, "completed", "PASS"); FAIL -> revise (up to 2x) or task_update(i, title, "failed", "FAIL")
+  Note: grade_batch runs all grades IN PARALLEL \u2014 much faster than grading one-by-one.
+  After revisions, you can grade_batch the revised tasks together too.
 
-PATH B \u2014 DEPENDENT (sequential):
+PATH B \u2014 DEPENDENT (sequential \u2014 one task at a time):
   Optional: task_update(1..N, title, "pending")  \u2190 pre-register all tasks first
   for i in 1..${args.total}:
     1. task_update(i, title, "generating")
@@ -1899,6 +1902,7 @@ PATH B \u2014 DEPENDENT (sequential):
     3. task_update(i, title, "grading")
     4. grade(...)  -> verdict + NEXT
     5. PASS -> task_update(i, title, "completed", "PASS"); FAIL -> revise (up to 2x) or failed
+  Note: use single grade() here \u2014 tasks are dependent, grading is one at a time.
 
 Then: harness_done(). Follow the [usage-coach NEXT] directive each tool returns. Do NOT improvise the sequence.`;
           }
@@ -2521,6 +2525,89 @@ The next generate call will automatically include the new rule.`;
             return out + "\n" + next;
           }
         }),
+        grade_batch: tool({
+          description: "Run the GRADER model on MULTIPLE tasks IN PARALLEL. Quota-aware: GO = full parallel; THROTTLE = concurrency capped at 2; STOP = refused. Use after generate_batch returns results for all INDEPENDENT tasks \u2014 grade them all at once instead of one-by-one. Each result includes a per-task PASS/FAIL verdict + NEXT directive. Resilient: failed grades are retried sequentially (once).",
+          args: {
+            tasks: tool.schema.array(tool.schema.object({
+              id: tool.schema.number().describe("Task ID (must match the task_update ID)."),
+              prompt: tool.schema.string().describe("The grading prompt for this task (same format as grade()).")
+            })).describe("One entry per task to grade. All run in parallel on GO.")
+          },
+          async execute(args, ctx) {
+            const cfg = readHarnessCfg(ctx.directory);
+            const model = cfg.grader ?? cfg.generator;
+            if (!model) {
+              return 'ERROR: no grader/generator model configured. Set "grader" or "generator" in harness.config.json.';
+            }
+            let decision = "GO";
+            try {
+              decision = current().decision;
+            } catch {
+            }
+            if (decision === "STOP") {
+              return 'ERROR: quota STOP \u2014 halt the harness loop now. Call task_update(current, "halted_quota") and stop.';
+            }
+            const limit = decision === "THROTTLE" ? 2 : args.tasks.length;
+            const gradeOne = async (t) => {
+              const gradeTaskId = findActiveTaskId(ctx.sessionID, "grading");
+              const out = await runModel(
+                input.client,
+                model,
+                t.prompt,
+                ctx.directory,
+                gradeTaskId ? { sessionID: ctx.sessionID, taskId: gradeTaskId } : void 0
+              );
+              let verdict = "FAIL";
+              if (!out.startsWith("ERROR:")) {
+                const f = (out.split("\n").find((l) => l.trim()) ?? "").trim();
+                if (/^pass\b/i.test(f)) verdict = "PASS";
+                else if (/^fail\b/i.test(f)) verdict = "FAIL";
+              }
+              const next = verdict === "PASS" ? `[usage-coach NEXT] task ${t.id}: PASS -> task_update(${t.id}, title, "completed", "PASS"), then proceed.` : `[usage-coach NEXT] task ${t.id}: FAIL -> if revisions < 2: task_update(${t.id}, title, "revising") + generate({prompt:"Apply feedback:\\n${out.slice(0, 500)}\\nTask: {title}"}); else: record_failure + investigate + verify + generalize, then task_update(${t.id}, title, "failed", "FAIL").`;
+              return { id: t.id, result: `[task ${t.id}] ${verdict}
+${out}
+${next}` };
+            };
+            const results = [];
+            const failed = [];
+            for (let i = 0; i < args.tasks.length; i += limit) {
+              const batch = args.tasks.slice(i, i + limit);
+              const settled = await Promise.allSettled(batch.map((t) => gradeOne(t)));
+              for (let j = 0; j < settled.length; j++) {
+                const s = settled[j];
+                const t = batch[j];
+                if (s.status === "fulfilled") {
+                  results.push(s.value.result);
+                } else {
+                  const err = String(s.reason ?? "unknown rejection");
+                  log(`grade_batch task ${t.id} REJECTED: ${err}`);
+                  failed.push({ id: t.id, prompt: t.prompt, error: err });
+                }
+              }
+            }
+            if (failed.length > 0) {
+              log(`grade_batch: retrying ${failed.length} failed grade(s) sequentially`);
+              for (const f of failed) {
+                try {
+                  const r = await gradeOne(f);
+                  results.push(r.result.replace(`[task ${r.id}]`, `[task ${r.id}] (retry)`));
+                } catch (e2) {
+                  const err2 = String(e2 ?? "unknown rejection on retry");
+                  log(`grade_batch task ${f.id} retry ALSO FAILED: ${err2}`);
+                  results.push(`[task ${f.id}] FAIL
+(ERROR: grade failed on both batch and retry: ${err2})
+[usage-coach NEXT] task ${f.id}: grade error \u2014 re-run grade() individually for this task.`);
+                }
+              }
+            }
+            const throttleNote = decision === "THROTTLE" ? `
+[usage-coach] quota THROTTLE \u2014 grader concurrency capped at ${limit}.` : "";
+            const passCount = results.filter((r) => /\[task \d+\] PASS/.test(r)).length;
+            const summary = `
+[usage-coach] Graded ${results.length} task(s): ${passCount} PASS, ${results.length - passCount} FAIL.`;
+            return results.join("\n\n") + summary + throttleNote;
+          }
+        }),
         reverse_interview: tool({
           description: "Reverse interview: identify ambiguities in the task and ask the user one question at a time, highest design-impact first. Call WITHOUT answer to start or get the next question. Call WITH answer to record the user's response and advance. Returns the next question or a completion summary. ALWAYS present the question to the user verbatim \u2014 do NOT answer it yourself.",
           args: {

package/package.json

@@ -1,29 +1,21 @@
 {
   "name": "opencode-usage-coach",
-  "version": "0.13.1",
+  "version": "0.13.3",
   "description": "opencode closed-loop usage coach — quota SENSE -> coaching DECIDE -> loop ACT + TUI integration",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./tui": {
-      "types": "./dist/tui.d.ts",
-      "import": "./dist/tui.js"
-    },
-    "./cli": {
-      "types": "./dist/cli.d.ts",
-      "import": "./dist/cli.js"
-    }
+    ".": "./dist/index.js",
+    "./tui": "./dist/tui.js",
+    "./cli": "./dist/cli.js"
   },
   "bin": {
     "usage-coach": "./dist/cli.js"
   },
   "scripts": {
     "build": "tsup",
+    "prepublishOnly": "npm run lint && npm run typecheck && npm test",
     "typecheck": "tsc --noEmit",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",