opencode-usage-coach 0.2.4 → 0.3.0

package/README.md

@@ -1,9 +1,9 @@
 # opencode-usage-coach
 
 A closed-loop usage coach and harness for [OpenCode](https://opencode.ai). Built for
-flat-rate coding plans (e.g. z.ai / GLM, or any quota-metered provider) where USD cost
-is meaningless, so it tracks **quota windows (5h / weekly / monthly)** and turns them
-into coaching + loop control. Provider-agnostic — configure via `harness.config.json`.
+flat-rate / quota-metered coding plans where USD cost is meaningless, so it tracks
+**quota windows (5h / weekly / monthly)** and turns them into coaching + loop control.
+Provider-agnostic — configure via `harness.config.json`.
 
 Existing plugins only *display* usage. This one **senses quota → coaches → stops/advances
 the loop** — and ships a harness agent mode.
@@ -23,6 +23,10 @@ the loop** — and ships a harness agent mode.
 - Multi-model via plugin tools `generate`/`grade`: run the configured generator/grader model
   (from `harness.config.json`) in a new session on the same server — no second terminal.
 - Reports progress via `task_update` → the sidebar panel shows live task states.
+- **Triggering the harness:** the agent auto-triages — trivial work is done directly,
+  substantive multi-step work enters the generate→grade loop. For reliable triggering,
+  explicitly ask "run this through the harness" or "use the harness for this". The harness
+  tools are only available when the harness agent mode is active (see Install).
 
 ## Requirements
 - opencode (tested on 1.17.13) with a quota-metered provider configured.
@@ -115,6 +119,51 @@ Place in the **work directory**. Each role runs on its model, so per-model quota
 opencode's bundled solid); TUI plugins must be compiled + loaded via `tui.json` file path;
 `codexbar` must be called via `spawn` (the `$` BunShell leaks output to the TUI).
 
+## Troubleshooting
+
+Recurring issues and fixes — mostly learned the hard way during development.
+
+### TUI panel missing or harness not shown
+- **Check `tui.json` points at the `dist/tui.js` file path** — not the `plugins/` directory.
+  ```jsonc
+  // ~/.config/opencode/tui.json
+  { "$schema": "https://opencode.ai/tui.json", "plugin": ["/abs/path/dist/tui.js"] }
+  ```
+- **Do NOT install `solid-js` in the config dir** — conflicts with opencode's bundled solid, causes a crash. Keep it peer + external only.
+- **Export must be `{ tui }`** (an object) — a bare function is misread as a server plugin.
+- **Color prop is `fg`** (not `foreground`): `style={{ fg: theme.current.success }}`.
+- **Call `codexbar` via `spawn`** — the `$` BunShell leaks command output into the TUI.
+- **Harness not visible?** The TUI scans session subdirectories for the most recent `active:true` harness. A finished harness (`active:false`) is hidden.
+
+### LLM model selection (generate/grade)
+- **`generator` is required in `harness.config.json`** — the tools return a clear error if missing (the old z.ai fallback was removed in v0.2.4).
+- Format: `"provider/model"` (e.g. `"opencode/deepseek-v4-flash-free"`, `"opencode/mimo-v2.5-free"` — see `harness.config.example.json`).
+- **Config precedence**: workdir `harness.config.json` > global `~/.config/opencode-usage-coach/harness.config.json`.
+- Omitting `grader` falls back to `generator`. If neither is set, the grade tool returns FAIL + guidance.
+- `provider` (quota source) and `lighterModel` (suggested on throttle) are also configurable in the same file.
+
+### Parallel harness execution (generate_batch)
+- **Only INDEPENDENT tasks should be batched** — dependent tasks (B needs A) require sequential `generate` calls.
+- `generate_batch` runs each task in a separate sub-session on the same server (shared model config).
+- runModel polls the sub-session until `idle`/`completed` (max 10 min). Trace with `UC_DEBUG=1`:
+  ```
+  runModel(<generator>): session xxx created, prompt 142 chars
+  runModel(<generator>): poll 3s status="running"
+  runModel(<generator>): done 48s, 1203 chars
+  ```
+- `(no output)` means the sub-session returned no text. Check `~/.cache/opencode-usage-coach/coach.log` for the runModel trace (requires `UC_DEBUG=1`).
+- **Note**: runModel only terminates on explicit `idle`/`completed` status. An earlier bug broke on `!status` (undefined) immediately — fixed.
+
+### Multi-session (per-session state isolation)
+- Each opencode session has a unique sessionID; harness state is isolated per-session:
+  ```
+  ~/.cache/opencode-usage-coach/projects/<dir-hash>/<sessionID>/harness.json
+  ```
+- Different working directories get separate project state (keyed by path hash).
+- The TUI auto-discovers the most recent `active:true` harness — switching sessions shows that session's harness.
+- Harness completion sets `active:false` → hidden from the TUI.
+- Override the state path with `UC_STATE_DIR` (forces global state).
+
 ## Status
 - ✅ Quota guardian + TUI panel (per-provider coach view, colors, collapsible Alt+H)
 - ✅ Harness: agent mode (triage) with generate/grade model-specific tools (1 terminal, multi-model)

package/agents/usage-coach-harness.md

@@ -34,20 +34,22 @@ Default to the loop only when it genuinely adds value. Do not over-engineer smal
 ## Harness loop (only for substantive work)
 The user's message is the task source. If it has multiple distinct parts, decompose into discrete tasks (N); if it is one unit, N = 1.
 
-**Multi-model, 1 terminal:** the work runs via the plugin tools `generate` and `grade`, which use the configured models (generator/grader from harness.config.json) on the same server — so you get e.g. GLM generation + free mimo grading without a second terminal. Do NOT use the `task` tool for harness work; use `generate`/`grade`.
+**Multi-model, 1 terminal:** the work runs via the plugin tools `generate` and `grade`, which use the configured models (generator/grader from harness.config.json) on the same server — so you get e.g. a paid generator + a free grader without a second terminal. Do NOT use the `task` tool for harness work; use `generate`/`grade`.
 
-**Independent tasks → parallel:** if the decomposed tasks are INDEPENDENT, call multiple `generate` tools in the same turn (parallel sub-sessions). Cap by quota coaching (big-OK → 3-4; throttle → 1-2; STOP → none). DEPENDENT tasks (B needs A) → sequential.
+**Parallel independent tasks:** if the decomposed tasks are INDEPENDENT, prefer `generate_batch` (one call, all results at once) over multiple sequential `generate` calls. Cap by quota coaching (big-OK → 3-4; throttle → 1-2; STOP → none). DEPENDENT tasks (B needs A) → sequential `generate` calls.
 
 1. Call `harness_start(name, N)` to register the run on the panel.
 2. For each task i (1..N):
    a. `task_update(i, title, "generating")`.
-   b. **Generate** — call `generate({ prompt: "Task: {title}. Perform it for real in the current directory (write/edit files)." })`. The generator model does the work and returns a summary.
-   c. `task_update(i, title, "grading")`.
-   d. **Grade** — call `grade({ prompt: "Evaluate the result against the request's intent and general quality. Output PASS or FAIL on the first line, then the reason.\\nRequest: {user request}\\nTask: {title}" })`.
-   e. Parse the verdict:
+   b. **Generate** — call `generate({ prompt: "Task: {title}. Perform it for real in the current directory (write/edit files)." })`. The generator model runs in a sub-session and writes files directly — its return value is a summary, NOT the work itself.
+   c. **Verify the work** — after generate returns, read the files it should have produced (use `read`/`glob`) to confirm the work actually exists and is non-trivial. Do not trust the summary alone.
+   d. `task_update(i, title, "grading")`.
+   e. **Grade** — call `grade({ prompt: "Evaluate the result against the request's intent and general quality. Output PASS or FAIL on the first line, then the reason.\\nRequest: {user request}\\nTask: {title}" })`. The grade tool normalizes the verdict: PASS/FAIL is always on the first line.
+   f. Parse the verdict (first non-empty line):
       - `PASS` → `task_update(i, title, "completed", score:"PASS")` → next.
-      - `FAIL` and revisions < 2 → `task_update(i, title, "revising", revisions:k)` → `generate({ prompt: "Apply the grading feedback and improve:\\n{grade result}\\nTask: {title}" })` → back to (c) re-grade.
+      - `FAIL` and revisions < 2 → `task_update(i, title, "revising", revisions:k)` → `generate({ prompt: "Apply the grading feedback and improve:\\n{grade result}\\nTask: {title}" })` → back to (d) re-grade.
       - `FAIL` and revisions exhausted → `task_update(i, title, "failed", score:"FAIL")` → next.
+   g. **Error handling:** if `generate` returns text starting with `ERROR:` or `[runModel TIMEOUT`, the sub-session failed. Log it via `task_update(i, title, "failed")` and continue to the next task — do not loop forever on a broken task.
 3. When all tasks are done → `harness_done()`.
 
 ## Rules

package/dist/index.js

@@ -25,7 +25,7 @@ function setStateDir(dir) {
 }
 var NOOP_HOOKS = {};
 function log(msg) {
-  if (DEBUG) try {
+  try {
     appendFileSync(LOG_FILE, `${(/* @__PURE__ */ new Date()).toISOString()} ${msg}
 `);
   } catch {
@@ -74,36 +74,59 @@ function readHarnessCfg(dir) {
 }
 async function runModel(client, model, prompt, directory) {
   const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+  const t0 = Date.now();
   try {
     const slash = model.indexOf("/");
     const providerID = slash >= 0 ? model.slice(0, slash) : model;
     const modelID = slash >= 0 ? model.slice(slash + 1) : "";
     const s = await client.session.create({ body: { title: "uc-harness-sub" }, query: { directory } });
-    const id = s?.data?.info?.id;
-    if (!id) return null;
+    log(`runModel(${model}): create resp = ${JSON.stringify(s?.data ?? s).slice(0, 500)}`);
+    const id = s?.data?.info?.id ?? s?.data?.id ?? s?.id;
+    if (!id) return `ERROR: session.create returned no id (response: ${JSON.stringify(s?.data ?? s).slice(0, 200)})`;
+    log(`runModel(${model}): session ${id} created, prompt ${prompt.length} chars`);
     await client.session.prompt({
       path: { id },
       body: { model: { providerID, modelID }, parts: [{ type: "text", text: prompt }] }
     });
+    log(`runModel(${model}): prompt sent to ${id}`);
+    let lastMsgCount = -1;
+    let timedOut = false;
+    let text = "";
     for (let i = 0; i < 600; i++) {
       await sleep(1e3);
-      const st = await client.session.status({ path: { id } });
-      const status = st?.data?.[id]?.status ?? st?.data?.status;
-      if (status === "idle" || status === "completed" || !status) break;
+      try {
+        const msgs = await client.session.messages({ path: { id } });
+        const all = msgs?.data ?? msgs ?? [];
+        if (all.length !== lastMsgCount) {
+          log(`runModel(${model}): poll[${i}] msgs=${all.length}`);
+          lastMsgCount = all.length;
+        }
+        const lastAssistant = all.filter((m) => (m?.info?.role ?? m?.role) === "assistant").pop();
+        const parts = lastAssistant?.parts ?? lastAssistant?.info?.parts ?? [];
+        const t = parts.filter((p) => p?.type === "text").map((p) => p?.text ?? "").join("").trim();
+        if (t) {
+          text = t;
+          log(`runModel(${model}): got assistant text at poll[${i}] (${t.length} chars)`);
+          break;
+        }
+      } catch (e) {
+        log(`runModel(${model}): poll[${i}] messages err: ${String(e).slice(0, 120)}`);
+      }
+      if (i === 599) timedOut = true;
     }
-    const msgs = await client.session.messages({ path: { id } });
-    const all = msgs?.data ?? [];
-    const lastAssistant = all.filter((m) => m?.info?.role === "assistant").pop();
-    const parts = lastAssistant?.parts ?? [];
-    const text = parts.filter((p) => p?.type === "text").map((p) => p?.text ?? "").join("");
+    const elapsed = Math.round((Date.now() - t0) / 1e3);
     try {
       await client.session.remove?.({ path: { id } });
     } catch {
     }
-    return text.trim() || null;
+    log(`runModel(${model}): done ${elapsed}s, ${text.length} chars${timedOut ? " [TIMEOUT]" : ""}`);
+    if (timedOut) return `[runModel TIMEOUT after ${elapsed}s \u2014 no assistant text appeared]
+${text}`;
+    return text || `ERROR: no assistant text after ${elapsed}s (${lastMsgCount} messages seen)`;
   } catch (e) {
-    log(`runModel err (${model}): ${String(e)}`);
-    return null;
+    const elapsed = Math.round((Date.now() - t0) / 1e3);
+    log(`runModel err (${model}, ${elapsed}s): ${String(e)}`);
+    return `ERROR: runModel exception after ${elapsed}s: ${String(e)}`;
   }
 }
 var num = (e, d) => {
@@ -360,7 +383,7 @@ async function UsageCoachPlugin(input) {
             const cfg = readHarnessCfg(ctx.directory);
             if (!cfg.generator) return 'ERROR: no generator model configured. Set "generator" in harness.config.json (see harness.config.example.json).';
             const out = await runModel(input.client, cfg.generator, args.prompt, ctx.directory);
-            return out ?? `(generator ${cfg.generator} produced no text)`;
+            return out;
           }
         }),
         generate_batch: tool({
@@ -371,7 +394,7 @@ async function UsageCoachPlugin(input) {
             if (!cfg.generator) return 'ERROR: no generator model configured. Set "generator" in harness.config.json (see harness.config.example.json).';
             const results = await Promise.all(args.tasks.map(async (t) => {
               const out = await runModel(input.client, cfg.generator, t.prompt, ctx.directory);
-              return `[task ${t.id}] ${out ?? "(no output)"}`;
+              return `[task ${t.id}] ${out}`;
             }));
             return results.join("\n\n");
           }
@@ -382,9 +405,20 @@ async function UsageCoachPlugin(input) {
           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" (and "generator") in harness.config.json (see harness.config.example.json).';
+            if (!model) return 'FAIL\n(ERROR: no grader/generator model configured. Set "grader" and "generator" in harness.config.json.)';
             const out = await runModel(input.client, model, args.prompt, ctx.directory);
-            return out ?? `(grader ${model} produced no text)`;
+            if (out.startsWith("ERROR:")) return `FAIL
+(${out})`;
+            const firstLine = out.split("\n").find((l) => l.trim()) ?? "";
+            const f = firstLine.trim();
+            const isPass = /^pass\b/i.test(f);
+            const isFail = /^fail\b/i.test(f);
+            if (!isPass && !isFail) {
+              return `FAIL
+(grader did not output PASS/FAIL on the first line; defaulting to FAIL to trigger a revise)
+${out}`;
+            }
+            return out;
           }
         })
       }

package/dist/tui.js

@@ -5,7 +5,7 @@ import { effect as _$effect } from "@opentui/solid";
 import { createTextNode as _$createTextNode } from "@opentui/solid";
 import { insertNode as _$insertNode } from "@opentui/solid";
 import { createElement as _$createElement } from "@opentui/solid";
-import { readFileSync, existsSync, writeFileSync, mkdirSync } from "fs";
+import { readFileSync, existsSync, writeFileSync, mkdirSync, readdirSync, statSync } from "fs";
 import { createHash } from "crypto";
 import { homedir } from "os";
 import { join, resolve } from "path";
@@ -29,8 +29,44 @@ function readState() {
 }
 function readHarness() {
   try {
-    if (!existsSync(HARNESS_FILE)) return null;
-    return JSON.parse(readFileSync(HARNESS_FILE, "utf8"));
+    let best = null;
+    let entries = [];
+    try {
+      entries = readdirSync(STATE_DIR);
+    } catch {
+    }
+    for (const d of entries) {
+      const sub = join(STATE_DIR, d);
+      let isDir = false;
+      try {
+        isDir = statSync(sub).isDirectory();
+      } catch {
+      }
+      if (!isDir) continue;
+      const f = join(sub, "harness.json");
+      if (!existsSync(f)) continue;
+      let st;
+      try {
+        st = statSync(f);
+      } catch {
+        continue;
+      }
+      let active = false;
+      try {
+        active = !!JSON.parse(readFileSync(f, "utf8")).active;
+      } catch {
+      }
+      if (!best || active && !best.active || active === best.active && st.mtimeMs > best.mtime) {
+        best = {
+          file: f,
+          mtime: st.mtimeMs,
+          active
+        };
+      }
+    }
+    if (best) return JSON.parse(readFileSync(best.file, "utf8"));
+    if (existsSync(HARNESS_FILE)) return JSON.parse(readFileSync(HARNESS_FILE, "utf8"));
+    return null;
   } catch {
     return null;
   }
@@ -137,6 +173,7 @@ function initializeTui(api, disposeRoot) {
         const hf = join(STATE_DIR, sid, "harness.json");
         if (existsSync(hf)) h = JSON.parse(readFileSync(hf, "utf8"));
       }
+      if (!h || h.active === false) h = readHarness();
     } catch {
       h = null;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-usage-coach",
-  "version": "0.2.4",
+  "version": "0.3.0",
   "description": "opencode closed-loop usage coach \u2014 quota SENSE -> coaching DECIDE -> loop ACT + TUI integration",
   "type": "module",
   "main": "./dist/index.js",