oma-coding-agent 1.1.4

package/src/slash-commands/helpers/ssh.ts

@@ -0,0 +1,195 @@
+import { getSSHConfigPath } from "@oh-my-pi/pi-utils";
+import { addSSHHost, readSSHConfigFile, removeSSHHost, type SSHHostConfig } from "../../ssh/config-writer";
+import { parseCommandArgs } from "../../utils/command-args";
+import type { ParsedSlashCommand, SlashCommandResult, SlashCommandRuntime } from "../types";
+import { commandConsumed, errorMessage, parseNamedScopeArgs, parseSubcommand, usage } from "./parse";
+
+interface ParsedSshAddArgs {
+	name?: string;
+	scope: "user" | "project";
+	host?: string;
+	username?: string;
+	port?: number;
+	keyPath?: string;
+	error?: string;
+}
+
+type SshAddOptionParser = (parsed: ParsedSshAddArgs, value: string | undefined) => string | undefined;
+
+const SSH_ADD_USAGE =
+	"Usage: /ssh add <name> --host <host> [--user <user>] [--port <port>] [--key <keyPath>] [--scope project|user]";
+
+const SSH_ADD_OPTION_PARSERS = new Map<string, SshAddOptionParser>([
+	[
+		"--host",
+		(parsed, value) => {
+			if (!value) return "Missing value for --host.";
+			parsed.host = value;
+			return undefined;
+		},
+	],
+	[
+		"--user",
+		(parsed, value) => {
+			if (!value) return "Missing value for --user.";
+			parsed.username = value;
+			return undefined;
+		},
+	],
+	[
+		"--port",
+		(parsed, value) => {
+			if (!value) return "Missing value for --port.";
+			// Reject any non-integer token. `Number.parseInt` accepts trailing
+			// garbage (parseInt("22oops") === 22) which silently coerces typos
+			// to valid-looking ports.
+			if (!/^\d+$/.test(value)) {
+				return "Invalid --port value. Must be an integer between 1 and 65535.";
+			}
+			const port = Number.parseInt(value, 10);
+			if (port < 1 || port > 65535) {
+				return "Invalid --port value. Must be an integer between 1 and 65535.";
+			}
+			parsed.port = port;
+			return undefined;
+		},
+	],
+	[
+		"--key",
+		(parsed, value) => {
+			if (!value) return "Missing value for --key.";
+			parsed.keyPath = value;
+			return undefined;
+		},
+	],
+	[
+		"--scope",
+		(parsed, value) => {
+			if (!value || (value !== "project" && value !== "user")) return "Invalid --scope value. Use project or user.";
+			parsed.scope = value;
+			return undefined;
+		},
+	],
+]);
+
+function parseSshAddArgs(rest: string): ParsedSshAddArgs {
+	const tokens = parseCommandArgs(rest);
+	const parsed: ParsedSshAddArgs = { scope: "project" };
+	let index = 0;
+	if (tokens.length > 0 && !tokens[0]!.startsWith("-")) {
+		parsed.name = tokens[0];
+		index = 1;
+	}
+	while (index < tokens.length) {
+		const arg = tokens[index]!;
+		const parser = SSH_ADD_OPTION_PARSERS.get(arg);
+		if (!parser) return { ...parsed, error: `Unknown option: ${arg}` };
+		const error = parser(parsed, tokens[index + 1]);
+		if (error) return { ...parsed, error };
+		index += 2;
+	}
+	return parsed;
+}
+
+const SSH_HELP_TEXT = [
+	"SSH host management (ACP mode)",
+	"  /ssh add <name> --host <host> [--user <user>] [--port <port>] [--key <keyPath>] [--scope project|user]",
+	"  /ssh list                                       List configured SSH hosts",
+	"  /ssh remove <name> [--scope project|user]       Remove an SSH host",
+	"  /ssh help                                        Show this help",
+].join("\n");
+
+async function handleListCommand(runtime: SlashCommandRuntime): Promise<SlashCommandResult> {
+	try {
+		const userPath = getSSHConfigPath("user", runtime.cwd);
+		const projectPath = getSSHConfigPath("project", runtime.cwd);
+		const [userConfig, projectConfig] = await Promise.all([
+			readSSHConfigFile(userPath),
+			readSSHConfigFile(projectPath),
+		]);
+		const entries: Array<{ name: string; host: string; user?: string; port?: number; scope: string }> = [];
+		// Capability loader resolves project before user, so list project hosts
+		// first and let the user-scope loop skip duplicates. Otherwise a host
+		// shared between scopes shows up under "user" when the project entry
+		// is the one actually in effect.
+		for (const [name, config] of Object.entries(projectConfig.hosts ?? {})) {
+			entries.push({ name, host: config.host, user: config.username, port: config.port, scope: "project" });
+		}
+		for (const [name, config] of Object.entries(userConfig.hosts ?? {})) {
+			if (!entries.some(entry => entry.name === name)) {
+				entries.push({ name, host: config.host, user: config.username, port: config.port, scope: "user" });
+			}
+		}
+		if (entries.length === 0) {
+			await runtime.output("No SSH hosts configured.");
+			return commandConsumed();
+		}
+		await runtime.output(
+			entries
+				.map(entry => `${entry.name} | ${entry.host} | ${entry.user ?? "-"} | ${entry.port ?? 22} [${entry.scope}]`)
+				.join("\n"),
+		);
+		return commandConsumed();
+	} catch (err) {
+		return usage(`Failed to list SSH hosts: ${errorMessage(err)}`, runtime);
+	}
+}
+
+async function handleRemoveCommand(rest: string, runtime: SlashCommandRuntime): Promise<SlashCommandResult> {
+	const parsed = parseNamedScopeArgs(rest, "Invalid --scope value. Use project or user.");
+	if (parsed.error) return usage(parsed.error, runtime);
+	if (!parsed.name) return usage("Usage: /ssh remove <name> [--scope project|user]", runtime);
+	try {
+		const filePath = getSSHConfigPath(parsed.scope, runtime.cwd);
+		await removeSSHHost(filePath, parsed.name);
+		await runtime.session.refreshSshTool();
+		await runtime.output(`Removed SSH host "${parsed.name}" from ${parsed.scope} config.`);
+		return commandConsumed();
+	} catch (err) {
+		return usage(`Failed to remove SSH host: ${errorMessage(err)}`, runtime);
+	}
+}
+
+async function handleAddCommand(rest: string, runtime: SlashCommandRuntime): Promise<SlashCommandResult> {
+	if (!rest) return usage(SSH_ADD_USAGE, runtime);
+	const parsed = parseSshAddArgs(rest);
+	if (parsed.error) return usage(parsed.error, runtime);
+	if (!parsed.name) return usage("Host name required. Usage: /ssh add <name> --host <host> ...", runtime);
+	if (!parsed.host) return usage("--host is required. Usage: /ssh add <name> --host <host> ...", runtime);
+	const hostConfig: SSHHostConfig = { host: parsed.host };
+	if (parsed.username) hostConfig.username = parsed.username;
+	if (parsed.port) hostConfig.port = parsed.port;
+	if (parsed.keyPath) hostConfig.keyPath = parsed.keyPath;
+	try {
+		const filePath = getSSHConfigPath(parsed.scope, runtime.cwd);
+		await addSSHHost(filePath, parsed.name, hostConfig);
+		await runtime.session.refreshSshTool({ activateIfAvailable: true });
+		await runtime.output(`Added SSH host "${parsed.name}" (${parsed.scope}).`);
+		return commandConsumed();
+	} catch (err) {
+		return usage(`Failed to add SSH host: ${errorMessage(err)}`, runtime);
+	}
+}
+
+/** ACP/text-mode `/ssh` handler. Shared by both dispatchers via the spec. */
+export async function handleSshAcp(
+	command: ParsedSlashCommand,
+	runtime: SlashCommandRuntime,
+): Promise<SlashCommandResult> {
+	const { verb, rest } = parseSubcommand(command.args);
+	if (!verb || verb === "help") {
+		await runtime.output(SSH_HELP_TEXT);
+		return commandConsumed();
+	}
+	switch (verb) {
+		case "list":
+			return await handleListCommand(runtime);
+		case "remove":
+		case "rm":
+			return await handleRemoveCommand(rest, runtime);
+		case "add":
+			return await handleAddCommand(rest, runtime);
+		default:
+			return usage(`Unknown /ssh subcommand: ${verb}. Use /ssh help for available subcommands.`, runtime);
+	}
+}

package/src/slash-commands/helpers/stats-dashboard.ts

@@ -0,0 +1,85 @@
+import * as stats from "@oh-my-pi/omp-stats";
+import * as openUtils from "../../utils/open";
+
+export const DEFAULT_STATS_DASHBOARD_PORT = 3847;
+
+interface StatsDashboardServer {
+	port: number;
+	stop: () => void;
+}
+
+export interface StatsDashboardArgs {
+	port: number;
+}
+
+export interface StatsDashboardLaunchResult {
+	url: string;
+	message: string;
+}
+
+let activeStatsServer: StatsDashboardServer | undefined;
+
+const STATS_DASHBOARD_USAGE = "Usage: /stats [--port <port>]";
+
+function parsePort(value: string | undefined): number | string {
+	if (!value) return `Missing port. ${STATS_DASHBOARD_USAGE}`;
+	if (!/^\d+$/.test(value)) return `Invalid port: ${value}`;
+	const port = Number(value);
+	if (!Number.isInteger(port) || port < 0 || port > 65_535) return `Invalid port: ${value}`;
+	return port;
+}
+
+export function parseStatsDashboardArgs(args: string): StatsDashboardArgs | { error: string } {
+	const tokens = args.split(/\s+/).filter(Boolean);
+	let port = DEFAULT_STATS_DASHBOARD_PORT;
+
+	for (let i = 0; i < tokens.length; i++) {
+		const token = tokens[i];
+		if (token === "--port" || token === "-p") {
+			const parsed = parsePort(tokens[++i]);
+			if (typeof parsed === "string") return { error: parsed };
+			port = parsed;
+			continue;
+		}
+		if (token.startsWith("--port=")) {
+			const parsed = parsePort(token.slice("--port=".length));
+			if (typeof parsed === "string") return { error: parsed };
+			port = parsed;
+			continue;
+		}
+		return { error: `Unknown option: ${token}. ${STATS_DASHBOARD_USAGE}` };
+	}
+
+	return { port };
+}
+
+export async function launchStatsDashboard(args: StatsDashboardArgs): Promise<StatsDashboardLaunchResult> {
+	const { processed, files } = await stats.syncAllSessions();
+	const total = await stats.getTotalMessageCount();
+	let requestedPortIgnored = false;
+
+	if (!activeStatsServer) {
+		activeStatsServer = await stats.startServer(args.port);
+	} else if (args.port !== activeStatsServer.port) {
+		requestedPortIgnored = true;
+	}
+
+	const url = `http://localhost:${activeStatsServer.port}`;
+	openUtils.openPath(url);
+
+	const serverLine = requestedPortIgnored
+		? `Dashboard already running at: ${url} (requested port ${args.port} ignored)`
+		: `Dashboard available at: ${url}`;
+
+	return {
+		url,
+		message: `Synced ${processed} new entries from ${files} files (${total} total)\n${serverLine}`,
+	};
+}
+
+export function stopStatsDashboard(): void {
+	if (!activeStatsServer) return;
+	activeStatsServer.stop();
+	activeStatsServer = undefined;
+	stats.closeDb();
+}

package/src/slash-commands/helpers/todo.ts

@@ -0,0 +1,279 @@
+import * as path from "node:path";
+import type { TodoPhase } from "../../tools/todo";
+import {
+	applyOpsToPhases,
+	getLatestTodoPhasesFromEntries,
+	markdownToPhases,
+	phasesToMarkdown,
+	USER_TODO_EDIT_CUSTOM_TYPE,
+} from "../../tools/todo";
+import type { ParsedSlashCommand, SlashCommandResult, SlashCommandRuntime } from "../types";
+import { commandConsumed, parseSubcommand, usage } from "./parse";
+
+type TodoMutationVerb = "done" | "drop" | "rm";
+
+interface TodoTaskMatch {
+	task: { content: string; status: string };
+	phase: TodoPhase;
+}
+
+function tokenize(input: string): string[] {
+	const tokens: string[] = [];
+	let current = "";
+	let inQuote = false;
+	for (let index = 0; index < input.length; index++) {
+		const ch = input[index];
+		if (ch === "\\" && index + 1 < input.length) {
+			current += input[++index];
+			continue;
+		}
+		if (ch === '"') {
+			inQuote = !inQuote;
+			continue;
+		}
+		if (!inQuote && /\s/.test(ch)) {
+			if (current) {
+				tokens.push(current);
+				current = "";
+			}
+			continue;
+		}
+		current += ch;
+	}
+	if (current) tokens.push(current);
+	return tokens;
+}
+
+function titleCaseWords(text: string): string {
+	return text
+		.split(/\s+/)
+		.filter(Boolean)
+		.map(word => word[0].toUpperCase() + word.slice(1))
+		.join(" ");
+}
+
+function titleCaseSentence(text: string): string {
+	const trimmed = text.trim();
+	if (!trimmed) return trimmed;
+	return trimmed[0].toUpperCase() + trimmed.slice(1);
+}
+
+function findPhaseFuzzy(phases: TodoPhase[], query: string): TodoPhase | undefined {
+	const normalizedQuery = query.trim().toLowerCase();
+	if (!normalizedQuery) return undefined;
+	const exact = phases.find(phase => phase.name.toLowerCase() === normalizedQuery);
+	if (exact) return exact;
+	const prefixMatches = phases.filter(phase => phase.name.toLowerCase().startsWith(normalizedQuery));
+	if (prefixMatches.length === 1) return prefixMatches[0];
+	const substringMatches = phases.filter(phase => phase.name.toLowerCase().includes(normalizedQuery));
+	if (substringMatches.length === 1) return substringMatches[0];
+	return undefined;
+}
+
+function findTaskFuzzy(phases: TodoPhase[], query: string): TodoTaskMatch | undefined {
+	const normalizedQuery = query.trim().toLowerCase();
+	if (!normalizedQuery) return undefined;
+	for (const phase of phases) {
+		for (const task of phase.tasks) {
+			if (task.content.toLowerCase() === normalizedQuery) return { task, phase };
+		}
+	}
+	const matches: TodoTaskMatch[] = [];
+	for (const phase of phases) {
+		for (const task of phase.tasks) {
+			if (task.content.toLowerCase().includes(normalizedQuery)) matches.push({ task, phase });
+		}
+	}
+	if (matches.length === 1) return matches[0];
+	const active = matches.filter(match => match.task.status === "in_progress" || match.task.status === "pending");
+	if (active.length === 1) return active[0];
+	return undefined;
+}
+
+function currentPhases(runtime: SlashCommandRuntime): TodoPhase[] {
+	const fromEntries = getLatestTodoPhasesFromEntries(runtime.sessionManager.getBranch());
+	return fromEntries.length > 0 ? fromEntries : runtime.session.getTodoPhases();
+}
+
+function commitTodos(runtime: SlashCommandRuntime, phases: TodoPhase[]): void {
+	runtime.session.setTodoPhases(phases);
+	runtime.sessionManager.appendCustomEntry(USER_TODO_EDIT_CUSTOM_TYPE, { phases });
+}
+
+const TODO_HELP_TEXT = [
+	"Usage: /todo <verb> [args]",
+	"  /todo                              Show current todos",
+	"  /todo edit                         (TUI only) open in $EDITOR",
+	"  /todo copy                         Print todos as Markdown",
+	"  /todo export [<path>]              Write todos to file (default: TODO.md)",
+	"  /todo import [<path>]              Replace todos from file (default: TODO.md)",
+	"  /todo append [<phase>] <task...>   Append a task",
+	"  /todo start  <task>                Mark task in_progress (fuzzy match)",
+	"  /todo done   [<task|phase>]        Mark task/phase/all completed",
+	"  /todo drop   [<task|phase>]        Mark task/phase/all abandoned",
+	"  /todo rm     [<task|phase>]        Remove task/phase/all",
+].join("\n");
+
+async function handleTodoCopyCommand(runtime: SlashCommandRuntime): Promise<SlashCommandResult> {
+	const phases = currentPhases(runtime);
+	const markdown = phases.length === 0 ? "" : phasesToMarkdown(phases).trimEnd();
+	await runtime.output(`Copy not available in ACP mode; printing instead:\n\n${markdown || "No todos."}`);
+	return commandConsumed();
+}
+
+async function handleTodoExportCommand(restArgs: string, runtime: SlashCommandRuntime): Promise<SlashCommandResult> {
+	const phases = currentPhases(runtime);
+	if (phases.length === 0) {
+		await runtime.output("No todos to export.");
+		return commandConsumed();
+	}
+	const target = restArgs ? path.resolve(runtime.cwd, restArgs) : path.resolve(runtime.cwd, "TODO.md");
+	await Bun.write(target, phasesToMarkdown(phases));
+	await runtime.output(`Wrote todos to ${target}`);
+	return commandConsumed();
+}
+
+async function handleTodoImportCommand(restArgs: string, runtime: SlashCommandRuntime): Promise<SlashCommandResult> {
+	const target = restArgs ? path.resolve(runtime.cwd, restArgs) : path.resolve(runtime.cwd, "TODO.md");
+	let content: string;
+	try {
+		content = await Bun.file(target).text();
+	} catch (err) {
+		return usage(`Failed to read ${target}: ${err instanceof Error ? err.message : String(err)}`, runtime);
+	}
+	const { phases, errors } = markdownToPhases(content);
+	if (errors.length > 0) return usage(`Could not parse ${target}:\n  ${errors.join("\n  ")}`, runtime);
+	commitTodos(runtime, phases);
+	const taskCount = phases.reduce((sum, phase) => sum + phase.tasks.length, 0);
+	await runtime.output(`Imported ${phases.length} phase(s), ${taskCount} task(s) from ${target}.`);
+	return commandConsumed();
+}
+
+async function handleTodoAppendCommand(restArgs: string, runtime: SlashCommandRuntime): Promise<SlashCommandResult> {
+	const tokens = tokenize(restArgs);
+	if (tokens.length === 0) return usage("Usage: /todo append [<phase>] <task...>", runtime);
+
+	const current = currentPhases(runtime);
+	const phaseName = tokens.length === 1 ? undefined : tokens[0];
+	const content = tokens.length === 1 ? tokens[0]! : tokens.slice(1).join(" ");
+	const next = current.map(phase => ({ ...phase, tasks: phase.tasks.slice() }));
+	let targetPhase: TodoPhase;
+
+	if (phaseName) {
+		const existing = findPhaseFuzzy(next, phaseName);
+		targetPhase = existing ?? { name: titleCaseWords(phaseName), tasks: [] };
+		if (!existing) next.push(targetPhase);
+	} else if (next.length > 0) {
+		targetPhase = next[next.length - 1]!;
+	} else {
+		targetPhase = { name: "Todos", tasks: [] };
+		next.push(targetPhase);
+	}
+
+	const finalContent = titleCaseSentence(content);
+	targetPhase.tasks.push({ content: finalContent, status: "pending" });
+	commitTodos(runtime, next);
+	await runtime.output(`Appended to ${targetPhase.name}: ${finalContent}`);
+	return commandConsumed();
+}
+
+async function handleTodoStartCommand(restArgs: string, runtime: SlashCommandRuntime): Promise<SlashCommandResult> {
+	if (!restArgs) return usage("Usage: /todo start <task>", runtime);
+	const current = currentPhases(runtime);
+	const query = tokenize(restArgs).join(" ") || restArgs;
+	const hit = findTaskFuzzy(current, query);
+	if (!hit) return usage(`No task matched "${restArgs}". Use /todo to list current tasks.`, runtime);
+	const { phases } = applyOpsToPhases(current, [{ op: "start", task: hit.task.content }]);
+	commitTodos(runtime, phases);
+	await runtime.output(`Started: ${hit.task.content}`);
+	return commandConsumed();
+}
+
+async function handleTodoMutationCommand(
+	verb: TodoMutationVerb,
+	restArgs: string,
+	runtime: SlashCommandRuntime,
+): Promise<SlashCommandResult> {
+	const current = currentPhases(runtime);
+	const trimmedArg = restArgs.trim();
+	if (!trimmedArg) {
+		if (verb === "rm") {
+			commitTodos(runtime, []);
+			await runtime.output("Cleared all todos.");
+			return commandConsumed();
+		}
+		const { phases } = applyOpsToPhases(current, [{ op: verb }]);
+		commitTodos(runtime, phases);
+		await runtime.output(verb === "done" ? "Marked all tasks completed." : "Marked all tasks abandoned.");
+		return commandConsumed();
+	}
+
+	const taskHit = findTaskFuzzy(current, trimmedArg);
+	if (taskHit) {
+		const { phases } = applyOpsToPhases(current, [{ op: verb, task: taskHit.task.content }]);
+		commitTodos(runtime, phases);
+		const label = verb === "done" ? "Marked completed" : verb === "drop" ? "Marked abandoned" : "Removed";
+		await runtime.output(`${label}: ${taskHit.task.content}`);
+		return commandConsumed();
+	}
+
+	const phaseHit = findPhaseFuzzy(current, trimmedArg);
+	if (phaseHit) {
+		const { phases } = applyOpsToPhases(current, [{ op: verb, phase: phaseHit.name }]);
+		commitTodos(runtime, phases);
+		const message =
+			verb === "done"
+				? `Marked phase ${phaseHit.name} completed.`
+				: verb === "drop"
+					? `Marked phase ${phaseHit.name} abandoned.`
+					: `Removed phase: ${phaseHit.name}`;
+		await runtime.output(message);
+		return commandConsumed();
+	}
+
+	return usage(`No task or phase matched "${trimmedArg}".`, runtime);
+}
+
+/** ACP/text-mode `/todo` handler. Shared by both dispatchers via the spec. */
+export async function handleTodoAcp(
+	command: ParsedSlashCommand,
+	runtime: SlashCommandRuntime,
+): Promise<SlashCommandResult> {
+	const trimmed = command.args.trim();
+	if (!trimmed) {
+		const phases = currentPhases(runtime);
+		await runtime.output(
+			phases.length === 0 ? "No todos. Use /todo append <task> to start one." : phasesToMarkdown(phases).trimEnd(),
+		);
+		return commandConsumed();
+	}
+
+	const { verb, rest } = parseSubcommand(trimmed);
+	switch (verb) {
+		case "copy":
+			return await handleTodoCopyCommand(runtime);
+		case "export":
+			return await handleTodoExportCommand(rest, runtime);
+		case "import":
+			return await handleTodoImportCommand(rest, runtime);
+		case "append":
+			return await handleTodoAppendCommand(rest, runtime);
+		case "start":
+			return await handleTodoStartCommand(rest, runtime);
+		case "done":
+		case "drop":
+		case "rm":
+			return await handleTodoMutationCommand(verb, rest, runtime);
+		case "edit":
+			return usage(
+				"/todo edit requires the TUI editor; use /todo export then /todo import for non-interactive edits.",
+				runtime,
+			);
+		case "help":
+		case "?":
+			await runtime.output(TODO_HELP_TEXT);
+			return commandConsumed();
+		default:
+			return usage("Unknown /todo subcommand. Use append, start, done, drop, rm, copy, export, import.", runtime);
+	}
+}

package/src/slash-commands/helpers/usage-report.ts

@@ -0,0 +1,128 @@
+import type { UsageLimit, UsageReport } from "@oh-my-pi/pi-ai";
+import type { OAuthAccountIdentity } from "../../session/auth-storage";
+import type { SlashCommandRuntime } from "../types";
+import { reportMatchesActiveAccount } from "./active-oauth-account";
+import { formatDuration, renderAsciiBar } from "./format";
+
+function formatProviderName(provider: string): string {
+	return provider
+		.split(/[-_]/g)
+		.map(part => (part ? part[0].toUpperCase() + part.slice(1) : ""))
+		.join(" ");
+}
+
+function formatUsageAmount(limit: UsageLimit): string {
+	const amount = limit.amount;
+	const used = amount.used ?? (amount.usedFraction !== undefined ? amount.usedFraction * 100 : undefined);
+	const remainingFraction =
+		amount.remainingFraction ??
+		(amount.usedFraction !== undefined ? Math.max(0, 1 - amount.usedFraction) : undefined);
+	const unit = amount.unit === "percent" ? "%" : ` ${amount.unit}`;
+	const usedText = used === undefined ? "unknown used" : `${used.toFixed(2)}${unit} used`;
+	const remainingText = remainingFraction === undefined ? "" : ` (${(remainingFraction * 100).toFixed(1)}% left)`;
+	return `${usedText}${remainingText}`;
+}
+
+function formatUsageReportAccount(report: UsageReport, limit: UsageLimit, index: number): string {
+	const email = report.metadata?.email;
+	if (typeof email === "string" && email) return email;
+	const accountId = report.metadata?.accountId ?? limit.scope.accountId;
+	if (typeof accountId === "string" && accountId) return accountId;
+	const projectId = report.metadata?.projectId ?? limit.scope.projectId;
+	if (typeof projectId === "string" && projectId) return projectId;
+	return `account ${index + 1}`;
+}
+
+function renderUsageReports(
+	reports: UsageReport[],
+	nowMs: number,
+	resolveActiveAccount?: (provider: string) => OAuthAccountIdentity | undefined,
+): string {
+	const latestFetchedAt = Math.max(...reports.map(report => report.fetchedAt ?? 0));
+	const lines = [`Usage${latestFetchedAt ? ` (${formatDuration(nowMs - latestFetchedAt)} ago)` : ""}`];
+	const grouped = new Map<string, UsageReport[]>();
+	for (const report of reports) {
+		const providerReports = grouped.get(report.provider) ?? [];
+		providerReports.push(report);
+		grouped.set(report.provider, providerReports);
+	}
+
+	for (const [provider, providerReports] of [...grouped.entries()].sort(([left], [right]) =>
+		left.localeCompare(right),
+	)) {
+		lines.push("", formatProviderName(provider));
+		const activeAccount = resolveActiveAccount?.(provider);
+		for (const report of providerReports) {
+			const inUse = reportMatchesActiveAccount(report, activeAccount);
+			const savedResets = report.resetCredits?.availableCount ?? 0;
+			if (savedResets > 0) {
+				const resetLabel =
+					typeof report.metadata?.email === "string"
+						? report.metadata.email
+						: typeof report.metadata?.accountId === "string"
+							? report.metadata.accountId
+							: "account";
+				lines.push(
+					`- ${resetLabel}: ${savedResets} saved rate-limit reset${savedResets === 1 ? "" : "s"} available — /usage reset to spend`,
+				);
+			}
+			if (report.limits.length === 0) {
+				const email = typeof report.metadata?.email === "string" ? report.metadata.email : "account";
+				lines.push(`- ${email}: no limits reported`);
+				continue;
+			}
+			for (let index = 0; index < report.limits.length; index++) {
+				const limit = report.limits[index]!;
+				const window = limit.window?.label ?? limit.scope.windowId;
+				const tier = limit.scope.tier ? ` (${limit.scope.tier})` : "";
+				lines.push(`- ${limit.label}${tier}${window ? ` — ${window}` : ""}`);
+				lines.push(
+					`  ${formatUsageReportAccount(report, limit, index)}: ${formatUsageAmount(limit)}${inUse ? "  ← in use by this session" : ""}`,
+				);
+				lines.push(`  ${renderAsciiBar(limit.amount.usedFraction)}`);
+				if (limit.window?.resetsAt && limit.window.resetsAt > nowMs) {
+					lines.push(`  resets in ${formatDuration(limit.window.resetsAt - nowMs)}`);
+				}
+				if (limit.notes && limit.notes.length > 0) lines.push(`  ${limit.notes.join(" • ")}`);
+			}
+		}
+	}
+	return ["```", ...lines, "```"].join("\n");
+}
+
+/**
+ * Build the `/usage` ACP-mode text. Prefers provider-reported limits when the
+ * session exposes `fetchUsageReports`; otherwise falls back to the local
+ * session-manager tallies.
+ */
+export async function buildUsageReportText(runtime: SlashCommandRuntime): Promise<string> {
+	const provider = runtime.session as SlashCommandRuntime["session"] & {
+		fetchUsageReports?: () => Promise<UsageReport[] | null>;
+	};
+	if (provider.fetchUsageReports) {
+		const reports = await provider.fetchUsageReports();
+		if (reports && reports.length > 0) {
+			const currentProvider = runtime.session.model?.provider;
+			const activeAccount = currentProvider
+				? runtime.session.modelRegistry.authStorage.getOAuthAccountIdentity(
+						currentProvider,
+						runtime.session.sessionId,
+					)
+				: undefined;
+			return renderUsageReports(reports, Date.now(), providerId =>
+				providerId === currentProvider ? activeAccount : undefined,
+			);
+		}
+	}
+
+	const stats = runtime.session.sessionManager.getUsageStatistics();
+	return [
+		"Usage",
+		`Input tokens: ${stats.input}`,
+		`Output tokens: ${stats.output}`,
+		`Cache read tokens: ${stats.cacheRead}`,
+		`Cache write tokens: ${stats.cacheWrite}`,
+		`Premium requests: ${stats.premiumRequests}`,
+		`Cost: $${stats.cost.toFixed(6)}`,
+	].join("\n");
+}