kira-glasses-bridge 2.31.0 → 2.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-glasses-bridge",
-  "version": "2.31.0",
+  "version": "2.32.0",
   "description": "Connects your Mac to Kira, the assistant for Even G2 glasses: Claude Code sessions, files, folders and apps, by voice.",
   "type": "module",
   "bin": {

package/src/agents/agent-usage.mjs

@@ -0,0 +1,87 @@
+// A run's usage, whichever agent it is: how full its thread's context is ({ used, window }) and the
+// person's plan limits (AgentLimits, packages/genui/src/wire/agentUsage.ts), as the protocol's `usage`
+// event, and the words a run fails with when a limit stops it: which limit, and when it resets (and that
+// window, as the run's stats.limitHit, for the card that offers the other agent). Each
+// agent reads its own reports into these shapes (claude-usage.mjs, codex-usage.mjs).
+
+/** A window's name: "5-hour", "weekly", "weekly Opus". */
+function windowName({ minutes, model }) {
+  const length = lengthName(minutes)
+  return model ? `${length} ${model}` : length
+}
+
+function lengthName(minutes) {
+  if (minutes === 7 * 24 * 60) return 'weekly'
+  if (minutes && minutes < 24 * 60) return `${Math.round(minutes / 60)}-hour`
+  return minutes ? `${Math.round(minutes / (24 * 60))}-day` : 'usage'
+}
+
+/** Every window the limits have: the plan's two, then each model's own. */
+const windowsOf = limits => [limits?.primary, limits?.secondary, ...(limits?.models ?? [])].filter(Boolean)
+
+/** The fullest window, the one that most likely stopped a run. */
+export const fullestOf = limits => windowsOf(limits).sort((a, b) => b.usedPercent - a.usedPercent)[0] ?? null
+
+/** "at 3:10 PM" today, "on Tue at 9:05 AM" otherwise, in this Mac's own way of saying times. */
+function resetWords(resetsAt, now) {
+  const at = new Date(resetsAt * 1000)
+  const time = at.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })
+  if (at.toDateString() === new Date(now).toDateString()) return `at ${time}`
+  return `on ${at.toLocaleDateString([], { weekday: 'short', month: 'short', day: 'numeric' })} at ${time}`
+}
+
+/**
+ * Which limit is used up and when it resets: "your 5-hour ChatGPT limit is used up (100%). It resets
+ * at 3:10 PM." (`plan` names whose: "ChatGPT", "Claude"; a model's own window names the model instead.)
+ */
+export function usedUpWords(window, plan, now = Date.now()) {
+  const when = window.resetsAt ? resetWords(window.resetsAt, now) : 'later'
+  const whose = window.model ? windowName(window) : `${windowName(window)} ${plan}`
+  return `your ${whose} limit is used up (${Math.round(window.usedPercent)}%). It resets ${when}.`
+}
+
+const pctOf = c => (c ? Math.round((c.used / c.window) * 100) : null)
+
+/**
+ * A run's usage feed: given the context and limits as they change, it emits a `usage` event with the
+ * latest of both, only when what a person sees changes (a whole percent of context, a limit), not on
+ * every token count.
+ */
+export function usageFeed(emit) {
+  let context = null
+  let limits = null
+  let limitHit = null
+  let sent = ''
+  const send = () => {
+    if (!context && !limits) return
+    const key = JSON.stringify([pctOf(context), limits])
+    if (key === sent) return
+    sent = key
+    emit({ kind: 'usage', context, limits })
+  }
+  return {
+    /** The context now (null: not known, the last one stands). */
+    context(next) {
+      context = next ?? context
+      send()
+    },
+    /** The limits now, whole (null: not known, the last ones stand). */
+    limits(next) {
+      limits = next ?? limits
+      if (limits) send()
+    },
+    /** The limits known so far, to merge an update over and for the words a run fails with. */
+    get known() {
+      return limits
+    },
+    /** A run stopped ({ error, hit } from an agent's stoppedBy): keeps the window that stopped it. */
+    stopped({ error, hit }) {
+      limitHit = hit ?? limitHit
+      return error
+    },
+    /** What the run ends with, for its stats: `limitHit` is the window that stopped it, if one did. */
+    get stats() {
+      return { ...(context ? { context } : {}), ...(limits ? { limits } : {}), ...(limitHit ? { limitHit } : {}) }
+    },
+  }
+}

package/src/agents/claude-local.mjs

@@ -1,7 +1,11 @@
-// Claude Code on this Mac, as the person signed in to it: which account it uses, the permission
-// rules in their own settings, and one piece of text written with that sign-in (complete.mjs).
+// Claude Code on this Mac, as the person signed in to it: which account it uses, its plan's usage
+// limits, the permission rules in their own settings, and one piece of text written with that sign-in
+// (complete.mjs).
 import { execFile } from 'node:child_process'
 import { readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { query } from '@anthropic-ai/claude-agent-sdk'
+import { limitsFromUsage } from './claude-usage.mjs'
 import { FOLDERS } from '../config-folders.mjs'
 import { completeText } from './complete.mjs'
 
@@ -28,6 +32,43 @@ async function claudeAccount() {
   )
 }
 
+/**
+ * The person's plan limits as a Claude Code session reads them: the data behind its /usage (the SDK's
+ * experimental structured answer; an older SDK or CLI without it gives none). No model call.
+ */
+export async function planLimits(q) {
+  const ask = q.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET
+  if (typeof ask !== 'function') return null
+  return limitsFromUsage(await ask.call(q, { skipBehaviors: true }).catch(() => null))
+}
+
+const LIMITS_MS = 15_000
+
+/**
+ * Their plan limits outside a run, for the composer: a session opened only to ask (its prompt never
+ * comes, so nothing is sent to a model), closed once it has answered.
+ */
+async function claudeLimits() {
+  let release
+  const never = (async function* () {
+    await new Promise(resolve => (release = resolve))
+  })()
+  const abortController = new AbortController()
+  const timer = setTimeout(() => abortController.abort(), LIMITS_MS)
+  const env = { ...process.env, ENABLE_CLAUDEAI_MCP_SERVERS: 'false' }
+  const bin = process.env.KIRA_CLAUDE_BIN ? { pathToClaudeCodeExecutable: process.env.KIRA_CLAUDE_BIN } : {}
+  // None of their settings or MCP servers: it only asks (a second, not three).
+  const quiet = { settingSources: [], strictMcpConfig: true }
+  const q = query({ prompt: never, options: { cwd: homedir(), env, abortController, ...quiet, ...bin } })
+  try {
+    return { limits: await planLimits(q) }
+  } finally {
+    clearTimeout(timer)
+    release?.()
+    q.close()
+  }
+}
+
 /** The permissions block of a Claude Code settings file, as written there (nothing when it has none). */
 export function permissionsIn(settings) {
   const p = settings?.permissions ?? {}
@@ -48,6 +89,7 @@ async function claudePermissions() {
 
 export const claudeTools = {
   claude_account: claudeAccount,
+  claude_limits: claudeLimits,
   claude_permissions: claudePermissions,
   complete_text: completeText,
 }

package/src/agents/claude-usage.mjs

@@ -0,0 +1,116 @@
+// How full a Claude Code session is and how much of the person's Claude plan is left, from the Agent
+// SDK: `getContextUsage()` (the context, as /context counts it), the structured /usage answer (the
+// plan, its 5-hour and weekly windows, each model's own weekly window, extra usage) and
+// `rate_limit_event` messages as a run goes. Read into the shapes every agent sends (agent-usage.mjs),
+// and the words a run fails with when a limit stops it. Pure.
+import { fullestOf, usedUpWords } from './agent-usage.mjs'
+
+const FIVE_HOURS = 300
+const WEEK = 7 * 24 * 60
+
+/** The context the session fills: its tokens out of the window Claude Code measures against. */
+export function contextFrom(usage) {
+  const window = usage?.rawMaxTokens || usage?.maxTokens
+  return window > 0 && typeof usage.totalTokens === 'number' ? { used: usage.totalTokens, window } : null
+}
+
+/** A /usage window ({ utilization: 0-100, resets_at: ISO }) as Kira sends it. */
+function windowOf(w, minutes, model = null) {
+  if (typeof w?.utilization !== 'number') return null
+  const at = w.resets_at ? Date.parse(w.resets_at) : NaN
+  const resetsAt = Number.isNaN(at) ? null : Math.round(at / 1000)
+  return { usedPercent: w.utilization, resetsAt, minutes, ...(model ? { model } : {}) }
+}
+
+/** Each model's own weekly window: the server's list, else the older Opus and Sonnet fields. */
+function modelWindows(r) {
+  const listed = Array.isArray(r.model_scoped) ? r.model_scoped : null
+  const named = listed
+    ? listed.map(w => windowOf(w, WEEK, w.display_name || 'Model'))
+    : [windowOf(r.seven_day_opus, WEEK, 'Opus'), windowOf(r.seven_day_sonnet, WEEK, 'Sonnet')]
+  return named.filter(Boolean)
+}
+
+/** Extra usage, from minor units (cents) to the currency's own. */
+function extraOf(x) {
+  if (!x) return null
+  const unit = 10 ** (Number.isInteger(x.decimal_places) ? x.decimal_places : 2)
+  const major = n => (typeof n === 'number' ? n / unit : null)
+  const currency = x.currency ?? null
+  return { enabled: !!x.is_enabled, used: major(x.used_credits), limit: major(x.monthly_limit), currency }
+}
+
+/** The /usage answer (`usage_EXPERIMENTAL…()`) as Kira's limits; null when no plan limits apply (an API key). */
+export function limitsFromUsage(answer) {
+  const r = answer?.rate_limits
+  if (!answer?.rate_limits_available || !r) return null
+  return {
+    account: 'claude',
+    primary: windowOf(r.five_hour, FIVE_HOURS),
+    secondary: windowOf(r.seven_day, WEEK),
+    models: modelWindows(r),
+    credits: null,
+    extra: extraOf(r.extra_usage),
+    plan: answer.subscription_type ?? null,
+  }
+}
+
+/** Where each `rateLimitType` of an event goes in Kira's limits. */
+const SLOTS = {
+  five_hour: { slot: 'primary', minutes: FIVE_HOURS },
+  seven_day: { slot: 'secondary', minutes: WEEK },
+  seven_day_opus: { slot: 'models', minutes: WEEK, model: 'Opus' },
+  seven_day_sonnet: { slot: 'models', minutes: WEEK, model: 'Sonnet' },
+}
+
+const EMPTY = { account: 'claude', primary: null, secondary: null, models: [], credits: null, extra: null, plan: null }
+
+/** One window of an event (utilization 0-1, resetsAt in seconds) set into the limits. */
+function setWindow(limits, type, { utilization, resetsAt, rejected }) {
+  const at = SLOTS[type]
+  if (!at) return limits
+  const prev = at.slot === 'models' ? limits.models.find(w => w.model === at.model) : limits[at.slot]
+  const said = typeof utilization === 'number' ? Math.round(utilization * 100) : rejected ? 100 : null
+  // An event's fraction is coarser than /usage's percent: within a point of the same window, what's known stands.
+  const same = prev && (resetsAt ?? prev.resetsAt) === prev.resetsAt
+  const usedPercent = said === null || (same && Math.abs(said - prev.usedPercent) <= 1) ? prev?.usedPercent : said
+  if (typeof usedPercent !== 'number') return limits
+  const window = { usedPercent, resetsAt: resetsAt ?? prev?.resetsAt ?? null, minutes: at.minutes }
+  if (at.slot !== 'models') return { ...limits, [at.slot]: window }
+  return { ...limits, models: [...limits.models.filter(w => w.model !== at.model), { ...window, model: at.model }] }
+}
+
+/**
+ * A `rate_limit_event` merged over what was known: the windows it carries (its `unifiedWindows` when
+ * the CLI sends them, and the one its `rateLimitType` names), the rest as they were.
+ */
+export function limitsFromEvent(info, prev = null) {
+  if (!info) return prev
+  let limits = { ...EMPTY, ...prev, models: prev?.models ?? [] }
+  for (const [type, w] of Object.entries(info.unifiedWindows ?? {})) limits = setWindow(limits, type, w ?? {})
+  if (info.rateLimitType) {
+    const rejected = info.status === 'rejected'
+    limits = setWindow(limits, info.rateLimitType, { ...info, rejected })
+  }
+  return limits
+}
+
+/** The window an event says is used up, to name it when the run stops. */
+export function rejectedWindow(info, limits) {
+  if (info?.status !== 'rejected' || !SLOTS[info.rateLimitType]) return null
+  const at = SLOTS[info.rateLimitType]
+  return at.slot === 'models' ? limits?.models?.find(w => w.model === at.model) : limits?.[at.slot]
+}
+
+/**
+ * What a run says when it ends on an error (`error`): for a usage limit (Claude Code's words start with
+ * one of `limitPrefixes`), which one and when it resets; else Claude Code's own words. `hit`: the
+ * window that stopped it, when a limit did and it's known.
+ */
+export function stoppedBy(said, { limits, rejected, limitPrefixes = [] }, now = Date.now()) {
+  const text = String(said ?? 'error').trim()
+  if (!limitPrefixes.some(p => text.startsWith(p))) return { error: `Claude stopped: ${text.slice(0, 300)}`, hit: null }
+  const full = rejected ?? fullestOf(limits)
+  if (!full) return { error: `Claude stopped: ${text}`, hit: null }
+  return { error: `Claude stopped: ${usedUpWords(full, 'Claude', now)}`, hit: full }
+}

package/src/agents/claude.mjs

@@ -1,6 +1,7 @@
 // Claude Code as an agent, through the Agent SDK. Runs in this process on the
 // user's Mac with their own Claude login; files never leave the machine.
-import { query } from '@anthropic-ai/claude-agent-sdk'
+import { USAGE_LIMIT_ERROR_PREFIXES, query } from '@anthropic-ai/claude-agent-sdk'
+import { usageFeed } from './agent-usage.mjs'
 import {
   NOT_ANOTHER_WAY,
   TEXT_CAP,
@@ -10,6 +11,8 @@ import {
   toRequest,
 } from './claude-calls.mjs'
 import { kiraDecides } from './checks.mjs'
+import { planLimits } from './claude-local.mjs'
+import { contextFrom, limitsFromEvent, rejectedWindow, stoppedBy } from './claude-usage.mjs'
 import { sdkOptionsFor } from './settings.mjs'
 import { kiraPluginOptions } from '../kira-plugin.mjs'
 
@@ -42,6 +45,11 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
   let error = null
   /** What Kira's rules said about each tool call, by its id, for the question if Claude Code asks. */
   const verdicts = new Map()
+  /** How full the session is and the person's limits, as they change (claude-usage.mjs). */
+  const usage = usageFeed(e => io.emit(e))
+  /** The limit a rate_limit_event said is used up, and the last turn whose context was read. */
+  let rejected = null
+  let turn = null
 
   /** Refused before it runs: the job shows why, and Claude is told (`told`, when it needs more). */
   const refuse = (tool, reason, told = reason) => {
@@ -127,11 +135,21 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
       if (m.type === 'system' && m.subtype === 'init') {
         session = m.session_id ?? session
         io.emit({ kind: 'session', sessionId: session, model: m.model ?? null })
+        // The plan's windows, each model's own and extra usage (events carry only some of them).
+        void planLimits(q).then(limits => usage.limits(limits))
+      } else if (m.type === 'rate_limit_event') {
+        usage.limits(limitsFromEvent(m.rate_limit_info, usage.known))
+        rejected = rejectedWindow(m.rate_limit_info, usage.known) ?? rejected
       } else if (m.type === 'system' && m.subtype === 'task_started') {
         if (m.is_backgrounded && m.tool_use_id) orphans.set(m.tool_use_id, m.description ?? m.subagent_type ?? 'task')
       } else if (m.type === 'system' && m.subtype === 'task_notification') {
         if (m.tool_use_id) orphans.delete(m.tool_use_id)
       } else if (m.type === 'assistant') {
+        // A new turn of the main thread: how full the context is now, as /context counts it (no model call).
+        if (!nested && m.message?.id && m.message.id !== turn) {
+          turn = m.message.id
+          usage.context(contextFrom(await q.getContextUsage({ detail: 'summary' }).catch(() => null)))
+        }
         for (const b of m.message?.content ?? []) {
           // A subagent's narration is for its parent, not the user; its actions still show what is going on while the Subtask runs.
           if (b.type === 'text' && b.text?.trim() && !nested) io.emit({ kind: 'message', text: short(b.text, TEXT_CAP) })
@@ -147,14 +165,18 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
         }
       } else if (m.type === 'result') {
         session = m.session_id ?? session
-        if (m.subtype === 'success') text = String(m.result ?? '')
+        // A turn that ended on an API error (a usage limit among them) is a success carrying the error.
+        const limit = { limits: usage.known, rejected, limitPrefixes: USAGE_LIMIT_ERROR_PREFIXES }
+        if (m.subtype === 'success' && !m.is_error) text = String(m.result ?? '')
+        else if (m.subtype === 'success') error = usage.stopped(stoppedBy(m.result, limit))
         else error = `Claude stopped: ${m.subtype}${Array.isArray(m.errors) && m.errors.length ? ` (${m.errors.join('; ').slice(0, 300)})` : ''}`
         // Work left running in the background dies with this process; say so rather than let "still running" stand as the outcome.
         if (orphans.size) {
           const note = `${orphans.size} background ${orphans.size === 1 ? 'task was' : 'tasks were'} still running when Claude ended its turn (${[...orphans.values()].slice(0, 5).join(', ')}); they were stopped with the session and their findings are not in this report. Send a follow-up to have that work done inline.`
           text = text ? `${text}\n\n(${note})` : `(${note})`
         }
-        const stats = { durationMs: m.duration_ms, turns: m.num_turns, costUsd: m.total_cost_usd }
+        // How full the session ended and the limits it last saw (claude-usage.mjs), beside the run's own.
+        const stats = { durationMs: m.duration_ms, turns: m.num_turns, costUsd: m.total_cost_usd, ...usage.stats }
         io.emit({ kind: 'result', ok: !error, text: short(text, TEXT_CAP), error, sessionId: session, stats })
         return { ok: !error, text, error, sessionId: session, stats }
       }

package/src/agents/codex-usage.mjs

@@ -1,7 +1,8 @@
 // How full a Codex thread is and how much of the person's ChatGPT plan is left, from Codex's app
 // server: `thread/tokenUsage/updated` (the context), `account/rateLimits/read` and
 // `account/rateLimits/updated` (the limits). Becomes the protocol's `usage` event, and the words a run
-// fails with when a limit stops it: which limit, and when it resets.
+// fails with when a limit stops it: which limit, and when it resets (agent-usage.mjs).
+import { fullestOf, usageFeed as agentUsageFeed, usedUpWords } from './agent-usage.mjs'
 
 /** A window as Kira sends it: { usedPercent, resetsAt (Unix seconds), minutes }. */
 const windowOf = w =>
@@ -28,6 +29,7 @@ export function limitsOf(snapshot, prev = null) {
   const c = snapshot.credits
   const credits = c ? { has: !!c.hasCredits, unlimited: !!c.unlimited, balance: c.balance ?? null } : null
   return {
+    account: 'chatgpt',
     primary: windowOf(snapshot.primary) ?? prev?.primary ?? null,
     secondary: windowOf(snapshot.secondary) ?? prev?.secondary ?? null,
     credits: credits ?? prev?.credits ?? null,
@@ -35,67 +37,35 @@ export function limitsOf(snapshot, prev = null) {
   }
 }
 
-/** A window's name: "5-hour", "weekly". */
-function windowName(minutes) {
-  if (minutes === 7 * 24 * 60) return 'weekly'
-  if (minutes && minutes < 24 * 60) return `${Math.round(minutes / 60)}-hour`
-  return minutes ? `${Math.round(minutes / (24 * 60))}-day` : 'usage'
-}
-
 const LIMIT_ERRORS = new Set(['usageLimitExceeded', 'rateLimitExceeded'])
 
-/** What a run says when it stops: which limit stopped it and when it resets, else Codex's own words. */
+/**
+ * What a run says when it stops (`error`): which limit stopped it and when it resets, else Codex's own
+ * words; and the window that stopped it (`hit`), when a limit did and it's known.
+ */
 export function stoppedBy(turnError, limits, now = Date.now()) {
   const said = `Codex stopped: ${turnError?.message ?? 'error'}`
-  if (!LIMIT_ERRORS.has(turnError?.codexErrorInfo)) return said
-  const full = [limits?.primary, limits?.secondary].filter(Boolean).sort((a, b) => b.usedPercent - a.usedPercent)[0]
-  if (!full) return `Codex stopped: you've reached your ChatGPT usage limit. ${turnError.message ?? ''}`.trim()
-  const when = full.resetsAt ? resetWords(full.resetsAt, now) : 'later'
-  const name = windowName(full.minutes)
-  return `Codex stopped: your ${name} ChatGPT limit is used up (${full.usedPercent}%). It resets ${when}.`
-}
-
-/** "at 3:10 PM" today, "on Tue at 9:05 AM" otherwise, in this Mac's own way of saying times. */
-function resetWords(resetsAt, now) {
-  const at = new Date(resetsAt * 1000)
-  const time = at.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })
-  if (at.toDateString() === new Date(now).toDateString()) return `at ${time}`
-  return `on ${at.toLocaleDateString([], { weekday: 'short', month: 'short', day: 'numeric' })} at ${time}`
+  if (!LIMIT_ERRORS.has(turnError?.codexErrorInfo)) return { error: said, hit: null }
+  const full = fullestOf(limits)
+  const reached = `Codex stopped: you've reached your ChatGPT usage limit. ${turnError.message ?? ''}`
+  if (!full) return { error: reached.trim(), hit: null }
+  return { error: `Codex stopped: ${usedUpWords(full, 'ChatGPT', now)}`, hit: full }
 }
 
-const pctOf = c => (c ? Math.round((c.used / c.window) * 100) : null)
-
-/**
- * A run's usage: fed Codex's notifications, it emits a `usage` event with the latest of both, only
- * when what a person sees changes (a whole percent of context, a limit), not on every token count.
- */
+/** A run's usage, fed Codex's notifications (agent-usage.mjs sends it). */
 export function usageFeed(emit) {
-  let context = null
-  let limits = null
-  let sent = ''
-  const send = () => {
-    if (!context && !limits) return
-    const key = JSON.stringify([pctOf(context), limits])
-    if (key === sent) return
-    sent = key
-    emit({ kind: 'usage', context, limits })
-  }
+  const feed = agentUsageFeed(emit)
   return {
-    onTokens(tokenUsage) {
-      context = contextOf(tokenUsage) ?? context
-      send()
-    },
-    onLimits(snapshot) {
-      limits = limitsOf(snapshot, limits)
-      if (limits) send()
-    },
+    onTokens: tokenUsage => feed.context(contextOf(tokenUsage)),
+    onLimits: snapshot => feed.limits(limitsOf(snapshot, feed.known)),
     /** The limits known so far, for the words a run fails with. */
     get limits() {
-      return limits
+      return feed.known
     },
+    stopped: feed.stopped,
     /** What the run ends with, for its stats. */
     get stats() {
-      return { ...(context ? { context } : {}), ...(limits ? { limits } : {}) }
+      return feed.stats
     },
   }
 }

package/src/agents/codex.mjs

@@ -111,11 +111,11 @@ async function run({ prompt, attachments, sessionId, cwd, persona, settings, abo
     } else if (method === 'account/rateLimits/updated') {
       usage.onLimits(p.rateLimits)
     } else if (method === 'error' && !p.willRetry) {
-      error = stoppedBy(p.error, usage.limits)
+      error = usage.stopped(stoppedBy(p.error, usage.limits))
     } else if (method === 'turn/completed' && p.turn?.id === turnId) {
       const t = p.turn
       steering.ended()
-      if (t.status === 'failed') error = stoppedBy(t.error ?? { message: 'failed' }, usage.limits)
+      if (t.status === 'failed') error = usage.stopped(stoppedBy(t.error ?? { message: 'failed' }, usage.limits))
       if (t.status === 'interrupted') error = 'Stopped by the user.'
       finished({ durationMs: t.durationMs ?? undefined })
     }

package/src/agents/protocol.mjs

@@ -13,10 +13,12 @@
 //   action_result    { kind, id, ok, preview? }
 //   request          { kind, request: AgentRequest }        needs a person; the job waits
 //   request_resolved { kind, id, answer, by }              by: voice | lens | phone | portal | timeout | policy
-//   usage            { kind, context: {used,window} | null, limits: CodexLimits | null }   Codex: how full its
-//                      thread is and the person's ChatGPT limits ({primary,secondary: {usedPercent,resetsAt,minutes},
-//                      credits, plan}), the latest of both each time one changes (codex-usage.mjs)
-//   result           { kind, ok, text?, error?, sessionId?, stats? }
+//   usage            { kind, context: {used,window} | null, limits: AgentLimits | null }   how full the thread
+//                      is and the person's plan limits ({account, primary, secondary, models: [...], credits,
+//                      extra, plan}; each window {usedPercent,resetsAt,minutes,model?}), the latest of both each
+//                      time one changes (agent-usage.mjs; Claude Code: claude-usage.mjs, Codex: codex-usage.mjs)
+//   result           { kind, ok, text?, error?, sessionId?, stats? }   stats: the agent's own, and its last
+//                      context and limits, and limitHit (the window, as above) when a usage limit stopped it
 //
 // Any event with an id may come first as `transient: true` (live.mjs): what is still being written,
 // sent live as it changes and never stored. The next event with the same id that isn't transient is