opencode-usage-coach 0.3.1 → 0.3.3

package/README.md

@@ -52,6 +52,39 @@ cp dist/index.js ~/.config/opencode/plugins/opencode-usage-coach.js
 #   ~/.config/opencode/tui.json: { "plugin": ["/abs/path/dist/tui.js"] }
 ```
 
+## Prompting the harness
+
+How to trigger and use the harness loop for substantive work.
+
+### Triggering
+With the harness agent mode active (`agents/usage-coach-harness.md` installed), ask for substantive work — explicitly or just describe a multi-step task:
+- `"run this through the harness: write CONTRIBUTING.md from git log"`
+- `"harness: add TypeScript strict mode across the repo"`
+- Or just describe the work; the agent triages and enters the loop.
+
+Trivial requests (a one-line fix, a direct answer) are done directly — the loop only runs when generate→grade adds value.
+
+### Independent vs dependent tasks
+The harness picks the loop path based on task dependency:
+- **Independent** (task B doesn't need A's output) → `generate_batch` runs all tasks in **parallel** (faster). Example: `"CONTRIBUTING.md, PR template, issue template"` — three separate docs.
+- **Dependent** (B needs A) → **sequential** `generate` calls. Example: `"1) schema, 2) migration, 3) API"` — each needs the prior.
+
+### Deterministic NEXT directives
+Each tool appends a `[usage-coach NEXT]` line to its return value, telling the agent exactly what to call next:
+- `generate` → NEXT: grade the work
+- `grade` PASS → NEXT: mark completed, proceed
+- `grade` FAIL → NEXT: revise (up to 2x) or mark failed
+
+The agent follows NEXT — you just describe the work, the loop runs itself.
+
+### Quota-aware (automatic)
+You don't manage quota — the tools adapt:
+- **GO** + headroom → strong generator, full parallel
+- **THROTTLE** → auto-switch to `lighterModel`, concurrency capped at 2
+- **STOP** → loop halts
+
+Set `lighterModel` in `harness.config.json` to enable THROTTLE switching.
+
 ## Config
 
 This plugin has **four config surfaces**. Only the first two are required to run.
@@ -133,7 +166,7 @@ Recurring issues and fixes — mostly learned the hard way during development.
 - **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.
+- **Harness not visible?** The TUI shows the **current session's** harness only. A finished harness (`active:false`) is hidden. A harness started in another session won't appear here — switch to that session to see it.
 
 ### 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).
@@ -154,13 +187,19 @@ Recurring issues and fixes — mostly learned the hard way during development.
 - `(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.
 
+### generate / generate_batch returns "Tool execution aborted"
+- **Cause:** opencode imposes a tool execution timeout (~60–120s, not configurable). `runModel` polls the sub-session for up to 10 min; if the generator model takes longer than the tool timeout, opencode aborts the call.
+- **This is a platform limit, not a plugin bug** — there is no config key to extend it.
+- **Mitigation:** split large tasks into smaller ones that finish within the timeout. The NEXT directives + revise loop help — a FAIL triggers a focused revise rather than a monolithic retry.
+- The sub-session keeps running in the background after abort; its file writes are preserved. Only the tool's return value is lost.
+
 ### 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.
+- The TUI shows the **current session's** harness only (per-session isolation) — no cross-session leakage. A harness running in session B does not appear in session A's panel.
 - Harness completion sets `active:false` → hidden from the TUI.
 - Override the state path with `UC_STATE_DIR` (forces global state).
 

package/agents/usage-coach-harness.md

@@ -58,6 +58,7 @@ DEPENDENT tasks (B needs A) → always sequential `generate` calls, regardless o
 3. When all tasks are done → `harness_done()`.
 
 ## Rules
+- **Follow the [usage-coach NEXT] directive each tool returns.** `harness_start`, `generate`, and `grade` all append a `NEXT` line telling you exactly what to call next. This makes the loop deterministic — do not improvise the sequence, follow `NEXT`.
 - In the loop, do NOT do the work yourself — call `generate`/`grade` (they run the configured models). You orchestrate. (Outside the loop, for trivial requests, act directly.)
 - Call `task_update` on every state transition — the sidebar panel reads it for live visibility.
 - Grading criteria come from the user's request, or sensible defaults; ask the user only if it is truly ambiguous and grading matters.

package/dist/index.js

@@ -38,6 +38,18 @@ function writeState(c) {
   } catch {
   }
 }
+function rulesFile() {
+  return join(STATE_DIR, "rules.md");
+}
+function readRules() {
+  try {
+    const f = rulesFile();
+    if (!existsSync(f)) return "";
+    return readFileSync(f, "utf8").trim();
+  } catch {
+    return "";
+  }
+}
 function harnessFile(sessionID) {
   return join(STATE_DIR, sessionID || "_default", "harness.json");
 }
@@ -73,56 +85,28 @@ 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 } });
-    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({
+    log(`runModel(${model}): session ${id} created, sending prompt (${prompt.length} chars)`);
+    const resp = 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);
-      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 elapsed = Math.round((Date.now() - t0) / 1e3);
+    const parts = resp?.data?.parts ?? resp?.parts ?? [];
+    const text = parts.filter((p) => p?.type === "text").map((p) => p?.text ?? "").join("");
     try {
       await client.session.remove?.({ path: { id } });
     } catch {
     }
-    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)`;
+    log(`runModel(${model}): done ${elapsed}s, ${text.length} chars`);
+    return text.trim() || `ERROR: no assistant text in prompt response after ${elapsed}s (parts: ${parts.length}, types: ${parts.map((p) => p?.type).join(",")})`;
   } catch (e) {
     const elapsed = Math.round((Date.now() - t0) / 1e3);
     log(`runModel err (${model}, ${elapsed}s): ${String(e)}`);
@@ -340,7 +324,27 @@ async function UsageCoachPlugin(input) {
           args: { name: tool.schema.string(), total: tool.schema.number() },
           async execute(args, ctx) {
             writeHarness(ctx.sessionID, { name: args.name, total: args.total, current: 0, tasks: [], usage: {}, active: true, startedAt: (/* @__PURE__ */ new Date()).toISOString() });
-            return `Harness '${args.name}' started (${args.total} tasks). Now report each task's status via task_update and run the loop.`;
+            return `Harness '${args.name}' started (${args.total} tasks).
+
+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):
+  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")
+
+PATH B \u2014 DEPENDENT (sequential):
+  for i in 1..${args.total}:
+    1. task_update(i, title, "generating")
+    2. generate({prompt:"Task: <title>. Perform it."})  -> work + NEXT
+    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
+
+Then: harness_done(). Follow the [usage-coach NEXT] directive each tool returns. Do NOT improvise the sequence.`;
           }
         }),
         task_update: tool({
@@ -356,7 +360,7 @@ async function UsageCoachPlugin(input) {
           async execute(args, ctx) {
             const h = readHarness(ctx.sessionID) ?? { name: "batch", total: 0, current: 0, tasks: [], usage: {}, active: true };
             h.tasks = h.tasks.filter((x) => x.id !== args.id);
-            h.tasks.push({ id: args.id, title: args.title, status: args.status, model: args.model ?? "", revisions: args.revisions ?? 0, score: args.score ?? null });
+            h.tasks.push({ id: args.id, title: args.title, status: args.status, model: args.model ?? "", revisions: args.revisions ?? 0, score: args.score ?? null, startedAt: (/* @__PURE__ */ new Date()).toISOString() });
             if (args.id > h.current) h.current = args.id;
             writeHarness(ctx.sessionID, h);
             return `task ${args.id} -> ${args.status}${args.score ? ` (${args.score})` : ""}`;
@@ -390,9 +394,17 @@ async function UsageCoachPlugin(input) {
             }
             const throttle = decision === "THROTTLE" && cfg.lighterModel;
             const model = throttle ? cfg.lighterModel : cfg.generator;
-            const out = await runModel(input.client, model, args.prompt, ctx.directory);
+            const rules = readRules();
+            const prefix = rules ? `Lessons learned from previous failures (apply where relevant):
+${rules}
+
+---
+
+` : "";
+            const out = await runModel(input.client, model, prefix + args.prompt, ctx.directory);
             return out + (throttle ? `
-[usage-coach] quota THROTTLE \u2014 used lighter model ${cfg.lighterModel}` : "");
+[usage-coach] quota THROTTLE \u2014 used lighter model ${cfg.lighterModel}` : "") + `
+[usage-coach NEXT] call task_update(i, title, "grading"), then grade to evaluate this work.`;
           }
         }),
         generate_batch: tool({
@@ -425,25 +437,24 @@ async function UsageCoachPlugin(input) {
           }
         }),
         grade: tool({
-          description: "Run the GRADER model on a prompt. Returns PASS/FAIL on the first line. Falls back to generator if grader quota is out.",
+          description: "Run the GRADER model on a prompt. Returns PASS/FAIL on the first line + a [usage-coach NEXT] directive. Falls back to generator if grader quota is out.",
           args: { prompt: tool.schema.string() },
           async execute(args, ctx) {
             const cfg = readHarnessCfg(ctx.directory);
             const model = cfg.grader ?? cfg.generator;
-            if (!model) return 'FAIL\n(ERROR: no grader/generator model configured. Set "grader" and "generator" in harness.config.json.)';
+            if (!model) return "FAIL\n(ERROR: no grader/generator model configured.)\n[usage-coach NEXT] configure grader in harness.config.json, then retry grade.";
             const out = await runModel(input.client, model, args.prompt, ctx.directory);
-            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}`;
+            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";
+              else verdict = "FAIL";
             }
-            return out;
+            const next = verdict === "PASS" ? `
+[usage-coach NEXT] PASS -> call task_update(i, title, "completed", "PASS"), then proceed to next task (or harness_done if last).` : `
+[usage-coach NEXT] FAIL -> if revisions < 2: task_update(i, title, "revising", revisions+1) + generate({prompt: "Apply feedback:\\n{grade result}\\nTask: {title}"}); else: task_update(i, title, "failed", "FAIL") -> next task.`;
+            return out + "\n" + next;
           }
         })
       }

package/dist/tui.js

@@ -172,8 +172,9 @@ function initializeTui(api, disposeRoot) {
       if (sid) {
         const hf = join(STATE_DIR, sid, "harness.json");
         if (existsSync(hf)) h = JSON.parse(readFileSync(hf, "utf8"));
+      } else {
+        h = readHarness();
       }
-      if (!h || h.active === false) h = readHarness();
     } catch {
       h = null;
     }
@@ -358,6 +359,8 @@ function initializeTui(api, disposeRoot) {
         const lbl = TLABEL[t.status] ?? t.status;
         const rev = t.revisions > 0 && t.status === "revising" ? `(${t.revisions})` : "";
         const mdl = t.model ? ` ${t.model.split("/").pop() ?? t.model}` : "";
+        const elapsed = t.startedAt ? Math.max(0, Math.round((Date.now() - new Date(t.startedAt).getTime()) / 1e3)) : 0;
+        const elapsedStr = t.status === "completed" || t.status === "failed" ? "" : elapsed > 0 ? ` ${elapsed}s` : "";
         nodes.push((() => {
           var _el$59 = _$createElement("text"), _el$60 = _$createTextNode(` \u25CF `), _el$61 = _$createTextNode(` `), _el$62 = _$createTextNode(` `);
           _$insertNode(_el$59, _el$60);
@@ -367,13 +370,14 @@ function initializeTui(api, disposeRoot) {
           _$insert(_el$59, mdl, _el$61);
           _$insert(_el$59, lbl, _el$62);
           _$insert(_el$59, rev, _el$62);
+          _$insert(_el$59, elapsedStr, _el$62);
           _$insert(_el$59, () => short(t.title, 12), null);
           _$effect((_$p) => _$setProp(_el$59, "style", st(sKey), _$p));
           return _el$59;
         })());
         const pv = t.model ? (t.model.split("/")[0] ?? "").split("-")[0] : "";
-        const q = pv && h.quotas?.[pv] ? h.quotas[pv] : null;
-        const pct = q ? q.fiveHour : 0;
+        const provCoach = s?.providers?.find((p) => p.id === pv || pv && p.id.startsWith(pv) || pv && pv.startsWith(p.id));
+        const pct = provCoach ? provCoach.fiveHour : s?.fiveHour ?? 0;
         nodes.push((() => {
           var _el$63 = _$createElement("box"), _el$64 = _$createElement("text"), _el$66 = _$createElement("text"), _el$67 = _$createElement("text"), _el$68 = _$createElement("text"), _el$69 = _$createTextNode(` `), _el$70 = _$createTextNode(`%`);
           _$insertNode(_el$63, _el$64);

package/package.json

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