usage-reporter

1// usage-reporter: keeps the weekly (seven_day) limit reading seen after each main-thread turn
2// and, only when configured, POSTs it hourly while this Claude Code session runs.
3//   observe -> turn.complete, after `next(e)`, main thread only
4//   answer  -> /usage-reporter
5//   timer   -> one `$.clock.every(HOUR)` per load; a hot reload cancels the old one
6import { atom, read, update } from 'claude-code'
7import type { EngineInterface, Register, Timer } from 'claude-code'
8
9import type { UsageReporterState } from '../types'
10import { HOUR, describeStatus, hourlySender, observe, readConfig } from './report'
11import type { Io } from './report'
12
13const NAME = 'usage-reporter'
14const reporter = atom({ plugin: 'usage-reporter', key: 'reporter' } as const, {} as UsageReporterState)
15
16const io = ($: EngineInterface): Io => ({
17  now: () => $.clock.now(),
18  fetch: (url, init) => $.http.fetch(url, init),
19  load: () => read($, reporter),
20  save: fn => update($, reporter, fn),
21})
22
23export const register: Register = (on, options) => {
24  const config = readConfig(options)
25  // Per load: session.start runs once per load, so these never outlive this module.
26  let timer: Timer | undefined
27  let tick: ReturnType<typeof hourlySender> | undefined
28
29  on('session.start', async ($, e, next) => {
30    await $.command.register({ name: NAME, description: 'Show the weekly limit reading and reporting status' })
31    if (config.kind === 'invalid') $.ui.status(`${NAME}: setup error, see /${NAME}`)
32    timer?.cancel()
33    tick ??= hourlySender(io($), config)
34    const runTick = tick
35    timer = $.clock.every(HOUR, () => {
36      void runTick().catch(() => $.ui.log(`${NAME}: tick failed (request details hidden)`, { to: 'debug' }))
37    })
38    return next(e)
39  })
40
41  on('turn.complete', async ($, e, next) => {
42    const result = await next(e)
43    if (!e.agentId) {
44      try {
45        await observe(io($), (await $.session.usage()).rateLimits)
46      } catch {
47        await update($, reporter, s => ({ ...s, weekly: undefined, unreadable: { reason: 'could not read usage' } }))
48          .catch(() => $.ui.log(`${NAME}: could not clear unavailable usage`, { to: 'debug' }))
49        $.ui.log(`${NAME}: could not read usage (details hidden)`, { to: 'debug' })
50      }
51    }
52    return result
53  })
54
55  on('command.run', { command: NAME }, async $ => ({
56    text: describeStatus(config, await read($, reporter), await $.clock.now()),
57  }))
58}
59

1// usage-reporter's logic, kept free of `$` so tests can drive it with a fake clock,
2// fetch and store. register.ts wires it to `$.clock`, `$.http` and `$.state`.
3import type { HttpInit, HttpResponse, PluginOptions, SessionRateLimit } from 'claude-code'
4
5import type { UsageReporterState, UsageReporterWeekly } from '../types'
6
7export const HOUR = 3_600_000
8const WEEKLY_KIND = 'seven_day'
9
10export type Config =
11  | { kind: 'disabled' }
12  | { kind: 'invalid'; problems: string[] }
13  | { kind: 'ready'; url: string; origin: string; accountId: string; token: string }
14
15export type Io = {
16  now: () => Promise<number>
17  fetch: (url: string, init: HttpInit) => Promise<HttpResponse>
18  load: () => Promise<UsageReporterState>
19  save: (fn: (s: UsageReporterState) => UsageReporterState) => Promise<unknown>
20}
21
22// The plugin's userConfig, checked. Off unless `enabled` is true and every field is usable.
23export function readConfig(options: PluginOptions): Config {
24  if (options.enabled !== true) return { kind: 'disabled' }
25  const problems: string[] = []
26  const rawUrl = typeof options.postUrl === 'string' ? options.postUrl.trim() : ''
27  const accountId = typeof options.accountId === 'string' ? options.accountId.trim() : ''
28  const token = typeof options.postToken === 'string' ? options.postToken.trim() : ''
29  let url: URL | undefined
30  if (!rawUrl) problems.push('postUrl is not set')
31  else {
32    try {
33      url = new URL(rawUrl)
34    } catch {
35      problems.push('postUrl is not a valid URL')
36    }
37    if (url && url.protocol !== 'https:') problems.push('postUrl must use https')
38    if (url && (url.username || url.password)) problems.push('postUrl must not carry user:password; use postToken')
39  }
40  if (!accountId) problems.push('accountId is not set')
41  if (!token) problems.push('postToken is not set')
42  if (/[\r\n]/.test(token)) problems.push('postToken must be one line')
43  if (problems.length || !url) return { kind: 'invalid', problems }
44  return { kind: 'ready', url: url.href, origin: url.origin, accountId, token }
45}
46
47// The seven_day window from a usage reading, or why there is none. Never a made-up 0.
48export function weeklyFrom(
49  rateLimits: readonly SessionRateLimit[] | undefined,
50): { ok: true; percentUsed: number; resetsAt: string | null } | { ok: false; reason: string } {
51  const week = rateLimits?.find(r => r.kind === WEEKLY_KIND)
52  if (!week) return { ok: false, reason: 'no seven_day window in the last API response' }
53  const p = week.percentUsed
54  if (typeof p !== 'number' || !Number.isFinite(p) || p < 0 || p > 100) {
55    return { ok: false, reason: `seven_day percentUsed out of range: ${String(p)}` }
56  }
57  const ms = typeof week.resetsAt === 'string' ? Date.parse(week.resetsAt) : NaN
58  return { ok: true, percentUsed: p, resetsAt: Number.isFinite(ms) ? new Date(ms).toISOString() : null }
59}
60
61// After a main-thread turn: record what the cached usage says, stamped with when we looked.
62export async function observe(io: Io, rateLimits: readonly SessionRateLimit[] | undefined) {
63  const at = new Date(await io.now()).toISOString()
64  const week = weeklyFrom(rateLimits)
65  await io.save(s =>
66    week.ok
67      ? { ...s, weekly: { percentUsed: week.percentUsed, resetsAt: week.resetsAt, observedAt: at }, unreadable: undefined }
68      : { ...s, weekly: undefined, unreadable: { at, reason: week.reason } },
69  )
70}
71
72export function isStale(weekly: UsageReporterWeekly, now: number) {
73  const resetMs = weekly.resetsAt ? Date.parse(weekly.resetsAt) : NaN
74  return now - Date.parse(weekly.observedAt) >= HOUR || now >= resetMs
75}
76
77export function reportBody(weekly: UsageReporterWeekly) {
78  return {
79    weekly_usage_percent: weekly.percentUsed,
80    weekly_resets_at: weekly.resetsAt,
81  }
82}
83
84// One hourly tick: POST the last observed reading, or do nothing when not set up or nothing observed.
85// The outcome lands in state; a failure waits for the next tick, never a retry loop.
86export async function send(io: Io, config: Config) {
87  if (config.kind !== 'ready') return
88  const { weekly, lastSuccess } = await io.load()
89  if (!weekly) return
90  const now = await io.now()
91  // The provided receiver contract has no source timestamp field. Do not make
92  // old or already submitted observations appear newly collected on the site.
93  if (!weekly.resetsAt || isStale(weekly, now) || lastSuccess?.observedAt === weekly.observedAt) return
94  const at = new Date(now).toISOString()
95  const headers: Record<string, string> = { 'content-type': 'application/json' }
96  if (config.token) headers.authorization = `Bearer ${config.token}`
97  try {
98    const res = await io.fetch(config.url, { method: 'POST', headers, body: JSON.stringify(reportBody(weekly)) })
99    await io.save(s =>
100      res.ok
101        ? { ...s, lastPost: { at, ok: true, status: res.status }, lastSuccess: { at, status: res.status, observedAt: weekly.observedAt } }
102        : { ...s, lastPost: { at, ok: false, status: res.status, error: `HTTP ${res.status}` } },
103    )
104  } catch {
105    // Transport errors can contain request headers or capability URLs.
106    await io.save(s => ({ ...s, lastPost: { at, ok: false, error: 'network request failed (receiver credentials hidden)' } }))
107  }
108}
109
110// Keep one request in flight even if a receiver takes longer than an hourly period.
111export function hourlySender(io: Io, config: Config) {
112  let inFlight = false
113  return async () => {
114    if (inFlight) return
115    inFlight = true
116    try {
117      await send(io, config)
118    } finally {
119      inFlight = false
120    }
121  }
122}
123
124// What /usage-reporter prints. Shows the receiver's origin only: its path may be a capability.
125export function describeStatus(config: Config, s: UsageReporterState, now: number) {
126  const lines = ['usage-reporter']
127  const w = s.weekly
128  if (w) {
129    lines.push(`Weekly limit: ${w.percentUsed}% used, resets ${w.resetsAt ?? 'unknown (not in the API response)'}`)
130    lines.push(`Observed: ${w.observedAt} (${age(now - Date.parse(w.observedAt))} ago, locally after a turn; not a server update time)`)
131    if (w.resetsAt && now >= Date.parse(w.resetsAt)) lines.push('Reset time has passed: the reading is out of date until the next turn.')
132    if (!w.resetsAt) lines.push('Reporting waits for a known weekly reset time.')
133    else if (isStale(w, now)) lines.push('Reporting waits for a fresh observation; old readings are not re-submitted as new collections.')
134    if (s.lastSuccess?.observedAt === w.observedAt) lines.push('This observation has already been reported; waiting for the next main-thread turn.')
135  } else {
136    lines.push('Weekly limit: unknown, no seven_day reading observed yet (it arrives after a turn on a subscription)')
137  }
138  if (s.unreadable) lines.push(`Last turn without a reading${s.unreadable.at ? ` at ${s.unreadable.at}` : ''}: ${s.unreadable.reason}`)
139  if (config.kind === 'disabled') lines.push('Reporting: off (enabled is false). Nothing is sent.')
140  else if (config.kind === 'invalid') lines.push(`Reporting: setup error, nothing is sent: ${config.problems.join('; ')}`)
141  else lines.push(`Reporting: hourly POST to ${config.origin} (path hidden) as account ${config.accountId}`)
142  const p = s.lastPost
143  if (!p) lines.push('Last POST: none yet')
144  else if (p.ok) lines.push(`Last POST: ok (${p.status}) at ${p.at}`)
145  else lines.push(`Last POST: failed at ${p.at}: ${p.error}; retries at the next hourly tick`)
146  if (s.lastSuccess && !p?.ok) lines.push(`Last success: ${s.lastSuccess.at} (${s.lastSuccess.status})`)
147  return lines.join('\n')
148}
149
150function age(ms: number) {
151  const min = Math.max(0, Math.floor(ms / 60_000))
152  return min < 60 ? `${min} min` : `${Math.floor(min / 60)} h ${min % 60} min`
153}
154

1// The mod's state contract: every `$.state` value the module names, under the mod's name.
2// `observedAt` is when this mod read the cached usage after a turn, not a provider timestamp.
3export type UsageReporterWeekly = { percentUsed: number; resetsAt: string | null; observedAt: string }
4
5export type UsageReporterState = {
6  weekly?: UsageReporterWeekly
7  unreadable?: { at?: string; reason: string }
8  lastPost?: { at: string; ok: boolean; status?: number; error?: string }
9  lastSuccess?: { at: string; status: number; observedAt: string }
10}
11
12declare module 'claude-code' {
13  interface PluginState {
14    'usage-reporter': { reporter: UsageReporterState }
15  }
16}
17