opencode-context-indicator 1.1.6 → 1.2.1

package/README.md

@@ -8,8 +8,13 @@ filling it: system prompt, tool schemas, user/assistant text, reasoning, tool
 arguments and the residual "other" bucket.
 
 The package ships a **dual V1 + V2 plugin** (one entry works in both OpenCode
-generations) plus an optional TUI sidebar module exposed as the `./tui` entry.
-The V2 path is **tested against opencode v2.0.21**; the V1 path against 1.18.29+.
+generations) plus an optional TUI module (`./tui` entry) that renders a **live
+sidebar** and a **zero-LLM `/cx` breakdown panel** with measured contributors
+and a redacted export. The V2 path is **tested against opencode v2.0.25**; the
+V1 path against 1.18.29+.
+
+> **V1 is feature-frozen.** It is kept working for compatibility (bug fixes
+> only); all new features land in the V2 path.
 
 ![TUI sidebar — per-category context breakdown](docs/sidebar.png)
 
@@ -38,11 +43,21 @@ For every served request the plugin estimates how the context window is split:
   (Cyrillic ≈ 2.5, CJK ≈ 1.5, latin/ASCII ≈ 4 chars/token) — not a tokenizer.
   `reasoning` also carries the exact value reported by the model when present.
 * `other` is the residual (`input − sum of estimates`).
-* Tool **results** are deliberately not counted; only tool **call arguments**
-  (results are not part of the sent prompt).
+* Tool **results** are deliberately not counted in the server-side categories;
+  only tool **call arguments** are. The TUI panel's *largest contributors*
+  section **does** measure retained results — that is why it can explain the
+  (often large) residual `other` bucket.
 * `ctx` is OpenCode's native overflow count: `tokens.total` when present, else
   `input + output + cache.read + cache.write`. Percentages are **not clamped**
   at 100% — exceeding the window stays visible.
+* The denominator is the **opencode v2.0.23 compaction ceiling**: `window =
+  limit.input || limit.context`; `reserve = max(floor(window * 0.1), window >=
+  32_000 ? 16_000 : 0)`; the ceiling is `window - reserve`. When opencode
+  carries a `compaction.buffer` configured in its own settings, the plugin
+  cannot read that value (it is not exposed to plugins), so the default
+  reserve formula is used — set `OPENCODE_CONTEXT_INDICATOR_COMPACT_BUFFER`
+  to override the reserve for testing or custom setups (positive integer <=
+  1e9; invalid values are silently ignored).
 
 ### Toast (V1 only)
 
@@ -218,23 +233,57 @@ back to a plain notice if needed.
   is evicted by the `state.json` LRU cap (`MAX_TRACKED_SESSIONS`) — it may
   momentarily appear in the table.
 
+### TUI session panel (V2, terminal only)
+
+#### TUI panel (/cx) — zero-LLM breakdown
+
+`/cx` opens a full `session.panel` showing the breakdown for the current session
+**and its subagent descendants**, read from the same `state.json` bridge as the
+sidebar. Keys: `/cx` opens, `esc` closes, `r` refreshes (re-read the bridge),
+`e` exports a redacted snapshot.
+
+**Zero LLM calls.** Unlike `/context` and `/context-breakdown` (which run a real
+agent turn so the model renders the table), the panel only reads local TUI data
+and the state file; it never wakes the session and never grows the context.
+
+The **largest contributors (measured)** section char-counts the in-process
+message list and labels each row `assistant 21:04 reasoning — 4.5k "…"`: role
+in full words, the message's own clock time, the bucket (`reasoning` /
+`tool args (bash)` / `tool result (task)`), the token estimate and a bounded
+one-line preview of that part. Tool calls are measured **per tool call** (each
+carries its tool name); tool **result outputs** are counted here but not by the
+server's categories — which is why the residual `other` can look large. Top 5
+are shown. Empty state: `no messages yet`.
+
+Live only for a `file://` install from a path outside `node_modules`; the npm
+path auto-disables it (upstream `#33884`). The Desktop has no TUI, so it uses
+`/context` and `/context-breakdown` instead.
+
+#### Export (redacted)
+
+`e` writes a redacted JSON snapshot — no message text, no full session id, no
+tool output content — under `%TEMP%/opencode-context-indicator/exports/`
+(`$TMPDIR/...` elsewhere), named `context-<id8>-<yyyymmdd-HHMMSSmmm>.json`, and
+shows a toast with the file name. It never throws; on failure it logs and shows
+an error toast.
+
 ---
 
 ## Surface matrix
 
-| Surface | Toast | TUI sidebar | Breakdown log file | Slash commands |
-| --- | :---: | :---: | :---: | :---: |
-| OpenCode **1.x** — Desktop | ✅ | — | ✅ | — |
-| OpenCode **1.x** — TUI | ✅ | — | ✅ | — |
-| OpenCode **2.x** — TUI | — | ✅ | ✅ | ✅ |
-| OpenCode **2.x** — Desktop | — | — | ✅ | ✅ |
+| Surface | Toast | TUI sidebar | TUI panel (/cx) | Breakdown log file | Slash commands |
+| --- | :---: | :---: | :---: | :---: | :---: |
+| OpenCode **1.x** — Desktop | ✅ | — | — | ✅ | — |
+| OpenCode **1.x** — TUI | ✅ | — | — | ✅ | — |
+| OpenCode **2.x** — TUI | — | ✅ | ✅ | ✅ | ✅ |
+| OpenCode **2.x** — Desktop | — | — | — | ✅ | ✅ |
 
 Notes — these reflect what the plugin API actually exposes today:
 
 * **V2 has no toast channel on the server side.** The V2 plugin API
   (`ctx.*`) exposes no TUI/toast method (opencode issue `#49380`); the V2 path
-  therefore delivers everything through the log file, the TUI sidebar and the
-  `/context` / `/context-breakdown` slash commands. The sidebar is a TUI-process
+  therefore delivers everything through the log file, the TUI sidebar, the
+  `/cx` session panel and the `/context` / `/context-breakdown` slash commands. The sidebar is a TUI-process
   slot and does not exist in the Desktop app; the slash commands work in **both**.
   The TUI sidebar is **live only for a `file://` install** from a path outside
   `node_modules`; on the npm path it is auto-disabled (upstream `#33884`) — see
@@ -255,7 +304,7 @@ and `$TMPDIR` (usually `/tmp`) elsewhere:
 | File | Purpose |
 | --- | --- |
 | `context-breakdown.log` | Human-readable live snapshot + bounded final summaries |
-| `opencode-context-indicator-state.json` | Machine-readable snapshot consumed by the TUI sidebar |
+| `opencode-context-indicator-state.json` | Machine-readable snapshot consumed by the TUI sidebar and the `/cx` panel. Fields per entry: `sessionID`, `parentID`, `role`, `agent`, `model`, `providerID`, `ctx`, `input`, `usable` (compaction ceiling), `reserve` (tokens reserved for compaction), `limit` (context window), `reasoning`, `categories{user,assistant,reasoning,toolArgs,system,toolSchemas,other}`, `updatedAt`. |
 | `context-events.log` | Raw event tap — **only** when `DEBUG_EVENTS` is flipped to `true` in the source (off by default) |
 
 The live `context-breakdown.log` snapshot is **rewritten** (never grows); final
@@ -306,15 +355,15 @@ limitation (`anomalyco/opencode#33884`), not a plugin bug: OpenCode's TUI loader
 skips the host Solid transform for any path inside a `node_modules` directory, so
 a slot mounted from an npm install renders once and then never live-updates.
 
-| Install | Desktop | TUI commands | TUI live sidebar |
-| --- | :---: | :---: | :---: |
-| npm (`opencode plugin add opencode-context-indicator`) | ✅ | ✅ | ❌ auto-disabled (upstream #33884) |
-| `file://` (path **outside** any `node_modules`) | ✅ | ✅ | ✅ live |
+| Install | Desktop | TUI commands | TUI live sidebar | TUI panel (/cx) |
+| --- | :---: | :---: | :---: | :---: |
+| npm (`opencode plugin add opencode-context-indicator`) | ✅ | ✅ | ❌ auto-disabled (upstream #33884) | ❌ auto-disabled |
+| `file://` (path **outside** any `node_modules`) | ✅ | ✅ | ✅ live | ✅ live |
 
 On the **npm** path the plugin detects that it lives under `node_modules` and
-**disables the sidebar gracefully** — it logs a single hint and registers no
-slot, so you never see a frozen "no data yet" panel. The `/context` /
-`/context-breakdown` slash commands and the breakdown log file keep working on
+**disables the sidebar and the panel gracefully** — it logs a single hint and
+registers no slot, so you never see a frozen "no data yet" panel. The `/context`
+/ `/context-breakdown` slash commands and the breakdown log file keep working on
 every install.
 
 #### Getting the live sidebar (`file://` install)
@@ -350,13 +399,21 @@ Add the package name to the `plugin` array in your `opencode.json`:
 
 ### Local file (no npm)
 
-Copy `index.js` and `lib/dedup.js` into `~/.config/opencode/plugins/`, keeping
-the `lib/` subdirectory next to the plugin file so the plugin's `import` of the
-helper resolves. The `lib/` folder is support code, not a separate plugin entry:
+Copy `index.js` and the whole `lib/` directory into
+`~/.config/opencode/plugins/`, keeping the `lib/` subdirectory next to the
+plugin file so the plugin's relative imports resolve. The `lib/` folder is
+support code, not a separate plugin entry:
 
 ```
 ~/.config/opencode/plugins/context-indicator.js
+~/.config/opencode/plugins/lib/cache.js
+~/.config/opencode/plugins/lib/commands.js
 ~/.config/opencode/plugins/lib/dedup.js
+~/.config/opencode/plugins/lib/estimate.js
+~/.config/opencode/plugins/lib/limits.js
+~/.config/opencode/plugins/lib/state.js
+~/.config/opencode/plugins/lib/v1.js
+~/.config/opencode/plugins/lib/v2.js
 ```
 
 To use the sidebar locally as well, point OpenCode at a `file://` copy of the
@@ -372,19 +429,21 @@ the sidebar instead.
 * **Node.js ≥ 18** (the main plugin uses only Node built-ins). `@opencode/plugin`
   is an **optional** peer dependency: OpenCode resolves it at runtime, and
   `index.js` itself does not import it (the V2 `define` helper is inlined).
-* **OpenCode ≥ 1.18.29** for the V1 path. ⚠️ The V1 path relies on
-  `experimental.chat.*` hooks, which are **experimental** and may change or stop
-  firing in future OpenCode 1.x releases; if they do, the indicator degrades
+* **OpenCode ≥ 1.18.29** for the V1 path. ⚠️ **V1 is feature-frozen** — it
+  receives bug fixes only; all new features land in the V2 path. The V1 path
+  relies on `experimental.chat.*` hooks, which are **experimental** and may
+  change or stop firing in future OpenCode 1.x releases; if they do, the
+  indicator degrades
   gracefully (the breakdown falls back to throttled `session.messages` fetches
   and toasts keep working).
 * **OpenCode ≥ 2.0.16** for the V2 path (built and verified against
-  **2.0.21**).
+  **2.0.25**).
 * **TUI sidebar**: terminal TUI only, requires the OpenTUI rendering stack that
   ships with OpenCode. `@opentui/core` and `solid-js` are **optional** peer
   dependencies resolved by OpenCode at runtime; the main plugin installs and runs
   fine without them (the sidebar simply is not available). `@opentui/solid` is
-  instead shipped as a **pinned direct dependency** (exact `0.5.14`, matching
-  the OpenTUI stack OpenCode 2.0.21 ships): OpenCode's
+  instead shipped as a **pinned direct dependency** (exact `0.5.16`, matching
+  the OpenTUI stack OpenCode 2.0.25 ships): OpenCode's
   TUI loader does not expose a host instance of it, so for npm-installed plugins
   the JSX pragma would otherwise fail to resolve `@opentui/solid/jsx-runtime`
   (upstream: opencode issue #33884 — `node_modules` plugins are excluded from the
@@ -420,7 +479,10 @@ The package default export is a dual plugin:
   experimental transform hooks + toasts.
 
 Both paths write the same breakdown log; the V2 path additionally feeds the
-sidebar through `opencode-context-indicator-state.json`. Cross-instance
+sidebar and the `/cx` panel through `opencode-context-indicator-state.json`.
+The `./tui` entry (OpenCode 2.x terminal TUI) renders the sidebar slot and the
+`session.panel` contribution (`/cx`), with measured per-part contributors and
+the redacted export. Cross-instance
 duplicate final summaries are suppressed with an atomic claim marker
 (`lib/dedup.js`). Every file / estimate / subagent path is fault-tolerant: a
 failure is logged and never breaks the main event or toast path.
@@ -430,14 +492,6 @@ This plugin does not touch `opencode-token-monitor`
 
 ---
 
-## Screenshots
-
-<!-- TODO: add screenshots -->
-
-_(to be added)_
-
----
-
 ## Contributing
 
 Issues and pull requests are welcome. Please keep changes minimal and
@@ -468,10 +522,12 @@ STEP 80 s, ~3 min total.
 
 | Step | What | Why |
 |---|---|---|
-| (a) tarball composition | `package.json` `files[]` field expands to exactly 6 members | no test/node_modules/tsconfig in the tarball |
+| (a) tarball composition | `package.json` `files[]` expands to the base files plus every `lib/*` module (count asserted dynamically) | 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 |
+| (e) corporate-identifier scan | no forbidden identifiers in the published surface + test tree | compliance |
+| (f) non-English scan | no non-ASCII letters (`\p{L}` above U+007F) in any repo file | English-only source rule |
 
 **Isolated E2E — `test/e2e-tui.mjs`** (requires the OpenCode CLI)
 

package/index.js

@@ -112,8 +112,8 @@
  *   Every live/final log write ALSO rewrites
  *     %TEMP%\opencode-context-indicator-state.json   (os.tmpdir())
  *   — a machine-readable { sessionID: { model, providerID, ctx, usable,
- *     limit, categories{...}, updatedAt } } snapshot consumed by the optional
- *   TUI sidebar in ./tui.tsx (package entry "./tui"). Written atomically
+ *     reserve, limit, categories{...}, updatedAt } } snapshot consumed by the
+ *   optional TUI sidebar in ./tui.tsx (package entry "./tui"). Written atomically
  *   (temp + rename), keyed by session, bounded to MAX_TRACKED_SESSIONS, and
  *   strictly additive: any failure is swallowed and never affects the log.
  *
@@ -123,9 +123,10 @@
  *
  *   - Metric: the native opencode overflow count — tokens.total when present,
  *     else input + output + cache.read + cache.write — compared against the
- *     model's usable window (limit.input − reserved, else limit.context −
- *     maxOutput). Percentages are NOT clamped at 100% — exceeding the window
- *     must stay visible.
+ *     model's compaction ceiling (opencode v2.0.23 calculateCeiling): window =
+  *     limit.input || limit.context, reserve = max(10% of window, 16k when
+  *     window >= 32k), usable = window - reserve. Percentages are NOT
+  *     clamped at 100% - exceeding the ceiling must stay visible.
  *   - Category estimates use a unicode-aware heuristic (see estimateTokens):
  *     Cyrillic ~2.5 chars/token, CJK ~1.5, latin/ASCII ~4. These are ESTIMATES,
  *     not a tokenizer; "other" is the residual input − sum of estimates.
@@ -165,6 +166,7 @@ import {
   getUsableContext,
   hydrateModelLimitsFromState,
   modelLimits,
+  reserveFor,
 } from "./lib/limits.js";
 import { sessionAgentCache, sessionParentCache } from "./lib/cache.js";
 import {
@@ -189,6 +191,7 @@ export {
   hydrateModelLimitsFromState,
   getUsableContext,
   getModelLimit,
+  reserveFor,
   collectSessionReport,
   renderSessionRow,
   shortSummaryText,

package/lib/commands.js

@@ -272,6 +272,12 @@ async function collectSessionReport(ctx, sessionID, state, deadline) {
   const usableInfo = getUsableContext(providerID, modelID);
   const usable =
     usableInfo?.usable ?? entry?.usable ?? getModelLimit(providerID, modelID) ?? null;
+  const reserve =
+    usableInfo?.reserved != null
+      ? usableInfo.reserved
+      : Number.isFinite(entry?.reserve) && entry.reserve > 0
+        ? entry.reserve
+        : null;
   const parentID = entry?.parentID ?? null;
   const updatedAt =
     entry?.updatedAt ||
@@ -284,6 +290,7 @@ async function collectSessionReport(ctx, sessionID, state, deadline) {
     providerID,
     ctxTokens,
     usable,
+    reserve,
     categories,
     source,
     updatedAt,
@@ -384,6 +391,14 @@ function shortSummaryText(r) {
   } else {
     lines.push("_category breakdown unavailable (no cache/state entry yet)_");
   }
+  // Compact-at line: show the new ceiling and, when known, the reserve.
+  if (r.usable && r.usable > 0) {
+    let compact = `compact at ${fmt(r.usable)}`;
+    if (r.reserve != null && r.reserve > 0) {
+      compact += ` (${fmt(r.reserve)} reserve)`;
+    }
+    lines.push(compact);
+  }
   lines.push(`updated ${timeOnly(r.updatedAt)} (${sourceTag(r.source)})`);
   return lines.join("\n");
 }

package/lib/contributors.js

@@ -0,0 +1,288 @@
+// lib/contributors.js
+//
+// Pure contributor-measurement helpers extracted from tui.tsx for unit testing.
+// All functions are stateless transforms of their arguments.
+//
+// Extracted 1:1 (behaviour + WHY comments, stripped of TS syntax):
+//   estimateTokensLocal, asRecord, safeText, measureContributors,
+//   contributorLine, exportFileName, buildRedactedPayload, panelDenom, panelRole.
+
+// ---------------------------------------------------------------------------
+// Token estimation (mirrors lib/estimate.js but self-contained — tui.tsx
+// loads standalone and must NOT import lib/*).
+// ---------------------------------------------------------------------------
+
+// Unicode heuristic — estimate, not a tokenizer. Cyrillic ~2.5, CJK ~1.5,
+// latin/ASCII ~4 chars/token.
+function estimateTokensLocal(s) {
+  let other = 0;
+  let cyr = 0;
+  let cjk = 0;
+  for (let i = 0; i < s.length; i++) {
+    const cp = s.codePointAt(i);
+    if (cp > 0xffff) i++; // astral pair — consume the low surrogate
+    if (cp < 0x80) other++;
+    else if (
+      (cp >= 0x0400 && cp <= 0x04ff) || // Cyrillic
+      (cp >= 0x0500 && cp <= 0x052f) || // Cyrillic Supplement
+      (cp >= 0x2de0 && cp <= 0x2dff) || // Cyrillic Extended-A
+      (cp >= 0xa640 && cp <= 0xa69f) || // Cyrillic Extended-B
+      (cp >= 0x1c80 && cp <= 0x1c8f) // Cyrillic Extended-C
+    )
+      cyr++;
+    else if (
+      (cp >= 0x4e00 && cp <= 0x9fff) || // CJK Unified Ideographs
+      (cp >= 0x3400 && cp <= 0x4dbf) || // CJK Extension A
+      (cp >= 0xf900 && cp <= 0xfaff) || // CJK Compatibility Ideographs
+      (cp >= 0x3040 && cp <= 0x30ff) || // Hiragana + Katakana
+      (cp >= 0xac00 && cp <= 0xd7af) || // Hangul Syllables
+      (cp >= 0x3000 && cp <= 0x303f) || // CJK Symbols and Punctuation
+      (cp >= 0xff00 && cp <= 0xffef) // Halfwidth/Fullwidth Forms
+    )
+      cjk++;
+    else other++;
+  }
+  return Math.round(other / 4 + cyr / 2.5 + cjk / 1.5);
+}
+
+// Live message data is untrusted: coerce every field defensively, never throw.
+function asRecord(v) {
+  return v && typeof v === "object" ? v : null;
+}
+
+// One-line sanitisation for untrusted labels (agent / model). Drops zero-width
+// + bidi control chars, collapses C0/C1 controls, caps at 32 code points
+// (surrogate-safe). Only labels are ever rendered — never message content.
+function safeText(v) {
+  try {
+    const s = v == null ? "" : String(v);
+    const cleaned = s
+      .replace(/[\u200B-\u200F\u202A-\u202E\u2066-\u2069]/g, "")
+      .replace(/[\u0000-\u001F\u007F-\u009F\u2028\u2029]/g, " ");
+    const cps = Array.from(cleaned);
+    return cps.length > 32 ? cps.slice(0, 31).join("") + "~" : cleaned;
+  } catch {
+    return "";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Contributor measurement
+// ---------------------------------------------------------------------------
+
+// Char counts per (message, bucket). `asst.text` = assistant text,
+// `asst.rsn` = reasoning, `asst.tool` = tool CALL arguments (streaming raw
+// string or JSON.stringify of the input object), `asst.result` = tool RESULT
+// outputs (text content of completed/error tool states). Sorted descending by
+// estimated tokens.
+//
+// Returns an array of plain objects (no class/prototype dependency):
+//   { kind, ref, chars, tokensEstimate, tool, preview }
+function measureContributors(messages) {
+  const out = [];
+  // Bounded preview: control chars collapse to spaces, bidi/zero-width stripped,
+  // capped at 26 code points with a "~" tail. Local rendering only.
+  const previewOf = (sample) => {
+    const cleaned = sample
+      .replace(/[\u200B-\u200F\u202A-\u202E\u2066-\u2069]/g, "")
+      .replace(/[\u0000-\u001F\u007F-\u009F\u2028\u2029]+/g, " ")
+      .trim();
+    const cps = Array.from(cleaned);
+    return cps.length > 26 ? cps.slice(0, 25).join("") + "~" : cleaned;
+  };
+  const add = (kind, ref, sample, tool, previewOverride) => {
+    if (sample.length === 0) return;
+    out.push({
+      kind,
+      ref,
+      chars: sample.length,
+      tokensEstimate: estimateTokensLocal(sample),
+      tool: tool || "",
+      preview: previewOverride !== undefined ? previewOverride : previewOf(sample),
+    });
+  };
+  // Human clock ref: "21:04" from the message's own creation time — far more
+  // actionable than an array ordinal. Falls back to "#N" when time is absent.
+  const hhmm = (ms) => {
+    if (typeof ms !== "number" || !Number.isFinite(ms) || ms <= 0) return "";
+    try {
+      const d = new Date(ms);
+      if (Number.isNaN(d.getTime())) return "";
+      const pad = (x) => String(x).padStart(2, "0");
+      return `${pad(d.getHours())}:${pad(d.getMinutes())}`;
+    } catch {
+      return "";
+    }
+  };
+  for (let i = 0; i < messages.length; i++) {
+    const m = asRecord(messages[i]);
+    if (!m) continue;
+    const timeRec = asRecord(m.time);
+    const ref = hhmm(timeRec && timeRec.created) || `#${i + 1}`;
+    const type = typeof m.type === "string" ? m.type : "";
+    if (type === "user") {
+      if (typeof m.text === "string") add("user.text", ref, m.text);
+      continue;
+    }
+    if (type !== "assistant") continue;
+    const content = Array.isArray(m.content) ? m.content : [];
+    let text = "";
+    let rsn = "";
+    for (const rawPart of content) {
+      const part = asRecord(rawPart);
+      if (!part) continue;
+      const pt = typeof part.type === "string" ? part.type : "";
+      if (pt === "text") {
+        if (typeof part.text === "string") text += part.text;
+      } else if (pt === "reasoning") {
+        if (typeof part.text === "string") rsn += part.text;
+      } else if (pt === "tool") {
+        const state = asRecord(part.state);
+        if (!state) continue;
+        // Per-tool-part contributors: each tool call carries its own name and
+        // measured size (one message can hold several tool calls). The raw
+        // args JSON is measured but NOT previewed — the tool name is the
+        // useful identifier; result text previews fine.
+        const toolName =
+          typeof part.name === "string" && part.name ? safeText(part.name) : "";
+        let toolArgs = "";
+        let result = "";
+        if (typeof state.input === "string") {
+          toolArgs += state.input;
+        } else if (state.input != null) {
+          try {
+            toolArgs += JSON.stringify(state.input) || "";
+          } catch {
+            /* unstringifiable input: skip its chars */
+          }
+        }
+        const c = state.content;
+        if (Array.isArray(c)) {
+          for (const rawItem of c) {
+            const item = asRecord(rawItem);
+            if (item && item.type === "text" && typeof item.text === "string")
+              result += item.text;
+          }
+        }
+        add("asst.tool", ref, toolArgs, toolName, ""); // raw args: no preview
+        add("asst.result", ref, result, toolName);
+      }
+    }
+    add("asst.text", ref, text);
+    add("asst.rsn", ref, rsn);
+  }
+  return out.sort((a, b) => b.tokensEstimate - a.tokensEstimate);
+}
+
+// Human line for one measured contributor: role in full words, the message's
+// own clock time, the bucket (with the tool name for tool buckets), the token
+// estimate, and a bounded single-line preview. Never contains a full session id
+// or file paths.
+function contributorLine(c, rank) {
+  const dot = c.kind.indexOf(".");
+  const who = dot >= 0 ? c.kind.slice(0, dot) : c.kind;
+  const bucket = dot >= 0 ? c.kind.slice(dot + 1) : "";
+  const role = who === "asst" ? "assistant" : who;
+  const what =
+    bucket === "rsn"
+      ? "reasoning"
+      : bucket === "tool"
+        ? "tool args"
+        : bucket === "result"
+          ? "tool result"
+          : "";
+  const tool = c.tool ? ` (${c.tool})` : "";
+  const whatFull = what ? `${what}${tool}` : "";
+  const head = `${rank}. ${role} ${c.ref}${whatFull ? ` ${whatFull}` : ""} \u2014 ${c.tokensEstimate}`;
+  return c.preview ? `${head}  "${c.preview}"` : head;
+}
+
+// ---------------------------------------------------------------------------
+// Redacted export helpers (pure)
+// ---------------------------------------------------------------------------
+
+// Filename for a redacted export snapshot:
+// context-<id8>-<yyyymmdd-HHMMSSmmm>.json
+function exportFileName(sessionID, now) {
+  const id8 = String(sessionID).slice(0, 8);
+  const pad = (n) => String(n).padStart(2, "0");
+  const stamp =
+    `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}` +
+    `-${pad(now.getHours())}${pad(now.getMinutes())}` +
+    `${pad(now.getSeconds())}${String(now.getMilliseconds()).padStart(3, "0")}`;
+  return `context-${id8}-${stamp}.json`;
+}
+
+// Build the redacted export payload. All IO (mkdirSync/writeFileSync) and
+// toasts stay in tui.tsx as the thin exportRedacted() wrapper.
+//
+// Fields: generatedAt, session{id8-prefixed id, model, providerID},
+// family[role/model/ctx/usable/limit/pct/updated], contributors[kind/tool/ref/
+// chars/tokensEstimate].  NO message text, NO full session id, NO tool output
+// content, NO contributor preview text.
+//
+// panelDenom / panelRole are passed as parameters so this file stays pure and
+// tui.tsx controls their source.
+function buildRedactedPayload({ sessionID, root, rows, contributors, now, panelDenom, panelRole, num }) {
+  const id8 = String(sessionID).slice(0, 8);
+  return {
+    generatedAt: now.toISOString(),
+    session: {
+      id: `${id8}...`,
+      model: safeText(root && root.model != null ? root.model : ""),
+      providerID: safeText(root && root.providerID != null ? root.providerID : ""),
+    },
+    family: rows.map((e, i) => {
+      const d = panelDenom(e);
+      const ctxVal = num(e && e.ctx);
+      return {
+        role: panelRole(e, i === 0),
+        model: safeText(e && e.model != null ? e.model : ""),
+        ctx: ctxVal,
+        usable: e && e.usable != null ? num(e.usable) : null,
+        limit: e && e.limit != null ? num(e.limit) : null,
+        pct: d > 0 ? Math.round((ctxVal / d) * 100) : null,
+        updated: safeText(e && e.updatedAt != null ? e.updatedAt : ""),
+      };
+    }),
+    contributors: contributors.map((c) => ({
+      kind: c.kind,
+      tool: c.tool || null,
+      ref: c.ref,
+      chars: c.chars,
+      tokensEstimate: c.tokensEstimate,
+    })),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Panel helpers (pure, shared with tui.tsx)
+// ---------------------------------------------------------------------------
+
+// Per-row denominator with the same fallback cascade as the server table:
+// usable, else limit, else 0.
+function panelDenom(e) {
+  const u = e && typeof e.usable === "number" && e.usable > 0 ? e.usable : 0;
+  if (u > 0) return u;
+  const l = e && typeof e.limit === "number" && e.limit > 0 ? e.limit : 0;
+  return l;
+}
+
+// Role label for a state entry: "main" for root, "sub" or "sub:<agent>" for
+// descendants.
+function panelRole(e, isMain) {
+  if (isMain) return "main";
+  return e && e.agent ? `sub:${safeText(e.agent)}` : "sub";
+}
+
+export {
+  estimateTokensLocal,
+  asRecord,
+  safeText,
+  measureContributors,
+  contributorLine,
+  exportFileName,
+  buildRedactedPayload,
+  panelDenom,
+  panelRole,
+};