opencode-usage-coach 0.3.5 → 0.4.0

package/README.md

@@ -152,6 +152,36 @@ Place in the **work directory**. Each role runs on its model, so per-model quota
 | `UC_PROVIDER` | (config `provider`) | codexbar provider for the guardian |
 | `UC_TTL_MS` | 60000 | quota cache TTL (ms) |
 | `UC_DEBUG` | 0 | set to `1` for a diagnostic log at `~/.cache/opencode-usage-coach/coach.log` |
+| `UC_HARNESS_AGENT` | `Usage-Coach-Harness` | comma-separated agent modes allowed to use harness tools + receive quota coaching (case-insensitive; must match the agent id, e.g. `usage-coach-harness` from `agents/usage-coach-harness.md`) |
+
+## Agent-mode scoping
+
+Harness tools (`generate`, `grade`, `harness_start`, …) and quota coaching are **scoped to
+the `usage-coach-harness` agent mode**. Other modes (build, general, your custom agents) stay
+completely clean — no harness tools in their tool list, no quota coaching injected into their
+system prompt.
+
+This is enforced on two independent layers (defense in depth):
+
+1. **Agent definition** (`agents/usage-coach-harness.md`) — its `permission` allowlist names the
+   harness tools, so they only appear in this mode. Other agents' permission lists don't name
+   them, so they're hidden from those modes automatically (this is the standard opencode
+   mechanism — tool visibility is the agent definition's responsibility).
+2. **Plugin runtime gate** (`tool.execute.before`) — even if a harness tool were somehow
+   invoked, the plugin resolves the current session's agent (`client.session.get` → `info.agent`,
+   60s-cached) and throws unless it matches `UC_HARNESS_AGENT` (default `Usage-Coach-Harness`,
+   case-insensitive). The quota system-prompt injection is gated the same way.
+
+**To use the harness tools**, switch to the `usage-coach-harness` agent mode.
+
+**To allow additional modes**, set `UC_HARNESS_AGENT` to a comma-separated list:
+```bash
+export UC_HARNESS_AGENT="usage-coach-harness,my-other-harness"
+```
+
+> Why not the v2 plugin API? v2 has no `tool` registration domain, so a plugin that provides
+> custom tools (like this one) cannot be fully rewritten in v2. Agent `permission` allowlists +
+> the v1 runtime gate is the structurally correct way to scope tool visibility.
 
 ## Architecture
 - **Server module** (`src/index.ts`) — SENSE/DECIDE/ACT + custom harness tools. Loaded via `opencode.json`.

package/agents/usage-coach-harness.md

@@ -12,7 +12,12 @@ permission:
   grep: allow
   task: allow
   generate: allow
+  generate_batch: allow
   grade: allow
+  investigate: allow
+  verify_diagnosis: allow
+  generalize: allow
+  record_failure: allow
   harness_start: allow
   task_update: allow
   harness_done: allow

package/dist/index.js

@@ -68,11 +68,9 @@ function saveInvestigationResult(keywords, result, source) {
 
 // src/index.ts
 var PLUGIN_NAME = "opencode-usage-coach";
-var DEBUG = process.env.UC_DEBUG === "1";
 var TTL_MS = Number(process.env.UC_TTL_MS ?? 6e4);
 var STATE_DIR = join2(homedir(), ".cache", "opencode-usage-coach");
 var STATE_FILE = join2(STATE_DIR, "state.json");
-var HARNESS_FILE = join2(STATE_DIR, "harness.json");
 var LOG_FILE = join2(STATE_DIR, "coach.log");
 function projectStateDir(dir) {
   const abs = resolve(dir || ".");
@@ -82,7 +80,6 @@ function projectStateDir(dir) {
 function setStateDir(dir) {
   STATE_DIR = process.env.UC_STATE_DIR ?? projectStateDir(dir);
   STATE_FILE = join2(STATE_DIR, "state.json");
-  HARNESS_FILE = join2(STATE_DIR, "harness.json");
   LOG_FILE = join2(STATE_DIR, "coach.log");
 }
 var NOOP_HOOKS = {};
@@ -200,6 +197,7 @@ async function runModel(client, model, prompt, directory) {
     return `ERROR: runModel exception after ${elapsed}s: ${String(e)}`;
   }
 }
+var HARNESS_AGENTS = (process.env.UC_HARNESS_AGENT ?? "Usage-Coach-Harness").split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
 var num = (e, d) => {
   try {
     const v = Number(process.env[e]);
@@ -325,6 +323,25 @@ function coach(q, lighter) {
   if (wk >= THR_WK) return thr(`weekly ${wk}% (${wkR})`);
   return { decision: "GO", advice: `Comfortable \u2014 weekly ${wk}% \xB7 5h ${h5}% \xB7 monthly ${mo}%. proceed. 5h window ${h5R}.`, weekly: wk, monthly: mo, fiveHour: h5 };
 }
+var agentCache = /* @__PURE__ */ new Map();
+async function resolveAgent(client, sessionID) {
+  if (!sessionID) return "";
+  const hit = agentCache.get(sessionID);
+  if (hit && Date.now() - hit.ts < 6e4) return hit.agent;
+  try {
+    const s = await client.session.get({ path: { id: sessionID } });
+    const agent = String(s?.data?.info?.agent ?? s?.data?.agent ?? s?.info?.agent ?? "");
+    agentCache.set(sessionID, { agent, ts: Date.now() });
+    return agent;
+  } catch (e) {
+    log(`resolveAgent err: ${String(e)}`);
+    return "";
+  }
+}
+function isHarnessAgent(agent) {
+  if (!agent) return false;
+  return HARNESS_AGENTS.includes(agent.toLowerCase());
+}
 var LOADING = { decision: "GO", advice: "quota loading\u2026", weekly: -1, monthly: -1, fiveHour: -1 };
 async function UsageCoachPlugin(input) {
   try {
@@ -384,26 +401,34 @@ async function UsageCoachPlugin(input) {
           log(`event err: ${String(e)}`);
         }
       },
-      // ACT(1) hard gate — ONLY for harness tools (generate/grade/etc.) that consume quota.
-      // General tools (read/edit/bash/grep/task) are NEVER blocked — they don't consume model quota.
-      // This ensures Agent-Factory-Coordinator and other modes work freely even at STOP.
+      // ACT(1) hard gate — harness tools are restricted to the configured harness
+      // agent mode AND gated by quota STOP. General tools (read/edit/bash/grep/task)
+      // are NEVER gated, in ANY mode — they don't consume model quota.
       "tool.execute.before": async (_input) => {
-        let decision = "GO";
+        const harnessTools = ["generate", "generate_batch", "grade", "investigate", "verify_diagnosis", "generalize", "harness_start", "task_update", "harness_done", "record_failure"];
+        if (!harnessTools.includes(_input.tool)) return;
+        const agent = await resolveAgent(input.client, _input.sessionID);
+        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.`);
+        }
+        let decision;
         try {
           decision = current().decision;
         } catch {
           decision = "GO";
         }
         if (decision === "STOP") {
-          const harnessTools = ["generate", "generate_batch", "grade", "investigate", "verify_diagnosis", "generalize"];
-          if (harnessTools.includes(_input.tool)) {
-            throw new Error(`[${PLUGIN_NAME}] blocked: quota limit exceeded. ${current().advice}`);
-          }
+          throw new Error(`[${PLUGIN_NAME}] blocked: quota limit exceeded. ${current().advice}`);
         }
       },
-      // ACT(2) inject coaching into system prompt (double defense). Silent on error.
+      // ACT(2) inject coaching into system prompt — ONLY in the harness agent mode,
+      // so other modes' system prompts stay completely clean. Silent on error.
       "experimental.chat.system.transform": async (_input, output) => {
         try {
+          if (_input.sessionID) {
+            const agent = await resolveAgent(input.client, _input.sessionID);
+            if (!isHarnessAgent(agent)) return;
+          }
           const c = current();
           let instruction = "";
           if (c.decision === "STOP") instruction = `[${PLUGIN_NAME}] QUOTA limit exceeded. ${c.advice} Stop making further tool calls, finish the in-progress work, then report the quota status to the user.`;

package/dist/tui.js

@@ -131,11 +131,9 @@ function initializeTui(api, disposeRoot) {
     tlog(`api probe err: ${String(e)}`);
   }
   const [getState, setState] = createSignal(readState());
-  const [getHarness, setHarness] = createSignal(readHarness());
   const timer = setInterval(() => {
     try {
       setState(readState());
-      setHarness(readHarness());
     } catch {
     }
   }, 3e3);
@@ -184,7 +182,7 @@ function initializeTui(api, disposeRoot) {
         return _el$;
       })();
     }
-    let s = null;
+    let s;
     try {
       s = getState();
     } catch {
@@ -415,16 +413,18 @@ function initializeTui(api, disposeRoot) {
     slots: {
       sidebar_footer(ctx) {
         tlog("sidebar_footer slot called");
+        let result;
         try {
-          return panel(ctx);
+          result = panel(ctx);
         } catch (e) {
           tlog(`sidebar_footer err: ${String(e)}`);
-          return (() => {
+          result = (() => {
             var _el$61 = _$createElement("text");
             _$insertNode(_el$61, _$createTextNode(`usage-coach`));
             return _el$61;
           })();
         }
+        return result;
       }
     }
   });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "opencode-usage-coach",
-  "version": "0.3.5",
-  "description": "opencode closed-loop usage coach \u2014 quota SENSE -> coaching DECIDE -> loop ACT + TUI integration",
+  "version": "0.4.0",
+  "description": "opencode closed-loop usage coach — quota SENSE -> coaching DECIDE -> loop ACT + TUI integration",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -18,6 +18,8 @@
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "prepack": "tsup"
   },
   "files": [
@@ -44,12 +46,17 @@
     "solid-js": ">=1.9.12"
   },
   "devDependencies": {
+    "@eslint/js": "^10.0.1",
     "@opencode-ai/plugin": "*",
     "@opentui/core": ">=0.4.0",
     "@opentui/solid": ">=0.4.0",
     "esbuild-plugin-solid": "^0.6.0",
+    "eslint": "^10.6.0",
+    "eslint-plugin-solid": "^0.14.5",
+    "globals": "^17.7.0",
     "solid-js": "^1.9",
     "tsup": "^8.5",
-    "typescript": "^5"
+    "typescript": "^5",
+    "typescript-eslint": "^8.63.0"
   }
 }