@rizal72/oc-budget 0.0.0-stage → 0.0.1

package/index.ts

@@ -0,0 +1,366 @@
+// oc-budget — server half.
+//
+// Owns the one thing the TUI cannot do: resolving a provider's credential out of
+// OpenCode's own integration store (`ctx.integration.connection.resolve`), never
+// from a file of ours. With a key (or the Console account token) in hand it reads
+// the four wallets and caches the result, so the TUI's slots and its `/budget`
+// command are pure rendering.
+//
+//   opencode-go  -> GET console/api/go/status             (5h / weekly / monthly meters)
+//                   GET opencode.ai/zen/go/v1/usage        (fallback: a machine with no console session)
+//   deepseek     -> GET api.deepseek.com/user/balance      (native wallet)
+//   openrouter   -> GET openrouter.ai/api/v1/credits (+ /key for the month)
+//   opencode     -> GET console/api/orgs -> /console/api/billing/status  (Zen balance)
+//
+// The Zen balance is the reason the Console integration exists: no API key opens
+// the console (it answers 401 to an `oc_sk_` key), only the account session does.
+// That is exactly what `opencode auth login opencode` stores, so there is no token
+// file here and no device flow to reimplement.
+//
+// Nothing rejects outward, and the two are not the same thing: a wallet with **no connection** is
+// left out of the snapshot, so both halves simply do not draw it — Zen included; a connected wallet
+// whose read failed keeps its branch and its `error`, because a fault must be visible where the number
+// would be.
+import { Budget } from "./rpc.ts"
+import type { BudgetSnapshot, UsageWindow } from "./rpc.ts"
+
+/** How long a collected snapshot is reused; the TUI also polls on this cadence. */
+const TTL_MS = 5 * 60 * 1000
+const TIMEOUT_MS = 10_000
+const USER_AGENT = "oc-budget/0.1"
+
+/** A test switch, inert unless the variable is set: `scripts/oc-dev-env.sh on OC_BUDGET_DEV=empty`.
+ *  `empty` fakes the one state a real machine cannot produce on demand — an account with nothing
+ *  connected. It answers **before** the cache and is never cached, so a real reading cannot be served
+ *  while the switch is on, and the fake cannot outlive the variable it came from. */
+const DEV = process.env.OC_BUDGET_DEV ?? ""
+
+const GO_USAGE_URL = "https://opencode.ai/zen/go/v1/usage"
+const GO_STATUS_URL = "https://opencode.ai/console/api/go/status"
+const DS_BALANCE_URL = "https://api.deepseek.com/user/balance"
+const OR_CREDITS_URL = "https://openrouter.ai/api/v1/credits"
+const OR_KEY_URL = "https://openrouter.ai/api/v1/key"
+const ZEN_CURRENT_URL = "https://opencode.ai/console/api/orgs/current"
+const ZEN_STATUS_URL = "https://opencode.ai/console/api/billing/status"
+
+function message(error: unknown): string {
+	return error instanceof Error ? error.message : String(error)
+}
+
+interface ResolvedKey {
+	key?: string
+	error?: string
+	/** No connection exists at all: the caller omits the wallet instead of reporting a failure. */
+	missing?: boolean
+}
+
+/** The API key of an integration, out of OpenCode's own credential store. */
+async function resolveKey(ctx: any, integrationID: string): Promise<ResolvedKey> {
+	try {
+		const connection = await ctx.integration.connection.active(integrationID)
+		if (!connection) {
+			return { missing: true, error: `${integrationID} is not connected (see: opencode auth list)` }
+		}
+		const value = await ctx.integration.connection.resolve(connection)
+		if (!value) return { error: `${integrationID} credential could not be resolved` }
+		if (value.type === "key") return { key: value.key }
+		return { error: `${integrationID} uses an unexpected credential type (${value.type})` }
+	} catch (error) {
+		return { error: message(error) }
+	}
+}
+
+/** The Console account token, which is what opens the Zen balance. */
+async function resolveConsoleToken(ctx: any): Promise<ResolvedKey> {
+	try {
+		const connection = await ctx.integration.connection.active("opencode")
+		if (!connection) {
+			return { missing: true, error: "OpenCode Console not connected (run: opencode auth login opencode)" }
+		}
+		const value = await ctx.integration.connection.resolve(connection)
+		if (!value) return { error: "OpenCode Console credential could not be resolved" }
+		if (value.type === "oauth") return { key: value.access }
+		if (value.type === "key") return { key: value.key }
+		return { error: `OpenCode Console uses an unexpected credential type (${value.type})` }
+	} catch (error) {
+		return { error: message(error) }
+	}
+}
+
+async function getJson(url: string, headers: Record<string, string>): Promise<any> {
+	const response = await fetch(url, {
+		headers: { ...headers, "User-Agent": USER_AGENT },
+		signal: AbortSignal.timeout(TIMEOUT_MS),
+	})
+	if (!response.ok) throw new Error(`HTTP ${response.status}`)
+	return (await response.json()) as any
+}
+
+/** Micro-cents (1e-8 USD) to a dollar amount, rounded on the integer: the console's
+ *  own scale, fixed by its invoices. `(micro / 1e8).toFixed(2)` is a cent low on
+ *  values like 100500000, so cents are rounded before the division. */
+function microCentsToDollars(micro: number): number {
+	return Math.round(micro / 1e6) / 100
+}
+
+/** How many console connections exist: with one, naming the workspace is noise. */
+async function consolePeers(ctx: any): Promise<number | undefined> {
+	try {
+		const listed: any = await ctx.integration.list()
+		const list: any[] = Array.isArray(listed) ? listed : listed?.data ?? []
+		const connections: any[] = list.find((item: any) => item?.id === "opencode")?.connections ?? []
+		return connections.length || undefined
+	} catch {
+		// A name is a convenience: never let it cost the balance.
+		return undefined
+	}
+}
+
+/** One Go window, from the console's own meter. The rule is the console's, copied from its bundle
+ *  (`(used*200 + limit) / (limit*2)`): round the percent, and cap it at 99 until the window is truly
+ *  spent, because the console says `>99% used` there and the wallet must not fall back to ZEN before
+ *  the limit is reached. The public endpoint rounds **down** instead: 0.98% reads 0 there and 1 here. */
+function goMeter(meter: any): UsageWindow | undefined {
+	const used = Number(meter?.usedMicroCents)
+	const limit = Number(meter?.limitMicroCents)
+	if (!Number.isFinite(used) || !Number.isFinite(limit) || limit <= 0) return undefined
+	const spent = used >= limit
+	return {
+		status: spent ? "rate-limited" : "ok",
+		percent: spent ? 100 : Math.min(99, Math.round((used * 100) / limit)),
+		resetsAt: typeof meter?.resetsAt === "string" ? meter.resetsAt : undefined,
+	}
+}
+
+/** The fallback endpoint's window, clamped to the three fields the contract allows: an extra field
+ *  fails the strict schema and takes the whole snapshot down with it, and its shape is documented
+ *  nowhere. `status` is derived from the percent when the endpoint does not name it, because an
+ *  exhausted window must still flip the paying wallet. */
+function goWindow(raw: any): UsageWindow | undefined {
+	const percent = typeof raw?.percent === "number" && Number.isFinite(raw.percent) ? raw.percent : undefined
+	if (percent === undefined) return undefined
+	const reported = typeof raw?.status === "string" ? raw.status : undefined
+	return {
+		status: percent >= 100 || reported === "rate-limited" ? "rate-limited" : (reported ?? "ok"),
+		percent,
+		resetsAt: typeof raw?.resetsAt === "string" ? raw.resetsAt : undefined,
+	}
+}
+
+async function collectGo(ctx: any): Promise<BudgetSnapshot["go"]> {
+	// Two ways in, one answer. A console session is preferred: it reports the spend in micro-cents and
+	// it is the credential the provider actually bills, so the counters and the payer cannot disagree.
+	// A Go API key alone still works, through the public endpoint. Both are enough on their own, and
+	// neither is required if the other is there.
+	const console = await resolveConsoleToken(ctx)
+	let consoleError: string | undefined
+	if (console.key) {
+		try {
+			const body = await getJson(GO_STATUS_URL, { Authorization: `Bearer ${console.key}` })
+			const meters = body?.access?.meters
+			if (!meters) throw new Error("unexpected go status shape")
+			const reading = {
+				rolling: goMeter(meters.fiveHour),
+				weekly: goMeter(meters.week),
+				monthly: goMeter(meters.month),
+			}
+			if (!reading.rolling && !reading.weekly && !reading.monthly) {
+				throw new Error("unexpected go status shape")
+			}
+			return reading
+		} catch (error) {
+			// A session that cannot read the meters — a workspace without the subscription — must not
+			// hide a key that can. Fall through, and report both failures if it also fails.
+			consoleError = message(error)
+		}
+	}
+	// A Console connection that exists but cannot produce a token is a fault, not an absence, and it is
+	// carried so that a machine with no Go key does not lose the reason.
+	if (!console.missing && console.error) consoleError ??= console.error
+	const credential = await resolveKey(ctx, "opencode-go")
+	// No Go key at all: the Console session is the only witness, and a workspace without the
+	// subscription answers exactly like a broken read. So GO is left out of the snapshot rather than
+	// reported — a free account must not carry a permanent error line. With a key, a failed read is
+	// a fault and keeps its branch.
+	if (credential.missing) {
+		// No Go key: the Console was the only witness. Its own fault is reported; its absence — or a
+		// read that failed without a key — means there is no plan to show.
+		return consoleError && !console.missing ? { error: consoleError } : undefined
+	}
+	if (credential.error) return { error: consoleError ? `${consoleError}; ${credential.error}` : credential.error }
+	try {
+		const body = await getJson(GO_USAGE_URL, { Authorization: `Bearer ${credential.key}` })
+		const usage = body?.usage
+		if (!usage) return { error: "unexpected usage response shape" }
+		const reading = {
+			rolling: goWindow(usage.rolling),
+			weekly: goWindow(usage.weekly),
+			monthly: goWindow(usage.monthly),
+		}
+		if (!reading.rolling && !reading.weekly && !reading.monthly) {
+			return { error: "unexpected usage response shape" }
+		}
+		return reading
+	} catch (error) {
+		return { error: consoleError ? `${consoleError}; ${message(error)}` : message(error) }
+	}
+}
+
+async function collectDeepSeek(ctx: any): Promise<BudgetSnapshot["ds"]> {
+	const credential = await resolveKey(ctx, "deepseek")
+	if (credential.missing) return undefined
+	if (credential.error) return { error: credential.error }
+	try {
+		const body = await getJson(DS_BALANCE_URL, { Authorization: `Bearer ${credential.key}` })
+		const info = body?.balance_infos?.[0]
+		const balance = info?.total_balance === undefined ? Number.NaN : Number(info.total_balance)
+		if (!Number.isFinite(balance)) return { error: "unexpected balance response shape" }
+		return { balance, currency: info?.currency ?? "USD" }
+	} catch (error) {
+		return { error: message(error) }
+	}
+}
+
+async function collectOpenRouter(ctx: any): Promise<BudgetSnapshot["or"]> {
+	const credential = await resolveKey(ctx, "openrouter")
+	if (credential.missing) return undefined
+	if (credential.error) return { error: credential.error }
+	const headers = { Authorization: `Bearer ${credential.key}` }
+	try {
+		const body = await getJson(OR_CREDITS_URL, headers)
+		const totalCredits = body?.data?.total_credits
+		const totalUsage = body?.data?.total_usage
+		if (typeof totalCredits !== "number" || typeof totalUsage !== "number") {
+			return { error: "unexpected credits response shape" }
+		}
+		const result: NonNullable<BudgetSnapshot["or"]> = {
+			totalCredits,
+			totalUsage,
+			balance: totalCredits - totalUsage,
+		}
+		// Best effort: /key enriches the report (month spend) and
+		// must never blank a balance already read.
+		try {
+			const keyBody = await getJson(OR_KEY_URL, headers)
+			const monthly = keyBody?.data?.usage_monthly
+			if (typeof monthly === "number") result.usageMonthly = monthly
+		} catch {
+			// keep the balance
+		}
+		return result
+	} catch (error) {
+		return { error: message(error) }
+	}
+}
+
+async function collectZen(ctx: any): Promise<BudgetSnapshot["zen"]> {
+	const token = await resolveConsoleToken(ctx)
+	// No Console connection at all is an absence, exactly like the other three: the account has no Zen
+	// wallet, and a line explaining a connection never made is the plugin teaching its own setup in
+	// someone else's sidebar. A Console that exists and cannot read keeps its error, because that is a
+	// fault and must be visible where the number would be.
+	if (token.missing) return undefined
+	if (token.error) return { error: token.error }
+	const headers = { Authorization: `Bearer ${token.key}` }
+	try {
+		// The Console session is bound to exactly one workspace — the one selected when the
+		// account was connected — and billing answers 403 for every other one (verified: a
+		// `go` login reads `go` and is refused `go-2` and `Personal`). So the workspace is
+		// read from the session, never guessed from a name: switching the Console account is
+		// the only way to switch which wallet the balance describes.
+		const current = await getJson(ZEN_CURRENT_URL, headers)
+		const org = current?.org
+		if (!org?.id) return { error: "Console session reports no current workspace" }
+		const body = await getJson(ZEN_STATUS_URL, { ...headers, "x-org-id": org.id })
+		const microOf = (value: unknown) => {
+			const n = typeof value === "string" ? Number(value) : value
+			return typeof n === "number" && Number.isFinite(n) ? n : undefined
+		}
+		// Two numbers, and the difference is the point. `balanceMicroCents` is the ledger: prepaid,
+		// so it goes a few cents under when the request that crosses the end costs more than what is
+		// left (measured 2026-10-26: -5076149, i.e. -$0.05). `availableMicroCents` is what the console
+		// prints as *available credit*: the balance clamped at 0, and raised by a credit limit when the
+		// account has one. Clamping the ledger in our code would lose the debt; reading this field
+		// keeps both, and stays right the day a limit is set.
+		const balance = microOf(body?.balanceMicroCents)
+		if (balance === undefined) return { error: "unexpected billing status shape", org: org.name }
+		const available = microOf(body?.availableMicroCents) ?? Math.max(0, balance)
+		return {
+			balance: microCentsToDollars(balance),
+			available: microCentsToDollars(available),
+			...(typeof org.name === "string" ? { org: org.name } : {}),
+			...(await consolePeers(ctx).then((peers) => (peers === undefined ? {} : { peers }))),
+		}
+	} catch (error) {
+		return { error: message(error) }
+	}
+}
+
+/** A snapshot that says why the read failed, in every wallet. A rejected handler answered HTTP 500 and
+ *  left the panel blank with nothing to read; this one is visible where the numbers would be. */
+function failedSnapshot(error: unknown): BudgetSnapshot {
+	// A last resort for a rejection no collector explains: it names the fault on every wallet, so an
+	// account with one connection does not lose the only line it had. Nothing reaches it today — each
+	// collector swallows its own failure — and a new one must keep that true.
+	const text = message(error)
+	return {
+		at: Date.now(),
+		go: { error: text },
+		ds: { error: text },
+		or: { error: text },
+		zen: { error: text },
+	}
+}
+
+/** The shape that crosses the wire, which is JSON: `goMeter` and `goWindow` leave fields `undefined` when
+ *  the endpoint omits them, and the output schema is strict — a present `undefined` is not a `string` and
+ *  not a missing key, so the whole answer is rejected **after** the handler ran (a 500 with `http.span=1`,
+ *  measured 2026-10-28: every poll failed from 07:00 to 12:26 and the pill vanished). `JSON.stringify`
+ *  drops them, which is exactly what the transport would do, only before validation instead of after. */
+const wire = (snapshot: BudgetSnapshot): BudgetSnapshot => JSON.parse(JSON.stringify(snapshot))
+
+export default {
+	id: "oc-budget",
+	async setup(ctx: any) {
+		let cache: BudgetSnapshot | null = null
+		let cacheAt = 0
+		/** One collection at a time: several TUIs, or a model switch racing the poll,
+		 *  join the same promise instead of issuing four redundant request sets. */
+		let inFlight: Promise<BudgetSnapshot> | null = null
+
+		function collect(): Promise<BudgetSnapshot> {
+			return (async () => {
+				const [go, ds, or, zen] = await Promise.all([
+					collectGo(ctx),
+					collectDeepSeek(ctx),
+					collectOpenRouter(ctx),
+					collectZen(ctx),
+				])
+				return { at: Date.now(), go, ds, or, zen }
+			})()
+		}
+
+		await ctx.rpc.register(Budget, {
+			snapshot: async (input: any) => {
+				if (DEV === "empty") return { at: Date.now() }
+				const force = input?.force === true
+				if (!force && cache && Date.now() - cacheAt < TTL_MS) return cache
+				// A forced read must not join a collection that started before it: a credential switch
+				// would receive the old account's numbers and cache them for five minutes.
+				if (force) await inFlight?.catch(() => {})
+				if (inFlight) return inFlight
+				inFlight = collect()
+					.catch(failedSnapshot)
+					.then((snapshot) => {
+						cache = wire(snapshot)
+						cacheAt = Date.now()
+						return cache
+					})
+					.finally(() => {
+						inFlight = null
+					})
+				return inFlight
+			},
+		})
+	},
+}

package/package.json

@@ -1,6 +1,34 @@
 {
-  "name": "@rizal72/oc-budget",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@rizal72/oc-budget",
+	"version": "0.0.1",
+	"type": "module",
+	"description": "How much credit is left on the account behind the model you are using: the Go subscription's windows, the Zen balance, and the pay-per-use wallets, in the sidebar, the footer and the header",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/rizal72/opencode-plugins.git"
+	},
+	"license": "MIT",
+	"keywords": [
+		"opencode",
+		"opencode-plugin",
+		"budget",
+		"credits",
+		"usage"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"exports": {
+		".": "./index.ts",
+		"./tui": "./tui.tsx",
+		"./rpc": "./rpc.ts",
+		"./gui-experimental": "./dist/gui-experimental.cjs"
+	},
+	"files": [
+		"*.ts",
+		"*.tsx",
+		"README.md",
+		"dist",
+		"!*.test.ts"
+	]
+}

package/peak.ts

@@ -0,0 +1,104 @@
+// oc-budget/peak.ts — DeepSeek's two tariffs, one definition for both surfaces.
+//
+// The terminal draws the glyph next to a bar, the desktop puts it on a pill and on the rows of its
+// menu. What "peak" means is neither of their business: the windows are DeepSeek's, published as
+// "01:00-04:00 and 06:00-10:00 UTC, Monday through Friday, excluding Chinese public holidays"
+// (read 2026-10-27).
+//
+// Runnable standalone for its self-check: node plugins/oc-budget/peak.ts --self-check
+
+/** Peak hours, in UTC. The arithmetic is DST-proof on purpose. A Chinese public holiday is not encoded,
+ *  so it reads as peak — over-warning, which is the safe direction. */
+const WINDOWS: ReadonlyArray<readonly [number, number]> = [
+	[1, 4],
+	[6, 10],
+]
+const EDGES = [1, 4, 6, 10]
+
+const at = (now: number) => new Date(now)
+
+/** A dev switch shared by both surfaces: set it to an instant inside a peak window and the peak marks
+ *  appear at any hour, so the look can be judged — or filmed — without waiting for 01:00 UTC. A Tuesday at
+ *  02:00 UTC: `Date.UTC(2026, 9, 27, 2, 0)`. Ships `undefined`, and this plugin is local, so nothing else
+ *  guards it. Both halves read it from here: one value, or the badge and the pill would disagree. */
+export const SIMULATE: number | undefined = undefined
+/** The clock the peak is judged by: the simulated instant when one is set, the real time otherwise. */
+export const clock = (): number => SIMULATE ?? Date.now()
+
+export function isPeak(now = Date.now()): boolean {
+	const date = at(now)
+	const day = date.getUTCDay()
+	if (day === 0 || day === 6) return false
+	const hour = date.getUTCHours() + date.getUTCMinutes() / 60
+	return WINDOWS.some(([from, to]) => hour >= from && hour < to)
+}
+
+/** The next instant the regime flips, and what it flips to. Candidates are the window edges over the
+ *  next ten days; the first that changes the state wins, which skips the weekend edges that open and
+ *  close nothing. */
+export function nextChange(now = Date.now()): { peak: boolean; at: number } {
+	const peak = isPeak(now)
+	const midnight = at(now)
+	midnight.setUTCHours(0, 0, 0, 0)
+	const edges: number[] = []
+	for (let offset = 0; offset <= 10; offset++) {
+		for (const hour of EDGES) {
+			const time = midnight.getTime() + offset * 86_400_000 + hour * 3_600_000
+			if (time > now) edges.push(time)
+		}
+	}
+	edges.sort((a, b) => a - b)
+	for (const time of edges) if (isPeak(time) !== peak) return { peak: !peak, at: time }
+	return { peak: !peak, at: edges[edges.length - 1] }
+}
+
+/**
+ * True when the price of *this model* doubles inside a peak window: native DeepSeek, and the DeepSeek
+ * ids on Go while the subscription pays. Zen never does — its DeepSeek price is flat at the peak
+ * figure, a constant and not a doubling.
+ */
+export function doubles(model: { providerID?: string; modelID?: string } | undefined, wallet: string, now = Date.now()): boolean {
+	if (!isPeak(now)) return false
+	const provider = model?.providerID ?? ""
+	if (provider === "deepseek") return true
+	if (provider === "opencode-go" && wallet === "go") return /^deepseek/.test(model?.modelID ?? "")
+	return false
+}
+
+// Self-check: node plugins/oc-budget/peak.ts --self-check
+// Guarded: this module is also bundled into the desktop window, where `process` does not exist.
+if (typeof process !== "undefined" && process.argv?.[2] === "--self-check") {
+	const check = (ok: boolean, message: string) => {
+		if (!ok) throw new Error("self-check: " + message)
+	}
+	// 2026-10-27 is a Tuesday: 02:00 UTC is peak, 04:30 is not, 06:00 is again.
+	const tue = (h: number, m = 0) => Date.UTC(2026, 9, 27, h, m)
+	const sat = (h: number) => Date.UTC(2026, 9, 31, h)
+
+	check(isPeak(tue(2)), "02:00 UTC on a weekday is peak")
+	check(!isPeak(tue(0, 30)), "00:30 UTC is off-peak")
+	check(!isPeak(tue(4)), "04:00 is the first off-peak minute")
+	check(isPeak(tue(6)), "06:00 is peak again")
+	check(!isPeak(tue(10)), "10:00 ends it")
+	check(!isPeak(sat(2)), "a weekend is never peak")
+
+	const deepseek = { providerID: "deepseek", modelID: "deepseek-chat" }
+	const goDeepseek = { providerID: "opencode-go", modelID: "deepseek-v4.1-flash" }
+	const goOther = { providerID: "opencode-go", modelID: "glm-5.3" }
+	const zenDeepseek = { providerID: "opencode", modelID: "deepseek-v4.1-flash" }
+
+	check(doubles(deepseek, "ds", tue(2)), "native DeepSeek doubles at peak")
+	check(!doubles(deepseek, "ds", tue(4)), "and not off-peak")
+	check(doubles(goDeepseek, "go", tue(2)), "a Go DeepSeek doubles while Go pays")
+	check(!doubles(goDeepseek, "ds", tue(2)), "but not while another wallet pays")
+	check(!doubles(goOther, "go", tue(2)), "a Go model that is not DeepSeek never doubles")
+	check(!doubles(zenDeepseek, "zen", tue(2)), "Zen's DeepSeek price is flat")
+	check(!doubles(undefined, "go", tue(2)), "no model, no doubling")
+
+	const soon = nextChange(tue(2))
+	check(!soon.peak && soon.at === tue(4), "the next change from 02:00 is off-peak at 04:00")
+	const friday = nextChange(Date.UTC(2026, 9, 30, 23))
+	check(friday.peak && friday.at === Date.UTC(2026, 10, 2, 1), "Friday night flips to peak on Monday at 01:00")
+
+	console.log("self-check ok: " + WINDOWS.length + " windows, Zen flat, the weekend never peak")
+}

package/rpc.ts

@@ -0,0 +1,111 @@
+// The one contract shared by the server half and the TUI half of the plugin.
+// The server registers it and implements `snapshot`; the TUI imports the same
+// definition to build an RPC client, so the two can never drift.
+import { Rpc } from "@opencode/plugin/rpc"
+
+/** One budget window: how much of it is spent, its status, and when it resets. */
+const Window = {
+	type: "object",
+	properties: {
+		status: { type: "string" },
+		percent: { type: "number" },
+		resetsAt: { type: "string" },
+	},
+	additionalProperties: false,
+}
+
+export const Budget = Rpc.define({
+	id: "budget",
+	methods: {
+		snapshot: {
+			input: {
+				type: "object",
+				properties: { force: { type: "boolean" } },
+				additionalProperties: false,
+			},
+			output: {
+				type: "object",
+				properties: {
+					at: { type: "number" },
+					go: {
+						type: "object",
+						properties: {
+							rolling: Window,
+							weekly: Window,
+							monthly: Window,
+							error: { type: "string" },
+						},
+						additionalProperties: false,
+					},
+					ds: {
+						type: "object",
+						properties: {
+							balance: { type: "number" },
+							currency: { type: "string" },
+							error: { type: "string" },
+						},
+						additionalProperties: false,
+					},
+					or: {
+						type: "object",
+						properties: {
+							balance: { type: "number" },
+							totalCredits: { type: "number" },
+							totalUsage: { type: "number" },
+							usageMonthly: { type: "number" },
+							error: { type: "string" },
+						},
+						additionalProperties: false,
+					},
+					zen: {
+						type: "object",
+						properties: {
+							/** The ledger: signed, and negative when a request cost more than was left. */
+							balance: { type: "number" },
+							/** The spendable credit, the figure the console prints; the balance clamped at 0. */
+							available: { type: "number" },
+							/** The console workspace: it pays, and it owns this balance. */
+							org: { type: "string" },
+							/** How many console connections exist: with one, the name is noise. */
+							peers: { type: "number" },
+							error: { type: "string" },
+						},
+						additionalProperties: false,
+					},
+				},
+				required: ["at"],
+				additionalProperties: false,
+			},
+		},
+	},
+	// Present (empty) on purpose: the loader walks `events` and a missing map is a
+	// hard failure rather than an empty one.
+	events: {},
+})
+
+export interface UsageWindow {
+	status?: string
+	percent?: number
+	resetsAt?: string
+}
+
+export interface BudgetSnapshot {
+	at: number
+	go?: {
+		rolling?: UsageWindow
+		weekly?: UsageWindow
+		monthly?: UsageWindow
+		error?: string
+	}
+	ds?: { balance?: number; currency?: string; error?: string }
+	or?: {
+		balance?: number
+		totalCredits?: number
+		totalUsage?: number
+		usageMonthly?: number
+		error?: string
+	}
+	zen?: { balance?: number; available?: number; org?: string; peers?: number; error?: string }
+}
+
+export default Budget