opencode-usage-coach 0.3.5 → 0.5.0

package/README.md

@@ -152,6 +152,38 @@ 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`) |
+| `UC_WORM_MAX_AGE_DAYS` | 180 | domain DB worm (GC): drop nodes not accessed in N days (~6 months) |
+| `UC_WORM_MAX_NODES` | 100000 | domain DB worm (GC): cap node count, evict oldest-accessed beyond this |
+
+## 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

@@ -1,5 +1,5 @@
 // src/index.ts
-import { mkdirSync as mkdirSync2, writeFileSync, appendFileSync as appendFileSync2, readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, appendFileSync as appendFileSync2, readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
 import { spawn } from "child_process";
 import { createHash } from "crypto";
 import { homedir } from "os";
@@ -7,7 +7,7 @@ import { join as join2, resolve, dirname } from "path";
 import { tool } from "@opencode-ai/plugin";
 
 // src/domain.ts
-import { mkdirSync, appendFileSync, readFileSync, existsSync } from "fs";
+import { mkdirSync, appendFileSync, readFileSync, existsSync, writeFileSync } from "fs";
 import { join } from "path";
 var BASE_DIR = "";
 function initDomain(stateDir) {
@@ -41,6 +41,14 @@ function addDomainNode(node) {
   }
   return full.id;
 }
+function writeNodes(nodes) {
+  try {
+    mkdirSync(BASE_DIR, { recursive: true });
+    const lines = nodes.map((n) => JSON.stringify(n));
+    writeFileSync(nodesFile(), lines.length ? lines.join("\n") + "\n" : "");
+  } catch {
+  }
+}
 function queryDomain(keywords) {
   const lc = keywords.map((k) => k.toLowerCase());
   const nodes = readNodes();
@@ -48,10 +56,47 @@ function queryDomain(keywords) {
     const hay = (n.name + " " + JSON.stringify(n.props)).toLowerCase();
     return lc.some((k) => k && hay.includes(k));
   });
+  if (matched.length) touchNodes(new Set(matched.map((n) => n.id)));
   const ids = new Set(matched.map((n) => n.id));
   const edges = readEdges().filter((e) => ids.has(e.from) || ids.has(e.to));
   return { nodes: matched, edges };
 }
+function touchNodes(ids) {
+  if (ids.size === 0) return;
+  try {
+    const nodes = readNodes();
+    let changed = false;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    for (const n of nodes) {
+      if (ids.has(n.id)) {
+        n.lastAccessed = now;
+        n.accessCount = (n.accessCount ?? 0) + 1;
+        changed = true;
+      }
+    }
+    if (changed) writeNodes(nodes);
+  } catch {
+  }
+}
+function evictStale(maxAgeDays = 30, maxNodes = 1e3) {
+  try {
+    const nodes = readNodes();
+    if (nodes.length === 0) return { removed: 0, kept: 0 };
+    const now = Date.now();
+    const ageMs = maxAgeDays * 864e5;
+    const lastTs = (n) => new Date(n.lastAccessed ?? n.ts).getTime();
+    let kept = nodes.filter((n) => now - lastTs(n) < ageMs);
+    if (kept.length > maxNodes) {
+      kept.sort((a, b) => lastTs(b) - lastTs(a));
+      kept = kept.slice(0, maxNodes);
+    }
+    const removed = nodes.length - kept.length;
+    if (removed > 0) writeNodes(kept);
+    return { removed, kept: kept.length };
+  } catch {
+    return { removed: 0, kept: 0 };
+  }
+}
 function saveInvestigationResult(keywords, result, source) {
   try {
     return addDomainNode({
@@ -68,11 +113,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 +125,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 = {};
@@ -96,7 +138,7 @@ function log(msg) {
 function writeState(c) {
   try {
     mkdirSync2(STATE_DIR, { recursive: true });
-    writeFileSync(STATE_FILE, JSON.stringify({ ...c, updatedAt: (/* @__PURE__ */ new Date()).toISOString() }));
+    writeFileSync2(STATE_FILE, JSON.stringify({ ...c, updatedAt: (/* @__PURE__ */ new Date()).toISOString() }));
   } catch {
   }
 }
@@ -149,7 +191,7 @@ function writeHarness(sessionID, h) {
     const f = harnessFile(sessionID);
     mkdirSync2(dirname(f), { recursive: true });
     h.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-    writeFileSync(f, JSON.stringify(h, null, 2));
+    writeFileSync2(f, JSON.stringify(h, null, 2));
   } catch {
   }
 }
@@ -200,6 +242,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]);
@@ -213,6 +256,8 @@ var THR_5H = num("UC_THROTTLE_5H", 70);
 var STOP_WK = num("UC_STOP_WEEKLY", 95);
 var THR_WK = num("UC_THROTTLE_WEEKLY", 85);
 var STOP_MO = num("UC_STOP_MONTHLY", 98);
+var WORM_MAX_AGE_DAYS = num("UC_WORM_MAX_AGE_DAYS", 180);
+var WORM_MAX_NODES = num("UC_WORM_MAX_NODES", 1e5);
 function humanRemaining(iso) {
   try {
     if (!iso) return "";
@@ -325,6 +370,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 {
@@ -380,30 +444,46 @@ async function UsageCoachPlugin(input) {
       event: async ({ event }) => {
         try {
           if (event.type === "session.created" || event.type === "session.idle") refreshBackground();
+          if (event.type === "session.idle") {
+            try {
+              const r = evictStale(WORM_MAX_AGE_DAYS, WORM_MAX_NODES);
+              if (r.removed) log(`evictStale: removed ${r.removed}, kept ${r.kept} (maxAge=${WORM_MAX_AGE_DAYS}d, maxNodes=${WORM_MAX_NODES})`);
+            } catch (e) {
+              log(`evictStale err: ${String(e)}`);
+            }
+          }
         } catch (e) {
           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.5.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"
   }
 }