opencode-usage-coach 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-usage-coach contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# 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) where USD cost is meaningless, so it tracks
+**quota windows (5h / weekly / monthly)** and turns them into coaching + loop control.
+
+Existing plugins only *display* usage. This one **senses quota → coaches → stops/advances
+the loop** — and ships a harness agent mode + a deterministic orchestrator.
+
+## What it does
+
+**Always-on guardian (plugin):**
+- Senses z.ai quota windows via the `codexbar` CLI.
+- On STOP threshold: blocks tool calls (`tool.execute.before` throws) → the agent self-stops.
+- Injects coaching (how to use right now) into the system prompt (double defense).
+- Surfaces a sidebar panel: quota meters + harness task states + per-model token usage.
+- Defensive: any plugin error never breaks opencode.
+
+**Harness (two ways):**
+- **Agent mode** (`usage-coach-harness`): triages each request — trivial → do directly;
+  unclear → clarify; substantive → generate(delegate)→grade(delegate)→revise→advance.
+  Conversation-driven, no file required. Adaptive (best-effort).
+- **Deterministic script** (`harness.ts`): `tasks.txt` + `rubric.md` → guaranteed loop.
+  Reliable for batch jobs. Tracks per-model tokens, auto-splits on timeout.
+
+## Requirements
+- opencode (tested on 1.17.13) with a z.ai coding-plan provider configured.
+- `codexbar` CLI with the z.ai key wired (`codexbar config set-api-key --provider zai --stdin`).
+
+## Install (from npm)
+```jsonc
+// ~/.config/opencode/opencode.json  (server plugin)
+{ "plugin": ["opencode-usage-coach"] }
+
+// ~/.config/opencode/tui.json        (TUI panel)
+{ "$schema": "https://opencode.ai/tui.json", "plugin": ["opencode-usage-coach/tui"] }
+```
+Drop `agents/usage-coach-harness.md` into `~/.config/opencode/agents/` for the agent mode.
+
+## Local dev / install (without npm)
+```bash
+bun install
+bun run build          # -> dist/index.js, dist/tui.js (solid external)
+# server plugin
+cp dist/index.js ~/.config/opencode/plugins/opencode-usage-coach.js
+# TUI plugin — point tui.json at the built file (NOT the plugins/ dir)
+#   ~/.config/opencode/tui.json: { "plugin": ["/abs/path/dist/tui.js"] }
+```
+
+## Config
+
+This plugin has **four config surfaces**. Only the first two are required to run.
+
+### 1. Install config (where opencode loads the plugin from)
+```jsonc
+// ~/.config/opencode/opencode.json — server plugin (guardian + harness tools)
+{ "plugin": ["opencode-usage-coach"] }            // from npm, OR a local path:
+// { "plugin": ["/abs/path/dist/index.js"] }
+
+// ~/.config/opencode/tui.json — TUI panel (MUST point at the built dist/tui.js)
+{ "$schema": "https://opencode.ai/tui.json",
+  "plugin": ["/abs/path/dist/tui.js"] }
+
+// ~/.config/opencode/agents/usage-coach-harness.md — agent mode (copy from agents/)
+```
+> The TUI file MUST be loaded via `tui.json` file path (not the `plugins/` dir), and MUST be
+> the compiled `dist/tui.js` (raw `.tsx` / installing `solid-js` crashes opencode).
+
+### 2. codexbar (quota data source)
+```bash
+printf '%s' "$Z_AI_API_KEY" | codexbar config set-api-key --provider zai --stdin
+```
+
+### 3. Harness config — `harness.config.json` (role → model) ★ the main one
+Place in the **work directory** beside `tasks.txt`/`rubric.md`. Each role runs on its model,
+so per-model quota is tracked (works for local LLMs — they show 0%).
+```jsonc
+{
+  "generator":     "zai-coding-plan/glm-5.1",   // model that produces the work
+  "grader":        "ollama/llama3",              // model that grades it
+  "taskTimeoutMs": 1800000,                       // per-task timeout (on exceed: auto-split)
+  "maxRevisions":  2                              // revise attempts before giving up
+}
+```
+| Field | Default | Notes |
+|---|---|---|
+| `generator` | `UC_MODEL` | any `provider/model` opencode knows |
+| `grader` | `UC_MODEL` | can differ from generator (multi-model) |
+| `taskTimeoutMs` | `1800000` (30m) | exceed → task split into subtasks |
+| `maxRevisions` | `2` | FAIL → revise → re-grade, up to N times |
+
+Missing roles fall back to `UC_MODEL`. Provider for quota is derived from the model id
+(`zai-coding-plan/...` → `zai`, `ollama/...` → `ollama`).
+
+### 4. Env vars (thresholds / tuning)
+| Var | Default | Meaning |
+|---|---|---|
+| `UC_STOP_5H` | 92 | 5h window STOP % (blocks tools) |
+| `UC_THROTTLE_5H` | 70 | 5h window throttle % |
+| `UC_STOP_WEEKLY` | 95 | weekly STOP % |
+| `UC_THROTTLE_WEEKLY` | 85 | weekly throttle % |
+| `UC_STOP_MONTHLY` | 98 | monthly STOP % |
+| `UC_LIGHTER_MODEL` | glm-4.5-air | suggested model when throttling |
+| `UC_PROVIDER` | zai | codexbar provider for the guardian |
+| `UC_TTL_MS` | 60000 | quota cache TTL (ms) |
+| `UC_MODEL` | zai-coding-plan/glm-5.1 | harness fallback model |
+| `UC_TASK_TIMEOUT_MS` | 1800000 | harness per-task timeout (overridden by config) |
+| `UC_MAX_REVISIONS` | 2 | harness revise attempts (overridden by config) |
+| `UC_DEBUG` | 0 | set to `1` for a diagnostic log at `~/.cache/opencode-usage-coach/coach.log` |
+
+## Architecture
+- **Server module** (`src/index.ts`) — SENSE/DECIDE/ACT + custom harness tools. Loaded via `opencode.json`.
+- **TUI module** (`src/tui.tsx`) — SolidJS, reads a state file, renders into `sidebar_footer`/`home_footer`. Loaded via `tui.json`. Bundled with `tsup` + `esbuild-plugin-solid`, solid kept **external** (resolves to opencode's bundle — avoids the duplicate-instance crash). Exports `{ tui }` (a bare function is misread as a server plugin).
+- server↔TUI communicate via a state file (`~/.cache/opencode-usage-coach/*.json`) — they are separate processes.
+
+Key lessons (see `PLAN.md`): never install `solid-js` in the config dir (conflicts with
+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).
+
+## Status
+- ✅ M0–M2 quota guardian + TUI panel
+- ✅ M3 harness: agent mode (triage) + deterministic script (per-model tokens, auto-split)
+- ⏳ M4 npm packaging
+
+License: MIT.

package/agents/usage-coach-harness.md

@@ -0,0 +1,61 @@
+---
+description: "usage-coach harness — an orchestrator agent mode. Triages each request: trivial -> do directly; unclear -> clarify; substantive -> generate(delegate) -> grade(delegate) -> revise -> advance. Self-stops on quota. No tasks.txt required."
+mode: primary
+color: "#16A34A"
+permission:
+  edit: allow
+  bash:
+    "*": allow
+  read: allow
+  write: allow
+  glob: allow
+  grep: allow
+  task: allow
+  harness_start: allow
+  task_update: allow
+  harness_done: allow
+steps: 200
+---
+
+# usage-coach Harness
+
+You are a **harness orchestrator agent**. For every user request you first TRIAGE, then act. No `tasks.txt`/`rubric.md` file is required — the user's message is the work.
+
+## Step 0 — Triage (always do this first)
+Judge the request against the conversation so far, then pick exactly one path:
+1. **Trivial / single quick action** (e.g. a one-line fix, a direct factual answer, a small edit) → just do it directly. Do NOT start a harness loop.
+2. **Unclear / not enough info to act well** (vague goal, missing constraints, ambiguous success criteria that matter) → ask a concise clarifying question or run a quick read/grep to gather context, then re-triage.
+3. **Substantive multi-step work** (a real feature, a multi-file change, content that benefits from a quality check, anything where "generate then verify" adds value) → enter the **harness loop** below.
+
+Default to the loop only when it genuinely adds value. Do not over-engineer small requests.
+
+## 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.
+
+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** — delegate to a subagent via the `task` tool (`subagent_type: "general"`):
+      prompt: `"Task: {title}. Perform it for real in the current directory (write/edit files, run commands as needed)."`
+      If a subagent is slow or the task looks too large, split it into smaller subtasks (autonomous decomposition).
+   c. `task_update(i, title, "grading")`.
+   d. **Grade** — delegate via the `task` tool:
+      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:
+      - `PASS` → `task_update(i, title, "completed", score:"PASS")` → next task.
+      - `FAIL` and revisions < 2 → `task_update(i, title, "revising", revisions:k)` → delegate a revision (`"Apply the grading feedback and improve:\n{grade result}"`) → go back to (c) to re-grade.
+      - `FAIL` and revisions exhausted → `task_update(i, title, "failed", score:"FAIL")` → next task.
+3. When all tasks are done → `harness_done()`.
+
+## Rules
+- In the loop, **delegate the real work** to subagents via the `task` tool — you orchestrate. (Outside the loop, for trivial requests, you may 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.
+- If the quota coaching injected into your system prompt says **STOP**, immediately `task_update(current, "halted_quota")` and halt the loop.
+- If a subagent returns an incomplete result, split the task into smaller subtasks.
+- Be concise. Report only progress summaries to the user.
+
+## Output
+- Trivial path: just the direct result.
+- Loop path: the actual results are the files/changes the subagents leave in the directory; at the end report a brief summary (passed / failed / split counts).
+

package/dist/index.js

@@ -0,0 +1,233 @@
+// src/index.ts
+import { mkdirSync, writeFileSync, appendFileSync, readFileSync, existsSync } from "fs";
+import { spawn } from "child_process";
+import { homedir } from "os";
+import { join } from "path";
+import { tool } from "@opencode-ai/plugin";
+var PLUGIN_NAME = "opencode-usage-coach";
+var STATE_DIR = process.env.UC_STATE_DIR ?? join(homedir(), ".cache", "opencode-usage-coach");
+var STATE_FILE = join(STATE_DIR, "state.json");
+var HARNESS_FILE = join(STATE_DIR, "harness.json");
+var LOG_FILE = join(STATE_DIR, "coach.log");
+var DEBUG = process.env.UC_DEBUG === "1";
+var TTL_MS = Number(process.env.UC_TTL_MS ?? 6e4);
+var NOOP_HOOKS = {};
+function log(msg) {
+  if (DEBUG) try {
+    appendFileSync(LOG_FILE, `${(/* @__PURE__ */ new Date()).toISOString()} ${msg}
+`);
+  } catch {
+  }
+}
+function writeState(c) {
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+    writeFileSync(STATE_FILE, JSON.stringify({ ...c, updatedAt: (/* @__PURE__ */ new Date()).toISOString() }));
+  } catch {
+  }
+}
+function readHarness() {
+  try {
+    if (!existsSync(HARNESS_FILE)) return null;
+    return JSON.parse(readFileSync(HARNESS_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function writeHarness(h) {
+  try {
+    mkdirSync(STATE_DIR, { recursive: true });
+    h.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    writeFileSync(HARNESS_FILE, JSON.stringify(h, null, 2));
+  } catch {
+  }
+}
+var PROVIDER = process.env.UC_PROVIDER ?? "zai";
+var num = (e, d) => {
+  try {
+    const v = Number(process.env[e]);
+    return Number.isFinite(v) && v >= 0 ? v : d;
+  } catch {
+    return d;
+  }
+};
+var STOP_5H = num("UC_STOP_5H", 92);
+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 LIGHTER = process.env.UC_LIGHTER_MODEL ?? "glm-4.5-air";
+function humanRemaining(iso) {
+  try {
+    if (!iso) return "";
+    const mins = Math.floor((new Date(iso).getTime() - Date.now()) / 6e4);
+    if (mins < 0) return "resets soon";
+    if (mins < 60) return `resets in ${mins}m`;
+    if (mins < 1440) return `resets in ${Math.floor(mins / 60)}h`;
+    return `resets in ${Math.floor(mins / 1440)}d`;
+  } catch {
+    return "";
+  }
+}
+function fetchQuota() {
+  return new Promise((resolve) => {
+    let out = "";
+    let p;
+    try {
+      p = spawn("codexbar", ["usage", "--provider", PROVIDER, "--json"], {
+        stdio: ["ignore", "pipe", "ignore"]
+      });
+    } catch {
+      return resolve(null);
+    }
+    p.stdout?.on("data", (d) => {
+      out += d.toString();
+    });
+    p.on("error", () => resolve(null));
+    p.on("close", () => {
+      try {
+        const text = out.trim();
+        if (!text || text === "[]") return resolve(null);
+        const u = JSON.parse(text)[0]?.usage;
+        if (!u) return resolve(null);
+        resolve({ weekly: u.primary ?? { usedPercent: 0 }, monthly: u.secondary ?? { usedPercent: 0 }, fiveHour: u.tertiary ?? { usedPercent: 0 } });
+      } catch {
+        resolve(null);
+      }
+    });
+  });
+}
+function coach(q) {
+  if (!q) return { decision: "GO", advice: "quota unavailable \u2014 proceeding cautiously.", weekly: -1, monthly: -1, fiveHour: -1 };
+  const wk = Math.round(q.weekly?.usedPercent ?? 0), mo = Math.round(q.monthly?.usedPercent ?? 0), h5 = Math.round(q.fiveHour?.usedPercent ?? 0);
+  const wkR = humanRemaining(q.weekly?.resetsAt), h5R = humanRemaining(q.fiveHour?.resetsAt);
+  const stop = (r) => ({ decision: "STOP", advice: `STOP recommend \u2014 ${r}. window nearly exhausted. stop now or it will be force-blocked.`, weekly: wk, monthly: mo, fiveHour: h5 });
+  const thr = (r) => ({ decision: "THROTTLE", advice: `Throttle recommend \u2014 ${r}. switch to lighter model (${LIGHTER}) or wait for window reset.`, weekly: wk, monthly: mo, fiveHour: h5 });
+  if (h5 >= STOP_5H) return stop(`5h window ${h5}% (${h5R})`);
+  if (wk >= STOP_WK) return stop(`weekly ${wk}% (${wkR})`);
+  if (mo >= STOP_MO) return stop(`monthly ${mo}%`);
+  if (h5 >= THR_5H) return thr(`5h window ${h5}% (${h5R})`);
+  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 LOADING = { decision: "GO", advice: "quota loading\u2026", weekly: -1, monthly: -1, fiveHour: -1 };
+async function UsageCoachPlugin(input) {
+  try {
+    let last = null;
+    let lastFetchedAt = 0;
+    let refreshing = false;
+    const refreshBackground = () => {
+      try {
+        if (refreshing) return;
+        if (last && Date.now() - lastFetchedAt < TTL_MS) return;
+        refreshing = true;
+        fetchQuota().then((q) => {
+          try {
+            last = coach(q);
+            lastFetchedAt = Date.now();
+            writeState(last);
+            log(`${last.decision} | weekly=${last.weekly}% 5h=${last.fiveHour}%`);
+          } catch (e) {
+            log(`refresh-in-then err: ${String(e)}`);
+          }
+        }).catch((e) => {
+          log(`fetchQuota err: ${String(e)}`);
+        }).finally(() => {
+          refreshing = false;
+        });
+      } catch (e) {
+        log(`refreshBackground err: ${String(e)}`);
+      }
+    };
+    const current = () => {
+      try {
+        if (!last) refreshBackground();
+        return last ?? LOADING;
+      } catch {
+        return LOADING;
+      }
+    };
+    return {
+      event: async ({ event }) => {
+        try {
+          if (event.type === "session.created" || event.type === "session.idle") refreshBackground();
+        } catch (e) {
+          log(`event err: ${String(e)}`);
+        }
+      },
+      // ACT(1) hard gate: only intentional STOP throws. Our own bugs never block.
+      "tool.execute.before": async (_input) => {
+        let decision = "GO";
+        try {
+          decision = current().decision;
+        } catch {
+          decision = "GO";
+        }
+        if (decision === "STOP") {
+          throw new Error(`[${PLUGIN_NAME}] blocked: quota limit exceeded. ${current().advice}`);
+        }
+      },
+      // ACT(2) inject coaching into system prompt (double defense). Silent on error.
+      "experimental.chat.system.transform": async (_input, output) => {
+        try {
+          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.`;
+          else if (c.decision === "THROTTLE") instruction = `[${PLUGIN_NAME}] ${c.advice} Hold off on long/heavy tasks.`;
+          else if (c.weekly >= 0) instruction = `[${PLUGIN_NAME}] quota ok \u2014 weekly ${c.weekly}% \xB7 5h ${c.fiveHour}% \xB7 monthly ${c.monthly}%.`;
+          if (instruction) output.system.push(instruction);
+        } catch (e) {
+          log(`system.transform err: ${String(e)}`);
+        }
+      },
+      // Custom tools for the harness agent mode — report status to the panel.
+      tool: {
+        harness_start: tool({
+          description: "Start the harness: register the total task count on the panel. Call once when the harness loop begins.",
+          args: { name: tool.schema.string(), total: tool.schema.number() },
+          async execute(args) {
+            writeHarness({ name: args.name, total: args.total, current: 0, tasks: [], usage: {}, 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.`;
+          }
+        }),
+        task_update: tool({
+          description: "Update a harness task's status on the panel. Call whenever a task transitions to generating/grading/revising/completed/failed.",
+          args: {
+            id: tool.schema.number(),
+            title: tool.schema.string(),
+            status: tool.schema.string().describe("generating | grading | revising | completed | failed | timed_out"),
+            revisions: tool.schema.number().optional(),
+            score: tool.schema.string().optional().describe("PASS | FAIL"),
+            model: tool.schema.string().optional()
+          },
+          async execute(args) {
+            const h = readHarness() ?? { name: "batch", total: 0, current: 0, tasks: [], usage: {} };
+            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 });
+            if (args.id > h.current) h.current = args.id;
+            writeHarness(h);
+            return `task ${args.id} -> ${args.status}${args.score ? ` (${args.score})` : ""}`;
+          }
+        }),
+        harness_done: tool({
+          description: "Mark the harness as complete \u2014 call when the loop ends.",
+          args: {},
+          async execute() {
+            const h = readHarness();
+            if (h) {
+              h.current = h.total;
+              writeHarness(h);
+            }
+            return "Harness complete.";
+          }
+        })
+      }
+    };
+  } catch (e) {
+    log(`PLUGIN INIT FAILED (no-op): ${String(e)}`);
+    return NOOP_HOOKS;
+  }
+}
+export {
+  UsageCoachPlugin as default
+};

package/dist/tui.js

@@ -0,0 +1,227 @@
+// src/tui.tsx
+import { setProp as _$setProp } from "@opentui/solid";
+import { insert as _$insert } 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 { homedir } from "os";
+import { join } from "path";
+import { createRoot, createSignal, onCleanup } from "solid-js";
+var STATE_DIR = process.env.UC_STATE_DIR ?? join(homedir(), ".cache", "opencode-usage-coach");
+var STATE_FILE = join(STATE_DIR, "state.json");
+var HARNESS_FILE = join(STATE_DIR, "harness.json");
+var MARKER = join(STATE_DIR, "tui-loaded.txt");
+function readState() {
+  try {
+    if (!existsSync(STATE_FILE)) return null;
+    return JSON.parse(readFileSync(STATE_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function readHarness() {
+  try {
+    if (!existsSync(HARNESS_FILE)) return null;
+    return JSON.parse(readFileSync(HARNESS_FILE, "utf8"));
+  } catch {
+    return null;
+  }
+}
+var TAG = {
+  GO: "ok",
+  THROTTLE: "slow",
+  STOP: "STOP"
+};
+var TLABEL = {
+  generating: "gen",
+  grading: "grade",
+  revising: "revise",
+  completed: "done",
+  failed: "fail",
+  timed_out: "timeout",
+  halted_quota: "quota-halt"
+};
+function bar(p) {
+  const n = Math.max(0, Math.min(10, Math.round(p / 10)));
+  return "\u2588".repeat(n) + "\u2591".repeat(10 - n);
+}
+function short(s, n) {
+  return s.length <= n ? s : s.slice(0, n - 1) + "\u2026";
+}
+function initializeTui(api, disposeRoot) {
+  try {
+    mkdirSync(STATE_DIR, {
+      recursive: true
+    });
+    writeFileSync(MARKER, `loaded ${(/* @__PURE__ */ new Date()).toISOString()}`);
+  } catch {
+  }
+  const [getState, setState] = createSignal(readState());
+  const [getHarness, setHarness] = createSignal(readHarness());
+  const timer = setInterval(() => {
+    try {
+      setState(readState());
+      setHarness(readHarness());
+    } catch {
+    }
+  }, 3e3);
+  onCleanup(() => clearInterval(timer));
+  onCleanup(() => disposeRoot());
+  const statusDot = {
+    generating: "\u25CF",
+    grading: "\u25CF",
+    revising: "\u25CF",
+    completed: "\u25CF",
+    failed: "\u25CF",
+    timed_out: "\u25CF",
+    halted_quota: "\u25CF"
+  };
+  const panel = (ctx) => {
+    let s = null;
+    try {
+      s = getState();
+    } catch {
+      s = null;
+    }
+    let h = null;
+    try {
+      h = getHarness();
+    } catch {
+      h = null;
+    }
+    const nodes = [];
+    if (s) {
+      nodes.push((() => {
+        var _el$ = _$createElement("text"), _el$2 = _$createTextNode(`usage-coach [`), _el$3 = _$createTextNode(`]`);
+        _$insertNode(_el$, _el$2);
+        _$insertNode(_el$, _el$3);
+        _$insert(_el$, () => TAG[s.decision], _el$3);
+        return _el$;
+      })());
+      nodes.push((() => {
+        var _el$4 = _$createElement("text"), _el$5 = _$createTextNode(` 5h `), _el$6 = _$createTextNode(` `), _el$7 = _$createTextNode(`%`);
+        _$insertNode(_el$4, _el$5);
+        _$insertNode(_el$4, _el$6);
+        _$insertNode(_el$4, _el$7);
+        _$insert(_el$4, () => bar(s.fiveHour), _el$6);
+        _$insert(_el$4, () => s.fiveHour, _el$7);
+        return _el$4;
+      })());
+      nodes.push((() => {
+        var _el$8 = _$createElement("text"), _el$9 = _$createTextNode(` wk `), _el$0 = _$createTextNode(` `), _el$1 = _$createTextNode(`%`);
+        _$insertNode(_el$8, _el$9);
+        _$insertNode(_el$8, _el$0);
+        _$insertNode(_el$8, _el$1);
+        _$insert(_el$8, () => bar(s.weekly), _el$0);
+        _$insert(_el$8, () => s.weekly, _el$1);
+        return _el$8;
+      })());
+      nodes.push((() => {
+        var _el$10 = _$createElement("text"), _el$11 = _$createTextNode(` mo `), _el$12 = _$createTextNode(` `), _el$13 = _$createTextNode(`%`);
+        _$insertNode(_el$10, _el$11);
+        _$insertNode(_el$10, _el$12);
+        _$insertNode(_el$10, _el$13);
+        _$insert(_el$10, () => bar(s.monthly), _el$12);
+        _$insert(_el$10, () => s.monthly, _el$13);
+        return _el$10;
+      })());
+    } else {
+      nodes.push((() => {
+        var _el$14 = _$createElement("text");
+        _$insertNode(_el$14, _$createTextNode(`usage-coach: ...`));
+        return _el$14;
+      })());
+    }
+    const hStatus = h && h.tasks.length > 0 ? `${h.name} ${h.current}/${h.total}` : "idle";
+    nodes.push((() => {
+      var _el$16 = _$createElement("text");
+      _$insertNode(_el$16, _$createTextNode(` `));
+      return _el$16;
+    })());
+    nodes.push((() => {
+      var _el$18 = _$createElement("text"), _el$19 = _$createTextNode(`harness: `);
+      _$insertNode(_el$18, _el$19);
+      _$insert(_el$18, hStatus, null);
+      return _el$18;
+    })());
+    if (h && h.tasks.length > 0) {
+      for (const t of h.tasks) {
+        const dot = statusDot[t.status] ?? "\xB7";
+        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}` : "";
+        nodes.push((() => {
+          var _el$20 = _$createElement("text"), _el$21 = _$createTextNode(` `), _el$22 = _$createTextNode(` `), _el$23 = _$createTextNode(` `), _el$24 = _$createTextNode(` `);
+          _$insertNode(_el$20, _el$21);
+          _$insertNode(_el$20, _el$22);
+          _$insertNode(_el$20, _el$23);
+          _$insertNode(_el$20, _el$24);
+          _$insert(_el$20, dot, _el$22);
+          _$insert(_el$20, () => t.id, _el$23);
+          _$insert(_el$20, mdl, _el$23);
+          _$insert(_el$20, lbl, _el$24);
+          _$insert(_el$20, rev, _el$24);
+          _$insert(_el$20, () => short(t.title, 12), null);
+          return _el$20;
+        })());
+        const pv = t.model ? t.model.startsWith("zai") ? "zai" : (t.model.split("/")[0] ?? "").split("-")[0] : "";
+        const q = pv && h.quotas?.[pv] ? h.quotas[pv] : null;
+        const pct = q ? q.fiveHour : 0;
+        nodes.push((() => {
+          var _el$25 = _$createElement("text"), _el$26 = _$createTextNode(` 5h `), _el$27 = _$createTextNode(` `), _el$28 = _$createTextNode(`%`);
+          _$insertNode(_el$25, _el$26);
+          _$insertNode(_el$25, _el$27);
+          _$insertNode(_el$25, _el$28);
+          _$insert(_el$25, () => bar(pct), _el$27);
+          _$insert(_el$25, pct, _el$28);
+          return _el$25;
+        })());
+      }
+    }
+    return (() => {
+      var _el$29 = _$createElement("box");
+      _$setProp(_el$29, "flexDirection", "column");
+      _$insert(_el$29, nodes);
+      return _el$29;
+    })();
+  };
+  api.slots.register({
+    order: 80,
+    slots: {
+      sidebar_footer(ctx) {
+        try {
+          return panel(ctx);
+        } catch {
+          return (() => {
+            var _el$30 = _$createElement("text");
+            _$insertNode(_el$30, _$createTextNode(`usage-coach`));
+            return _el$30;
+          })();
+        }
+      },
+      home_footer(ctx) {
+        try {
+          return panel(ctx);
+        } catch {
+          return (() => {
+            var _el$32 = _$createElement("text");
+            _$insertNode(_el$32, _$createTextNode(`usage-coach`));
+            return _el$32;
+          })();
+        }
+      }
+    }
+  });
+}
+var tui = async (api) => {
+  createRoot((disposeRoot) => initializeTui(api, disposeRoot));
+};
+var plugin = {
+  id: "opencode-usage-coach-tui",
+  tui
+};
+var tui_default = plugin;
+export {
+  tui_default as default
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "opencode-usage-coach",
+  "version": "0.1.1",
+  "description": "opencode closed-loop usage coach — quota SENSE -> coaching DECIDE -> loop ACT + TUI integration",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tui": {
+      "types": "./dist/tui.d.ts",
+      "import": "./dist/tui.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "prepack": "tsup"
+  },
+  "files": [
+    "dist",
+    "agents",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": ["opencode", "opencode-plugin", "quota", "usage", "coach", "loop", "zai", "glm"],
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.14",
+    "@opentui/core": ">=0.4.0",
+    "@opentui/solid": ">=0.4.0",
+    "solid-js": ">=1.9.12"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "*",
+    "@opentui/core": ">=0.4.0",
+    "@opentui/solid": ">=0.4.0",
+    "esbuild-plugin-solid": "^0.6.0",
+    "solid-js": "^1.9",
+    "tsup": "^8.5",
+    "typescript": "^5"
+  }
+}