@estebanforge/pi-antigravity-bridge 1.7.3 → 1.7.5

package/src/subagent-roster.ts

@@ -0,0 +1,245 @@
+// In-memory subagent roster, folded from driver activities.
+//
+// agy has no read-only subcommand for live subagent state, so the only
+// zero-token source is the turn stream: subagent spawns arrive as ordinary
+// tool steps (invoke_subagent, run_subagent, define_subagent,
+// browser_subagent), send_message addresses a spawned agent, and
+// manage_subagents carries lifecycle actions. The roster folds
+// DriverActivity — the engine-agnostic contract both turn engines emit — so
+// stream-json (stepId-keyed) and ACP (toolCallId-keyed) feed one roster.
+//
+// Accepted heuristic limits (telemetry only, never persisted — agy's own
+// conversation database remains the durable record):
+// - send_message routes to the FIRST entry with the matching agent name
+//   regardless of status, so a message after a name is reused may credit a
+//   stale entry.
+// - manage_subagents kill marks ALL running entries killed; the target arg
+//   is ignored because its shape is not stable across agy builds.
+// - Parallel spawns with the same agent name are separate entries, but
+//   name-based routing cannot tell them apart.
+
+import type { DriverActivity } from "./driver-types.js";
+
+/** Tools whose start opens a roster entry and whose done/error closes it. */
+const SPAWN_TOOLS = new Set(["invoke_subagent", "run_subagent", "browser_subagent"]);
+/** Tools addressed at an already-spawned agent. */
+const MESSAGE_TOOLS = new Set(["send_message"]);
+/** Tools carrying lifecycle actions (kill/stop/...). */
+const MANAGE_TOOLS = new Set(["manage_subagents"]);
+
+/** Arg keys that plausibly name the target agent (their casing varies). */
+const NAME_ARG_KEYS = /^(name|subagent|subagent_name|agent|agent_name|type|recipient|role|to)$/i;
+/** Arg keys plausibly holding a manage_subagents lifecycle action. */
+const ACTION_ARG_KEYS = /^(action|command|operation|op)$/i;
+const DETAIL_MAX = 120;
+
+export interface SubagentEntry {
+	/** Stable fold key: `s:<stepId>` on stream-json, `n:<seq>` on ACP. */
+	key: string;
+	name: string;
+	status: "running" | "done" | "error" | "killed";
+	spawnedAtMs: number;
+	lastActivityMs: number;
+	/** send_message count since spawn. */
+	messages: number;
+	/** First non-name string arg, truncated — usually the task text. */
+	detail: string;
+	error?: string;
+}
+
+function truncate(value: string): string {
+	return value.length > DETAIL_MAX ? `${value.slice(0, DETAIL_MAX)}…` : value;
+}
+
+/** First string arg whose key plausibly names the agent. */
+function subagentNameFromArgs(args: Record<string, unknown>): string {
+	for (const [k, v] of Object.entries(args)) {
+		if (NAME_ARG_KEYS.test(k) && typeof v === "string" && v.trim()) return truncate(v.trim());
+	}
+	return "subagent";
+}
+
+/** First string arg that is not the name — the task text, when agy passes one. */
+function detailFromArgs(args: Record<string, unknown>): string {
+	for (const [k, v] of Object.entries(args)) {
+		if (!NAME_ARG_KEYS.test(k) && typeof v === "string" && v.trim()) return truncate(v.trim());
+	}
+	return "";
+}
+
+interface ExtractedSpawn {
+	name: string;
+	detail: string;
+}
+
+function extractSpawnsFromArgs(args: Record<string, unknown>): ExtractedSpawn[] {
+	const raw = args.Subagents ?? args.subagents;
+	if (Array.isArray(raw) && raw.length > 0) {
+		const out: ExtractedSpawn[] = [];
+		for (const item of raw) {
+			if (item && typeof item === "object") {
+				const rec = item as Record<string, unknown>;
+				const name =
+					(typeof rec.Role === "string" && rec.Role.trim()) ||
+					(typeof rec.role === "string" && rec.role.trim()) ||
+					(typeof rec.TypeName === "string" && rec.TypeName.trim()) ||
+					(typeof rec.type_name === "string" && rec.type_name.trim()) ||
+					(typeof rec.name === "string" && rec.name.trim()) ||
+					"subagent";
+				const detail =
+					(typeof rec.Prompt === "string" && rec.Prompt.trim()) ||
+					(typeof rec.prompt === "string" && rec.prompt.trim()) ||
+					(typeof rec.task === "string" && rec.task.trim()) ||
+					"";
+				out.push({ name: truncate(name), detail: truncate(detail) });
+			}
+		}
+		if (out.length > 0) return out;
+	}
+	return [{ name: subagentNameFromArgs(args), detail: detailFromArgs(args) }];
+}
+
+function manageActionIsKill(args: Record<string, unknown>): boolean {
+	for (const [k, v] of Object.entries(args)) {
+		if (ACTION_ARG_KEYS.test(k) && typeof v === "string" && /kill|stop|terminate|cancel/i.test(v))
+			return true;
+	}
+	return false;
+}
+
+export class SubagentRoster {
+	#entries = new Map<string, SubagentEntry>();
+	#acpSeq = 0;
+
+	/** Fold key precedence: ACP toolCallId (stable protocol id), stream-json
+	 *  numeric stepId, then a process-local sequence for hypothetical engines
+	 *  with neither. */
+	#keyFor(activity: Extract<DriverActivity, { type: "tool_start" }>): string {
+		if (activity.toolCallId !== undefined) return `t:${activity.toolCallId}`;
+		if (activity.stepId !== undefined) return `s:${activity.stepId}`;
+		return `n:${this.#acpSeq++}`;
+	}
+
+	#entriesFor(activity: Extract<DriverActivity, { type: "tool_done" | "tool_error" }>): SubagentEntry[] {
+		const baseKey =
+			activity.toolCallId !== undefined
+				? `t:${activity.toolCallId}`
+				: activity.stepId !== undefined
+					? `s:${activity.stepId}`
+					: undefined;
+		if (baseKey !== undefined) {
+			const matched: SubagentEntry[] = [];
+			for (const [k, v] of this.#entries) {
+				if (k === baseKey || k.startsWith(`${baseKey}:`)) matched.push(v);
+			}
+			return matched;
+		}
+		for (const entry of this.#entries.values()) {
+			if (entry.status === "running") return [entry];
+		}
+		return [];
+	}
+
+	/** Fold one driver activity. Non-tool activities are ignored; unknown
+	 *  tool names are other features' business. Never throws: roster
+	 *  bookkeeping must not be able to fail a turn. */
+	fold(activity: DriverActivity): void {
+		try {
+			this.#fold(activity);
+		} catch {
+			/* roster is best-effort telemetry */
+		}
+	}
+
+	#fold(activity: DriverActivity): void {
+		if (activity.type === "tool_start") {
+			if (SPAWN_TOOLS.has(activity.name)) {
+				const baseKey = this.#keyFor(activity);
+				const spawns = extractSpawnsFromArgs(activity.args);
+				const now = Date.now();
+				for (let i = 0; i < spawns.length; i++) {
+					const key = spawns.length === 1 ? baseKey : `${baseKey}:${i}`;
+					this.#entries.set(key, {
+						key,
+						name: spawns[i]!.name,
+						status: "running",
+						spawnedAtMs: now,
+						lastActivityMs: now,
+						messages: 0,
+						detail: spawns[i]!.detail,
+					});
+				}
+				return;
+			}
+			if (MESSAGE_TOOLS.has(activity.name)) {
+				const entry = this.#entryByName(subagentNameFromArgs(activity.args));
+				if (entry) {
+					entry.messages += 1;
+					entry.lastActivityMs = Date.now();
+				}
+				return;
+			}
+			if (MANAGE_TOOLS.has(activity.name) && manageActionIsKill(activity.args)) {
+				const now = Date.now();
+				for (const entry of this.#entries.values()) {
+					if (entry.status === "running") {
+						entry.status = "killed";
+						entry.lastActivityMs = now;
+					}
+				}
+			}
+			return;
+		}
+		if (activity.type === "tool_done" || activity.type === "tool_error") {
+			const entries = this.#entriesFor(activity);
+			if (entries.length === 0) return;
+			const now = Date.now();
+			for (const entry of entries) {
+				entry.lastActivityMs = now;
+				if (activity.type === "tool_error") {
+					entry.status = "error";
+					entry.error = truncate(activity.message);
+				} else if (entry.status === "running") {
+					entry.status = "done";
+				}
+			}
+		}
+	}
+
+	#entryByName(name: string, ...statuses: SubagentEntry["status"][]): SubagentEntry | undefined {
+		for (const entry of this.#entries.values()) {
+			if (entry.name === name && (statuses.length === 0 || statuses.includes(entry.status)))
+				return entry;
+		}
+		return undefined;
+	}
+
+	/** Entries in spawn order (Map preserves insertion). */
+	snapshot(): SubagentEntry[] {
+		return [...this.#entries.values()];
+	}
+
+	/** Live wire for status surfaces. */
+	runningCount(): number {
+		let n = 0;
+		for (const entry of this.#entries.values()) if (entry.status === "running") n += 1;
+		return n;
+	}
+}
+
+export function formatSubagentRoster(entries: SubagentEntry[]): string {
+	const running = entries.filter((e) => e.status === "running").length;
+	const lines = [`antigravity subagents: ${entries.length} tracked, ${running} running`];
+	for (const entry of entries) {
+		const secs = Math.max(0, Math.round((Date.now() - entry.spawnedAtMs) / 1000));
+		const dur = secs >= 60 ? `${Math.floor(secs / 60)}m${String(secs % 60).padStart(2, "0")}s` : `${secs}s`;
+		const parts = [
+			`${entry.name} · ${entry.status} · ${dur}`,
+			entry.messages > 0 ? `${entry.messages} msg` : undefined,
+			entry.detail || undefined,
+			entry.error ? `error: ${entry.error}` : undefined,
+		].filter((p): p is string => p !== undefined);
+		lines.push(`- ${parts.join(" · ")}`);
+	}
+	return lines.join("\n");
+}

package/src/tasks-ui.ts

@@ -0,0 +1,88 @@
+// /agy tasks overlay: SelectList over one conversation's background tasks.
+//
+// UI mirrors the artifacts browser (engine-picker pattern). Watch-only:
+// enter closes (the list IS the dashboard), r rescans, esc closes. Tails
+// live in the command form: /agy tasks tail <id> — a log tail is chat
+// content, not overlay content.
+
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+import { DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { Container, type SelectItem, SelectList, Spacer, Text } from "@earendil-works/pi-tui";
+import type { AgyTask } from "./tasks.js";
+
+export type TasksBrowserAction = { type: "rescan" } | { type: "close" };
+
+export function taskItems(tasks: AgyTask[]): SelectItem[] {
+	return tasks.map((t) => {
+		const when = new Date(t.modifiedMs);
+		const stamp = `${String(when.getHours()).padStart(2, "0")}:${String(when.getMinutes()).padStart(2, "0")}`;
+		const state = t.livenessKnown ? (t.active ? "ACTIVE" : "idle") : "liveness?";
+		return {
+			value: String(t.id),
+			label: `#${t.id} · ${state}`,
+			description: `${humanBytes(t.bytes)} · last write ${stamp}`,
+		};
+	});
+}
+
+function humanBytes(n: number): string {
+	if (n < 1024) return `${n}B`;
+	if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`;
+	return `${(n / (1024 * 1024)).toFixed(1)}MB`;
+}
+
+/** Render the overlay. Resolves rescan (caller re-lists and reopens) or
+ *  close. */
+export async function showTasksBrowser(
+	ctx: ExtensionUIContext,
+	tasks: AgyTask[],
+	livenessKnown: boolean,
+): Promise<TasksBrowserAction> {
+	const items = taskItems(tasks);
+	return ctx.custom<TasksBrowserAction>((tui, theme, _keybindings, done) => {
+		const container = new Container();
+		container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+		container.addChild(
+			new Text(theme.fg("accent", theme.bold(`Antigravity tasks (${tasks.length})`)), 1, 0),
+		);
+		if (!livenessKnown) {
+			container.addChild(
+				new Text(theme.fg("warning", "lsof not found; liveness unknown (install lsof for ACTIVE/idle)"), 1, 0),
+			);
+		}
+		container.addChild(new Spacer(1));
+
+		const list = new SelectList(items, Math.min(items.length, 12), {
+			selectedPrefix: (t: string) => theme.fg("accent", t),
+			selectedText: (t: string) => theme.fg("accent", t),
+			description: (t: string) => theme.fg("muted", t),
+			scrollInfo: (t: string) => theme.fg("dim", t),
+			noMatch: (t: string) => theme.fg("warning", t),
+		});
+		list.onSelect = () => done({ type: "close" });
+		list.onCancel = () => done({ type: "close" });
+		container.addChild(list);
+
+		container.addChild(new Spacer(1));
+		container.addChild(
+			new Text(theme.fg("dim", "↑↓ navigate · r rescan · esc close · /agy tasks tail <id> for a log"), 1, 0),
+		);
+		container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+		return {
+			render: (width: number) => container.render(width),
+			invalidate: () => container.invalidate(),
+			handleInput: (data: string) => {
+				if (data.trim().toLowerCase() === "r") {
+					done({ type: "rescan" });
+					return;
+				}
+				list.handleInput(data);
+				tui.requestRender();
+			},
+		};
+	}, {
+		overlay: true,
+		overlayOptions: { anchor: "center" as const, width: 72, maxHeight: "85%" as const, margin: 1 },
+	});
+}

package/src/tasks.ts

@@ -0,0 +1,174 @@
+// Read-only task dashboard over one agy conversation's background tasks
+// (.system_generated/tasks/task-<N>.log under the brain dir).
+//
+// WATCH-ONLY by design. The stream RPC never reports agy's background
+// tasks, so visibility comes from this filesystem scan; liveness comes
+// from one batched lsof call over every log path (per-file lsof would
+// fork-storm). Ownership is deliberately NOT resolved: modern agy pipes
+// task output through itself, so the process holding a log open proves
+// nothing about which spawned job it is, and we never kill what we cannot
+// prove we own. A task is "active" while any process holds its log open
+// (a reader counts too — cat/less/tail -f will light it up; the dashboard
+// is a watch, not a fact), "idle" otherwise; when lsof is missing,
+// liveness is unknown and the dashboard says so instead of guessing.
+
+import { readdir, stat } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { readTranscriptTail } from "./parked-turn.js";
+
+const TASK_LOG_RE = /^task-(\d+)\.log$/;
+const MAX_TASKS = 128;
+const LSOFT_TIMEOUT_MS = 5_000;
+const LSOFT_CAP_BYTES = 1024 * 1024;
+export const TASK_TAIL_BYTES = 2 * 1024;
+
+export interface AgyTask {
+	id: number;
+	logPath: string;
+	bytes: number;
+	modifiedMs: number;
+	/** Any process currently holds the log open. */
+	active: boolean;
+	/** false when lsof is unavailable (liveness could not be checked). */
+	livenessKnown: boolean;
+}
+
+/** Scan task logs under one conversation dir. Missing dirs return []
+ *  (tasks are created on demand). Newest activity first, capped. */
+export async function scanAgyTasks(conversationDir: string): Promise<AgyTask[]> {
+	const dir = path.join(conversationDir, ".system_generated", "tasks");
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	const tasks: AgyTask[] = [];
+	for (const entry of entries) {
+		if (!entry.isFile()) continue;
+		const match = TASK_LOG_RE.exec(entry.name);
+		if (!match) continue;
+		const logPath = path.join(dir, entry.name);
+		try {
+			const stats = await stat(logPath);
+			tasks.push({
+				id: Number(match[1]),
+				logPath,
+				bytes: stats.size,
+				modifiedMs: stats.mtimeMs,
+				active: false,
+				livenessKnown: false,
+			});
+		} catch {
+			continue; // vanished mid-scan
+		}
+	}
+	tasks.sort((a, b) => b.modifiedMs - a.modifiedMs || b.id - a.id);
+	return tasks.slice(0, MAX_TASKS);
+}
+
+/** Parse `lsof -nP -Fpn` output into path -> pids holding it open.
+ *  Format: `p<PID>` starts a process block; `n<PATH>` marks a file of the
+ *  current process. Pure; exported for tests.
+ *  Known gap: a log unlinked while held open gets an "n<path> (deleted)"
+ *  line whose key never equals the scanned path, so that holder is
+ *  invisible and the task reads idle. Left as-is: stripping the suffix
+ *  would attribute a rotation survivor to the REPLACEMENT file at the
+ *  same path, which is a worse lie. */
+export function parseLsofOwners(output: string): Map<string, Set<number>> {
+	const owners = new Map<string, Set<number>>();
+	let pid: number | undefined;
+	for (const line of output.split("\n")) {
+		if (line.startsWith("p")) {
+			const parsed = Number(line.slice(1));
+			pid = Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+			continue;
+		}
+		if (!line.startsWith("n")) continue;
+		if (pid === undefined) continue;
+		const filePath = line.slice(1);
+		if (!filePath) continue;
+		let set = owners.get(filePath);
+		if (!set) owners.set(filePath, (set = new Set()));
+		set.add(pid);
+	}
+	return owners;
+}
+
+type SpawnRaw = (cmd: string, args: string[], timeoutMs: number, capBytes: number) => Promise<string>;
+
+/** One batched lsof over every task log. Resolves undefined when lsof is
+ *  missing or failed (spawn error / timeout); resolves "" when lsof ran
+ *  and nothing is open (its normal exit-1-empty answer). */
+async function lsofOwners(
+	logPaths: string[],
+	spawnRaw: SpawnRaw = defaultSpawnRaw,
+): Promise<string | undefined> {
+	if (logPaths.length === 0) return "";
+	try {
+		return await spawnRaw("lsof", ["-nP", "-Fpn", ...logPaths], LSOFT_TIMEOUT_MS, LSOFT_CAP_BYTES);
+	} catch {
+		return undefined;
+	}
+}
+
+async function defaultSpawnRaw(
+	cmd: string,
+	args: string[],
+	timeoutMs: number,
+	capBytes: number,
+): Promise<string> {
+	return new Promise<string>((resolve, reject) => {
+		const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "ignore"] });
+		let out = "";
+		let settled = false;
+		const done = (fn: () => void) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			fn();
+		};
+		const timer = setTimeout(() => {
+			child.kill("SIGKILL");
+			done(() => reject(new Error(`${cmd} timed out`)));
+		}, timeoutMs);
+		child.stdout.on("data", (d: Buffer) => {
+			if (out.length + d.length > capBytes) {
+				try {
+					child.kill("SIGKILL");
+				} catch {
+					/* already gone */
+				}
+				done(() => reject(new Error(`${cmd} output cap exceeded`)));
+				return;
+			}
+			out += d.toString("utf8");
+		});
+		child.on("error", (err) => done(() => reject(err)));
+		child.on("close", () => done(() => resolve(out)));
+	});
+}
+
+/** Scan plus liveness in one call. Never throws; a missing or failed lsof
+ *  leaves livenessKnown false rather than guessing. */
+export async function listAgyTasks(
+	conversationDir: string,
+	spawnRaw?: SpawnRaw,
+): Promise<AgyTask[]> {
+	const tasks = await scanAgyTasks(conversationDir);
+	if (tasks.length === 0) return tasks;
+	const rawOwners = await lsofOwners(tasks.map((t) => t.logPath), spawnRaw);
+	const owners = rawOwners === undefined ? undefined : parseLsofOwners(rawOwners);
+	for (const task of tasks) {
+		task.livenessKnown = owners !== undefined;
+		task.active = (owners?.get(task.logPath)?.size ?? 0) > 0;
+	}
+	return tasks;
+}
+
+/** Last bytes of a task log for the tail command. Empty string on any
+ *  error — tails are best-effort views, not facts. */
+export async function tailAgyTaskLog(logPath: string): Promise<string> {
+	return readTranscriptTail(logPath, TASK_TAIL_BYTES);
+}

package/src/usage.ts

@@ -0,0 +1,174 @@
+// Subscription quota view: `agy --print /usage --output-format json`.
+//
+// agy has no usage subcommand; the /usage slash command inside print mode
+// returns the same structured payload the agy TUI panel shows and burns
+// zero tokens (live-verified agy 1.2.10: status SUCCESS, usage all zeros,
+// command.data.groups[] with window "weekly" | "5h" buckets carrying
+// remaining_fraction and reset_time). Print mode answers in ~10s on this
+// machine, so the spawn budget here is its own 30s, not the 8s discovery
+// watchdog shared by models/agents.
+//
+// The quota is account-level: it reads the agy CLI's Google identity, so it
+// is equally true for stream-json turns and ACP-server turns (same account)
+// — but a pure-ACP install without the CLI cannot fetch it; the command
+// layer fails closed with a pointer instead of a raw error.
+
+import { spawnAgyRaw } from "./models.js";
+
+export const USAGE_TIMEOUT_MS = 30_000;
+const USAGE_CAP_BYTES = 1024 * 1024;
+
+export interface AgyQuotaBucket {
+	id?: string;
+	name: string;
+	/** agy's window tag: "weekly" | "5h" (tolerant of future tags). */
+	window: string;
+	remainingFraction: number;
+	resetTime?: string;
+}
+
+export interface AgyQuotaGroup {
+	name: string;
+	description?: string;
+	buckets: AgyQuotaBucket[];
+}
+
+export interface AgyQuotaReport {
+	groups: AgyQuotaGroup[];
+}
+
+type Json = Record<string, unknown>;
+
+const asObject = (v: unknown): Json | undefined => (v !== null && typeof v === "object" ? (v as Json) : undefined);
+const asString = (v: unknown): string | undefined => (typeof v === "string" ? v : undefined);
+const asNumber = (v: unknown): number | undefined => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+const firstString = (o: Json, keys: string[]): string | undefined => {
+	for (const k of keys) {
+		const v = asString(o[k]);
+		if (v !== undefined) return v;
+	}
+	return undefined;
+};
+
+function parseBucket(v: unknown): AgyQuotaBucket | undefined {
+	const o = asObject(v);
+	if (!o) return undefined;
+	const remaining = asNumber(o.remaining_fraction) ?? asNumber(o.remainingFraction) ?? asNumber(o.remaining);
+	const name = firstString(o, ["name", "id"]);
+	if (remaining === undefined || name === undefined) return undefined;
+	return {
+		id: asString(o.id),
+		name,
+		window: firstString(o, ["window"]) ?? "unknown",
+		remainingFraction: Math.max(0, Math.min(1, remaining)),
+		resetTime: firstString(o, ["reset_time", "resetTime"]),
+	};
+}
+
+function parseGroup(v: unknown): AgyQuotaGroup | undefined {
+	const o = asObject(v);
+	if (!o) return undefined;
+	const name = asString(o.name);
+	if (name === undefined) return undefined;
+	const buckets = Array.isArray(o.buckets)
+		? o.buckets.map(parseBucket).filter((b): b is AgyQuotaBucket => b !== undefined)
+		: [];
+	return { name, description: asString(o.description), buckets };
+}
+
+/** Parse the /usage JSON payload. Tolerant: unwraps a stream-json result
+ *  envelope when present (print mode does not send one), accepts snake_case
+ *  and camelCase field aliases, clamps fractions. Throws a short reason on
+ *  any structural mismatch — callers render it, never stack it. */
+export function parseAgyUsageJson(text: string): AgyQuotaReport {
+	let payload: Json | undefined;
+	try {
+		payload = asObject(JSON.parse(text));
+	} catch {
+		throw new Error("response was not JSON");
+	}
+	if (!payload) throw new Error("response was not an object");
+	// Print mode answers at the top level; if some future agy shells the
+	// command through its stream instead, the wrapper is the same event-keyed
+	// NDJSON grammar the driver already parses (see fake-agy-bin frames:
+	// {"event":"init",...}), so unwrap {event:"result", result:{...}}.
+	const inner = payload.event !== undefined ? asObject(payload.result) : payload;
+	if (!inner) throw new Error("result envelope carried no result object");
+	const status = (firstString(inner, ["status"]) ?? "").toUpperCase();
+	if (status !== "" && status !== "SUCCESS" && status !== "OK") {
+		throw new Error(`agy reported status ${status}`);
+	}
+	const command = asObject(inner.command);
+	if (command === undefined || command.name !== "usage") {
+		throw new Error("payload is not a /usage command result");
+	}
+	const data = asObject(command.data) ?? asObject(inner.data);
+	const rawGroups = data !== undefined && Array.isArray(data.groups) ? data.groups : undefined;
+	if (rawGroups === undefined) throw new Error("no quota groups in payload");
+	const groups = rawGroups.map(parseGroup).filter((g): g is AgyQuotaGroup => g !== undefined);
+	if (groups.length === 0) throw new Error("no quota groups returned");
+	return { groups };
+}
+
+/** Fetch quota through the CLI. Undefined on any fetch failure (missing
+ *  binary, non-zero exit, timeout, cap) — same degrade-to-empty contract as
+ *  the model catalog; the caller renders the difference. The spawn watchdog
+ *  runs 5s past agy's own --print-timeout so the CLI's clean timeout-exit
+ *  always wins the race over our SIGKILL. */
+export async function fetchAgyQuota(binary: string): Promise<AgyQuotaReport | undefined> {
+	const raw = await spawnAgyRaw(
+		binary,
+		["--print", "/usage", "--output-format", "json", "--print-timeout", `${Math.ceil(USAGE_TIMEOUT_MS / 1000)}s`],
+		USAGE_TIMEOUT_MS + 5_000,
+		USAGE_CAP_BYTES,
+	);
+	if (raw === "") return undefined;
+	try {
+		return parseAgyUsageJson(raw);
+	} catch {
+		return undefined;
+	}
+}
+
+// --- rendering ---------------------------------------------------------------
+
+/** 20-segment remaining bar. */
+export function quotaBar(fraction: number): string {
+	const filled = Math.round(Math.max(0, Math.min(1, fraction)) * 20);
+	return `${"█".repeat(filled)}${"░".repeat(20 - filled)}`;
+}
+
+/** Clock-style reset label: "resets 19:53" today, else "resets 09:10 on 4 Sep". */
+export function resetLabel(resetTime: string, now: Date): string {
+	const at = new Date(resetTime);
+	if (Number.isNaN(at.getTime())) return "";
+	const hhmm = `${String(at.getHours()).padStart(2, "0")}:${String(at.getMinutes()).padStart(2, "0")}`;
+	const sameDay =
+		at.getFullYear() === now.getFullYear() &&
+		at.getMonth() === now.getMonth() &&
+		at.getDate() === now.getDate();
+	if (sameDay) return `resets ${hhmm}`;
+	const day = at.getDate();
+	const mon = at.toLocaleString("en", { month: "short" });
+	return `resets ${hhmm} on ${day} ${mon}`;
+}
+
+const WINDOW_RANK: Record<string, number> = { "5h": 0, weekly: 1 };
+
+/** Full report text: per group, 5h bucket before weekly (the window users
+ *  hit first), name labeled bar with percent and reset time. */
+export function formatAgyQuotaReport(report: AgyQuotaReport, now: Date = new Date()): string {
+	const lines: string[] = ["Antigravity quota (account-level, both engines)"];
+	for (const group of report.groups) {
+		lines.push("", group.name);
+		const buckets = [...group.buckets].sort(
+			(a, b) => (WINDOW_RANK[a.window] ?? 9) - (WINDOW_RANK[b.window] ?? 9),
+		);
+		for (const bucket of buckets) {
+			const pct = Math.round(bucket.remainingFraction * 100);
+			const reset = bucket.resetTime !== undefined ? ` · ${resetLabel(bucket.resetTime, now)}` : "";
+			lines.push(`  ${bucket.name}: ${quotaBar(bucket.remainingFraction)} ${pct}%${reset}`);
+		}
+	}
+	return lines.join("\n");
+}