Public: anyone can read this; the crew can change it.
A held account's usage is read free from Claude Code's /usage #14388
Check · Review · Land · Live done — Landed and live in production.
usage-check → main 1 commit
10 files
changed +482
−2
src/core/subscriptions.ts +17
| @@ -261,6 +261,23 @@ export function credentialEnvOf( | ||
| 261 | 261 | return accountEnv(picked); |
| 262 | 262 | } |
| 263 | 263 | |
| 264 | /** | |
| 265 | * The credential a run on this sealed account would carry, without picking it (no reservation, no | |
| 266 | * touch): what a free read of its usage needs. Undefined for an unknown account or a token that | |
| 267 | * will not open. | |
| 268 | */ | |
| 269 | export function accountCredential(db: Database, dataDir: string, subscriptionId: string): Record<string, string> | undefined { | |
| 270 | const row = db | |
| 271 | .query<{ kind: string; token_enc: string; api_base: string | null }, [string]>( | |
| 272 | "SELECT kind, token_enc, api_base FROM subscription WHERE id = ?1 AND id <> 'platform'", | |
| 273 | ) | |
| 274 | .get(subscriptionId); | |
| 275 | if (row === null) return undefined; | |
| 276 | const opened = open(dataDir, row.token_enc, aad(subscriptionId)); | |
| 277 | if (!opened.ok) return undefined; | |
| 278 | return accountEnv({ envName: envNameOf(row.kind as SubscriptionKind), token: opened.value, apiBase: row.api_base }); | |
| 279 | } | |
| 280 | ||
| 264 | 281 | export function isSubscriptionName(name: string): boolean { |
| 265 | 282 | return ( |
| 266 | 283 | name.length > 0 && |
src/crew/agent_runner.ts +25
| @@ -13,6 +13,7 @@ import type { RunLimits } from "./run-cell.ts"; | ||
| 13 | 13 | import type { SandboxPolicy } from "./sandbox.ts"; |
| 14 | 14 | import type { ToolNames } from "./brief.ts"; |
| 15 | 15 | import { detectClaude, runClaude } from "./claude.ts"; |
| 16 | import { readClaudeUsage } from "./claude_usage.ts"; | |
| 16 | 17 | import { openaiRunner } from "./openai_runner.ts"; |
| 17 | 18 | |
| 18 | 19 | export interface AgentRun { |
| @@ -146,12 +147,31 @@ export interface AgentRunner { | ||
| 146 | 147 | * says these names; absent, it says the neutral ones (`DEFAULT_TOOLS`). |
| 147 | 148 | */ |
| 148 | 149 | readonly tools?: Partial<ToolNames> | undefined; |
| 150 | /** | |
| 151 | * The account's use of its windows, asked of the provider without a run; null when it could | |
| 152 | * not tell. Optional: a runner without it is measured only by its runs' replies, and a held | |
| 153 | * crew by the one run `week_read.ts`'s probe lets through. | |
| 154 | */ | |
| 155 | readUsage?(input: UsageAsk): Promise<readonly Measure[] | null>; | |
| 156 | } | |
| 157 | ||
| 158 | /** | |
| 159 | * What `readUsage` is handed: the agent, the account's credential as a run carries it, a directory | |
| 160 | * to run in. | |
| 161 | */ | |
| 162 | export interface UsageAsk { | |
| 163 | readonly binary: string; | |
| 164 | readonly env: Record<string, string>; | |
| 165 | readonly cwd: string; | |
| 166 | /** The runner's own signed-in config, when the forge was started with one (`runnerSettings`). */ | |
| 167 | readonly configDir?: string | undefined; | |
| 149 | 168 | } |
| 150 | 169 | |
| 151 | 170 | // Wrapped, not bound, so the two modules may load in either order. |
| 152 | 171 | const claude: AgentRunner = { |
| 153 | 172 | run: (input) => runClaude(input), |
| 154 | 173 | detect: (binary) => detectClaude(binary), |
| 174 | readUsage: (input) => readClaudeUsage(input), | |
| 155 | 175 | }; |
| 156 | 176 | |
| 157 | 177 | let chosen: AgentRunner | undefined; |
| @@ -175,6 +195,11 @@ export function runAgent(input: AgentRun): Promise<AgentOutcome> { | ||
| 175 | 195 | return currentRunner().run(input); |
| 176 | 196 | } |
| 177 | 197 | |
| 198 | /** The current runner's free read of an account's windows; null when it offers none. */ | |
| 199 | export function readUsage(input: UsageAsk): Promise<readonly Measure[] | null> { | |
| 200 | return currentRunner().readUsage?.(input) ?? Promise.resolve(null); | |
| 201 | } | |
| 202 | ||
| 178 | 203 | export function detectAgent(binary: string): Promise<AgentDetection> { |
| 179 | 204 | return currentRunner().detect(binary); |
| 180 | 205 | } |
src/crew/claude_usage.ts added +128
| @@ -0,0 +1,128 @@ | ||
| 1 | /** | |
| 2 | * An account's use of its windows, read from Claude Code's own `/usage` without a run (#14352 | |
| 3 | * lets one run through to re-measure; this asks for free). `claude -p /usage` prints the plan's | |
| 4 | * bars and exits: no model turn, no cost. Only an account on a Claude plan has bars; an API key, | |
| 5 | * a gateway or a refused token prints none, and the read is null. | |
| 6 | * | |
| 7 | * The lines read (Claude Code 2.1.328, `TZ=UTC`): | |
| 8 | * | |
| 9 | * Current session: 41% used · resets 3pm (UTC) | |
| 10 | * Current week (all models): 2% used · resets Nov 22 at 2am (UTC) | |
| 11 | * | |
| 12 | * A model's own week (`Current week (Fable)`) is not the account's and is left out. | |
| 13 | */ | |
| 14 | ||
| 15 | import type { Measure } from "../core/measure.ts"; | |
| 16 | import type { LimitWindow } from "../core/standing.ts"; | |
| 17 | import { childEnv } from "../apps/process.ts"; | |
| 18 | import { quietEnv } from "./runner_env.ts"; | |
| 19 | import type { UsageAsk } from "./agent_runner.ts"; | |
| 20 | ||
| 21 | const MONTHS = [ | |
| 22 | "jan", | |
| 23 | "feb", | |
| 24 | "mar", | |
| 25 | "apr", | |
| 26 | "may", | |
| 27 | "jun", | |
| 28 | "jul", | |
| 29 | "aug", | |
| 30 | "sep", | |
| 31 | "oct", | |
| 32 | "nov", | |
| 33 | "dec", | |
| 34 | ]; | |
| 35 | ||
| 36 | /** How long `/usage` may take before it is stopped and the read is null. */ | |
| 37 | const USAGE_TIMEOUT_MS = 30_000; | |
| 38 | ||
| 39 | /** | |
| 40 | * The reset an `/usage` line names, in UTC: `Nov 22 at 2am (UTC)` or `3:30pm (UTC)`; the next | |
| 41 | * such instant after `now` (a day or a year on when the date has passed). Undefined for any other | |
| 42 | * zone or shape. | |
| 43 | */ | |
| 44 | function resetOf(text: string, now: Date): string | undefined { | |
| 45 | const m = | |
| 46 | /^(?:([A-Za-z]{3})[a-z]* (\d{1,2}),? at )?(\d{1,2})(?::(\d{2}))?\s*(am|pm) \((?:UTC|Etc\/UTC|GMT)\)$/i.exec( | |
| 47 | text.trim(), | |
| 48 | ); | |
| 49 | if (m === null) return undefined; | |
| 50 | const hour12 = Number(m[3]); | |
| 51 | const minute = m[4] === undefined ? 0 : Number(m[4]); | |
| 52 | if (hour12 < 1 || hour12 > 12 || minute > 59) return undefined; | |
| 53 | const hour = (hour12 % 12) + (m[5]!.toLowerCase() === "pm" ? 12 : 0); | |
| 54 | const t = now.getTime(); | |
| 55 | if (m[1] === undefined) { | |
| 56 | let at = Date.UTC( | |
| 57 | now.getUTCFullYear(), | |
| 58 | now.getUTCMonth(), | |
| 59 | now.getUTCDate(), | |
| 60 | hour, | |
| 61 | minute, | |
| 62 | ); | |
| 63 | if (at <= t) at += 24 * 3_600_000; | |
| 64 | return new Date(at).toISOString(); | |
| 65 | } | |
| 66 | const month = MONTHS.indexOf(m[1].toLowerCase()); | |
| 67 | const day = Number(m[2]); | |
| 68 | if (month < 0 || day < 1 || day > 31) return undefined; | |
| 69 | let at = Date.UTC(now.getUTCFullYear(), month, day, hour, minute); | |
| 70 | // The bars name a reset ahead; one a day or more behind is next year's (late December). | |
| 71 | if (at < t - 24 * 3_600_000) | |
| 72 | at = Date.UTC(now.getUTCFullYear() + 1, month, day, hour, minute); | |
| 73 | return new Date(at).toISOString(); | |
| 74 | } | |
| 75 | ||
| 76 | /** | |
| 77 | * The windows `/usage` printed, as measurements observed `now`; empty when it printed no plan bars. | |
| 78 | */ | |
| 79 | export function usageOf(text: string, now: Date): Measure[] { | |
| 80 | const out: Measure[] = []; | |
| 81 | for (const raw of text.split("\n")) { | |
| 82 | const m = | |
| 83 | /^Current (session|week \(all models\)):\s*(\d+(?:\.\d+)?)% used\s*·\s*resets (.+)$/.exec( | |
| 84 | raw.trim(), | |
| 85 | ); | |
| 86 | if (m === null) continue; | |
| 87 | const window: LimitWindow = m[1] === "session" ? "5h" : "week"; | |
| 88 | const usedPct = Number(m[2]); | |
| 89 | const resetsAt = resetOf(m[3]!, now); | |
| 90 | if (!(usedPct >= 0 && usedPct <= 100) || resetsAt === undefined) continue; | |
| 91 | if (out.some((x) => x.window === window)) continue; | |
| 92 | out.push({ window, usedPct, resetsAt, observedAt: now.toISOString() }); | |
| 93 | } | |
| 94 | return out; | |
| 95 | } | |
| 96 | ||
| 97 | /** | |
| 98 | * Ask Claude Code for the account's bars: `claude -p /usage` with the account's credential, in a | |
| 99 | * short environment, the clock in UTC so the resets parse. Null when it fails, times out or | |
| 100 | * prints no bars. Never throws. | |
| 101 | */ | |
| 102 | export async function readClaudeUsage(input: UsageAsk): Promise<Measure[] | null> { | |
| 103 | try { | |
| 104 | const proc = Bun.spawn([input.binary, "-p", "/usage"], { | |
| 105 | cwd: input.cwd, | |
| 106 | env: childEnv({ | |
| 107 | ...quietEnv(), | |
| 108 | ...input.env, | |
| 109 | ...(input.configDir === undefined ? {} : { CLAUDE_CONFIG_DIR: input.configDir }), | |
| 110 | TZ: "UTC", | |
| 111 | }), | |
| 112 | stdin: "ignore", | |
| 113 | stdout: "pipe", | |
| 114 | stderr: "ignore", | |
| 115 | }); | |
| 116 | const timer = setTimeout(() => proc.kill("SIGKILL"), USAGE_TIMEOUT_MS); | |
| 117 | const [text, code] = await Promise.all([ | |
| 118 | new Response(proc.stdout).text(), | |
| 119 | proc.exited, | |
| 120 | ]); | |
| 121 | clearTimeout(timer); | |
| 122 | if (code !== 0) return null; | |
| 123 | const read = usageOf(text, new Date()); | |
| 124 | return read.length === 0 ? null : read; | |
| 125 | } catch { | |
| 126 | return null; | |
| 127 | } | |
| 128 | } |
src/crew/dispatch.ts +6
| @@ -143,6 +143,7 @@ import { stoppedMark } from "../spawn/stopped.ts"; | ||
| 143 | 143 | import { abortAgentRun } from "./running.ts"; |
| 144 | 144 | import { during } from "../perf/jobs.ts"; |
| 145 | 145 | import { threadHeld } from "../perf/held.ts"; |
| 146 | import { recheckUsage } from "./usage_check.ts"; | |
| 146 | 147 | |
| 147 | 148 | const log = createLog("crew"); |
| 148 | 149 | |
| @@ -289,6 +290,8 @@ export async function startCrew( | ||
| 289 | 290 | sweeps.add(sweep); |
| 290 | 291 | void sweep.finally(() => sweeps.delete(sweep)); |
| 291 | 292 | }; |
| 293 | // When each held account's usage was last asked of the provider (`usage_check.ts`). | |
| 294 | const usageAsked = new Map<string, number>(); | |
| 292 | 295 | const timer = setInterval(() => { |
| 293 | 296 | if (stopped) return; |
| 294 | 297 | // A tick that throws is logged and the next one tries again: thrown |
| @@ -305,6 +308,9 @@ export async function startCrew( | ||
| 305 | 308 | track(autonomyTick(app).catch((error) => |
| 306 | 309 | log.error("autonomy tick failed", { error: String(error) }), |
| 307 | 310 | )); |
| 311 | track(recheckUsage(app, ready, usageAsked).catch((error) => | |
| 312 | log.error("usage check failed", { error: String(error) }), | |
| 313 | )); | |
| 308 | 314 | } |
| 309 | 315 | pump(app, ready, inFlight); |
| 310 | 316 | }, undefined, app); |
src/crew/usage_check.ts added +57
| @@ -0,0 +1,57 @@ | ||
| 1 | /** | |
| 2 | * A free check of a held account's usage (2026-11-19). The week is otherwise heard only in the | |
| 3 | * replies to the crew's own runs, and a held crew makes none: `week_read.ts`'s probe lets one run | |
| 4 | * through every twenty minutes to hear it again. Where the runner can ask the provider without a | |
| 5 | * run (`AgentRunner.readUsage`), the crew's tick asks for each account a reading holds, at most | |
| 6 | * every `USAGE_EVERY_MS`, and writes the answer as the newest measurement: an early reset is seen | |
| 7 | * within minutes, and the crew starts again on it. A runner that cannot ask leaves the probe. | |
| 8 | */ | |
| 9 | ||
| 10 | import { tmpdir } from "node:os"; | |
| 11 | import type { App } from "../app.ts"; | |
| 12 | import { noteMeasure } from "../core/measure.ts"; | |
| 13 | import { accountCredential, PLATFORM } from "../core/subscriptions.ts"; | |
| 14 | import { readUsage } from "./agent_runner.ts"; | |
| 15 | import { ownEnv } from "./runner_env.ts"; | |
| 16 | import { forgetWeek, heldAccounts } from "./week_read.ts"; | |
| 17 | ||
| 18 | /** How often one held account is asked again. */ | |
| 19 | const USAGE_EVERY_MS = 3 * 60_000; | |
| 20 | ||
| 21 | /** | |
| 22 | * Ask the provider again about every account a reading holds, each at most every | |
| 23 | * `USAGE_EVERY_MS` (`asked` remembers when, by account), and note what it says. Never on a | |
| 24 | * request: the crew's tick calls it. Resolves to the accounts measured again. | |
| 25 | */ | |
| 26 | export async function recheckUsage( | |
| 27 | app: App, | |
| 28 | runner: { readonly binary: string; readonly configDir?: string | undefined }, | |
| 29 | asked: Map<string, number>, | |
| 30 | now: Date = new Date(), | |
| 31 | read: typeof readUsage = readUsage, | |
| 32 | ): Promise<string[]> { | |
| 33 | const measured: string[] = []; | |
| 34 | for (const id of heldAccounts(app, now)) { | |
| 35 | const last = asked.get(id); | |
| 36 | if (last !== undefined && now.getTime() - last < USAGE_EVERY_MS) continue; | |
| 37 | asked.set(id, now.getTime()); | |
| 38 | const env = | |
| 39 | id === PLATFORM | |
| 40 | ? ownEnv() | |
| 41 | : accountCredential(app.db, app.config.dataDir, id); | |
| 42 | if (env === undefined) continue; | |
| 43 | const got = await read({ | |
| 44 | binary: runner.binary, | |
| 45 | env, | |
| 46 | cwd: tmpdir(), | |
| 47 | ...(id === PLATFORM && runner.configDir !== undefined | |
| 48 | ? { configDir: runner.configDir } | |
| 49 | : {}), | |
| 50 | }); | |
| 51 | if (got === null) continue; | |
| 52 | for (const m of got) noteMeasure(app.db, id, m); | |
| 53 | measured.push(id); | |
| 54 | } | |
| 55 | if (measured.length > 0) forgetWeek(); | |
| 56 | return measured; | |
| 57 | } |
src/crew/week_read.ts +24 −2
| @@ -43,11 +43,16 @@ function weekOf(app: Reads, repo: Repo, now: Date): Week { | ||
| 43 | 43 | return week; |
| 44 | 44 | } |
| 45 | 45 | |
| 46 | function readWeek(app: Reads, repo: Repo, now: Date): Week { | |
| 46 | /** The accounts a repository's crew draws on. */ | |
| 47 | function accountsOf(app: Reads, repo: Repo): string[] { | |
| 47 | 48 | // A crew with no grant runs on the forge's own token: the account `usage` |
| 48 | 49 | // prints as `platform`. It is metered too, never skipped (#8873). |
| 49 | 50 | const granted = grantedAccounts(app.db, repo.id, repo.ownerId).map((a) => a.id); |
| 50 | const accounts = granted.length > 0 ? granted : [PLATFORM]; | |
| 51 | return granted.length > 0 ? granted : [PLATFORM]; | |
| 52 | } | |
| 53 | ||
| 54 | function readWeek(app: Reads, repo: Repo, now: Date): Week { | |
| 55 | const accounts = accountsOf(app, repo); | |
| 51 | 56 | // The provider's own percent of the week used (#8960), never dollars: an |
| 52 | 57 | // account it has not measured, or whose week has reset since, is unknown. |
| 53 | 58 | let usedPct = 0; |
| @@ -149,6 +154,23 @@ export function crewWeekFor(app: Reads, repo: Repo, now: Date): WeekDecision | n | ||
| 149 | 154 | return probed(app, week, weekDecision({ meter: week.meter, now, ceiling: crewCeiling(app, repo), reserve: 1 - weekUse(app.db) / 100 }), now); |
| 150 | 155 | } |
| 151 | 156 | |
| 157 | /** | |
| 158 | * The accounts whose week reading holds the crew now, on any autonomous repository: before the | |
| 159 | * probe's one run, the week leaves no slot. What the free usage check (`usage_check.ts`) asks | |
| 160 | * the provider about again. | |
| 161 | */ | |
| 162 | export function heldAccounts(app: Reads, now: Date): string[] { | |
| 163 | const held = new Set<string>(); | |
| 164 | for (const repo of listAutonomousRepos(app.db)) { | |
| 165 | if (repo.autonomy !== "autonomous" || repo.archivedAt !== null) continue; | |
| 166 | const week = weekOf(app, repo, now); | |
| 167 | const decision = weekDecision({ meter: week.meter, now, ceiling: crewCeiling(app, repo), reserve: 1 - weekUse(app.db) / 100 }); | |
| 168 | if (decision === null || decision.slots > 0) continue; | |
| 169 | for (const id of accountsOf(app, repo)) held.add(id); | |
| 170 | } | |
| 171 | return [...held]; | |
| 172 | } | |
| 173 | ||
| 152 | 174 | /** A sentence saying the crew's cap is lowered, so pacing is not mistaken for it; empty at the ceiling. */ |
| 153 | 175 | function heldWords(app: App): string { |
| 154 | 176 | const held = belowCeiling(app.db, "crew.concurrency"); |
test/spawn-pipes.test.ts +1
| @@ -24,6 +24,7 @@ const PIPING: Record<string, { sites: string[]; reason: string }> = { | ||
| 24 | 24 | "src/spawn/cell.ts": { sites: ["stdout+stderr"], reason: "drain() reads the child forge's stdout and stderr to its log until exit" }, |
| 25 | 25 | "src/chaos/faults.ts": { sites: ["stdout"], reason: "stdout is read until the kill closes it, then cancelled; stderr is ignored" }, |
| 26 | 26 | "src/crew/claude.ts": { sites: ["stdout+stderr", "stdout"], reason: "session pumps stdout and stderr; --version awaits stdout, stderr ignored" }, |
| 27 | "src/crew/claude_usage.ts": { sites: ["stdout"], reason: "/usage stdout awaited with the exit, under a kill timer; stderr ignored" }, | |
| 27 | 28 | "src/crew/openai_runner.ts": { sites: ["stdout+stderr"], reason: "bash() reads stdout and stderr to the end alongside the exit, under a kill timer" }, |
| 28 | 29 | "src/crew/orphans.ts": { sites: ["stdout"], reason: "git stdout is read to its end alongside the exit; stderr ignored" }, |
| 29 | 30 | "src/crew/plan.ts": { sites: ["stdout"], reason: "stdout awaited with the exit; stderr ignored" }, |
test/spawn-sites.test.ts +2
| @@ -37,6 +37,8 @@ const SITES: Record<string, string> = { | ||
| 37 | 37 | "osascript/notify-send with title and body as separate argv elements after the script or `--`, so a repo name stays data", |
| 38 | 38 | "src/crew/claude.ts": |
| 39 | 39 | "the agent binary from configuration with flags the runner fixes; the prompt (a person's issue text) is one argv element after its flag and the binary never hands it to a shell; `--version` probe is fixed", |
| 40 | "src/crew/claude_usage.ts": | |
| 41 | "the agent binary from configuration with the fixed argv `-p /usage`; only the account's credential, in the environment, varies", | |
| 40 | 42 | "src/crew/openai_runner.ts": |
| 41 | 43 | "the Bash tool of the OpenAI-compatible runner: /bin/sh -c with the model's command, which is the point of the tool, run in the run's clone (under bwrap when the sandbox is enforced); no person's text reaches argv", |
| 42 | 44 | "src/crew/orphans.ts": |
test/timers-named.test.ts +1
| @@ -169,6 +169,7 @@ const ALLOWED: readonly Allowed[] = [ | ||
| 169 | 169 | ["src/release/launch.ts", "() => child.kill(\"SIGKILL\")"], |
| 170 | 170 | ["src/release/checkout.ts", "() => proc.kill(\"SIGKILL\")"], |
| 171 | 171 | ["src/crew/sandbox.ts", "() => proc.kill(\"SIGKILL\")"], |
| 172 | ["src/crew/claude_usage.ts", "() => proc.kill(\"SIGKILL\")"], | |
| 172 | 173 | ["src/crew/workdir.ts", "() => { timedOut = true; proc.kill(\"SIGKILL\"); }"], |
| 173 | 174 | ["src/crew/plan.ts", "() => { try { proc.kill(\"SIGKILL\"); }"], |
| 174 | 175 | ["src/crew/runner.ts", "() => proc.kill(\"SIGKILL\")"], |
test/usage-check.test.ts added +221
| @@ -0,0 +1,221 @@ | ||
| 1 | /** | |
| 2 | * A held account's usage, read from Claude Code's `/usage` without a run and written as the newest | |
| 3 | * measure. | |
| 4 | */ | |
| 5 | import { afterAll, beforeAll, expect, test } from "bun:test"; | |
| 6 | import { chmodSync, writeFileSync } from "node:fs"; | |
| 7 | import { mkdtemp, rm } from "node:fs/promises"; | |
| 8 | import { tmpdir } from "node:os"; | |
| 9 | import { join } from "node:path"; | |
| 10 | import { createRepo, updateRepoSettings } from "../src/actions/repos.ts"; | |
| 11 | import { createApp, type App } from "../src/app.ts"; | |
| 12 | import { measureFor, noteMeasure } from "../src/core/measure.ts"; | |
| 13 | import { setHeadroom } from "../src/core/standing.ts"; | |
| 14 | import { addSubscription } from "../src/core/subscriptions.ts"; | |
| 15 | import { readClaudeUsage, usageOf } from "../src/crew/claude_usage.ts"; | |
| 16 | import { recheckUsage } from "../src/crew/usage_check.ts"; | |
| 17 | import { forgetWeek, weekSpent } from "../src/crew/week_read.ts"; | |
| 18 | import { getRepoById, type Repo } from "../src/core/repos.ts"; | |
| 19 | import { seedAdmin } from "./helpers/admin.ts"; | |
| 20 | ||
| 21 | const NOW = new Date("2026-11-19T20:00:00Z"); | |
| 22 | const MIN = 60_000; | |
| 23 | const BARS = [ | |
| 24 | "You are currently using your subscription to power your Claude Code usage", | |
| 25 | "", | |
| 26 | "Current session: 41% used · resets 11pm (UTC)", | |
| 27 | "Current week (all models): 2% used · resets Nov 22 at 2am (UTC)", | |
| 28 | "Current week (Fable): 0% used · resets Nov 22 at 2am (UTC)", | |
| 29 | "", | |
| 30 | "What's contributing to your usage?", | |
| 31 | ].join("\n"); | |
| 32 | ||
| 33 | test("the bars of /usage are the session and the week, each with its reset", () => { | |
| 34 | expect(usageOf(BARS, NOW)).toEqual([ | |
| 35 | { | |
| 36 | window: "5h", | |
| 37 | usedPct: 41, | |
| 38 | resetsAt: "2026-11-19T23:00:00.000Z", | |
| 39 | observedAt: NOW.toISOString(), | |
| 40 | }, | |
| 41 | { | |
| 42 | window: "week", | |
| 43 | usedPct: 2, | |
| 44 | resetsAt: "2026-11-22T02:00:00.000Z", | |
| 45 | observedAt: NOW.toISOString(), | |
| 46 | }, | |
| 47 | ]); | |
| 48 | }); | |
| 49 | ||
| 50 | test("a reset whose hour has passed today is tomorrow's; a date passed is next year's", () => { | |
| 51 | const [session] = usageOf( | |
| 52 | "Current session: 7% used · resets 3:30pm (UTC)", | |
| 53 | NOW, | |
| 54 | ); | |
| 55 | expect(session?.resetsAt).toBe("2026-11-20T15:30:00.000Z"); | |
| 56 | const late = new Date("2026-12-30T12:00:00Z"); | |
| 57 | expect( | |
| 58 | usageOf( | |
| 59 | "Current week (all models): 80% used · resets Jan 2 at 12am (UTC)", | |
| 60 | late, | |
| 61 | )[0]?.resetsAt, | |
| 62 | ).toBe("2027-01-02T00:00:00.000Z"); | |
| 63 | }); | |
| 64 | ||
| 65 | test("no bars, another zone or a model's own week is no measure", () => { | |
| 66 | expect(usageOf("Total cost: $0.0000\nUsage: 0 input, 0 output", NOW)).toEqual( | |
| 67 | [], | |
| 68 | ); | |
| 69 | expect( | |
| 70 | usageOf( | |
| 71 | "Current week (all models): 2% used · resets Nov 21 at 8pm (America/Chicago)", | |
| 72 | NOW, | |
| 73 | ), | |
| 74 | ).toEqual([]); | |
| 75 | expect( | |
| 76 | usageOf("Current week (Fable): 0% used · resets Nov 22 at 2am (UTC)", NOW), | |
| 77 | ).toEqual([]); | |
| 78 | }); | |
| 79 | ||
| 80 | let dir: string; | |
| 81 | let app: App; | |
| 82 | let repo: Repo; | |
| 83 | let sub: string; | |
| 84 | ||
| 85 | beforeAll(async () => { | |
| 86 | dir = await mkdtemp(join(tmpdir(), "forge-usage-check-")); | |
| 87 | app = createApp({ dataDir: dir, port: 0 }); | |
| 88 | const a = await seedAdmin(app, { | |
| 89 | username: "alice", | |
| 90 | email: "[email protected]", | |
| 91 | password: "a-long-passphrase", | |
| 92 | }); | |
| 93 | if (!a.ok) throw new Error(String(a.error)); | |
| 94 | const made = await createRepo(app, a.value, { | |
| 95 | name: "held", | |
| 96 | visibility: "private", | |
| 97 | }); | |
| 98 | if (!made.ok) throw new Error(String(made.error)); | |
| 99 | const on = await updateRepoSettings(app, a.value, made.value, { | |
| 100 | autonomy: "autonomous", | |
| 101 | autonomyDirection: "Ship.", | |
| 102 | autonomySlots: 4, | |
| 103 | autonomyBy: a.value.id, | |
| 104 | }); | |
| 105 | if (!on.ok) throw new Error(String(on.error)); | |
| 106 | repo = getRepoById(app.db, made.value.id)!; | |
| 107 | const added = addSubscription(app.db, dir, { | |
| 108 | name: "main", | |
| 109 | token: "sk-ant-oat01-usage-check-1", | |
| 110 | }); | |
| 111 | if (!added.ok) throw new Error(added.error); | |
| 112 | sub = added.value.id; | |
| 113 | setHeadroom(app.db, sub, 0); | |
| 114 | app.db | |
| 115 | .query( | |
| 116 | "INSERT INTO subscription_grant (scope_id, agent_id, subscription_id) VALUES (?1, '', ?2)", | |
| 117 | ) | |
| 118 | .run(repo.id, sub); | |
| 119 | }); | |
| 120 | ||
| 121 | afterAll(async () => { | |
| 122 | app.close(); | |
| 123 | await rm(dir, { recursive: true, force: true }); | |
| 124 | }); | |
| 125 | ||
| 126 | const week = (usedPct: number, at: Date) => | |
| 127 | noteMeasure(app.db, sub, { | |
| 128 | window: "week", | |
| 129 | usedPct, | |
| 130 | resetsAt: new Date(at.getTime() + 3 * 86_400_000).toISOString(), | |
| 131 | observedAt: at.toISOString(), | |
| 132 | }); | |
| 133 | ||
| 134 | test("a reading that does not hold the crew is not asked about", async () => { | |
| 135 | week(40, NOW); | |
| 136 | forgetWeek(); | |
| 137 | let asked = 0; | |
| 138 | const measured = await recheckUsage( | |
| 139 | app, | |
| 140 | { binary: "claude" }, | |
| 141 | new Map(), | |
| 142 | NOW, | |
| 143 | async () => { | |
| 144 | asked++; | |
| 145 | return null; | |
| 146 | }, | |
| 147 | ); | |
| 148 | expect(asked).toBe(0); | |
| 149 | expect(measured).toEqual([]); | |
| 150 | }); | |
| 151 | ||
| 152 | test("a holding reading is asked again, written as observed now, and releases the crew", async () => { | |
| 153 | const then = new Date(NOW.getTime() - 10 * MIN); | |
| 154 | week(99, then); | |
| 155 | forgetWeek(); | |
| 156 | expect(weekSpent(app, repo, NOW)).toBe(true); | |
| 157 | const seen: Record<string, string>[] = []; | |
| 158 | const asked = new Map<string, number>(); | |
| 159 | const answer = async (input: { env: Record<string, string> }) => { | |
| 160 | seen.push(input.env); | |
| 161 | return [ | |
| 162 | { | |
| 163 | window: "week" as const, | |
| 164 | usedPct: 3, | |
| 165 | resetsAt: new Date(NOW.getTime() + 7 * 86_400_000).toISOString(), | |
| 166 | observedAt: NOW.toISOString(), | |
| 167 | }, | |
| 168 | ]; | |
| 169 | }; | |
| 170 | expect( | |
| 171 | await recheckUsage(app, { binary: "claude" }, asked, NOW, answer), | |
| 172 | ).toEqual([sub]); | |
| 173 | // The account's own credential, as a run carries it. | |
| 174 | expect(seen).toEqual([ | |
| 175 | { CLAUDE_CODE_OAUTH_TOKEN: "sk-ant-oat01-usage-check-1" }, | |
| 176 | ]); | |
| 177 | expect(measureFor(app.db, sub, "week", NOW)).toMatchObject({ | |
| 178 | usedPct: 3, | |
| 179 | observedAt: NOW.toISOString(), | |
| 180 | }); | |
| 181 | expect(weekSpent(app, repo, NOW)).toBe(false); | |
| 182 | }); | |
| 183 | ||
| 184 | test("a held account is asked at most every few minutes", async () => { | |
| 185 | week(99, NOW); | |
| 186 | forgetWeek(); | |
| 187 | const asked = new Map<string, number>([[sub, NOW.getTime() - MIN]]); | |
| 188 | let n = 0; | |
| 189 | const none = async () => { | |
| 190 | n++; | |
| 191 | return null; | |
| 192 | }; | |
| 193 | await recheckUsage(app, { binary: "claude" }, asked, NOW, none); | |
| 194 | expect(n).toBe(0); | |
| 195 | await recheckUsage( | |
| 196 | app, | |
| 197 | { binary: "claude" }, | |
| 198 | asked, | |
| 199 | new Date(NOW.getTime() + 3 * MIN), | |
| 200 | none, | |
| 201 | ); | |
| 202 | expect(n).toBe(1); | |
| 203 | // Nothing heard leaves the reading as it was. | |
| 204 | expect(measureFor(app.db, sub, "week", NOW)?.usedPct).toBe(99); | |
| 205 | }); | |
| 206 | ||
| 207 | test("Claude Code's /usage is run with the account's credential, in UTC", async () => { | |
| 208 | const bin = join(dir, "fake-claude"); | |
| 209 | writeFileSync( | |
| 210 | bin, | |
| 211 | `#!/bin/sh\n[ "$1 $2" = "-p /usage" ] || exit 2\n[ "$TZ" = UTC ] || exit 3\n[ -n "$CLAUDE_CODE_OAUTH_TOKEN" ] || exit 4\nprintf '%s\\n' 'Current week (all models): 12% used · resets Nov 22 at 2am (UTC)'\n`, | |
| 212 | ); | |
| 213 | chmodSync(bin, 0o755); | |
| 214 | const read = await readClaudeUsage({ | |
| 215 | binary: bin, | |
| 216 | env: { CLAUDE_CODE_OAUTH_TOKEN: "t" }, | |
| 217 | cwd: dir, | |
| 218 | }); | |
| 219 | expect(read?.map((m) => [m.window, m.usedPct])).toEqual([["week", 12]]); | |
| 220 | expect(await readClaudeUsage({ binary: bin, env: {}, cwd: dir })).toBeNull(); | |
| 221 | }); |
new above
offline