thinkpool-pair 0.7.184 → 0.7.185

package/bridge.mjs

@@ -96,6 +96,7 @@ import { formatPeek, PEEK, siblingsOf, resolveSibling, crossPostDecision, CROSSP
 import { turnInFlight } from './update-gate.mjs'
 import { saveSession, flushSession, deleteSession, loadAll, canResume, loadPtyId, savePtyId, loadNames, saveNames, appendDurableEvents, seedDurableEvents, readDurablePage, readDurableOldestSeq } from './session-store.mjs'
 import { stampEvent, makeSeqCounter, maxSeq, seqable, capReplayEvents, chunkReplayEvents, boundEventForBroadcast, inlineImageBlocks, usageReportLine, buildRecapFromLog, RECAP_CAP } from './event-id.mjs'
+import { planMeterLine } from './plan-meters.mjs'
 import { makeThrottledTrack } from './presence.mjs'
 
 // Public client creds (the same anon values the web app ships — safe to embed).
@@ -2848,9 +2849,16 @@ channel
     // Computed by REPLAYING the session's own retained result events (each completed turn
     // persists kind:'result' with usage + costUsd + model — see onEvent). No new accumulator
     // state: the log is durable, so this survives a bridge restart for free. Reported as ◆
-    // control lines (like /model) so both members AND late-joiners see it. Scope is honest —
-    // the Agent SDK exposes tokens + cost, not plan/rate-limit meters, and the card says so.
-    if (/^\/usage\s*$/.test(text)) { ctlLine(usageReportLine(s.model, s.log)); return }
+    // control lines (like /model) so both members AND late-joiners see it. Two lines: the
+    // token/cost report (instant, from the retained log), then the plan meters (5h + weekly
+    // utilization + server-authoritative resets) once the OAuth usage endpoint answers. The
+    // meter line is fired-and-forgotten so a slow/unreachable endpoint never stalls /usage;
+    // it degrades to "plan meters unavailable" rather than printing an inferred reset.
+    if (/^\/usage\s*$/.test(text)) {
+      ctlLine(usageReportLine(s.model, s.log))
+      planMeterLine().then((l) => { if (l) ctlLine(l) }).catch(() => { /* meters are never load-bearing */ })
+      return
+    }
     // Context-carry (2026-07-08) point 4: a real human turn arrived BEFORE the post-switch/
     // restore recap fired on init-`system`. Prepend the recap to THIS turn (one turn, not two
     // — a separate recap turn would race + double-fire) and clear the flag so the init handler

package/event-id.mjs

@@ -264,7 +264,10 @@ export function usageReportLine (sessionModel, logEvents) {
   const total = rows.length > 1 ? ` · total ${fmtTok(sum.totalIn)} in / ${fmtTok(sum.totalOut)} out` : ''
   const cost = sum.haveCost ? ` · ~$${sum.totalCost.toFixed(2)} est` : ''
   const turns = `${sum.turns} turn${sum.turns === 1 ? '' : 's'}`
-  return `usage · ${turns} · ${perStr}${total}${cost} · tokens + cost only (no plan/rate-limit meters)`
+  // No "(no plan/rate-limit meters)" tail any more — the handler appends a second control
+  // line from bridge/plan-meters.mjs carrying the real 5h/weekly utilization + resets, or
+  // an explicit "plan meters unavailable". Neither claim belongs on this token/cost line.
+  return `usage · ${turns} · ${perStr}${total}${cost}`
 }
 
 /* The context-carry recap moved to ./recap.mjs (ADR-0010 / S4, 2026-07-09).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thinkpool-pair",
-  "version": "0.7.184",
+  "version": "0.7.185",
   "description": "Share a local coding-agent CLI (Claude Code, Codex, Gemini, Aider, …) into a ThinkPool Code room, live.",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
     "update-gate.mjs",
     "agent-notify.mjs",
     "event-id.mjs",
+    "plan-meters.mjs",
     "recap.mjs",
     "transcript-sanitize.mjs",
     "session-store.mjs",

package/plan-meters.mjs

@@ -0,0 +1,144 @@
+/* Plan / rate-limit meters for the /usage report.
+ *
+ * WHERE THE NUMBERS COME FROM. `GET https://api.anthropic.com/api/oauth/usage`
+ * with the Claude Code OAuth access token — the SAME endpoint the CLI's own /usage
+ * screen reads. So the percentages and, critically, the RESET TIMES are the
+ * server's, not ours. We never infer a 5-hour block boundary from transcript
+ * timestamps (the ccusage approach): an inferred reset is a number that looks
+ * authoritative and is wrong, which is exactly the bug this module exists to avoid.
+ *
+ * READ-ONLY, AND DELIBERATELY SO. We read the access token and we never refresh it.
+ * Refreshing rotates the refresh token; two processes rotating against one credential
+ * store is how the bridge's login died before (memory: thinkpool_bridge_login_headless_recovery).
+ * An expired token therefore degrades to "plan meters unavailable" rather than
+ * quietly re-authenticating behind the user's back.
+ *
+ * DEGRADE HONESTLY. Every failure — no token, non-Claude provider, network error,
+ * 401, shape change, a reset timestamp in the past — returns null, and the caller
+ * prints "plan meters unavailable". A stale or invented meter is worse than no meter.
+ */
+
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+const USAGE_URL = 'https://api.anthropic.com/api/oauth/usage'
+const CACHE_MS = 45_000
+const FETCH_TIMEOUT_MS = 4_000
+
+// ── token ────────────────────────────────────────────────────────────────────
+// macOS keeps Claude Code's credentials in the login keychain; Linux writes
+// ~/.claude/.credentials.json. Same JSON shape either way: { claudeAiOauth: { accessToken } }.
+// Any failure here is a normal, expected state (BYOK lane, API-key auth, logged out).
+export function readOAuthToken (deps = {}) {
+  const {
+    platform = process.platform,
+    env = process.env,
+    exec = execFileSync,
+    read = readFileSync,
+    home = homedir()
+  } = deps
+  if (env.THINKPOOL_OAUTH_TOKEN) return env.THINKPOOL_OAUTH_TOKEN // test/override seam
+  let raw = null
+  try {
+    if (platform === 'darwin') {
+      raw = exec('security', ['find-generic-password', '-s', 'Claude Code-credentials', '-w'],
+        { encoding: 'utf8', timeout: 3000, stdio: ['ignore', 'pipe', 'ignore'] })
+    } else {
+      raw = read(join(home, '.claude', '.credentials.json'), 'utf8')
+    }
+    const tok = JSON.parse(raw)?.claudeAiOauth?.accessToken
+    return (typeof tok === 'string' && tok.startsWith('sk-ant-oat')) ? tok : null
+  } catch { return null }
+}
+
+// ── fetch ────────────────────────────────────────────────────────────────────
+export async function fetchPlanUsage (token, fetchImpl = globalThis.fetch) {
+  if (!token) return null
+  const ac = new AbortController()
+  const timer = setTimeout(() => ac.abort(), FETCH_TIMEOUT_MS)
+  try {
+    const res = await fetchImpl(USAGE_URL, {
+      method: 'GET',
+      headers: { authorization: `Bearer ${token}`, 'anthropic-beta': 'oauth-2025-04-20' },
+      signal: ac.signal
+    })
+    if (!res.ok) return null // 401 (expired) / 403 / 5xx → unavailable, never a guess
+    return await res.json()
+  } catch { return null } finally { clearTimeout(timer) }
+}
+
+// ── format (pure) ────────────────────────────────────────────────────────────
+const DAYS = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat']
+
+// A reset renders in LOCAL time. Beyond ~20h out (the weekly meter) a bare HH:MM is
+// ambiguous, so it carries a weekday. Returns null for an unparseable timestamp OR one
+// already in the past — a past reset means the payload is stale, and printing "resets
+// 10:10" when 10:10 has been and gone is precisely the lie we refuse to tell.
+export function fmtReset (iso, now) {
+  const t = new Date(iso).getTime()
+  if (!Number.isFinite(t) || t <= now.getTime()) return null
+  // ROUND to the nearest minute, don't floor. The endpoint stamps `resets_at` with
+  // sub-second jitter around the true boundary — two calls seconds apart returned
+  // 10:10:00.355Z and 10:09:59.873Z for the same reset. Flooring renders those as
+  // 12:10 and 12:09, so the meter visibly flickers a minute back and forth on a
+  // surface whose whole job is to be the trustworthy number. Observed 2026-07-10.
+  const d = new Date(Math.round(t / 60000) * 60000)
+  const hhmm = `${String(d.getHours()).padStart(2, '0')}:${String(d.getMinutes()).padStart(2, '0')}`
+  return (t - now.getTime()) > 20 * 3600 * 1000 ? `${DAYS[d.getDay()]} ${hhmm}` : hhmm
+}
+
+const fmtIn = (ms) => {
+  const m = Math.max(0, Math.round(ms / 60000))
+  return m >= 60 ? `${Math.floor(m / 60)}h${String(m % 60).padStart(2, '0')}m` : `${m}m`
+}
+
+// Render one block ("5h" / "week") or null if it can't be stated truthfully.
+function block (label, node, now, withRelative) {
+  const pct = node && typeof node.utilization === 'number' ? Math.round(node.utilization) : null
+  if (pct == null) return null
+  const at = fmtReset(node.resets_at, now)
+  if (!at) return `${label}: ${pct}%` // percent is still true even if the reset isn't usable
+  const rel = withRelative ? ` (${fmtIn(new Date(node.resets_at).getTime() - now.getTime())})` : ''
+  return `${label}: ${pct}% · resets ${at}${rel}`
+}
+
+// json → "plan · 5h: 10% · resets 12:10 (1h04m) · week: 26% · resets Tue 11:00"
+// Returns null when nothing truthful can be said, so the caller prints the honest
+// "plan meters unavailable" instead of a half-line.
+export function formatPlanMeters (json, now = new Date()) {
+  if (!json || typeof json !== 'object') return null
+  const parts = [block('5h', json.five_hour, now, true), block('week', json.seven_day, now, false)]
+  // A scoped weekly cap (e.g. a per-model ceiling) only matters while it's the binding
+  // one — surface it, named, so a lane that's about to hit a model-specific wall sees it.
+  const scoped = Array.isArray(json.limits)
+    ? json.limits.find((l) => l && l.is_active && l.kind === 'weekly_scoped' && typeof l.percent === 'number')
+    : null
+  if (scoped) {
+    const name = scoped.scope?.model?.display_name
+    parts.push(`${name ? `week ${name}` : 'week scoped'}: ${Math.round(scoped.percent)}%`)
+  }
+  const live = parts.filter(Boolean)
+  return live.length ? `plan · ${live.join(' · ')}` : null
+}
+
+// ── cached entry point ───────────────────────────────────────────────────────
+let cache = { at: 0, line: null }
+
+// The ONE line bridge.mjs appends under the token/cost line. Cached ~45s so a user
+// spamming /usage doesn't hammer the endpoint. Never throws.
+export async function planMeterLine (deps = {}) {
+  const { now = () => Date.now(), clock = () => new Date(), token = readOAuthToken, fetchUsage = fetchPlanUsage } = deps
+  const t = now()
+  if (cache.line !== null && (t - cache.at) < CACHE_MS) return cache.line
+  let line = 'plan meters unavailable'
+  try {
+    const json = await fetchUsage(token())
+    line = formatPlanMeters(json, clock()) || 'plan meters unavailable'
+  } catch { /* stays unavailable */ }
+  cache = { at: t, line }
+  return line
+}
+
+export function _resetCache () { cache = { at: 0, line: null } } // test seam