opencode-context-indicator 1.1.2 → 1.1.4

package/README.md

@@ -196,6 +196,13 @@ back to a plain notice if needed.
   with no category data (no cache/snapshot and the fallback failed or ran out of
   budget) is tagged `no-data`; `ctx` / `model` / `updatedAt` still come from
   `state.json` / the live lookup, while its category cells stay `n/a`.
+* **The denominator survives a transient model-registry miss.** If the serving
+  instance's `ctx.model.list()` returns no usable limits (freshly loaded instance,
+  provider not yet registered, malformed payload), the window is recovered from
+  the `state.json` snapshot instead of degrading the `ctx` column to `?`; limits
+  are also seeded from the snapshot at startup, and the retry backs off
+  (30 s → 5 min, capped). A known `usable`/`limit`/`agent` is never overwritten
+  with `null` when another instance rewrites the snapshot.
 * Both commands append their payload to `context-breakdown.log` (final-summaries
   section), so it stays recoverable even if delivery fails.
 * If `ctx.session.synthetic` throws, the command logs an actionable error and the
@@ -438,6 +445,66 @@ caller.
 
 ---
 
+## Development / Testing
+
+### Running tests
+
+```bash
+npm run test:prepublish       # fast gate: tarball + tui.tsx + resolve + T1–T12 unit
+npm run test:e2e              # full E2E: isolated plugin load + one "Say OK" round-trip
+npm run test:e2e:quick        # E2E load-only, no LLM call
+```
+
+`prepublishOnly` runs **both** gates automatically on `npm publish`
+(`node test/prepublish.mjs && node test/e2e-tui.mjs --full`) and is skipped with
+`--ignore-scripts`. The whole chain takes roughly **1 minute** (fast gate ~20 s,
+isolated E2E ~10 s warm / up to ~90 s cold); the E2E is bounded by INIT 45 s +
+STEP 80 s, ~3 min total.
+
+### What the gates check
+
+**Fast gate — `test/prepublish.mjs`**
+
+| Step | What | Why |
+|---|---|---|
+| (a) tarball composition | `package.json` `files[]` field expands to exactly 6 members | no test/node_modules/tsconfig in the tarball |
+| (b) pragma regression | esbuild `--jsx=automatic` → `@opentui/solid/jsx-runtime` present, `react/jsx-runtime` absent | a removed/broken pragma kills the sidebar on npm install |
+| (c) resolve chain | replica install → `import.meta.resolve` for all tui.tsx imports | broken peer/optional dep silently breaks the sidebar |
+| (d) unit harness T1–T12 | all limit/agent/state fix assertions | regressions in modelLimits, writeStateFile, hydrate |
+
+**Isolated E2E — `test/e2e-tui.mjs`** (requires the OpenCode CLI)
+
+| Check | What | Why |
+|---|---|---|
+| A — plugin load | spins a private `opencode --standalone` PTY, asserts `msg="loading plugin" → opencode-context-indicator` and that the `file:///` entrypoint is **this checkout** | catches a plugin that no longer imports cleanly, or a config pointing at the published npm copy |
+| B — live update | one `opencode run "Say OK" --standalone` round-trip; asserts the LLM answered **and** the isolated `state.json` gained a session with `ctx > 0` | catches a regression in the `session.idle` → `writeStateFile` path |
+
+The E2E is fully **non-invasive** to your running OpenCode Desktop:
+
+- `--standalone` starts a *private* server instead of the background service Desktop uses;
+- `OPENCODE_DB` points at a throwaway DB in `%TEMP%` (your sessions are untouched);
+- `OPENCODE_CONTEXT_INDICATOR_STATE_FILE` points at a throwaway state file in `%TEMP%`
+  — the live `opencode-context-indicator-state.json` is never read or written;
+- `OPENCODE_DISABLE_PROJECT_CONFIG=1` avoids project-level config;
+- exactly **one** minimal LLM call (`Say OK`) is made, in the isolated session.
+
+The script prints `[e2e] running against ISOLATED opencode instance — your running
+sessions are not touched` at start and reports the Desktop service/GUI PIDs before
+and after the run. Override the binary with `OPENCODE_CLI`. The full run needs a
+model for the one round-trip: set `OPENCODE_E2E_MODEL` to *your* `provider/model`
+id (e.g. `OPENCODE_E2E_MODEL=myprovider/some-model`); it is **required** in full
+mode and the script exits with an instruction if it is unset. `--quick` needs no
+model.
+
+### CI
+
+`.github/workflows/ci.yml` runs `test/prepublish.mjs` on every push/PR and additionally
+does a standalone esbuild transpile check (pragmas, no React). The Node-pty E2E is not
+run in CI (requires the OpenCode Desktop binary) and is skipped gracefully when the CLI
+is absent (`[SKIP] opencode CLI not found`).
+
+---
+
 ## License
 
 [MIT](./LICENSE)

package/index.js

@@ -177,7 +177,8 @@ const CRITICAL_THROTTLE_MS = 10000; // min gap between critical (>90%) toasts
 const ERROR_TOAST_DEDUP_MS = 60000; // same error -> at most one toast / window
 const COMPACTED_TOAST_DEDUP_MS = 60000; // compacted-toast dedup window
 const PROVIDERS_TTL_MS = 5 * 60 * 1000; // providers()/model.list() cache TTL after SUCCESS
-const PROVIDERS_FAIL_TTL_MS = 30 * 1000; // retry-no-sooner gate after FAILURE
+const PROVIDERS_FAIL_TTL_MS = 30 * 1000; // retry-no-sooner base after FAILURE (doubles per consecutive miss)
+const V2_LIMITS_MAX_BACKOFF_MS = 5 * 60 * 1000; // cap for the model.list retry backoff
 const PROVIDERS_FETCH_TIMEOUT_MS = 2000; // hard cap for one providers() call (V1)
 const V2_MODEL_FETCH_TIMEOUT_MS = 8000; // hard cap for one ctx.model.list() call (V2)
 const TOAST_MS_ERROR = 8000; // duration for error / overflow toasts
@@ -194,7 +195,13 @@ const LOG_FILE = join(tmpdir(), "context-breakdown.log");
 // Machine-readable snapshot consumed by the optional TUI sidebar (./tui.tsx,
 // package entry "./tui"). Written next to each log update — same moment, same
 // data. See writeStateFile() below.
-const STATE_FILE = join(tmpdir(), "opencode-context-indicator-state.json");
+// State file path — overridable via env for test isolation.
+// In production the env is never set, so behaviour is unchanged.
+// In tests: export OPENCODE_CONTEXT_INDICATOR_STATE_FILE=/tmp/test-state.json
+// and the harness writes a controlled seed; no live file is touched.
+const STATE_FILE =
+  process.env.OPENCODE_CONTEXT_INDICATOR_STATE_FILE ||
+  join(tmpdir(), "opencode-context-indicator-state.json");
 
 // Separate tap log for raw events (written only when DEBUG_EVENTS is true).
 const EVENT_LOG_FILE = join(tmpdir(), "context-events.log");
@@ -278,6 +285,7 @@ let providersInFlight = null;
 // absolute tokens (as in V1).
 let v2LimitsLoadedAt = 0;
 let v2LimitsFailAt = 0;
+let v2LimitsFailCount = 0; // consecutive soft-failures -> exponential retry backoff
 let v2LimitsInFlight = null;
 
 // Bounded list of final summaries written on session.idle
@@ -472,6 +480,14 @@ function writeStateFile(
     const prevEntry = all[sessionID] || null;
     const pc = all[sessionID]?.categories || null;
 
+    // Same model AND provider? Only then is a previously persisted denominator
+    // meaningful — a session that switched model (or provider, even with the
+    // same modelID) must not inherit the old window.
+    const sameModelAsPrev =
+      prevEntry != null &&
+      prevEntry.model === (modelID || "unknown") &&
+      (prevEntry.providerID || "") === (providerID || "");
+
     const catUser = bd ? bd.userChars || 0 : pc?.user ?? 0;
     const catAssistant = bd ? bd.assistantChars || 0 : pc?.assistant ?? 0;
     const catReasoning = bd ? bd.reasoningChars || 0 : pc?.reasoning ?? 0;
@@ -504,13 +520,23 @@ function writeStateFile(
       sessionID,
       parentID,
       role: parentID ? "sub" : "main",
-      agent: sessionAgentCache.get(sessionID) || null,
+      agent: sessionAgentCache.get(sessionID) || prevEntry?.agent || null,
       model: modelID || "unknown",
       providerID: providerID || "",
       ctx: total,
       input: inputTokens || 0,
-      usable: denom,
-      limit: limit != null ? limit : null,
+      // Do NOT clobber a known denominator with null: multiple plugin instances
+      // share this file and one of them may lack modelLimits (its ctx.model.list
+      // returned nothing). Keep the previous model's known value when the live
+      // lookup came back empty, so a transient miss never becomes permanent.
+      usable:
+        denom != null ? denom : sameModelAsPrev ? prevEntry.usable ?? null : null,
+      limit:
+        limit != null
+          ? limit
+          : sameModelAsPrev && typeof prevEntry.limit === "number"
+            ? prevEntry.limit
+            : null,
       reasoning: typeof reasoningTokens === "number" ? reasoningTokens : 0,
       categories: {
         user: catUser,
@@ -1916,7 +1942,14 @@ async function ensureV2Breakdown(ctx, sessionID) {
 async function ensureModelLimits(ctx) {
   const now = Date.now();
   if (now - v2LimitsLoadedAt < PROVIDERS_TTL_MS) return; // fresh success
-  if (now - v2LimitsFailAt < PROVIDERS_FAIL_TTL_MS) return; // recent failure
+  // Recent failure: back off exponentially (30s, 60s, 120s … capped at 5 min)
+  // so a registry that is slow to expose the provider is retried without
+  // hammering it, while a one-off blip still recovers quickly.
+  const failBackoff = Math.min(
+    PROVIDERS_FAIL_TTL_MS * Math.pow(2, Math.max(0, v2LimitsFailCount - 1)),
+    V2_LIMITS_MAX_BACKOFF_MS,
+  );
+  if (now - v2LimitsFailAt < failBackoff) return; // recent failure
   if (v2LimitsInFlight) return v2LimitsInFlight; // dedup parallel callers
   v2LimitsInFlight = (async () => {
     try {
@@ -1927,7 +1960,13 @@ async function ensureModelLimits(ctx) {
       );
       const models = Array.isArray(res) ? res : res?.data;
       if (!Array.isArray(models)) {
+        v2LimitsFailCount++;
         v2LimitsFailAt = Date.now(); // malformed payload -> retry soon
+        const seeded = hydrateModelLimitsFromState();
+        logErr(
+          "model.list returned no model array — limits unavailable, will retry",
+          { payloadType: typeof res, hydratedFromState: seeded },
+        );
         return;
       }
       let found = 0;
@@ -1964,11 +2003,36 @@ async function ensureModelLimits(ctx) {
       // An empty / limit-less payload right after boot (registry not ready yet)
       // must NOT be cached as success, or limits would stay unknown for the
       // full TTL — treat it as a soft failure and retry after the fail gate.
-      if (found > 0) v2LimitsLoadedAt = Date.now();
-      else v2LimitsFailAt = Date.now();
+      if (found > 0) {
+        v2LimitsLoadedAt = Date.now();
+        v2LimitsFailCount = 0; // recovered
+      } else {
+        // Soft failure: the registry answered but carried no usable limit for
+        // any model (provider not registered yet, or `limit` absent). Log WHY
+        // once per backoff window, and fall back to the shared snapshot so
+        // denominators do not vanish meanwhile.
+        const withLimit = models.filter(
+          (m) => m?.limit && typeof m.limit === "object",
+        ).length;
+        const withProvider = models.filter(
+          (m) => m?.providerID || m?.provider?.id,
+        ).length;
+        const seeded = hydrateModelLimitsFromState();
+        v2LimitsFailCount++;
+        v2LimitsFailAt = Date.now();
+        logErr(
+          "model.list yielded 0 usable limits — retrying",
+          { models: models.length, withLimit, withProvider, hydratedFromState: seeded },
+        );
+      }
     } catch (err) {
-      v2LimitsFailAt = Date.now(); // failed attempt -> short retry gate
-      logErr("model.list failed", err);
+      v2LimitsFailCount++;
+      v2LimitsFailAt = Date.now(); // failed attempt -> backoff gate
+      const seeded = hydrateModelLimitsFromState();
+      logErr(
+        `model.list failed (hydrated ${seeded} limit(s) from state.json)`,
+        err,
+      );
     } finally {
       v2LimitsInFlight = null;
     }
@@ -2377,6 +2441,115 @@ function readStateSnapshot() {
   }
 }
 
+// Seed `modelLimits` from previously persisted state.json entries. state.json is
+// a SHARED cross-instance snapshot rewritten at every live step, so it carries a
+// model's window even when THIS instance's ctx.model.list() came back empty (a
+// cold instance, or one whose model registry did not expose the provider).
+// Without this, a transient list miss degraded every denominator to "?" — and
+// because writeStateFile used to rewrite usable/limit from the (empty) in-memory
+// map, the degradation became permanent.
+//
+// The snapshot also holds history: during an earlier outage some instances wrote
+// a WRONG usable window (e.g. 168000 instead of 1015808). A naive
+// first-match seed would then re-inject that stale garbage. Therefore, per
+// `<provider>:<model>`:
+//   * candidates are sanity-filtered (drop `usable >= limit`, `usable <= 0`);
+//   * when any candidate carries a precise `usable`, only those are considered;
+//   * the FRESHEST (max `updatedAt`) candidate wins;
+//   * a divergent spread (max > 3× min usable) is logged for diagnosis.
+// Strictly additive: real in-memory records always win (never overwritten).
+// Returns the number of records seeded.
+function hydrateModelLimitsFromState() {
+  try {
+    const all = readStateSnapshot();
+    // Group candidate entries by key first, so "freshest" is decided against
+    // ALL records of that model — not the first one encountered.
+    const byKey = new Map(); // key -> [ { usable, limit, updatedAt } ]
+    for (const entry of Object.values(all)) {
+      const providerID =
+        typeof entry?.providerID === "string" ? entry.providerID : "";
+      const modelID = entry?.model;
+      const key = modelKey(providerID, modelID);
+      if (!key || !modelID || modelID === "unknown") continue;
+      if (modelLimits.has(key)) continue; // a real in-memory record always wins
+      const usable =
+        typeof entry?.usable === "number" && entry.usable > 0
+          ? entry.usable
+          : null;
+      const limit =
+        typeof entry?.limit === "number" && entry.limit > 0 ? entry.limit : null;
+      if (usable == null && limit == null) continue;
+      let arr = byKey.get(key);
+      if (!arr) {
+        arr = [];
+        byKey.set(key, arr);
+      }
+      arr.push({
+        usable,
+        limit,
+        updatedAt: typeof entry?.updatedAt === "string" ? entry.updatedAt : "",
+      });
+    }
+
+    let added = 0;
+    for (const [key, candidates] of byKey) {
+      // (b) Sanity: drop impossible records (usable >= limit, usable <= 0).
+      // Candidates without a usable (context-only) are kept as-is.
+      const sane = candidates.filter(
+        (c) =>
+          c.usable == null ||
+          (c.usable > 0 && (c.limit == null || c.usable <= c.limit)),
+      );
+      if (sane.length === 0) continue; // every record was impossible -> skip
+
+      // (a) Prefer the precise variant (a recorded usable) when any exists.
+      const precise = sane.filter((c) => c.usable != null);
+      const pool = precise.length > 0 ? precise : sane;
+
+      // (1) Freshest wins (ISO timestamps compare lexicographically).
+      let best = pool[0];
+      for (const c of pool) {
+        if (String(c.updatedAt) > String(best.updatedAt)) best = c;
+      }
+
+      // (c) Diagnostic: a >3× spread means the snapshot is polluted by a
+      // limited/fallback instance — log the numbers once for this model.
+      const usables = pool.map((c) => c.usable).filter((u) => u != null);
+      if (usables.length > 1) {
+        const max = Math.max(...usables);
+        const min = Math.min(...usables);
+        if (min > 0 && max / min > 3) {
+          logErr(
+            `limit seed spread for ${key} — using freshest`,
+            { min, max, candidates: pool.length, chosen: best.usable ?? best.limit },
+          );
+        }
+      }
+
+      // Build the record: precise usable-as-input when known (so getUsableContext
+      // re-derives EXACTLY the persisted window), else the raw context window.
+      let rec = null;
+      if (best.usable != null) {
+        rec = { context: best.limit, input: best.usable, output: null, reserved: 0 };
+      } else if (best.limit != null) {
+        rec = { context: best.limit, input: null, output: null, reserved: null };
+      }
+      if (rec == null) continue;
+      modelLimits.set(key, rec);
+      added++;
+      // (3) One seed line per model: chosen value + provenance.
+      console.log(
+        `[context-indicator] limit seed ${key} -> usable=${
+          best.usable != null ? best.usable : best.limit
+        } (from ${best.updatedAt || "unknown"}, ${pool.length} candidates)`,
+      );
+    }
+    return added;
+  } catch {
+    return 0;
+  }
+}
+
 // True when a state.json entry carries no measured tokens at all: a session
 // registered (session.created) but with no served step. `writeStateFile` always
 // persists `categories` as an object, so the emptiness test must SUM those
@@ -2767,6 +2940,29 @@ async function commandContextBreakdown(ctx, invocation, opts) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// Named exports for the prepublish unit harness (test/prepublish.mjs).
+// These are module-level const variables that the harness needs to mutate
+// (modelLimits, sessionAgentCache, etc.) and functions it needs to call
+// directly (hydrateModelLimitsFromState, writeStateFile, etc.).
+// The plugin itself works without any of these — they are additive.
+// ---------------------------------------------------------------------------
+export {
+  modelLimits,
+  sessionAgentCache,
+  sessionParentCache,
+  writeStateFile,
+  hydrateModelLimitsFromState,
+  getUsableContext,
+  getModelLimit,
+  collectSessionReport,
+  renderSessionRow,
+  shortSummaryText,
+  shortSummaryDescription,
+  ensureModelLimits,
+  readStateSnapshot,
+};
+
 // ---------------------------------------------------------------------------
 // Entrypoints
 // ---------------------------------------------------------------------------
@@ -2796,6 +2992,10 @@ export default {
     // to the generic 200k default), so the transform is not used for limit
     // population.
 
+    // Seed limits from the shared snapshot FIRST: another instance may already
+    // have resolved them, so a cold start never shows "?" denominators.
+    hydrateModelLimitsFromState();
+
     // Fire-and-forget prefetch of effective model limits.
     ensureModelLimits(ctx).catch((err) =>
       logErr("model limits prefetch failed", err),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-context-indicator",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Real-time OpenCode context-window usage indicator: per-category token breakdown written to a log file, plus an optional TUI sidebar. Dual V1 + V2 plugin entry.",
   "type": "module",
   "license": "MIT",
@@ -31,9 +31,14 @@
     "access": "public"
   },
   "author": "VladSmr",
-  "repository": { "type": "git", "url": "git+https://github.com/VladSmr/opencode-context-indicator.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/VladSmr/opencode-context-indicator.git"
+  },
   "homepage": "https://github.com/VladSmr/opencode-context-indicator#readme",
-  "bugs": { "url": "https://github.com/VladSmr/opencode-context-indicator/issues" },
+  "bugs": {
+    "url": "https://github.com/VladSmr/opencode-context-indicator/issues"
+  },
   "peerDependencies": {
     "@opencode/plugin": ">=2.0.16",
     "@opentui/core": ">=0.5.12",
@@ -56,6 +61,14 @@
   "devDependencies": {
     "@opencode/plugin": "^2.0.19",
     "@opentui/core": "^0.5.12",
+    "esbuild": "^0.28.2",
+    "node-pty": "^1.1.0",
     "solid-js": "^1.9.12"
-  }
+  },
+  "scripts": {
+    "test:prepublish": "node test/prepublish.mjs",
+    "test:e2e": "node test/e2e-tui.mjs --full",
+    "test:e2e:quick": "node test/e2e-tui.mjs --quick"
+  },
+  "prepublishOnly": "node test/prepublish.mjs && node test/e2e-tui.mjs --full"
 }

package/tui.tsx

@@ -45,7 +45,9 @@ import {tmpdir} from "node:os"
 import {join} from "node:path"
 import {fileURLToPath} from "node:url"
 
-const STATE_FILE = join(tmpdir(), "opencode-context-indicator-state.json")
+const STATE_FILE =
+  process.env.OPENCODE_CONTEXT_INDICATOR_STATE_FILE ||
+  join(tmpdir(), "opencode-context-indicator-state.json")
 const POLL_MS = 1000
 const LABEL_WIDTH = 12