opencode-usage-coach 0.3.0 → 0.3.2

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.

package/agents/usage-coach-harness.md

@@ -36,7 +36,12 @@ The user's message is the task source. If it has multiple distinct parts, decomp
 
 **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`.
 
-**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.
+**Quota-aware loop strategy (the tools handle this):** the quota coaching injected into your system prompt drives loop strategy. You do NOT pick the model — `generate`/`generate_batch` auto-switch to a lighter model on THROTTLE (if `lighterModel` is configured) and refuse on STOP. You pick the **task size and parallelism**:
+- **GO + headroom** → big tasks OK, use `generate_batch` for independent tasks (full parallel).
+- **THROTTLE** → small tasks only, sequential or limited parallelism. Tools cap concurrency at 2 and use a lighter model automatically.
+- **STOP** → finish the in-progress task, then halt. `generate_batch` returns an error on STOP — call `task_update(current, "halted_quota")` and stop.
+
+DEPENDENT tasks (B needs A) → always sequential `generate` calls, regardless of quota.
 
 1. Call `harness_start(name, N)` to register the run on the panel.
 2. For each task i (1..N):
@@ -53,6 +58,7 @@ The user's message is the task source. If it has multiple distinct parts, decomp
 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

@@ -340,7 +340,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({
@@ -375,50 +395,75 @@ async function UsageCoachPlugin(input) {
             return "Harness complete.";
           }
         }),
-        // Per-role model execution (config-driven, same server, no deadlock).
+        // Per-role model execution (config-driven, quota-aware, same server, no deadlock).
+        // P1: quota decision drives model selection + concurrency.
         generate: tool({
-          description: "Run the GENERATOR model on a prompt. The generator can use tools (write/edit files). Returns the model's text response.",
+          description: "Run the GENERATOR model on a prompt. Quota-aware: on THROTTLE, auto-switches to lighterModel if configured. Returns the model's text response.",
           args: { prompt: tool.schema.string() },
           async execute(args, ctx) {
             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;
+            let decision = "GO";
+            try {
+              decision = current().decision;
+            } catch {
+            }
+            const throttle = decision === "THROTTLE" && cfg.lighterModel;
+            const model = throttle ? cfg.lighterModel : cfg.generator;
+            const out = await runModel(input.client, model, args.prompt, ctx.directory);
+            return out + (throttle ? `
+[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({
-          description: "Run the GENERATOR model on MULTIPLE tasks in PARALLEL. Pass an array of {id, prompt}. Returns all results at once. Use for INDEPENDENT tasks (much faster than sequential generate calls).",
+          description: "Run the GENERATOR model on MULTIPLE tasks. Quota-aware: GO = full parallel; THROTTLE = lighter model + concurrency capped at 2; STOP = refused. Use for INDEPENDENT tasks.",
           args: { tasks: tool.schema.array(tool.schema.object({ id: tool.schema.number(), prompt: tool.schema.string() })) },
           async execute(args, ctx) {
             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 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}`;
-            }));
-            return results.join("\n\n");
+            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 throttle = decision === "THROTTLE" && cfg.lighterModel;
+            const model = throttle ? cfg.lighterModel : cfg.generator;
+            const limit = decision === "THROTTLE" ? 2 : args.tasks.length;
+            const results = [];
+            for (let i = 0; i < args.tasks.length; i += limit) {
+              const batch = args.tasks.slice(i, i + limit);
+              const out = await Promise.all(batch.map(async (t) => {
+                const r = await runModel(input.client, model, t.prompt, ctx.directory);
+                return `[task ${t.id}] ${r}`;
+              }));
+              results.push(...out);
+            }
+            const note = throttle ? `
+[usage-coach] quota THROTTLE \u2014 lighter model ${cfg.lighterModel}, concurrency capped at ${limit}` : "";
+            return results.join("\n\n") + note;
           }
         }),
         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/package.json

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