feat(usage): add a Usage tab with provider limits and usage history

packages/types/src/__tests__/history.test.ts

@@ -64,3 +64,38 @@ describe("historyItemSchema", () => {
 		expect(historyItemSchema.parse(baseItem)).not.toHaveProperty("title")
 	})
 })
+
+describe("usageByModel on history items", () => {
+	const base = { id: "task-1", number: 1, ts: 1, task: "t", tokensIn: 1, tokensOut: 1, totalCost: 0 }
+
+	it("preserves every field of a per-model entry", () => {
+		const entry = {
+			apiProvider: "provider-a",
+			modelId: "model-a",
+			requests: 3,
+			tokensIn: 100,
+			tokensOut: 50,
+			cacheReads: 40,
+			cacheWrites: 10,
+			cost: 0.25,
+		}
+		expect(historyItemSchema.parse({ ...base, usageByModel: [entry, { ...entry, modelId: "model-b" }] })).toEqual({
+			...base,
+			usageByModel: [entry, { ...entry, modelId: "model-b" }],
+		})
+	})
+
+	it("accepts an entry with no provider, model or cache counts, and an item with no breakdown", () => {
+		const bare = { requests: 1, tokensIn: 2, tokensOut: 3, cost: 0 }
+		expect(historyItemSchema.parse({ ...base, usageByModel: [bare] }).usageByModel).toEqual([bare])
+		expect(historyItemSchema.parse(base).usageByModel).toBeUndefined()
+	})
+
+	it.each([
+		["a missing request count", { tokensIn: 1, tokensOut: 1, cost: 0 }],
+		["a non-numeric cost", { requests: 1, tokensIn: 1, tokensOut: 1, cost: "free" }],
+		["a non-numeric token count", { requests: 1, tokensIn: "1", tokensOut: 1, cost: 0 }],
+	])("rejects %s", (_name, entry) => {
+		expect(historyItemSchema.safeParse({ ...base, usageByModel: [entry] }).success).toBe(false)
+	})
+})

packages/types/src/global-settings.ts

@@ -309,6 +309,7 @@ export const globalSettingsSchema = z.object({
 	lastSettingsExportPath: z.string().optional(),
 	lastTaskExportPath: z.string().optional(),
 	lastImageSavePath: z.string().optional(),
+	lastUsageExportPath: z.string().optional(),
 
 	/**
 	 * Path to worktree to auto-open after switching workspaces.

packages/types/src/history.ts

@@ -26,6 +26,23 @@ export const pendingTaskActionSchema = z.discriminatedUnion("kind", [
 
 export type PendingTaskAction = z.infer<typeof pendingTaskActionSchema>
 
+/**
+ * Token/cost totals for one provider+model within a task. A task can span
+ * several (the user may switch profiles mid-task), so history keeps a list.
+ */
+export const usageByModelEntrySchema = z.object({
+	apiProvider: z.string().optional(),
+	modelId: z.string().optional(),
+	requests: z.number(),
+	tokensIn: z.number(),
+	tokensOut: z.number(),
+	cacheReads: z.number().optional(),
+	cacheWrites: z.number().optional(),
+	cost: z.number(),
+})
+
+export type UsageByModelEntry = z.infer<typeof usageByModelEntrySchema>
+
 export const historyItemSchema = z.object({
 	id: z.string(),
 	rootTaskId: z.string().optional(),
@@ -39,6 +56,8 @@ export const historyItemSchema = z.object({
 	cacheWrites: z.number().optional(),
 	cacheReads: z.number().optional(),
 	totalCost: z.number(),
+	/** Per provider+model breakdown, recorded as requests happen. Absent on tasks created before this was tracked. */
+	usageByModel: z.array(usageByModelEntrySchema).optional(),
 	size: z.number().optional(),
 	workspace: z.string().optional(),
 	mode: z.string().optional(),

packages/types/src/providers/vscode-llm.ts

@@ -11,8 +11,93 @@ export const vsCodeLmModelsMessageTypes = [
 	"githubCopilotManageAccount",
 	"githubCopilotSignInResult",
 	"githubCopilotModels",
+	"requestProviderQuotas",
+	"cancelProviderQuotas",
+	"providerQuotas",
 ] as const
 
+/** The fixed name of a window, so the webview can show it in the user's language. */
+export type ProviderQuotaWindowName = {
+	key: "weekly" | "daily" | "monthly" | "unlimited" | "hours" | "days" | "credits" | "tokens"
+	count?: number
+}
+
+/**
+ * The figure of a window, as data, so the webview writes the words around it in the user's language. The amounts are
+ * already formatted (a currency, a count): they are not translated. `valueLabel` stays as the English fallback.
+ */
+export type ProviderQuotaValue =
+	| { kind: "usedOf"; used: string; limit: string }
+	| { kind: "percentUsed"; percent: number }
+	| { kind: "spentMonth" | "spentTotal" | "left"; amount: string }
+	| { kind: "notReported" }
+	/** `window` is the English name of the window, for one that has no `name`. */
+	| { kind: "creditsOf"; window: string; name?: ProviderQuotaWindowName; used: string; total: string }
+	| { kind: "windowState"; window: string; name?: ProviderQuotaWindowName; state: string }
+	| { kind: "windowDegraded"; window: string; name?: ProviderQuotaWindowName }
+
+/**
+ * One limit/balance a provider reports (e.g. Copilot premium credits for the
+ * month, an OpenRouter key limit, a DeepSeek prepaid balance).
+ */
+export interface ProviderQuotaWindow {
+	/** Stable key, e.g. "premium", "key_limit", "balance". */
+	id: string
+	/** Pre-formatted primary figure, e.g. "39,389.3 / 140,000 used", "$12.40 left". */
+	valueLabel: string
+	/**
+	 * Set when the label is just the name of a fixed window ("Weekly", "5-hour", "Unlimited"), so the webview can
+	 * show it in the user's language. `valueLabel` stays as the English fallback.
+	 */
+	name?: ProviderQuotaWindowName
+	/** Set when the figure has words around it ("$5.00 left", "12 / 20 used"): the webview writes them in the user's language. */
+	value?: ProviderQuotaValue
+	/** 0–100 when the provider reports a bounded allowance. */
+	usedPercent?: number
+	/** Epoch ms. */
+	resetAt?: number
+}
+
+export type ProviderQuota =
+	| {
+			providerId: string
+			ok: true
+			plan?: string
+			windows: ProviderQuotaWindow[]
+			fetchedAt: number
+	  }
+	| {
+			providerId: string
+			ok: false
+			reason: "signedOut" | "noCopilot" | "noKey" | "unsupported" | "error"
+			message?: string
+			fetchedAt: number
+	  }
+
+/**
+ * The signed-in account's GitHub Copilot premium-request allowance, as reported by
+ * `GET /copilot_internal/user` (the same source Copilot Chat's own usage panel reads).
+ */
+export interface GitHubCopilotQuota {
+	/** e.g. "business", "individual". */
+	plan?: string
+	unlimited: boolean
+	/** Total credits for the period; undefined when unlimited or not reported. */
+	entitlement?: number
+	/** Credits used this period, `entitlement - quota_remaining` (one decimal, like GitHub's panel). */
+	used?: number
+	/** 0–100. */
+	usedPercent?: number
+	/** Epoch ms when the allowance resets. */
+	resetAt?: number
+	/** Epoch ms when this snapshot was fetched. */
+	fetchedAt: number
+}
+
+export type GitHubCopilotQuotaResult =
+	| { ok: true; quota: GitHubCopilotQuota }
+	| { ok: false; reason: "signedOut" | "noCopilot" | "error"; message?: string }
+
 export const vsCodeLmModelsMessageTypeSchema = z.enum(vsCodeLmModelsMessageTypes)
 
 export const VsCodeLmModelsMessageType = vsCodeLmModelsMessageTypeSchema.enum

packages/types/src/vscode-extension-host.ts

@@ -16,7 +16,7 @@ import { RouterModelsMessageType, type ModelInfo, type ModelRecord, type RouterM
 import { LmStudioModelsMessageType } from "./providers/lm-studio.js"
 import { OllamaModelsMessageType } from "./providers/ollama.js"
 import { OpenAiModelsMessageType } from "./providers/openai.js"
-import { VsCodeLmModelsMessageType } from "./providers/vscode-llm.js"
+import { VsCodeLmModelsMessageType, type ProviderQuota } from "./providers/vscode-llm.js"
 import type { OpenAiCodexRateLimitInfo } from "./providers/openai-codex-rate-limits.js"
 import type { SkillMetadata } from "./skills.js"
 import type { RuleMetadata } from "./rules.js"
@@ -50,6 +50,7 @@ export interface ExtensionMessage {
 		| typeof VsCodeLmModelsMessageType.vsCodeLmModels
 		| typeof VsCodeLmModelsMessageType.githubCopilotModels
 		| typeof VsCodeLmModelsMessageType.githubCopilotSignInResult
+		| typeof VsCodeLmModelsMessageType.providerQuotas
 		| "settingsSaveResult"
 		| "vsCodeLmApiAvailable"
 		| "updatePrompt"
@@ -160,6 +161,9 @@ export interface ExtensionMessage {
 		modelInfo?: ModelInfo
 	}[]
 	githubCopilotAccount?: string | null
+	providerQuotas?: ProviderQuota[]
+	/** True when the quotas could not be loaded at all (as opposed to "no provider has a usage API"). */
+	providerQuotasFailed?: boolean
 	mcpServers?: McpServer[]
 	commits?: GitCommit[]
 	listApiConfig?: ProviderSettingsEntry[]
@@ -546,6 +550,7 @@ export interface WebviewMessage {
 		| "renameTaskWithId"
 		| "importSettings"
 		| "exportSettings"
+		| "exportUsageCsv"
 		| "resetState"
 		| typeof RouterModelsMessageType.flushRouterModels
 		| typeof RouterModelsMessageType.requestRouterModels
@@ -557,6 +562,8 @@ export interface WebviewMessage {
 		| typeof VsCodeLmModelsMessageType.githubCopilotSignIn
 		| typeof VsCodeLmModelsMessageType.githubCopilotReconnect
 		| typeof VsCodeLmModelsMessageType.githubCopilotManageAccount
+		| typeof VsCodeLmModelsMessageType.requestProviderQuotas
+		| typeof VsCodeLmModelsMessageType.cancelProviderQuotas
 		| "openImage"
 		| "saveImage"
 		| "openFile"
@@ -995,6 +1002,13 @@ export interface ClineApiReqInfo {
 	cancelReason?: ClineApiReqCancelReason
 	streamingFailedMessage?: string
 	apiProtocol?: "anthropic" | "openai"
+	/**
+	 * The provider and model that actually served this request, recorded at the
+	 * time of the call. Usage reporting reads these instead of the *current*
+	 * profile, so switching providers later doesn't relabel past requests.
+	 */
+	apiProvider?: string
+	modelId?: string
 }
 
 export type ClineApiReqCancelReason = "streaming_failed" | "user_cancelled"

src/core/checkpoints/ConversationRewindError.ts

@@ -0,0 +1,56 @@
+import { t } from "../../i18n"
+
+/**
+ * The files were put back to the checkpoint, but the conversation could not be rewound to it (the messages could not be
+ * saved, and were left as they were). The task is started again from what is saved, so the workspace and the task are
+ * not left apart with the task stopped; the caller still has to tell the user, and may keep an edit for it.
+ */
+export class ConversationRewindError extends Error {
+	/** Whether the task was started again. When it was not, nothing will take a pending edit: the caller hands it back. */
+	readonly restarted: boolean
+
+	/** `restartFailure` is given when starting the task again failed too (what failed is in its `error`). */
+	constructor(
+		override readonly cause: unknown,
+		readonly restartFailure?: { error: unknown },
+	) {
+		super(cause instanceof Error ? cause.message : String(cause))
+		this.name = "ConversationRewindError"
+		this.restarted = restartFailure === undefined
+	}
+}
+
+/**
+ * The files were restored and the conversation was rewound, but the task could not be started again (or was not
+ * rehydrated). Nothing will take a pending edit, so the caller clears it and hands it back to the user.
+ */
+export class TaskNotRestartedError extends Error {
+	constructor(override readonly cause: unknown) {
+		super(cause instanceof Error ? cause.message : String(cause))
+		this.name = "TaskNotRestartedError"
+	}
+}
+
+/** Whether the task that a restore left behind has not been started again, so that nothing will apply a pending edit. */
+export function taskWasNotRestarted(error: unknown): boolean {
+	return error instanceof TaskNotRestartedError || (error instanceof ConversationRewindError && !error.restarted)
+}
+
+/**
+ * What the user is told when a checkpoint restore failed. A restore that put the files back but could not rewind the
+ * conversation says so: the files did change, and the task was started again with its previous conversation (or, when
+ * that failed too, it has to be started by the user).
+ */
+export function checkpointRestoreFailureMessage(error: unknown): string {
+	const reason = error instanceof Error ? error.message : String(error)
+	if (error instanceof TaskNotRestartedError) return t("common:errors.checkpoint_restart_failed", { error: reason })
+	if (!(error instanceof ConversationRewindError))
+		return t("common:errors.checkpoint_restore_failed", { error: reason })
+	if (error.restarted) return t("common:errors.checkpoint_rewind_failed", { error: reason })
+	// Both failures are told: why the conversation was not rewound, and why the task was not started again.
+	const restartError = error.restartFailure?.error
+	return t("common:errors.checkpoint_rewind_restart_failed", {
+		error: reason,
+		restartError: restartError instanceof Error ? restartError.message : String(restartError),
+	})
+}

src/core/checkpoints/__tests__/ConversationRewindError.spec.ts

@@ -0,0 +1,91 @@
+import { t } from "../../../i18n"
+import {
+	checkpointRestoreFailureMessage,
+	ConversationRewindError,
+	TaskNotRestartedError,
+	taskWasNotRestarted,
+} from "../ConversationRewindError"
+
+vi.mock("../../../i18n", () => ({
+	t: vi.fn((key: string, options?: { error?: string }) => `${key}: ${options?.error}`),
+}))
+
+describe("ConversationRewindError", () => {
+	it("is restarted unless the restart failed too", () => {
+		expect(new ConversationRewindError(new Error("x")).restarted).toBe(true)
+		const failed = new ConversationRewindError(new Error("x"), { error: new Error("y") })
+		expect(failed.restarted).toBe(false)
+		expect(failed.restartFailure).toEqual({ error: new Error("y") })
+	})
+})
+
+describe("checkpointRestoreFailureMessage", () => {
+	it.each([
+		["an Error", new Error("Missing commit"), "Missing commit"],
+		["a plain value", "Invalid reference", "Invalid reference"],
+	])("says a failed restore as such, for %s", (_name, error, reason) => {
+		expect(checkpointRestoreFailureMessage(error)).toBe(`common:errors.checkpoint_restore_failed: ${reason}`)
+	})
+
+	it.each([
+		["an Error", new Error("Failed to save the messages"), "Failed to save the messages"],
+		["a plain value", "disk full", "disk full"],
+	])(
+		"says that the files were restored, and the conversation was not rewound, when the cause is %s",
+		(_name, cause, reason) => {
+			expect(checkpointRestoreFailureMessage(new ConversationRewindError(cause))).toBe(
+				`common:errors.checkpoint_rewind_failed: ${reason}`,
+			)
+		},
+	)
+
+	it.each([
+		["an Error", new Error("cannot rehydrate"), "cannot rehydrate"],
+		["a plain value", "no history", "no history"],
+	])(
+		"tells why the task could not be started again too, when the restart failure is %s",
+		(_name, restartFailure, restartError) => {
+			const error = new ConversationRewindError(new Error("Failed to save the messages"), {
+				error: restartFailure,
+			})
+
+			expect(checkpointRestoreFailureMessage(error)).toBe(
+				"common:errors.checkpoint_rewind_restart_failed: Failed to save the messages",
+			)
+			expect(t).toHaveBeenLastCalledWith("common:errors.checkpoint_rewind_restart_failed", {
+				error: "Failed to save the messages",
+				restartError,
+			})
+		},
+	)
+
+	it("says that the task has to be opened from the history when it could not be started again after a rewind that worked", () => {
+		expect(checkpointRestoreFailureMessage(new TaskNotRestartedError(new Error("cannot rehydrate")))).toBe(
+			"common:errors.checkpoint_restart_failed: cannot rehydrate",
+		)
+	})
+})
+
+describe("TaskNotRestartedError and taskWasNotRestarted", () => {
+	it.each([
+		["a restart that failed after a rewind that worked", new TaskNotRestartedError("x"), true],
+		["a failed rewind whose restart failed too", new ConversationRewindError(new Error("x"), { error: "y" }), true],
+		["a failed rewind whose task was restarted", new ConversationRewindError(new Error("x")), false],
+		["any other failure", new Error("Missing commit"), false],
+		["something that is not an error", "Invalid reference", false],
+	])("for %s: %s", (_name, error, expected) => {
+		expect(taskWasNotRestarted(error)).toBe(expected)
+	})
+
+	it.each([
+		["an Error", new Error("cannot rehydrate"), "cannot rehydrate"],
+		["a plain value", "cannot rehydrate", "cannot rehydrate"],
+	])("keeps the cause, an %s", (_name, cause, message) => {
+		const error = new TaskNotRestartedError(cause)
+
+		expect(error).toBeInstanceOf(Error)
+		expect(error.name).toBe("TaskNotRestartedError")
+		expect(error.message).toBe(message)
+		expect(error.cause).toBe(cause)
+	})
+})