@oh-my-pi/pi-coding-agent 14.9.8 → 15.0.0

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

@@ -0,0 +1,85 @@
+import type { ParsedSlashCommand, SlashCommandResult, SlashCommandRuntime } from "../types";
+
+export interface ParsedSubcommand {
+	verb: string;
+	rest: string;
+}
+
+export type ConfigScope = "user" | "project";
+
+export interface NamedScopeArgs {
+	name?: string;
+	scope: ConfigScope;
+	error?: string;
+}
+
+/**
+ * Parse a slash-invocation string into `name`/`args`.
+ *
+ * The separator is the earliest whitespace or `:` character so that both
+ * `/foo bar` and `/foo:bar` map to `{ name: "foo", args: "bar" }`.
+ */
+export function parseSlashCommand(text: string): ParsedSlashCommand | null {
+	if (!text.startsWith("/")) return null;
+	const body = text.slice(1);
+	if (!body) return null;
+	const firstWhitespace = body.search(/\s/);
+	const firstColon = body.indexOf(":");
+	const firstSeparator =
+		firstWhitespace === -1 ? firstColon : firstColon === -1 ? firstWhitespace : Math.min(firstWhitespace, firstColon);
+	if (firstSeparator === -1) return { name: body, args: "", text };
+	return {
+		name: body.slice(0, firstSeparator),
+		args: body.slice(firstSeparator + 1).trim(),
+		text,
+	};
+}
+
+/** Mark a command as fully consumed in the ACP shape. */
+export function commandConsumed(): { consumed: true } {
+	return { consumed: true };
+}
+
+/** Emit a usage/error message and consume the command. */
+export async function usage(text: string, runtime: SlashCommandRuntime): Promise<SlashCommandResult> {
+	await runtime.output(text);
+	return commandConsumed();
+}
+
+/** Split `<verb> <rest>` on the first whitespace; lowercases `verb`. */
+export function parseSubcommand(input: string): ParsedSubcommand {
+	const trimmed = input.trim();
+	if (!trimmed) return { verb: "", rest: "" };
+	const spaceIdx = trimmed.search(/\s/);
+	if (spaceIdx === -1) return { verb: trimmed.toLowerCase(), rest: "" };
+	return { verb: trimmed.slice(0, spaceIdx).toLowerCase(), rest: trimmed.slice(spaceIdx + 1).trim() };
+}
+
+export function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Parse `<name?> [--scope project|user]`-style argument strings used by
+ * remove/rm-style subcommands. `name` is optional so callers can surface
+ * "name required" diagnostics with their own messaging.
+ */
+export function parseNamedScopeArgs(rest: string, invalidScopeMessage: string): NamedScopeArgs {
+	const tokens = rest.split(/\s+/).filter(Boolean);
+	let name: string | undefined;
+	let scope: ConfigScope = "project";
+	let i = 0;
+	if (tokens.length > 0 && !tokens[0]!.startsWith("-")) {
+		name = tokens[0];
+		i = 1;
+	}
+	while (i < tokens.length) {
+		const token = tokens[i]!;
+		if (token !== "--scope") return { scope, error: `Unknown option: ${token}` };
+		const value = tokens[i + 1];
+		if (!value || (value !== "project" && value !== "user")) return { scope, error: invalidScopeMessage };
+		scope = value;
+		i += 2;
+	}
+	return { name, scope };
+}

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

@@ -0,0 +1,193 @@
+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.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.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/todo.ts

@@ -0,0 +1,279 @@
+import * as path from "node:path";
+import type { TodoPhase } from "../../tools/todo-write";
+import {
+	applyOpsToPhases,
+	getLatestTodoPhasesFromEntries,
+	markdownToPhases,
+	phasesToMarkdown,
+	USER_TODO_EDIT_CUSTOM_TYPE,
+} from "../../tools/todo-write";
+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,91 @@
+import type { UsageLimit, UsageReport } from "@oh-my-pi/pi-ai";
+import type { SlashCommandRuntime } from "../types";
+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;
+	return `account ${index + 1}`;
+}
+
+function renderUsageReports(reports: UsageReport[], nowMs: number): 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));
+		for (const report of providerReports) {
+			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)}`);
+				lines.push(`  ${renderAsciiBar(limit.amount.usedFraction)}`);
+				if (limit.window?.resetsAt) 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) return renderUsageReports(reports, Date.now());
+	}
+
+	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");
+}