Run local usage services in a supervised backend process (#40792)

* Move local usage services into a supervised backend process

* Own usage recovery and worker retirement lifetimes

* Preserve answered usage data during background refresh

* Run independent usage scans concurrently in the backend

* Limit backend startup paths to the delegated usage service

* Show usage failures through backend recovery

* Include usage failure strings in the English catalog

* Keep usage update details beside refresh failures

* Resolve usage freshness failure from the final producer snapshot

* Retain the forced refresh completion requirement

* Keep managed backend failures out of application crash reports

* Preserve usage recovery boundaries across backend reconnects

* Match the backend RPC cancellation signal in the usage seam proof

* Avoid serializing backend requests before port delivery

* Keep receiving request validation in the boundary schemas

* test: align usage transport coverage with renderer project

* fix: preserve unknown usage state and renderer retirement

* fix(usage): revalidate tracking before scan admission

* fix(usage): retry failed backend startup on demand

* test(usage): isolate stale backend ownership checks
This commit is contained in:
Brennan Benson
2026-11-11 16:39:52 -08:00
committed by GitHub
parent 890ad4d8aa
commit 175f10e32b
85 changed files with 4898 additions and 789 deletions
@@ -1,4 +1,5 @@
import { useEffect } from 'react'
import { usageFailureMessage } from './usage-failure-message'
import { useUsageObservation } from '../../store/slices/usage/use-usage-observation'
import {
Activity,
Coins,
@@ -54,6 +55,8 @@ export function ClaudeUsagePane(): React.JSX.Element {
const t = useTranslate()
const intlLocale = useIntlLocale()
const scanState = useAppStore((state) => state.claudeUsageScanState)
const failure = useAppStore((state) => state.claudeUsageFailure)
const failureMessage = usageFailureMessage(failure, t)
const summary = useAppStore((state) => state.claudeUsageSummary)
const daily = useAppStore((state) => state.claudeUsageDaily)
const modelBreakdown = useAppStore((state) => state.claudeUsageModelBreakdown)
@@ -61,16 +64,14 @@ export function ClaudeUsagePane(): React.JSX.Element {
const recentSessions = useAppStore((state) => state.claudeUsageRecentSessions)
const scope = useAppStore((state) => state.claudeUsageScope)
const range = useAppStore((state) => state.claudeUsageRange)
const fetchClaudeUsage = useAppStore((state) => state.fetchClaudeUsage)
const observeClaudeUsage = useAppStore((state) => state.observeClaudeUsage)
const setClaudeUsageEnabled = useAppStore((state) => state.setClaudeUsageEnabled)
const refreshClaudeUsage = useAppStore((state) => state.refreshClaudeUsage)
const setClaudeUsageScope = useAppStore((state) => state.setClaudeUsageScope)
const setClaudeUsageRange = useAppStore((state) => state.setClaudeUsageRange)
const recordFeatureInteraction = useAppStore((state) => state.recordFeatureInteraction)
useEffect(() => {
void fetchClaudeUsage()
}, [fetchClaudeUsage])
useUsageObservation(observeClaudeUsage)
const handleSetEnabled = (enabled: boolean): void => {
recordFeatureInteraction('usage-tracking')
@@ -87,6 +88,9 @@ export function ClaudeUsagePane(): React.JSX.Element {
return (
<UsageTrackingPaneShell
enabled={false}
failure={failureMessage}
stateKnown={scanState !== null}
retry={{ label: t('usage.failure.retry', 'Refresh'), onRefresh: refreshClaudeUsage }}
title={title}
disabledDescription={t(
'auto.components.stats.ClaudeUsagePane.0cb1a36d7d',
@@ -98,7 +102,11 @@ export function ClaudeUsagePane(): React.JSX.Element {
)
}
if (!summary && (scanState.isScanning || scanState.lastScanCompletedAt === null)) {
if (
!failureMessage &&
!summary &&
(scanState.isScanning || scanState.lastScanCompletedAt === null)
) {
return <ClaudeUsageLoadingState />
}
@@ -107,6 +115,7 @@ export function ClaudeUsagePane(): React.JSX.Element {
return (
<UsageTrackingPaneShell
enabled
failure={failureMessage}
title={title}
status={
<>
@@ -1,4 +1,5 @@
import { useEffect } from 'react'
import { usageFailureMessage } from './usage-failure-message'
import { useUsageObservation } from '../../store/slices/usage/use-usage-observation'
import { Activity, Brain, Coins, DatabaseZap, FolderKanban, Sparkles } from 'lucide-react'
import type { CodexUsageRange, CodexUsageScope } from '../../../../shared/codex-usage-types'
import { useAppStore } from '../../store'
@@ -46,6 +47,8 @@ export function CodexUsagePane(): React.JSX.Element {
const t = useTranslate()
const intlLocale = useIntlLocale()
const scanState = useAppStore((state) => state.codexUsageScanState)
const failure = useAppStore((state) => state.codexUsageFailure)
const failureMessage = usageFailureMessage(failure, t)
const summary = useAppStore((state) => state.codexUsageSummary)
const daily = useAppStore((state) => state.codexUsageDaily)
const modelBreakdown = useAppStore((state) => state.codexUsageModelBreakdown)
@@ -53,16 +56,14 @@ export function CodexUsagePane(): React.JSX.Element {
const recentSessions = useAppStore((state) => state.codexUsageRecentSessions)
const scope = useAppStore((state) => state.codexUsageScope)
const range = useAppStore((state) => state.codexUsageRange)
const fetchCodexUsage = useAppStore((state) => state.fetchCodexUsage)
const observeCodexUsage = useAppStore((state) => state.observeCodexUsage)
const setCodexUsageEnabled = useAppStore((state) => state.setCodexUsageEnabled)
const refreshCodexUsage = useAppStore((state) => state.refreshCodexUsage)
const setCodexUsageScope = useAppStore((state) => state.setCodexUsageScope)
const setCodexUsageRange = useAppStore((state) => state.setCodexUsageRange)
const recordFeatureInteraction = useAppStore((state) => state.recordFeatureInteraction)
useEffect(() => {
void fetchCodexUsage()
}, [fetchCodexUsage])
useUsageObservation(observeCodexUsage)
const handleSetEnabled = (enabled: boolean): void => {
recordFeatureInteraction('usage-tracking')
@@ -79,6 +80,9 @@ export function CodexUsagePane(): React.JSX.Element {
return (
<UsageTrackingPaneShell
enabled={false}
failure={failureMessage}
stateKnown={scanState !== null}
retry={{ label: t('usage.failure.retry', 'Refresh'), onRefresh: refreshCodexUsage }}
title={title}
disabledDescription={t(
'auto.components.stats.CodexUsagePane.13badcd8f2',
@@ -90,7 +94,11 @@ export function CodexUsagePane(): React.JSX.Element {
)
}
if (!summary && (scanState.isScanning || scanState.lastScanCompletedAt === null)) {
if (
!failureMessage &&
!summary &&
(scanState.isScanning || scanState.lastScanCompletedAt === null)
) {
return (
<ClaudeUsageLoadingState
title={title}
@@ -110,6 +118,7 @@ export function CodexUsagePane(): React.JSX.Element {
return (
<UsageTrackingPaneShell
enabled
failure={failureMessage}
title={title}
status={
<>
@@ -1,4 +1,5 @@
import { useEffect } from 'react'
import { usageFailureMessage } from './usage-failure-message'
import { useUsageObservation } from '../../store/slices/usage/use-usage-observation'
import { Activity, Brain, DatabaseZap, FolderKanban, Sigma, Sparkles } from 'lucide-react'
import type { MuseUsageRange, MuseUsageScope } from '../../../../shared/muse-usage-types'
import { useAppStore } from '../../store'
@@ -45,6 +46,8 @@ export function MuseUsagePane(): React.JSX.Element {
const t = useTranslate()
const intlLocale = useIntlLocale()
const scanState = useAppStore((state) => state.museUsageScanState)
const failure = useAppStore((state) => state.museUsageFailure)
const failureMessage = usageFailureMessage(failure, t)
const summary = useAppStore((state) => state.museUsageSummary)
const daily = useAppStore((state) => state.museUsageDaily)
const modelBreakdown = useAppStore((state) => state.museUsageModelBreakdown)
@@ -52,16 +55,14 @@ export function MuseUsagePane(): React.JSX.Element {
const recentSessions = useAppStore((state) => state.museUsageRecentSessions)
const scope = useAppStore((state) => state.museUsageScope)
const range = useAppStore((state) => state.museUsageRange)
const fetchMuseUsage = useAppStore((state) => state.fetchMuseUsage)
const observeMuseUsage = useAppStore((state) => state.observeMuseUsage)
const setMuseUsageEnabled = useAppStore((state) => state.setMuseUsageEnabled)
const refreshMuseUsage = useAppStore((state) => state.refreshMuseUsage)
const setMuseUsageScope = useAppStore((state) => state.setMuseUsageScope)
const setMuseUsageRange = useAppStore((state) => state.setMuseUsageRange)
const recordFeatureInteraction = useAppStore((state) => state.recordFeatureInteraction)
useEffect(() => {
void fetchMuseUsage()
}, [fetchMuseUsage])
useUsageObservation(observeMuseUsage)
const handleSetEnabled = (enabled: boolean): void => {
recordFeatureInteraction('usage-tracking')
@@ -78,6 +79,9 @@ export function MuseUsagePane(): React.JSX.Element {
return (
<UsageTrackingPaneShell
enabled={false}
failure={failureMessage}
stateKnown={scanState !== null}
retry={{ label: t('usage.failure.retry', 'Refresh'), onRefresh: refreshMuseUsage }}
title={title}
disabledDescription={t(
'auto.components.stats.MuseUsagePane.disabledDescription',
@@ -89,7 +93,11 @@ export function MuseUsagePane(): React.JSX.Element {
)
}
if (!summary && (scanState.isScanning || scanState.lastScanCompletedAt === null)) {
if (
!failureMessage &&
!summary &&
(scanState.isScanning || scanState.lastScanCompletedAt === null)
) {
return (
<ClaudeUsageLoadingState
title={title}
@@ -104,6 +112,7 @@ export function MuseUsagePane(): React.JSX.Element {
return (
<UsageTrackingPaneShell
enabled
failure={failureMessage}
title={title}
status={
<>
@@ -1,4 +1,5 @@
import { useEffect } from 'react'
import { usageFailureMessage } from './usage-failure-message'
import { useUsageObservation } from '../../store/slices/usage/use-usage-observation'
import { Activity, Brain, Coins, DatabaseZap, FolderKanban, Sparkles } from 'lucide-react'
import type {
OpenCodeUsageRange,
@@ -50,6 +51,8 @@ export function OpenCodeUsagePane(): React.JSX.Element {
const t = useTranslate()
const intlLocale = useIntlLocale()
const scanState = useAppStore((state) => state.openCodeUsageScanState)
const failure = useAppStore((state) => state.openCodeUsageFailure)
const failureMessage = usageFailureMessage(failure, t)
const summary = useAppStore((state) => state.openCodeUsageSummary)
const daily = useAppStore((state) => state.openCodeUsageDaily)
const modelBreakdown = useAppStore((state) => state.openCodeUsageModelBreakdown)
@@ -57,16 +60,14 @@ export function OpenCodeUsagePane(): React.JSX.Element {
const recentSessions = useAppStore((state) => state.openCodeUsageRecentSessions)
const scope = useAppStore((state) => state.openCodeUsageScope)
const range = useAppStore((state) => state.openCodeUsageRange)
const fetchOpenCodeUsage = useAppStore((state) => state.fetchOpenCodeUsage)
const observeOpenCodeUsage = useAppStore((state) => state.observeOpenCodeUsage)
const setOpenCodeUsageEnabled = useAppStore((state) => state.setOpenCodeUsageEnabled)
const refreshOpenCodeUsage = useAppStore((state) => state.refreshOpenCodeUsage)
const setOpenCodeUsageScope = useAppStore((state) => state.setOpenCodeUsageScope)
const setOpenCodeUsageRange = useAppStore((state) => state.setOpenCodeUsageRange)
const recordFeatureInteraction = useAppStore((state) => state.recordFeatureInteraction)
useEffect(() => {
void fetchOpenCodeUsage()
}, [fetchOpenCodeUsage])
useUsageObservation(observeOpenCodeUsage)
const handleSetEnabled = (enabled: boolean): void => {
recordFeatureInteraction('usage-tracking')
@@ -83,6 +84,9 @@ export function OpenCodeUsagePane(): React.JSX.Element {
return (
<UsageTrackingPaneShell
enabled={false}
failure={failureMessage}
stateKnown={scanState !== null}
retry={{ label: t('usage.failure.retry', 'Refresh'), onRefresh: refreshOpenCodeUsage }}
title={title}
disabledDescription={t(
'auto.components.stats.OpenCodeUsagePane.b8b3522436',
@@ -94,7 +98,11 @@ export function OpenCodeUsagePane(): React.JSX.Element {
)
}
if (!summary && (scanState.isScanning || scanState.lastScanCompletedAt === null)) {
if (
!failureMessage &&
!summary &&
(scanState.isScanning || scanState.lastScanCompletedAt === null)
) {
return (
<ClaudeUsageLoadingState
title={title}
@@ -109,6 +117,7 @@ export function OpenCodeUsagePane(): React.JSX.Element {
return (
<UsageTrackingPaneShell
enabled
failure={failureMessage}
title={title}
status={
<>
@@ -1,4 +1,6 @@
import { useEffect, useMemo } from 'react'
import { usageFailureMessage } from './usage-failure-message'
import { useUsageObservation } from '../../store/slices/usage/use-usage-observation'
import { useMemo } from 'react'
import { Activity, CalendarDays, Coins, DatabaseZap, RefreshCw, Sparkles } from 'lucide-react'
import { useAppStore } from '../../store'
import { Badge } from '../ui/badge'
@@ -36,22 +38,26 @@ function formatUpdatedAt(
export function UsageOverviewPane(): React.JSX.Element {
const t = useTranslate()
const intlLocale = useIntlLocale()
const claudeFailure = useAppStore((state) => state.claudeUsageFailure)
const claudeScanState = useAppStore((state) => state.claudeUsageScanState)
const claudeSummary = useAppStore((state) => state.claudeUsageSummary)
const claudeDaily = useAppStore((state) => state.claudeUsageDaily)
const codexFailure = useAppStore((state) => state.codexUsageFailure)
const codexScanState = useAppStore((state) => state.codexUsageScanState)
const codexSummary = useAppStore((state) => state.codexUsageSummary)
const codexDaily = useAppStore((state) => state.codexUsageDaily)
const openCodeFailure = useAppStore((state) => state.openCodeUsageFailure)
const openCodeScanState = useAppStore((state) => state.openCodeUsageScanState)
const openCodeSummary = useAppStore((state) => state.openCodeUsageSummary)
const openCodeDaily = useAppStore((state) => state.openCodeUsageDaily)
const museFailure = useAppStore((state) => state.museUsageFailure)
const museScanState = useAppStore((state) => state.museUsageScanState)
const museSummary = useAppStore((state) => state.museUsageSummary)
const museDaily = useAppStore((state) => state.museUsageDaily)
const fetchClaudeUsage = useAppStore((state) => state.fetchClaudeUsage)
const fetchCodexUsage = useAppStore((state) => state.fetchCodexUsage)
const fetchOpenCodeUsage = useAppStore((state) => state.fetchOpenCodeUsage)
const fetchMuseUsage = useAppStore((state) => state.fetchMuseUsage)
const observeClaudeUsage = useAppStore((state) => state.observeClaudeUsage)
const observeCodexUsage = useAppStore((state) => state.observeCodexUsage)
const observeOpenCodeUsage = useAppStore((state) => state.observeOpenCodeUsage)
const observeMuseUsage = useAppStore((state) => state.observeMuseUsage)
const refreshClaudeUsage = useAppStore((state) => state.refreshClaudeUsage)
const refreshCodexUsage = useAppStore((state) => state.refreshCodexUsage)
const refreshOpenCodeUsage = useAppStore((state) => state.refreshOpenCodeUsage)
@@ -62,12 +68,10 @@ export function UsageOverviewPane(): React.JSX.Element {
const enableMuseUsage = useAppStore((state) => state.enableMuseUsage)
const recordFeatureInteraction = useAppStore((state) => state.recordFeatureInteraction)
useEffect(() => {
void fetchClaudeUsage()
void fetchCodexUsage()
void fetchOpenCodeUsage()
void fetchMuseUsage()
}, [fetchClaudeUsage, fetchCodexUsage, fetchOpenCodeUsage, fetchMuseUsage])
useUsageObservation(observeClaudeUsage)
useUsageObservation(observeCodexUsage)
useUsageObservation(observeOpenCodeUsage)
useUsageObservation(observeMuseUsage)
const overview = useMemo(
() =>
@@ -114,12 +118,44 @@ export function UsageOverviewPane(): React.JSX.Element {
)
const isScanning = overview.providers.some((provider) => provider.isScanning)
const failures = [
{ name: 'Claude', message: usageFailureMessage(claudeFailure, t) },
{ name: 'Codex', message: usageFailureMessage(codexFailure, t) },
{ name: 'OpenCode', message: usageFailureMessage(openCodeFailure, t) },
{ name: 'Muse', message: usageFailureMessage(museFailure, t) }
]
const failureGroups = new Map<string, string[]>()
for (const { name, message } of failures) {
if (message) {
failureGroups.set(message, [...(failureGroups.get(message) ?? []), name])
}
}
const knownProviders = {
claude: claudeScanState,
codex: codexScanState,
opencode: openCodeScanState,
muse: museScanState
}
const allProvidersKnown = Object.values(knownProviders).every(Boolean)
const canRefresh =
overview.hasAnyEnabledProvider ||
failureGroups.size > 0 ||
Object.values(knownProviders).some((state) => !state)
const handleRefresh = (): void => {
void Promise.all([
claudeScanState?.enabled ? refreshClaudeUsage() : Promise.resolve(),
codexScanState?.enabled ? refreshCodexUsage() : Promise.resolve(),
openCodeScanState?.enabled ? refreshOpenCodeUsage() : Promise.resolve(),
museScanState?.enabled ? refreshMuseUsage() : Promise.resolve()
claudeScanState?.enabled || claudeFailure || !claudeScanState
? refreshClaudeUsage()
: Promise.resolve(),
codexScanState?.enabled || codexFailure || !codexScanState
? refreshCodexUsage()
: Promise.resolve(),
openCodeScanState?.enabled || openCodeFailure || !openCodeScanState
? refreshOpenCodeUsage()
: Promise.resolve(),
museScanState?.enabled || museFailure || !museScanState
? refreshMuseUsage()
: Promise.resolve()
])
}
@@ -140,6 +176,11 @@ export function UsageOverviewPane(): React.JSX.Element {
)
: ''}
</p>
{[...failureGroups].map(([message, names]) => (
<p key={message} role="alert" className="mt-1 text-xs text-destructive">
{names.join(', ')}: {message}
</p>
))}
</div>
<Tooltip>
<TooltipTrigger asChild>
@@ -147,7 +188,7 @@ export function UsageOverviewPane(): React.JSX.Element {
variant="ghost"
size="icon-xs"
onClick={handleRefresh}
disabled={!overview.hasAnyEnabledProvider || isScanning}
disabled={!canRefresh || isScanning}
aria-label={t(
'auto.components.stats.UsageOverviewPane.e06d1baf5c',
'Refresh usage overview'
@@ -162,7 +203,7 @@ export function UsageOverviewPane(): React.JSX.Element {
</Tooltip>
</div>
{!overview.hasAnyEnabledProvider ? (
{allProvidersKnown && !overview.hasAnyEnabledProvider ? (
<div className="mt-4 rounded-lg border border-dashed border-border/60 bg-card/30 px-4 py-5">
<div className="max-w-xl space-y-3">
<div>
@@ -183,6 +224,7 @@ export function UsageOverviewPane(): React.JSX.Element {
recordFeatureInteraction('usage-tracking')
void enableClaudeUsage()
}}
disabled={!claudeScanState}
>
{t('auto.components.stats.UsageOverviewPane.0ea0cae435', 'Enable Claude')}
</Button>
@@ -193,6 +235,7 @@ export function UsageOverviewPane(): React.JSX.Element {
recordFeatureInteraction('usage-tracking')
void enableCodexUsage()
}}
disabled={!codexScanState}
>
{t('auto.components.stats.UsageOverviewPane.2f1ee2878b', 'Enable Codex')}
</Button>
@@ -203,6 +246,7 @@ export function UsageOverviewPane(): React.JSX.Element {
recordFeatureInteraction('usage-tracking')
void enableOpenCodeUsage()
}}
disabled={!openCodeScanState}
>
{t('auto.components.stats.UsageOverviewPane.2d13e57f72', 'Enable OpenCode')}
</Button>
@@ -213,13 +257,14 @@ export function UsageOverviewPane(): React.JSX.Element {
recordFeatureInteraction('usage-tracking')
void enableMuseUsage()
}}
disabled={!museScanState}
>
{t('auto.components.stats.UsageOverviewPane.enableMuse', 'Enable Muse')}
</Button>
</div>
</div>
</div>
) : (
) : overview.hasAnyEnabledProvider ? (
<>
<div className="mt-4 grid gap-3 md:grid-cols-2 xl:grid-cols-4">
<StatCard
@@ -244,21 +289,21 @@ export function UsageOverviewPane(): React.JSX.Element {
/>
</div>
{!overview.hasAnyData ? (
{!overview.hasAnyData && allProvidersKnown ? (
<div className="mt-4 rounded-lg border border-dashed border-border/60 bg-card/30 px-4 py-5 text-sm text-muted-foreground">
{t(
'auto.components.stats.UsageOverviewPane.noLocalUsageYet',
'No local Claude, Codex, OpenCode, or Muse usage found yet. The overview will populate after the next agent session writes token logs.'
)}
</div>
) : (
) : overview.hasAnyData ? (
<div className="mt-4 grid gap-4 xl:grid-cols-[minmax(0,1.2fr)_minmax(0,0.8fr)]">
<DailyIntensityGrid days={recentDays} bestDay={overview.bestDay} />
<TokenMixBar overview={overview} />
</div>
)}
) : null}
</>
)}
) : null}
</section>
<section className="space-y-3">
@@ -268,11 +313,13 @@ export function UsageOverviewPane(): React.JSX.Element {
{t('auto.components.stats.UsageOverviewPane.33f7b043d2', 'Providers')}
</h4>
<p className="text-xs text-muted-foreground">
{t(
'auto.components.stats.UsageOverviewPane.providersEnabledWithData',
'{{enabled}} enabled - {{withData}} with data',
{ enabled: overview.enabledProviderCount, withData: overview.dataProviderCount }
)}
{allProvidersKnown
? t(
'auto.components.stats.UsageOverviewPane.providersEnabledWithData',
'{{enabled}} enabled - {{withData}} with data',
{ enabled: overview.enabledProviderCount, withData: overview.dataProviderCount }
)
: '—'}
</p>
</div>
<Badge variant="outline" className="gap-1">
@@ -290,6 +337,7 @@ export function UsageOverviewPane(): React.JSX.Element {
key={provider.id}
provider={provider}
totalTokens={overview.totalTokens}
stateKnown={!!knownProviders[provider.id]}
onEnable={() => {
recordFeatureInteraction('usage-tracking')
if (provider.id === 'claude') {
@@ -45,6 +45,9 @@ export function UsageFilterRadioGroup<Value extends string>({
type UsageTrackingPaneShellProps = {
title: ReactNode
failure?: string | null
stateKnown?: boolean
retry?: { label: string; onRefresh: () => void | Promise<void> }
enableLabel: string
onEnabledChange: (enabled: boolean) => void
} & (
@@ -78,9 +81,20 @@ export function UsageTrackingPaneShell(props: UsageTrackingPaneShellProps): Reac
<div className="space-y-2">
<h3 className="text-sm font-semibold text-foreground">{props.title}</h3>
<p className="text-sm text-muted-foreground">{props.disabledDescription}</p>
{props.failure && (
<p role="alert" className="text-xs text-destructive">
{props.failure}
</p>
)}
{props.failure && props.retry && (
<Button variant="outline" size="sm" onClick={() => void props.retry?.onRefresh()}>
{props.retry.label}
</Button>
)}
</div>
<Switch
checked={false}
disabled={props.stateKnown === false}
aria-label={props.enableLabel}
onCheckedChange={props.onEnabledChange}
/>
@@ -95,6 +109,11 @@ export function UsageTrackingPaneShell(props: UsageTrackingPaneShellProps): Reac
<div className="min-w-0 flex-1">
<h3 className="text-sm font-semibold text-foreground">{props.title}</h3>
<p className="mt-1 text-xs text-muted-foreground">{props.status}</p>
{props.failure && (
<p role="alert" className="mt-1 text-xs text-destructive">
{props.failure}
</p>
)}
</div>
<div className="flex shrink-0 items-center gap-2 self-start">
{props.headerAction}
@@ -0,0 +1,24 @@
import type { UsageFailure } from '../../store/slices/usage/usage-provider-types'
import type { Translate } from '@/i18n/use-translate'
export function usageFailureMessage(failure: UsageFailure | null, t: Translate): string | null {
if (failure?.terminal) {
return t('usage.failure.unavailable', 'Usage is unavailable. Try Refresh to reconnect.')
}
if (failure?.setting) {
return t(
'usage.failure.setting',
'The tracking change could not be confirmed. Try changing it again.'
)
}
if (failure?.refresh) {
return t(
'usage.failure.refresh',
'The previous Refresh could not be completed. Try Refresh again.'
)
}
if (failure?.read) {
return t('usage.failure.read', 'Usage could not be loaded. Try Refresh again.')
}
return null
}
@@ -0,0 +1,132 @@
// @vitest-environment happy-dom
import { afterEach, expect, it, vi } from 'vitest'
import { cleanup, fireEvent, render, screen } from '@testing-library/react'
import { ClaudeUsagePane } from './ClaudeUsagePane'
import { CodexUsagePane } from './CodexUsagePane'
import { OpenCodeUsagePane } from './OpenCodeUsagePane'
import { MuseUsagePane } from './MuseUsagePane'
import { UsageOverviewPane } from './UsageOverviewPane'
import type { AppState } from '../../store/types'
import { TooltipProvider } from '../ui/tooltip'
import { i18n } from '@/i18n/i18n'
import es from '../../i18n/locales/es.json'
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: Setup replaces this placeholder before any usage component renders.
const fixture = vi.hoisted(() => ({ state: {} as AppState }))
vi.mock('../../store', () => ({
useAppStore: (select: (state: AppState) => unknown) => select(fixture.state)
}))
const providers = [
['claude', 'Claude', ClaudeUsagePane],
['codex', 'Codex', CodexUsagePane],
['openCode', 'OpenCode', OpenCodeUsagePane],
['muse', 'Muse', MuseUsagePane]
] as const
function setup(kind: 'unknown' | 'disabled' | 'empty' | 'cached') {
const values: Record<string, unknown> = { recordFeatureInteraction: vi.fn() }
for (const [prefix, name] of providers) {
Object.assign(values, {
[`${prefix}UsageFailure`]: { terminal: false, read: false, refresh: true, setting: false },
[`${prefix}UsageScanState`]:
kind === 'unknown'
? null
: {
enabled: kind !== 'disabled',
isScanning: false,
lastScanCompletedAt: kind === 'empty' ? null : 1,
lastScanError: kind === 'cached' ? 'source scan failed' : null,
[`hasAny${name}Data`]: false
},
[`${prefix}UsageSummary`]: null,
[`${prefix}UsageDaily`]: [],
[`${prefix}UsageScope`]: 'orca',
[`${prefix}UsageRange`]: '30d',
[`observe${name}Usage`]: () => () => {},
[`refresh${name}Usage`]: vi.fn(),
[`enable${name}Usage`]: vi.fn(),
[`set${name}UsageEnabled`]: vi.fn()
})
}
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: Only the populated usage surface selectors are exercised.
fixture.state = values as unknown as AppState
}
afterEach(async () => {
cleanup()
await i18n.changeLanguage('en')
})
it.each(providers)(
'%s exposes failure and Refresh in unknown, disabled, empty and cached states',
(_prefix, name, Pane) => {
for (const kind of ['unknown', 'disabled', 'empty', 'cached'] as const) {
setup(kind)
const view = render(<Pane />)
expect(screen.getByRole('alert').textContent).toBe(
'The previous Refresh could not be completed. Try Refresh again.'
)
if (kind === 'cached') {
expect(screen.getByText(/Updated/).textContent).toContain('source scan failed')
}
const retry = screen.getByRole('button', { name: /Refresh/ })
expect(retry.hasAttribute('disabled')).toBe(false)
fireEvent.click(retry)
expect(fixture.state[`refresh${name}Usage`]).toHaveBeenCalledTimes(1)
expect(screen.getByRole('switch').hasAttribute('disabled')).toBe(kind === 'unknown')
view.unmount()
}
}
)
it('deduplicates overview failure, retries unknown providers without enabling, and removes recovered warnings', () => {
setup('unknown')
const view = render(
<TooltipProvider>
<UsageOverviewPane />
</TooltipProvider>
)
expect(screen.getAllByRole('alert')).toHaveLength(1)
expect(screen.queryByText('Start tracking tokens')).toBeNull()
expect(screen.queryByText('0 enabled - 0 with data')).toBeNull()
fireEvent.click(screen.getByRole('button', { name: 'Refresh usage overview' }))
for (const [prefix, name] of providers) {
expect(fixture.state[`refresh${name}Usage`]).toHaveBeenCalledTimes(1)
expect(fixture.state[`enable${name}Usage`]).not.toHaveBeenCalled()
fixture.state[`${prefix}UsageFailure`] = null
}
view.rerender(
<TooltipProvider>
<UsageOverviewPane />
</TooltipProvider>
)
expect(screen.queryByRole('alert')).toBeNull()
setup('disabled')
view.rerender(
<TooltipProvider>
<UsageOverviewPane />
</TooltipProvider>
)
expect(screen.getByText('Start tracking tokens')).toBeTruthy()
expect(screen.getByText('0 enabled - 0 with data')).toBeTruthy()
})
it('renders translated failure and retry on the provider and overview', async () => {
i18n.addResourceBundle('es', 'translation', es)
await i18n.changeLanguage('es')
setup('unknown')
const view = render(<ClaudeUsagePane />)
expect(screen.getByRole('alert').textContent).toBe(
'No se pudo completar la actualización anterior. Pulsa Actualizar de nuevo.'
)
fireEvent.click(screen.getByRole('button', { name: 'Actualizar' }))
expect(fixture.state.refreshClaudeUsage).toHaveBeenCalledTimes(1)
view.unmount()
render(
<TooltipProvider>
<UsageOverviewPane />
</TooltipProvider>
)
expect(screen.queryByText('Empezar a rastrear tokens')).toBeNull()
expect(screen.getByRole('alert').textContent).toContain(
'No se pudo completar la actualización anterior.'
)
})
@@ -240,11 +240,13 @@ export function DailyIntensityGrid({
export function ProviderUsageRow({
provider,
totalTokens,
onEnable
onEnable,
stateKnown = true
}: {
provider: UsageProviderOverview
totalTokens: number
onEnable: () => void
stateKnown?: boolean
}): React.JSX.Element {
const t = useTranslate()
const intlLocale = useIntlLocale()
@@ -262,7 +264,7 @@ export function ProviderUsageRow({
<div className="min-w-0">
<div className="flex min-w-0 items-center gap-2">
<h5 className="truncate text-sm font-semibold text-foreground">{provider.label}</h5>
<Badge variant={statusVariant}>{status}</Badge>
<Badge variant={statusVariant}>{stateKnown ? status : '—'}</Badge>
</div>
<p className="mt-1 truncate text-xs text-muted-foreground">
{provider.topModel ??
@@ -271,7 +273,7 @@ export function ProviderUsageRow({
</p>
</div>
{!provider.enabled ? (
<Button variant="outline" size="xs" onClick={onEnable}>
<Button variant="outline" size="xs" onClick={onEnable} disabled={!stateKnown}>
{t('auto.components.stats.usage.overview.sections.57d1448ef8', 'Enable')}
</Button>
) : null}
+9
View File
@@ -25277,5 +25277,14 @@
"notGitRepository": "Not a valid Git repository",
"importFailed": "Repository could not be imported"
}
},
"usage": {
"failure": {
"unavailable": "Usage is unavailable. Try Refresh to reconnect.",
"setting": "The tracking change could not be confirmed. Try changing it again.",
"refresh": "The previous Refresh could not be completed. Try Refresh again.",
"read": "Usage could not be loaded. Try Refresh again.",
"retry": "Refresh"
}
}
}
+9
View File
@@ -24207,5 +24207,14 @@
"dismiss": "Descartar",
"cancelDownload": "Cancelar descarga"
}
},
"usage": {
"failure": {
"unavailable": "El uso no está disponible. Pulsa Actualizar para reconectar.",
"setting": "No se pudo confirmar el cambio de seguimiento. Intenta cambiarlo de nuevo.",
"refresh": "No se pudo completar la actualización anterior. Pulsa Actualizar de nuevo.",
"read": "No se pudo cargar el uso. Pulsa Actualizar de nuevo.",
"retry": "Actualizar"
}
}
}
@@ -0,0 +1,265 @@
import { MessageChannel, type MessagePort } from 'node:worker_threads'
import { afterEach, expect, it, vi } from 'vitest'
import { BackendPortRpc, type BackendPort } from '../../../../../shared/backend-port-rpc'
import { createStore } from 'zustand/vanilla'
import { createClaudeUsageSlice } from './usage-provider-slices'
import { createUsageProviderApi } from '../../../../../preload/usage-provider-api'
import type { AppState } from '../../types'
import type { ClaudeUsageScanState } from '../../../../../shared/claude-usage-types'
import {
BACKEND_CONNECTION_CHANGED,
BACKEND_PORT_DELIVERY
} from '../../../../../shared/backend-service-contract'
const electron = vi.hoisted(() => ({
handlers: new Map<string, (...args: unknown[]) => void>(),
invoke: vi.fn(async (_channel: string, _token: string, _purpose?: string) => {})
}))
vi.mock('electron', () => ({
ipcRenderer: {
on: (channel: string, listener: (...args: unknown[]) => void) => {
electron.handlers.set(channel, listener)
},
invoke: electron.invoke
}
}))
const servers: BackendPortRpc[] = []
const ports: MessagePort[] = []
const detach: (() => void)[] = []
function emit(channel: string, data: unknown, delivered: MessagePort[] = []): void {
electron.handlers.get(channel)?.({ ports: delivered }, data)
}
function deliver(invoke: (method: string, params?: unknown) => Promise<unknown>): () => void {
const channel = new MessageChannel()
const added = vi.spyOn(channel.port2, 'addEventListener')
ports.push(channel.port1, channel.port2)
const adapter: BackendPort = {
postMessage: (message) => channel.port1.postMessage(message),
onMessage(listener) {
channel.port1.on('message', listener)
return () => channel.port1.off('message', listener)
},
onClose(listener) {
channel.port1.on('close', listener)
return () => channel.port1.off('close', listener)
},
close: () => channel.port1.close()
}
servers.push(new BackendPortRpc(adapter, 'backend', invoke))
emit(BACKEND_PORT_DELIVERY, { token: electron.invoke.mock.lastCall?.[1] }, [channel.port2])
const close = added.mock.calls.find(([event]) => event === 'close')?.[1]
return () => {
if (typeof close === 'function') {
close.call(channel.port2, new Event('close'))
} else {
close?.handleEvent(new Event('close'))
}
}
}
afterEach(() => {
detach.splice(0).forEach((unsubscribe) => unsubscribe())
emit(BACKEND_CONNECTION_CHANGED, { connected: false })
servers.splice(0).forEach((server) => server.close())
ports.splice(0).forEach((port) => port.close())
electron.handlers.clear()
electron.invoke.mockClear()
vi.restoreAllMocks()
vi.resetModules()
vi.unstubAllGlobals()
})
it('publishes port loss before rejection and preserves fresh work through duplicate loss', async () => {
const { backendUsageTransport: transport } =
await import('../../../../../preload/backend-port-client')
const events: string[] = []
let fresh: Promise<unknown> | undefined
detach.push(
transport.onConnectionChanged((connected, detail) => {
if (detail?.initial || detail?.unavailable) {
return
}
events.push(connected ? 'ready' : 'lost')
if (!connected) {
fresh = transport.invoke('snapshot')
}
})
)
const started = Promise.withResolvers<void>()
const held = Promise.withResolvers<unknown>()
const first = transport.invoke('snapshot').catch(() => events.push('rejected'))
emit(BACKEND_CONNECTION_CHANGED, { connected: true })
const closeAgain = deliver(async () => {
started.resolve()
return held.promise
})
await started.promise
servers[0].close()
await first
expect(events).toEqual(['ready', 'lost', 'rejected'])
expect(electron.invoke).toHaveBeenCalledTimes(2)
emit(BACKEND_CONNECTION_CHANGED, { connected: false })
emit(BACKEND_CONNECTION_CHANGED, { connected: false })
deliver(async () => ({ inputTokens: 123 }))
await expect(fresh).resolves.toEqual({ inputTokens: 123 })
closeAgain()
expect(events).toEqual(['ready', 'lost', 'rejected', 'ready'])
held.resolve(null)
await expect(transport.invoke('snapshot')).resolves.toEqual({ inputTokens: 123 })
expect(electron.invoke).toHaveBeenCalledTimes(2)
})
it('keeps a replacement handshake when the old handshake rejects after loss', async () => {
const { backendUsageTransport: transport } =
await import('../../../../../preload/backend-port-client')
let fresh: Promise<unknown> | undefined
detach.push(
transport.onConnectionChanged((connected, detail) => {
if (detail?.initial || detail?.unavailable) {
return
}
if (!connected) {
fresh = transport.invoke('snapshot')
}
})
)
const first = transport.invoke('snapshot')
const rejected = expect(first).rejects.toThrow('Usage disconnected')
emit(BACKEND_CONNECTION_CHANGED, { connected: false })
await rejected
emit(BACKEND_CONNECTION_CHANGED, { connected: false })
deliver(async () => ({ inputTokens: 123 }))
await expect(fresh).resolves.toEqual({ inputTokens: 123 })
expect(electron.invoke).toHaveBeenCalledTimes(2)
})
it('initializes terminal presentation without RPCs and preserves a fresh handshake through terminal escalation', async () => {
const { backendUsageTransport: transport } =
await import('../../../../../preload/backend-port-client')
emit(BACKEND_CONNECTION_CHANGED, { connected: false })
const fresh = transport.invoke('snapshot')
emit(BACKEND_CONNECTION_CHANGED, { connected: false, unavailable: true })
const statuses: unknown[] = []
detach.push(
transport.onConnectionChanged((connected, detail) => statuses.push({ connected, detail }))
)
expect(statuses).toEqual([{ connected: false, detail: { initial: true, unavailable: true } }])
expect(electron.invoke).toHaveBeenCalledTimes(1)
deliver(async () => ({ inputTokens: 123 }))
await expect(fresh).resolves.toEqual({ inputTokens: 123 })
expect(statuses.at(-1)).toEqual({ connected: true, detail: undefined })
})
it('clears terminal metadata on main ready without port delivery or mounted demand', async () => {
const { backendUsageTransport: transport } =
await import('../../../../../preload/backend-port-client')
emit(BACKEND_CONNECTION_CHANGED, { connected: false, unavailable: true })
emit(BACKEND_CONNECTION_CHANGED, { connected: true })
const statuses: unknown[] = []
detach.push(
transport.onConnectionChanged((connected, detail) => statuses.push({ connected, detail }))
)
expect(statuses).toEqual([{ connected: true, detail: { initial: true, unavailable: false } }])
expect(electron.invoke).not.toHaveBeenCalled()
})
it('promotes pending recovery once and ignores its stale delivery and rejection', async () => {
const { backendUsageTransport: transport } =
await import('../../../../../preload/backend-port-client')
const old = Promise.withResolvers<void>()
electron.invoke.mockImplementationOnce(() => old.promise)
const recovery = transport.invoke('snapshot', undefined, 'recovery')
const oldToken = electron.invoke.mock.lastCall?.[1]
const demand = transport.invoke('snapshot')
const sharedDemand = transport.invoke('snapshot')
expect(electron.invoke.mock.calls.map((call) => call[2])).toEqual(['recovery', 'demand'])
expect(electron.invoke.mock.lastCall?.[1]).not.toBe(oldToken)
const stale = new MessageChannel()
ports.push(stale.port1, stale.port2)
const close = vi.spyOn(stale.port2, 'close')
emit(BACKEND_PORT_DELIVERY, { token: oldToken }, [stale.port2])
expect(close).toHaveBeenCalledOnce()
old.reject(new Error('Old document replaced'))
await Promise.resolve()
deliver(async () => ({ inputTokens: 123 }))
await expect(Promise.all([recovery, demand, sharedDemand])).resolves.toEqual([
{ inputTokens: 123 },
{ inputTokens: 123 },
{ inputTokens: 123 }
])
expect(electron.invoke).toHaveBeenCalledTimes(2)
})
it('cancels pending recovery on loss without rearming, and admits fresh post-loss demand', async () => {
const { backendUsageTransport: transport } =
await import('../../../../../preload/backend-port-client')
const old = Promise.withResolvers<void>()
electron.invoke.mockImplementationOnce(() => old.promise)
const recovery = transport.invoke('snapshot', undefined, 'recovery')
const failed = expect(recovery).rejects.toThrow('Usage disconnected')
emit(BACKEND_CONNECTION_CHANGED, { connected: false })
await failed
expect(electron.invoke).toHaveBeenCalledTimes(1)
const fresh = transport.invoke('snapshot')
old.reject(new Error('Old acquisition failed'))
await Promise.resolve()
deliver(async () => 123)
await expect(fresh).resolves.toBe(123)
expect(electron.invoke.mock.calls.map((call) => call[2])).toEqual(['recovery', 'demand'])
})
it('carries mounted recovery purpose through both real usage reads without sending it to the service', async () => {
const { backendUsageTransport: transport } =
await import('../../../../../preload/backend-port-client')
const invoke = vi.spyOn(transport, 'invoke')
const scanState: ClaudeUsageScanState = {
enabled: true,
isScanning: false,
lastScanStartedAt: null,
lastScanCompletedAt: 1,
lastScanError: null,
hasAnyClaudeData: true
}
const snapshot = {
scanState,
summary: { inputTokens: 123 },
daily: [],
modelBreakdown: [],
projectBreakdown: [],
recentSessions: []
}
const received = vi.fn(async (method: string, _params?: unknown) =>
method.endsWith(':getSnapshot') ? snapshot : scanState
)
vi.stubGlobal('window', {
api: { claudeUsage: createUsageProviderApi(transport, 'claudeUsage') }
})
const store = createStore<AppState>()((...args) => {
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: This fixture uses only the production usage slice's public state/actions.
return createClaudeUsageSlice(...args) as AppState
})
detach.push(store.getState().observeClaudeUsage())
await vi.waitFor(() => expect(electron.invoke).toHaveBeenCalledTimes(1))
expect(electron.invoke.mock.lastCall?.[2]).toBe('demand')
deliver(received)
await store.getState().fetchClaudeUsage()
invoke.mockClear()
received.mockClear()
emit(BACKEND_CONNECTION_CHANGED, { connected: false })
emit(BACKEND_CONNECTION_CHANGED, { connected: true })
await vi.waitFor(() => expect(electron.invoke).toHaveBeenCalledTimes(2))
expect(electron.invoke.mock.lastCall?.[2]).toBe('recovery')
deliver(received)
await vi.waitFor(() => expect(received).toHaveBeenCalledTimes(2))
expect(invoke.mock.calls).toEqual([
['claudeUsage:getScanState', undefined, 'recovery'],
['claudeUsage:getSnapshot', { scope: 'orca', range: '30d', limit: 10 }, 'recovery']
])
expect(received.mock.calls).toEqual([
['claudeUsage:getScanState', undefined, expect.any(AbortSignal)],
['claudeUsage:getSnapshot', { scope: 'orca', range: '30d', limit: 10 }, expect.any(AbortSignal)]
])
})
@@ -0,0 +1,101 @@
import type {
BackendConnectionListener,
BackendConnectionPurpose
} from '../../../../../shared/backend-service-contract'
import type {
ClaudeUsageRange,
ClaudeUsageScope,
ClaudeUsageSnapshot
} from '../../../../../shared/claude-usage-types'
import type {
CodexUsageRange,
CodexUsageScope,
CodexUsageSnapshot
} from '../../../../../shared/codex-usage-types'
import type {
OpenCodeUsageRange,
OpenCodeUsageScope,
OpenCodeUsageSnapshot
} from '../../../../../shared/opencode-usage-types'
import type {
MuseUsageRange,
MuseUsageScope,
MuseUsageSnapshot
} from '../../../../../shared/muse-usage-types'
import type { UsageSnapshot, UsageProviderTypes, UsageFailure } from './usage-provider-types'
export type UsageData<T extends UsageProviderTypes<string, string, UsageSnapshot>> = {
failure: UsageFailure | null
scope: T['scope']
range: T['range']
scanState: T['snapshot']['scanState'] | null
summary: T['snapshot']['summary'] | null
daily: T['snapshot']['daily']
modelBreakdown: T['snapshot']['modelBreakdown']
projectBreakdown: T['snapshot']['projectBreakdown']
recentSessions: T['snapshot']['recentSessions']
}
export type UsageApi<T extends UsageProviderTypes<string, string, UsageSnapshot>> = {
onConnectionChanged?: (listener: BackendConnectionListener) => () => void
getScanState: (purpose?: BackendConnectionPurpose) => Promise<T['snapshot']['scanState']>
setEnabled: (args: { enabled: boolean }) => Promise<T['snapshot']['scanState']>
refresh: (args?: { force?: boolean }) => Promise<T['snapshot']['scanState']>
getSnapshot: (
args: {
scope: T['scope']
range: T['range']
limit?: number
},
purpose?: BackendConnectionPurpose
) => Promise<T['snapshot']>
}
export type ProviderUsageSlice<
Prefix extends string,
Name extends string,
T extends UsageProviderTypes<string, string, UsageSnapshot>
> = {
[K in keyof UsageData<T> as `${Prefix}Usage${Capitalize<K & string>}`]: UsageData<T>[K]
} & Record<`set${Name}UsageEnabled`, (enabled: boolean) => Promise<void>> &
Record<`set${Name}UsageScope`, (scope: T['scope']) => Promise<void>> &
Record<`set${Name}UsageRange`, (range: T['range']) => Promise<void>> &
Record<`fetch${Name}Usage`, (opts?: { forceRefresh?: boolean }) => Promise<void>> &
Record<`observe${Name}Usage`, () => () => void> &
Record<`enable${Name}Usage`, () => Promise<void>> &
Record<`refresh${Name}Usage`, () => Promise<void>>
export type UsageProviderConfig<
Prefix extends string,
Name extends string,
T extends UsageProviderTypes<string, string, UsageSnapshot>
> = {
prefix: Prefix
name: Name
initialScope: T['scope']
initialRange: T['range']
getApi: () => UsageApi<T>
hasCachedData: (scanState: T['snapshot']['scanState']) => boolean
}
export type ClaudeUsageTypes = UsageProviderTypes<
ClaudeUsageScope,
ClaudeUsageRange,
ClaudeUsageSnapshot
>
export type CodexUsageTypes = UsageProviderTypes<
CodexUsageScope,
CodexUsageRange,
CodexUsageSnapshot
>
export type OpenCodeUsageTypes = UsageProviderTypes<
OpenCodeUsageScope,
OpenCodeUsageRange,
OpenCodeUsageSnapshot
>
export type MuseUsageTypes = UsageProviderTypes<MuseUsageScope, MuseUsageRange, MuseUsageSnapshot>
export type ClaudeUsageSlice = ProviderUsageSlice<'claude', 'Claude', ClaudeUsageTypes>
export type CodexUsageSlice = ProviderUsageSlice<'codex', 'Codex', CodexUsageTypes>
export type OpenCodeUsageSlice = ProviderUsageSlice<'openCode', 'OpenCode', OpenCodeUsageTypes>
export type MuseUsageSlice = ProviderUsageSlice<'muse', 'Muse', MuseUsageTypes>
@@ -0,0 +1,87 @@
import type { AppState } from '../../types'
import type { UsageSnapshot, UsageProviderTypes, UsageFailure } from './usage-provider-types'
import type { UsageData } from './usage-provider-slice-contract'
const usageDataFields = [
'failure',
'scope',
'range',
'scanState',
'summary',
'daily',
'modelBreakdown',
'projectBreakdown',
'recentSessions'
] as const satisfies readonly (keyof UsageData<UsageProviderTypes<string, string, UsageSnapshot>>)[]
function usageDataKey(prefix: string, field: string): string {
return `${prefix}Usage${field[0].toUpperCase()}${field.slice(1)}`
}
export function readUsageData<T extends UsageProviderTypes<string, string, UsageSnapshot>>(
state: AppState,
prefix: string
): UsageData<T> {
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: AppState contains each configured provider field; the prefix is fixed by the slice factory.
const values = state as unknown as Record<string, unknown>
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: The fixed field list maps the configured provider keys back to their data fields.
return Object.fromEntries(
usageDataFields.map((field) => [field, values[usageDataKey(prefix, field)]])
) as UsageData<T>
}
export function createUsagePatch<T extends UsageProviderTypes<string, string, UsageSnapshot>>(
prefix: string,
patch: Partial<UsageData<T>>
): Partial<AppState> {
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: The fixed field list maps the configured provider keys back to their data fields.
return Object.fromEntries(
usageDataFields
.filter((field) => field in patch)
.map((field) => [usageDataKey(prefix, field), patch[field]])
) as Partial<AppState>
}
export function createInitialUsageData<T extends UsageProviderTypes<string, string, UsageSnapshot>>(
scope: T['scope'],
range: T['range']
): UsageData<T> {
return {
failure: null,
scope,
range,
scanState: null,
summary: null,
daily: [],
modelBreakdown: [],
projectBreakdown: [],
recentSessions: []
}
}
export function mergeUsageFailure(
previous: UsageFailure | null,
patch: Partial<UsageFailure>
): UsageFailure | null {
const next = {
terminal: false,
read: false,
refresh: false,
setting: false,
...previous,
...patch
}
if (!next.terminal && !next.read && !next.refresh && !next.setting) {
return null
}
if (
previous &&
previous.terminal === next.terminal &&
previous.read === next.read &&
previous.refresh === next.refresh &&
previous.setting === next.setting
) {
return previous
}
return next
}
@@ -0,0 +1,308 @@
import type { StateCreator } from 'zustand'
import type {
UsageData,
UsageApi,
ProviderUsageSlice,
UsageProviderConfig
} from './usage-provider-slice-contract'
import type { AppState } from '../../types'
import type { UsageSnapshot, UsageProviderTypes, UsageFailure } from './usage-provider-types'
import {
mergeUsageFailure,
readUsageData,
createUsagePatch,
createInitialUsageData
} from './usage-provider-slice-state'
export function createUsageProviderSlice<
Prefix extends string,
Name extends string,
T extends UsageProviderTypes<string, string, UsageSnapshot>
>(
config: UsageProviderConfig<Prefix, Name, T>
): StateCreator<AppState, [], [], ProviderUsageSlice<Prefix, Name, T>> {
return (set, get) => {
const update = (patch: Partial<UsageData<T>>): void =>
set(createUsagePatch(config.prefix, patch))
const read = (): UsageData<T> => readUsageData<T>(get(), config.prefix)
const updateFailure = (patch: Partial<UsageFailure>): void => {
const previous = read().failure
const failure = mergeUsageFailure(previous, patch)
if (failure !== previous) {
update({ failure })
}
}
const stopLoading = (): void => {
const state = read().scanState
if (state?.isScanning) {
update({ scanState: { ...state, isScanning: false } })
}
}
type Intent = 0 | 1 | 2
type Operation = {
intent: Intent
phase: 'reading' | 'refreshing' | 'projecting'
disconnected: boolean
readOnFailure: boolean
promise: Promise<void>
}
let operation: Operation | null = null
let pending: Intent | null = null
const queueIntent = (intent: Intent): void => {
pending = pending === null || intent > pending ? intent : pending
}
const markLoading = (): void => {
const state = read().scanState
if (state?.enabled) {
update({ scanState: { ...state, isScanning: true } })
}
}
const project = async (
api: UsageApi<T>,
current: Operation,
beforeRefresh: boolean
): Promise<T['snapshot']['scanState'] | undefined> => {
while (!current.disconnected) {
const { scope, range } = read()
const snapshot = await api.getSnapshot(
{ scope, range, limit: 10 },
current.intent === 0 ? 'recovery' : undefined
)
if (current.disconnected) {
return
}
if (scope !== read().scope || range !== read().range) {
continue
}
const loading = pending === 2 || (beforeRefresh && current.intent === 2)
if (
beforeRefresh &&
current.intent > 0 &&
snapshot.scanState.lastScanCompletedAt === null &&
!config.hasCachedData(snapshot.scanState)
) {
update({ scanState: { ...snapshot.scanState, isScanning: true, lastScanError: null } })
} else {
update({
...snapshot,
scanState: loading ? { ...snapshot.scanState, isScanning: true } : snapshot.scanState
})
}
return snapshot.scanState
}
return undefined
}
const request = (intent: Intent, recovery = false): Promise<void> => {
if (intent === 2) {
markLoading()
}
if (operation) {
if (recovery) {
operation.readOnFailure = true
if (operation.disconnected) {
queueIntent(0)
}
} else if (
operation.disconnected ||
intent > operation.intent ||
(intent > 0 && operation.phase === 'projecting')
) {
queueIntent(intent)
}
return operation.promise
}
const current: Operation = {
intent,
phase: 'reading',
disconnected: false,
readOnFailure: false,
promise: Promise.resolve()
}
operation = current
const unsubscribe = config.getApi()?.onConnectionChanged?.((connected, detail) => {
if (detail?.initial || detail?.unavailable) {
return
}
if (!connected && operation === current) {
if (current.intent === 2 || pending === 2) {
updateFailure({ refresh: true })
}
current.disconnected = true
current.readOnFailure = false
pending = null
stopLoading()
}
})
// Publish the operation before the first port handshake can notify mounted readers.
current.promise = Promise.resolve()
.then(async () => {
let next: Intent | null = intent
while (next !== null) {
current.intent = next
current.phase = 'reading'
current.disconnected = false
current.readOnFailure = false
pending = null
try {
const api = config.getApi()
const state = await api.getScanState(next === 0 ? 'recovery' : undefined)
if (current.disconnected) {
throw new Error('Usage disconnected.')
}
if (state) {
update({
scanState:
(next === 2 || pending === 2) && state.enabled
? { ...state, isScanning: true }
: state
})
if (state.enabled) {
const baseline = await project(api, current, next > 0)
if (current.disconnected) {
throw new Error('Usage disconnected.')
}
if (next > 0) {
current.phase = 'refreshing'
const olderFailure = read().failure
const refreshed = await api.refresh({ force: next === 2 })
if (current.disconnected) {
throw new Error('Usage disconnected.')
}
current.phase = 'projecting'
const completed = await project(api, current, false)
if (current.disconnected) {
throw new Error('Usage disconnected.')
}
if (
completed?.enabled &&
!completed.isScanning &&
!completed.lastScanError &&
((next === 2 &&
refreshed &&
!refreshed.isScanning &&
!refreshed.lastScanError) ||
(next === 1 &&
olderFailure === read().failure &&
baseline &&
completed.lastScanCompletedAt !== null &&
(baseline.lastScanCompletedAt === null ||
completed.lastScanCompletedAt > baseline.lastScanCompletedAt)))
) {
updateFailure({ refresh: false })
}
}
}
updateFailure({ read: false })
}
} catch (error) {
updateFailure({ read: true, ...(next === 2 ? { refresh: true } : {}) })
if (pending !== 2) {
stopLoading()
}
if (current.readOnFailure) {
queueIntent(0)
}
console.error(`Failed to fetch ${config.name} usage:`, error)
}
next = pending
}
if (operation === current) {
operation = null
}
})
.finally(() => {
unsubscribe?.()
if (operation === current) {
operation = null
}
})
return current.promise
}
const fetchUsage = (opts?: { forceRefresh?: boolean }): Promise<void> =>
request(opts?.forceRefresh ? 2 : 1)
const observeUsage = (): (() => void) => {
const unsubscribe = config.getApi()?.onConnectionChanged?.((connected, detail) => {
if (detail?.initial) {
updateFailure({ terminal: detail.unavailable === true })
return
}
if (detail?.unavailable) {
updateFailure({ terminal: true })
return
}
if (connected) {
updateFailure({ terminal: false })
void request(0, true)
} else {
stopLoading()
}
})
void fetchUsage()
return () => unsubscribe?.()
}
const setEnabled = async (enabled: boolean): Promise<void> => {
try {
const nextScanState = (await config.getApi().setEnabled({ enabled })) as
| T['snapshot']['scanState']
| undefined
if (!nextScanState) {
return
}
updateFailure(
enabled
? { setting: false, read: false, terminal: false }
: { setting: false, read: false, terminal: false, refresh: false }
)
update({
scanState: enabled
? {
...nextScanState,
isScanning: true,
lastScanCompletedAt: null,
lastScanError: null
}
: nextScanState,
summary: null,
daily: [],
modelBreakdown: [],
projectBreakdown: [],
recentSessions: []
})
if (enabled) {
await fetchUsage({ forceRefresh: true })
}
} catch (error) {
updateFailure({ setting: true })
stopLoading()
console.error(`Failed to update ${config.name} usage setting:`, error)
}
}
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: The configured prefix/name maps the declared data and action keys for this provider.
return {
...createUsagePatch(
config.prefix,
createInitialUsageData<T>(config.initialScope, config.initialRange)
),
[`set${config.name}UsageEnabled`]: setEnabled,
[`set${config.name}UsageScope`]: async (scope: T['scope']) => {
update({ scope })
await fetchUsage()
},
[`set${config.name}UsageRange`]: async (range: T['range']) => {
update({ range })
await fetchUsage()
},
[`fetch${config.name}Usage`]: fetchUsage,
[`observe${config.name}Usage`]: observeUsage,
[`enable${config.name}Usage`]: () => setEnabled(true),
[`refresh${config.name}Usage`]: () => fetchUsage({ forceRefresh: true })
} as ProviderUsageSlice<Prefix, Name, T>
}
}
@@ -0,0 +1,419 @@
// @vitest-environment happy-dom
import { afterEach, expect, it, vi } from 'vitest'
import { act, cleanup, renderHook } from '@testing-library/react'
import { createStore } from 'zustand/vanilla'
import { createClaudeUsageSlice } from './usage-provider-slices'
import { useUsageObservation } from './use-usage-observation'
import type {
BackendConnectionListener,
BackendConnectionDetail
} from '../../../../../shared/backend-service-contract'
import type { AppState } from '../../types'
import type { ClaudeUsageScanState } from '../../../../../shared/claude-usage-types'
const scanState: ClaudeUsageScanState = {
enabled: true,
isScanning: false,
lastScanStartedAt: null,
lastScanCompletedAt: 1,
lastScanError: null,
hasAnyClaudeData: true
}
const snapshot = {
scanState,
summary: { turns: 1, inputTokens: 123 },
daily: [],
modelBreakdown: [],
projectBreakdown: [],
recentSessions: []
}
function deferred<T>() {
let resolve!: (value: T) => void
let reject!: (error: Error) => void
const promise = new Promise<T>((done, fail) => {
resolve = done
reject = fail
})
return { promise, resolve, reject }
}
function fixture() {
const listeners = new Set<BackendConnectionListener>()
let status = { connected: false, unavailable: false }
const api = {
onConnectionChanged: (listener: BackendConnectionListener) => {
listeners.add(listener)
listener(status.connected, { initial: true, unavailable: status.unavailable })
return () => {
listeners.delete(listener)
}
},
setEnabled: vi.fn(async ({ enabled }: { enabled: boolean }) => ({ ...scanState, enabled })),
getScanState: vi.fn(async () => scanState),
getSnapshot: vi.fn(async (_selection: { scope: string; range: string }) => snapshot),
refresh: vi.fn(async (_options?: { force?: boolean }) => scanState)
}
vi.stubGlobal('api', { claudeUsage: api })
const store = createStore<AppState>()((...args) => {
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: The fixture uses only this production slice's public state/actions.
return createClaudeUsageSlice(...args) as AppState
})
return {
store,
api,
notify: (connected: boolean, detail?: BackendConnectionDetail) => {
status = { connected, unavailable: detail?.unavailable === true }
for (const listener of listeners) {
listener(connected, detail)
}
}
}
}
afterEach(() => {
cleanup()
vi.unstubAllGlobals()
vi.restoreAllMocks()
})
it.each([1, 10])(
'hydrates only %i mounted outputs and does no hidden reconnect work',
async (count) => {
const { api, notify } = fixture()
const stores = Array.from({ length: count }, () =>
createStore<AppState>()((...args) => {
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: Only the usage slice is exercised.
return createClaudeUsageSlice(...args) as AppState
})
)
const hooks = stores.map((store) =>
renderHook(() => useUsageObservation(store.getState().observeClaudeUsage))
)
await act(async () => {
await Promise.all(stores.map((store) => store.getState().fetchClaudeUsage()))
})
api.getScanState.mockClear()
api.getSnapshot.mockClear()
api.refresh.mockClear()
await act(async () => {
notify(false)
notify(true)
})
expect(api.getScanState).toHaveBeenCalledTimes(count)
expect(api.getSnapshot).toHaveBeenCalledTimes(count)
expect(api.refresh).not.toHaveBeenCalled()
expect(stores[0].getState().claudeUsageSummary).toMatchObject({ inputTokens: 123 })
for (const hook of hooks) {
hook.unmount()
}
api.getScanState.mockClear()
api.getSnapshot.mockClear()
await act(async () => {
notify(false)
notify(true)
})
expect(api.getScanState).not.toHaveBeenCalled()
expect(api.getSnapshot).not.toHaveBeenCalled()
}
)
it.each([1, 10])('drops lost queued force after %i outputs unmount', async (count) => {
const { api, notify } = fixture()
vi.spyOn(console, 'error').mockImplementation(() => {})
const refresh = deferred<typeof scanState>()
api.refresh.mockReturnValue(refresh.promise)
const stores = Array.from({ length: count }, () =>
createStore<AppState>()((...args) => {
// oxlint-disable-next-line typescript/consistent-type-assertions -- SAFETY: Only the usage slice is exercised.
return createClaudeUsageSlice(...args) as AppState
})
)
const hooks = stores.map((store) =>
renderHook(() => useUsageObservation(store.getState().observeClaudeUsage))
)
await act(async () => {})
expect(api.refresh).toHaveBeenCalledTimes(count)
const forced = stores.map((store) => store.getState().refreshClaudeUsage())
for (const hook of hooks) {
hook.unmount()
}
api.getScanState.mockClear()
api.getSnapshot.mockClear()
api.refresh.mockClear()
await act(async () => {
notify(false)
refresh.reject(new Error('port closed'))
await Promise.all(forced)
notify(true)
})
expect(api.getScanState).not.toHaveBeenCalled()
expect(api.getSnapshot).not.toHaveBeenCalled()
expect(api.refresh).not.toHaveBeenCalled()
expect(stores[0].getState().claudeUsageScanState?.isScanning).toBe(false)
})
it.each([false, true])(
'preserves admitted work after unmount and same-connection failure=%s',
async (fail) => {
const { api, store } = fixture()
vi.spyOn(console, 'error').mockImplementation(() => {})
const refresh = deferred<typeof scanState>()
api.refresh.mockReturnValueOnce(refresh.promise)
const hook = renderHook(() => useUsageObservation(store.getState().observeClaudeUsage))
await act(async () => {})
expect(api.refresh).toHaveBeenCalledTimes(1)
const forced = store.getState().refreshClaudeUsage()
hook.unmount()
if (fail) {
refresh.reject(new Error('scan failed on the same connection'))
} else {
refresh.resolve(scanState)
}
await forced
expect(api.refresh.mock.calls.map(([options]) => options?.force)).toEqual([false, true])
expect(store.getState().claudeUsageSummary).toMatchObject({ inputTokens: 123 })
}
)
it('retains fresh explicit intent after loss while the old call is rejecting', async () => {
const { api, store, notify } = fixture()
vi.spyOn(console, 'error').mockImplementation(() => {})
const refresh = deferred<typeof scanState>()
api.refresh.mockReturnValueOnce(refresh.promise)
const hook = renderHook(() => useUsageObservation(store.getState().observeClaudeUsage))
await act(async () => {})
const oldForce = store.getState().refreshClaudeUsage()
hook.unmount()
notify(false)
const fresh = store.getState().refreshClaudeUsage()
refresh.reject(new Error('old port closed'))
await Promise.all([oldForce, fresh])
expect(api.refresh.mock.calls.map(([options]) => options?.force)).toEqual([false, true])
expect(store.getState().claudeUsageSummary).toMatchObject({ inputTokens: 123 })
})
it('retains mounted recovery after the first state request fails', async () => {
const { store, api, notify } = fixture()
vi.spyOn(console, 'error').mockImplementation(() => {})
api.getScanState.mockRejectedValueOnce(new Error('first connection failed'))
renderHook(() => useUsageObservation(store.getState().observeClaudeUsage))
await act(async () => {
await store.getState().fetchClaudeUsage()
})
expect(store.getState().claudeUsageScanState).toBeNull()
await act(async () => {
notify(true)
})
expect(store.getState().claudeUsageSummary).toMatchObject({ inputTokens: 123 })
expect(api.refresh).not.toHaveBeenCalled()
})
it('joins the startup-ready signal and bounds selection storms while retaining a late force', async () => {
const { store, api, notify } = fixture()
const refresh = deferred<typeof scanState>()
api.refresh.mockReturnValueOnce(refresh.promise)
renderHook(() => useUsageObservation(store.getState().observeClaudeUsage))
await act(async () => {
notify(true)
})
expect(api.getScanState).toHaveBeenCalledTimes(1)
const requests = Array.from({ length: 40 }, (_, i) =>
store.getState().setClaudeUsageRange(i === 39 ? 'all' : '7d')
)
const forced = store.getState().refreshClaudeUsage()
await act(async () => {
refresh.resolve(scanState)
await Promise.all([...requests, forced])
})
expect(api.refresh.mock.calls.map(([options]) => options?.force)).toEqual([false, true])
expect(store.getState().claudeUsageRange).toBe('all')
expect(api.getSnapshot.mock.calls.at(-1)?.[0]).toMatchObject({ range: 'all' })
})
it.each([false, true])(
'owns queued explicit refresh across ordinary failure=%s',
async (failed) => {
const { store, api } = fixture()
const background = deferred<typeof scanState>()
const forcedState = deferred<typeof scanState>()
const forcedScan = deferred<typeof scanState>()
vi.spyOn(console, 'error').mockImplementation(() => {})
api.getScanState.mockResolvedValueOnce(scanState).mockReturnValueOnce(forcedState.promise)
api.refresh.mockReturnValueOnce(background.promise).mockReturnValueOnce(forcedScan.promise)
const first = store.getState().fetchClaudeUsage()
await vi.waitFor(() => expect(api.refresh).toHaveBeenCalledTimes(1))
expect(store.getState().claudeUsageSummary).toMatchObject({ inputTokens: 123 })
expect(store.getState().claudeUsageScanState?.isScanning).toBe(false)
const forced = store.getState().refreshClaudeUsage()
expect(store.getState().claudeUsageScanState?.isScanning).toBe(true)
const busy: boolean[] = []
const unsubscribe = store.subscribe((state) => {
busy.push(state.claudeUsageScanState?.isScanning ?? false)
})
if (failed) {
background.reject(new Error('Catalog unavailable'))
} else {
background.resolve(scanState)
}
await vi.waitFor(() => expect(api.getScanState).toHaveBeenCalledTimes(2))
expect(store.getState().claudeUsageScanState?.isScanning).toBe(true)
expect(busy.every(Boolean)).toBe(true)
forcedState.resolve(scanState)
await vi.waitFor(() => expect(api.refresh).toHaveBeenCalledTimes(2))
expect(busy.length).toBeGreaterThan(0)
expect(busy.every(Boolean)).toBe(true)
expect(store.getState().claudeUsageSummary).toMatchObject({ inputTokens: 123 })
unsubscribe()
forcedScan.resolve(scanState)
await Promise.all([first, forced])
expect(store.getState().claudeUsageScanState?.isScanning).toBe(false)
}
)
it('shows first-load scanning without masking a reported scan on answered data', async () => {
const { store, api } = fixture()
const background = deferred<typeof scanState>()
api.getSnapshot.mockResolvedValueOnce({
...snapshot,
scanState: { ...scanState, lastScanCompletedAt: null, hasAnyClaudeData: false }
})
api.refresh.mockReturnValueOnce(background.promise)
const first = store.getState().fetchClaudeUsage()
await vi.waitFor(() => expect(api.refresh).toHaveBeenCalledTimes(1))
expect(store.getState().claudeUsageScanState?.isScanning).toBe(true)
background.resolve(scanState)
await first
expect(store.getState().claudeUsageScanState?.isScanning).toBe(false)
const scanning = deferred<typeof scanState>()
api.getScanState.mockResolvedValueOnce({ ...scanState, isScanning: true })
api.getSnapshot.mockResolvedValueOnce({
...snapshot,
scanState: { ...scanState, isScanning: true }
})
api.refresh.mockReturnValueOnce(scanning.promise)
const next = store.getState().fetchClaudeUsage()
await vi.waitFor(() => expect(api.refresh).toHaveBeenCalledTimes(2))
expect(store.getState().claudeUsageScanState?.isScanning).toBe(true)
scanning.resolve(scanState)
await next
})
it('does not publish an obsolete selection or swallow force after refresh has finished', async () => {
const { store, api } = fixture()
const projection = deferred<typeof snapshot>()
api.getSnapshot.mockResolvedValueOnce(snapshot).mockReturnValueOnce(projection.promise)
const first = store.getState().fetchClaudeUsage()
await vi.waitFor(() => expect(api.getSnapshot).toHaveBeenCalledTimes(2))
const selected = store.getState().setClaudeUsageRange('all')
const forced = store.getState().refreshClaudeUsage()
projection.resolve({ ...snapshot, summary: { turns: 2, inputTokens: 999 } })
await Promise.all([first, selected, forced])
expect(store.getState().claudeUsageSummary).toMatchObject({ inputTokens: 123 })
expect(api.refresh.mock.calls.map(([options]) => options?.force)).toEqual([false, true])
expect(api.getSnapshot.mock.calls.at(-1)?.[0]).toMatchObject({ range: 'all' })
})
it('shows lost Refresh through read-only recovery and clears it only after a successful explicit retry', async () => {
const { api, store, notify } = fixture()
vi.spyOn(console, 'error').mockImplementation(() => {})
const stop = store.getState().observeClaudeUsage()
await store.getState().fetchClaudeUsage()
const held = deferred<typeof scanState>()
api.refresh.mockReturnValueOnce(held.promise)
const refresh = store.getState().refreshClaudeUsage()
await vi.waitFor(() => expect(api.refresh).toHaveBeenCalledTimes(2))
notify(false)
notify(false, { unavailable: true })
held.reject(new Error('Usage disconnected'))
await refresh
expect(store.getState().claudeUsageFailure).toMatchObject({ terminal: true, refresh: true })
expect(store.getState().claudeUsageScanState?.isScanning).toBe(false)
api.refresh.mockClear()
notify(true)
await store.getState().fetchClaudeUsage()
expect(api.refresh).not.toHaveBeenCalled()
expect(store.getState().claudeUsageFailure).toMatchObject({ terminal: false, refresh: true })
expect(store.getState().claudeUsageSummary).toMatchObject({ inputTokens: 123 })
await store.getState().refreshClaudeUsage()
expect(api.refresh.mock.calls.map(([options]) => options?.force)).toEqual([true])
expect(store.getState().claudeUsageFailure).toBeNull()
stop()
})
it.each([
'skip',
'scanning',
'error',
'completed',
'first-completion',
'intermediate-scanning'
] as const)(
'resolves old Refresh failure only with a newer settled producer result: %s',
async (outcome) => {
const { api, store } = fixture()
vi.spyOn(console, 'error').mockImplementation(() => {})
api.refresh.mockRejectedValueOnce(new Error('lost Refresh'))
await store.getState().refreshClaudeUsage()
expect(store.getState().claudeUsageFailure?.refresh).toBe(true)
const baseline = {
...scanState,
lastScanCompletedAt: outcome === 'first-completion' ? null : 1
}
const final = {
...scanState,
lastScanCompletedAt: outcome === 'skip' ? 1 : 2,
isScanning: outcome === 'scanning',
lastScanError: outcome === 'error' ? 'scan failed' : null
}
api.getSnapshot
.mockResolvedValueOnce({ ...snapshot, scanState: baseline })
.mockResolvedValueOnce({ ...snapshot, scanState: final })
api.refresh.mockResolvedValueOnce(
outcome === 'intermediate-scanning' ? { ...final, isScanning: true } : final
)
await store.getState().fetchClaudeUsage()
expect(store.getState().claudeUsageFailure?.refresh ?? false).toBe(
outcome !== 'completed' &&
outcome !== 'first-completion' &&
outcome !== 'intermediate-scanning'
)
}
)
it('retains unacknowledged setting writes through cache reads and never enables a disabled retry', async () => {
const { api, store, notify } = fixture()
vi.spyOn(console, 'error').mockImplementation(() => {})
api.setEnabled.mockRejectedValueOnce(new Error('lost acknowledgement'))
await store.getState().setClaudeUsageEnabled(false)
const stop = store.getState().observeClaudeUsage()
await store.getState().fetchClaudeUsage()
expect(store.getState().claudeUsageFailure?.setting).toBe(true)
notify(false, { unavailable: true })
stop()
notify(true)
api.getScanState.mockResolvedValue({ ...scanState, enabled: false })
const remount = store.getState().observeClaudeUsage()
await store.getState().fetchClaudeUsage()
expect(store.getState().claudeUsageFailure).toMatchObject({ terminal: false, setting: true })
api.refresh.mockClear()
await store.getState().refreshClaudeUsage()
expect(api.refresh).not.toHaveBeenCalled()
expect(api.setEnabled).toHaveBeenCalledTimes(1)
await store.getState().setClaudeUsageEnabled(false)
expect(store.getState().claudeUsageFailure).toBeNull()
remount()
})
it('does not treat an unsuccessful forced command as ordinary newer-scan recovery', async () => {
const { api, store } = fixture()
vi.spyOn(console, 'error').mockImplementation(() => {})
api.refresh.mockRejectedValueOnce(new Error('lost Refresh'))
await store.getState().refreshClaudeUsage()
api.getSnapshot.mockResolvedValueOnce(snapshot).mockResolvedValueOnce({
...snapshot,
scanState: { ...scanState, lastScanCompletedAt: 2 }
})
api.refresh.mockResolvedValueOnce({ ...scanState, lastScanError: 'scan failed' })
await store.getState().refreshClaudeUsage()
expect(store.getState().claudeUsageFailure?.refresh).toBe(true)
})
@@ -1,283 +1,17 @@
import type { StateCreator } from 'zustand'
import { createUsageProviderSlice } from './usage-provider-slice'
import type {
ClaudeUsageRange,
ClaudeUsageScope,
ClaudeUsageSnapshot
} from '../../../../../shared/claude-usage-types'
import type {
CodexUsageRange,
CodexUsageScope,
CodexUsageSnapshot
} from '../../../../../shared/codex-usage-types'
import type {
OpenCodeUsageRange,
OpenCodeUsageScope,
OpenCodeUsageSnapshot
} from '../../../../../shared/opencode-usage-types'
import type {
MuseUsageRange,
MuseUsageScope,
MuseUsageSnapshot
} from '../../../../../shared/muse-usage-types'
import type { AppState } from '../../types'
ClaudeUsageTypes,
CodexUsageTypes,
OpenCodeUsageTypes,
MuseUsageTypes
} from './usage-provider-slice-contract'
type UsageSnapshot = {
scanState: {
enabled: boolean
isScanning: boolean
lastScanCompletedAt: number | null
lastScanError: string | null
}
summary: object
daily: object[]
modelBreakdown: object[]
projectBreakdown: object[]
recentSessions: object[]
}
type UsageProviderTypes<
Scope extends string,
Range extends string,
Snapshot extends UsageSnapshot
> = {
scope: Scope
range: Range
snapshot: Snapshot
}
type UsageData<T extends UsageProviderTypes<string, string, UsageSnapshot>> = {
scope: T['scope']
range: T['range']
scanState: T['snapshot']['scanState'] | null
summary: T['snapshot']['summary'] | null
daily: T['snapshot']['daily']
modelBreakdown: T['snapshot']['modelBreakdown']
projectBreakdown: T['snapshot']['projectBreakdown']
recentSessions: T['snapshot']['recentSessions']
}
type UsageApi<T extends UsageProviderTypes<string, string, UsageSnapshot>> = {
getScanState: () => Promise<T['snapshot']['scanState']>
setEnabled: (args: { enabled: boolean }) => Promise<T['snapshot']['scanState']>
refresh: (args?: { force?: boolean }) => Promise<T['snapshot']['scanState']>
getSnapshot: (args: {
scope: T['scope']
range: T['range']
limit?: number
}) => Promise<T['snapshot']>
}
type ProviderUsageSlice<
Prefix extends string,
Name extends string,
T extends UsageProviderTypes<string, string, UsageSnapshot>
> = {
[K in keyof UsageData<T> as `${Prefix}Usage${Capitalize<K & string>}`]: UsageData<T>[K]
} & Record<`set${Name}UsageEnabled`, (enabled: boolean) => Promise<void>> &
Record<`set${Name}UsageScope`, (scope: T['scope']) => Promise<void>> &
Record<`set${Name}UsageRange`, (range: T['range']) => Promise<void>> &
Record<`fetch${Name}Usage`, (opts?: { forceRefresh?: boolean }) => Promise<void>> &
Record<`enable${Name}Usage`, () => Promise<void>> &
Record<`refresh${Name}Usage`, () => Promise<void>>
type UsageProviderConfig<
Prefix extends string,
Name extends string,
T extends UsageProviderTypes<string, string, UsageSnapshot>
> = {
prefix: Prefix
name: Name
initialScope: T['scope']
initialRange: T['range']
getApi: () => UsageApi<T>
hasCachedData: (scanState: T['snapshot']['scanState']) => boolean
}
const usageDataFields = [
'scope',
'range',
'scanState',
'summary',
'daily',
'modelBreakdown',
'projectBreakdown',
'recentSessions'
] as const satisfies readonly (keyof UsageData<UsageProviderTypes<string, string, UsageSnapshot>>)[]
function usageDataKey(prefix: string, field: string): string {
return `${prefix}Usage${field[0].toUpperCase()}${field.slice(1)}`
}
function readUsageData<T extends UsageProviderTypes<string, string, UsageSnapshot>>(
state: AppState,
prefix: string
): UsageData<T> {
const values = state as unknown as Record<string, unknown>
return Object.fromEntries(
usageDataFields.map((field) => [field, values[usageDataKey(prefix, field)]])
) as UsageData<T>
}
function createUsagePatch<T extends UsageProviderTypes<string, string, UsageSnapshot>>(
prefix: string,
patch: Partial<UsageData<T>>
): Partial<AppState> {
return Object.fromEntries(
usageDataFields
.filter((field) => field in patch)
.map((field) => [usageDataKey(prefix, field), patch[field]])
) as Partial<AppState>
}
function createUsageProviderSlice<
Prefix extends string,
Name extends string,
T extends UsageProviderTypes<string, string, UsageSnapshot>
>(
config: UsageProviderConfig<Prefix, Name, T>
): StateCreator<AppState, [], [], ProviderUsageSlice<Prefix, Name, T>> {
return (set, get) => {
const update = (patch: Partial<UsageData<T>>): void =>
set(createUsagePatch(config.prefix, patch))
const read = (): UsageData<T> => readUsageData<T>(get(), config.prefix)
const fetchUsage = async (opts?: { forceRefresh?: boolean }): Promise<void> => {
try {
const api = config.getApi()
const scanState = (await api.getScanState()) as T['snapshot']['scanState'] | undefined
// Desktop-only usage APIs resolve undefined in paired web clients.
if (!scanState) {
return
}
const current = read()
const preserveLoading =
opts?.forceRefresh === true &&
current.scanState?.enabled === true &&
current.summary === null
update({
scanState: preserveLoading
? {
...scanState,
isScanning: true,
lastScanCompletedAt: null,
lastScanError: null
}
: scanState
})
if (!scanState.enabled) {
return
}
const selection = read()
const snapshot = await api.getSnapshot({
scope: selection.scope,
range: selection.range,
limit: 10
})
if (
snapshot.scanState.lastScanCompletedAt !== null ||
config.hasCachedData(snapshot.scanState)
) {
update({
...snapshot,
scanState:
opts?.forceRefresh === true
? { ...snapshot.scanState, isScanning: true }
: snapshot.scanState
})
} else {
update({ scanState: { ...scanState, isScanning: true, lastScanError: null } })
}
await api.refresh({ force: opts?.forceRefresh ?? false })
const refreshedSelection = read()
update(
await api.getSnapshot({
scope: refreshedSelection.scope,
range: refreshedSelection.range,
limit: 10
})
)
} catch (error) {
console.error(`Failed to fetch ${config.name} usage:`, error)
}
}
const setEnabled = async (enabled: boolean): Promise<void> => {
try {
const nextScanState = (await config.getApi().setEnabled({ enabled })) as
| T['snapshot']['scanState']
| undefined
if (!nextScanState) {
return
}
update({
scanState: enabled
? {
...nextScanState,
isScanning: true,
lastScanCompletedAt: null,
lastScanError: null
}
: nextScanState,
summary: null,
daily: [],
modelBreakdown: [],
projectBreakdown: [],
recentSessions: []
})
if (enabled) {
await fetchUsage({ forceRefresh: true })
}
} catch (error) {
console.error(`Failed to update ${config.name} usage setting:`, error)
}
}
const initialData: UsageData<T> = {
scope: config.initialScope,
range: config.initialRange,
scanState: null,
summary: null,
daily: [],
modelBreakdown: [],
projectBreakdown: [],
recentSessions: []
}
return {
...createUsagePatch(config.prefix, initialData),
[`set${config.name}UsageEnabled`]: setEnabled,
[`set${config.name}UsageScope`]: async (scope: T['scope']) => {
update({ scope })
await fetchUsage()
},
[`set${config.name}UsageRange`]: async (range: T['range']) => {
update({ range })
await fetchUsage()
},
[`fetch${config.name}Usage`]: fetchUsage,
[`enable${config.name}Usage`]: () => setEnabled(true),
[`refresh${config.name}Usage`]: () => fetchUsage({ forceRefresh: true })
} as ProviderUsageSlice<Prefix, Name, T>
}
}
type ClaudeUsageTypes = UsageProviderTypes<ClaudeUsageScope, ClaudeUsageRange, ClaudeUsageSnapshot>
type CodexUsageTypes = UsageProviderTypes<CodexUsageScope, CodexUsageRange, CodexUsageSnapshot>
type OpenCodeUsageTypes = UsageProviderTypes<
OpenCodeUsageScope,
OpenCodeUsageRange,
OpenCodeUsageSnapshot
>
type MuseUsageTypes = UsageProviderTypes<MuseUsageScope, MuseUsageRange, MuseUsageSnapshot>
export type ClaudeUsageSlice = ProviderUsageSlice<'claude', 'Claude', ClaudeUsageTypes>
export type CodexUsageSlice = ProviderUsageSlice<'codex', 'Codex', CodexUsageTypes>
export type OpenCodeUsageSlice = ProviderUsageSlice<'openCode', 'OpenCode', OpenCodeUsageTypes>
export type MuseUsageSlice = ProviderUsageSlice<'muse', 'Muse', MuseUsageTypes>
export type {
ClaudeUsageSlice,
CodexUsageSlice,
OpenCodeUsageSlice,
MuseUsageSlice
} from './usage-provider-slice-contract'
export const createClaudeUsageSlice = createUsageProviderSlice<
'claude',
@@ -0,0 +1,30 @@
export type UsageFailure = {
terminal: boolean
read: boolean
refresh: boolean
setting: boolean
}
export type UsageSnapshot = {
scanState: {
enabled: boolean
isScanning: boolean
lastScanCompletedAt: number | null
lastScanError: string | null
}
summary: object
daily: object[]
modelBreakdown: object[]
projectBreakdown: object[]
recentSessions: object[]
}
export type UsageProviderTypes<
Scope extends string,
Range extends string,
Snapshot extends UsageSnapshot
> = {
scope: Scope
range: Range
snapshot: Snapshot
}
@@ -0,0 +1,5 @@
import { useEffect } from 'react'
export function useUsageObservation(observe: () => () => void): void {
useEffect(() => observe(), [observe])
}