Files

T

StillKnotKnown cfe7dedd09 feat: Add API profile providers usage endpoints support (#1279 )

* auto-claude: subtask-1-1 - Add provider type definitions and detection utility

This commit adds:
- ApiProvider type definition for usage monitoring (anthropic | zai | zhipu | unknown)
- ProviderPattern interface mapping domain patterns to provider types
- detectProvider() utility function to identify API provider from baseUrl
- Support for subdomain matching (e.g., dev.bigmodel.cn matches bigmodel.cn)
- Graceful error handling for invalid URLs (returns 'unknown')

The detection function correctly identifies all known provider baseUrl patterns
and returns 'unknown' for unsupported URLs.

Co-Authored-By: Claude <noreply@anthropic.com>

* auto-claude: subtask-1-2 - Create provider endpoint configuration mapping

- Added ProviderUsageEndpoint interface following api-profiles.ts pattern
- Created PROVIDER_USAGE_ENDPOINTS constant with usage paths for each provider:
  - anthropic: /api/oauth/usage (existing)
  - zai: /api/monitor/usage/model-usage (new)
  - zhipu: /api/monitor/usage/model-usage (new)
- Added getUsageEndpoint() function to construct full usage endpoint URLs
- Includes proper error handling and JSDoc documentation
- Uses readonly arrays and const assertions matching codebase patterns

Co-Authored-By: Claude <noreply@anthropic.com>

* auto-claude: subtask-1-3 - Add credential detection logic (OAuth token vs API key)

Implement credential detection logic that automatically determines whether to use
OAuth token or API key based on the active profile type.

Changes:
- Add getCredential() private method that:
  * Checks for active API profile (via loadProfilesFile)
  * Returns apiKey directly if API profile is active
  * Falls back to OAuth profile (via getProfileToken)
  * Returns undefined if no credential available
- Update checkUsageAndSwap() to use new getCredential() method
- Add debug logging to trace credential type selection
- Import required modules (loadProfilesFile, APIProfile type)

This enables usage monitoring to work with both OAuth profiles (ClaudeProfile)
and API profiles (APIProfile), paving the way for multi-provider support.

Co-Authored-By: Claude <noreply@anthropic.com>

* auto-claude: subtask-2-1 - Implement z.ai usage fetcher with response normalization

Refactored fetchUsageViaAPI to support multiple providers:
- Added provider detection from active API profile's baseUrl
- Implemented provider-specific usage endpoint routing (anthropic, z.ai, zhipu)
- Created normalizeZAIResponse with flexible field name matching for undocumented API
- Created normalizeZhipuResponse using same flexible parsing as z.ai
- Added helper methods: extractUsageField, extractLimitField, extractResetField
- Added getAPIProfile to load active API profile with baseUrl and apiKey
- Comprehensive logging for empirical response structure discovery
- Graceful fallback to 0% usage when endpoints unavailable

Follows existing Anthropic OAuth pattern while extending to support API profiles.
Logs raw response structures for debugging undocumented endpoints.

Co-Authored-By: Claude <noreply@anthropic.com>

* auto-claude: subtask-2-3 - Create generic response normalization helper function

- Added normalizeGenericProviderResponse() helper function to handle
  heterogeneous response formats from different providers
- Refactored normalizeZAIResponse() to use the generic helper with
  zai-specific field mappings
- Refactored normalizeZhipuResponse() to use the generic helper with
  zhipu-specific field mappings
- The helper function accepts configurable field name mappings and
  performs flexible parsing for undocumented API response structures
- Added comprehensive logging for debugging provider-specific issues
- Maintains graceful degradation by returning 0% usage when parsing fails

Co-Authored-By: Claude <noreply@anthropic.com>

* auto-claude: subtask-3-2 - Add comprehensive logging for debugging provider issues

Enhanced debug logging across all provider-related decision points:
- Provider detection: Log baseUrl, domain extraction, pattern matching
- Endpoint construction: Log URL building process, path replacement
- API fetch orchestration: Track method selection, fallback behavior
- Field extraction: Log attempted fields, matched fields, available keys
- Normalization flow: Track method selection, percentage calculation
- Provider-specific normalization: Detailed logging for zai/zhipu

All debug logs are gated by DEBUG=true environment variable to avoid
spam in production. Logs use structured [UsageMonitor:*] prefixes for
easy filtering and grep.

This makes it much easier to diagnose issues with:
- Unknown provider baseUrl patterns
- Incorrect endpoint path construction
- Response format changes from providers
- Field mapping failures in generic normalization

* auto-claude: subtask-3-3 - Update error handling to trigger proactive swap for all providers

Enhanced auth failure detection in fetchUsageViaAPI to support all providers:
- Added response body parsing for auth error pattern detection
- Checks for common auth error messages (unauthorized, invalid token, etc.)
- Re-throws auth failures regardless of status code
- Ensures proactive swap is triggered for auth failures from any provider

This handles cases where providers might return non-401/403 status codes
with auth-related error messages in the response body.

* auto-claude: subtask-4-1 - Create test file structure and mocks

- Created usage-monitor.test.ts with comprehensive test coverage
- Tests provider detection (anthropic, zai, zhipu, unknown)
- Tests usage endpoint construction for all providers
- Tests UsageMonitor singleton pattern
- Tests start/stop monitoring functionality
- Tests event emission and listener management
- All 25 tests passing

Co-Authored-By: Claude <noreply@anthropic.com>

* auto-claude: subtask-4-3 - Write response normalization tests

Implemented comprehensive normalization tests for all providers:
- Anthropic response normalization (2 tests)
- z.ai response normalization (3 tests)
- ZHIPU response normalization (2 tests)
- Percentage calculation tests (2 tests)
- Malformed response handling tests (2 tests)

All tests pass and verify:
- Correct percentage calculations from usage/limit values
- Flexible field name matching for undocumented APIs
- Graceful handling of missing/invalid data
- Proper limitType determination
- Reset time formatting

Co-Authored-By: Claude <noreply@anthropic.com>

* auto-claude: subtask-4-4 - Write error handling tests

Added comprehensive error handling tests for usage-monitor:
- API error handling (401, 403, 500, network failures, invalid JSON)
- Credential error handling (missing/empty credentials)
- Profile error handling (null profiles, missing fields)
- Provider-specific error handling (zai, ZHIPU, unknown providers)
- Reset time formatting error handling (invalid timestamps, null/undefined)
- Concurrent check prevention

All 55 tests passing successfully.

* auto-claude: subtask-4-5 - Write backward compatibility tests

- Added comprehensive backward compatibility tests for usage-monitor
- Tests cover: legacy OAuth profiles, settings compatibility, response format changes, provider detection
- All 18 backward compatibility tests pass

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: Add frontend provider badges for OAuth, API token, and API profiles

QA Fix - Addresses request to display provider type badges in the UI.

Changes:
- Created provider detection utility (provider-detection.ts) for renderer process
- Updated AuthStatusIndicator to display provider type badges:
  - OAuth: Shows "Anthropic" with orange badge and Lock icon
  - z.ai API Profile: Shows "z.ai" with blue badge and Key icon
  - ZHIPU AI API Profile: Shows "ZHIPU AI" with purple badge and Key icon
- Added AuthStatusIndicator to ProjectTabBar next to UsageIndicator
- Provider detection based on baseUrl patterns matches backend logic
- Added comprehensive tests for provider detection (18 tests)
- Updated AuthStatusIndicator tests (9 tests) for new behavior
- All 49 ProjectTabBar integration tests still pass

The badges now clearly show which authentication method and provider is active:
- Users can see at a glance whether they're using OAuth or an API profile
- Provider-specific colors help distinguish between Anthropic, z.ai, and ZHIPU
- Tooltips provide detailed information about authentication type and profile name

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: Add usage window labels and fix z.ai monthly calculation

This commit addresses QA feedback to improve usage badge display and
correctly handle z.ai's monthly limits.

Changes:
- Add usageWindows metadata to ClaudeUsageSnapshot to track window types
- Update normalizeAnthropicResponse to include '5-hour window' and '7-day window' labels
- Update normalizeZAIResponse to include '5-hour window' and 'Calendar month' labels
  - Add monthly_usage/month_limit fields to z.ai weekly usage mapping
- Update normalizeZhipuResponse to include '5-hour window' and '7-day window' labels
- Update normalizeGenericProviderResponse to accept and use window labels
- Update UsageIndicator to:
  - Show 5-hour window (sessionPercent) on the badge per QA feedback
  - Use dynamic window labels in hover tooltip instead of hardcoded text
  - Display provider-specific window types (e.g., "Calendar month" for z.ai)

This ensures:
- Badge shows the 5-hour window as requested
- z.ai correctly calculates monthly limits (resets on 1st of month)
- Hover tooltip shows all usage endpoints with clear labels
- Usage badge displays for API profiles (z.ai, ZHIPU)

All 1855 tests passing (0 regressions)

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: Make usage badge show regardless of proactive swap settings

The usage monitor now always starts and fetches usage data for the badge,
even when proactive swap is disabled. Proactive swapping only occurs when
explicitly enabled in settings.

Changes:
- Remove proactive swap check from start() method
- Move proactive swap check into checkUsageAndSwap() before swapping logic
- Always emit usage-updated events for UI badge
- Only perform threshold checks and swaps when proactive swap enabled
- Auth failure swaps also respect proactive swap setting

This ensures the usage badge is always visible when usage data is available,
while respecting user preferences for automatic account switching.

Fixes QA issue: "The badge is not showing on the topbar next to the provider badge"

QA Fix Session: 1

* fix: Always show usage badge regardless of endpoint availability

Fixes QA issue: \"the usage badge is still not showing\"

Problem:
The UsageIndicator component would hide completely when usage data was
unavailable (e.g., when z.ai or ZHIPU usage endpoints return errors or
are unsupported). This left users with no indication that usage monitoring
was active.

Solution:
Modified UsageIndicator to always display, showing three states:
1. Loading state (\"...\") - while fetching initial data
2. Unavailable state (\"N/A\") - when endpoint doesn't return data
3. Usage percentage - when data is available

This ensures users can always see that usage monitoring is active and
which profile is being used, with clear feedback when usage data is
unavailable for certain providers.

Changes:
- Added isLoading state to show loading indicator on mount
- Added isAvailable state to track if usage data is available
- Render loading state with animated pulse icon
- Render unavailable state with tooltip explanation
- Only hide badge if both loading is done AND no data available

All tests pass (1855 passed, 6 skipped).

QA Fix Session: 1

* fix: Correct z.ai and ZHIPU usage endpoint implementation

Fixes QA issue where z.ai provider was not being detected correctly
and showed "N/A usage data is unavailable".

Changes:
1. Add required query parameters (startTime, endTime) to z.ai and ZHIPU endpoints
   - Time window: from yesterday at current hour to today at current hour end
   - Matches reference implementation from z.ai usage script

2. Fix authentication header for z.ai and ZHIPU providers
   - Anthropic: Uses "Bearer ${token}" format
   - z.ai/ZHIPU: Use token directly (no "Bearer" prefix)
   - Matches reference implementation from z.ai usage script

3. Extract data wrapper from z.ai and ZHIPU responses
   - These providers wrap usage data in a "data" field
   - Extract data field before normalization
   - Matches reference implementation from z.ai usage script

4. Update tests to expect query parameters in endpoints
   - Tests now verify presence of startTime and endTime parameters
   - All 73 tests passing

Verified:
- All unit tests pass (73/73)
- Provider detection works correctly for all providers
- Endpoint construction includes required query parameters
- Response parsing extracts data wrapper correctly
- Authentication uses correct format per provider

QA Fix Session: 1

* fix: Correct usage monitor auth detection for API profiles vs OAuth

The usage monitor was not correctly detecting whether an API profile or
OAuth profile was active, causing it to always show OAuth usage information
even when an API profile was active.

Changes:
- Modified checkUsageAndSwap() to first check if an API profile is active
  (by checking profilesFile.activeProfileId)
- Only fall back to OAuth profiles if no API profile is active
- Updated fetchUsage() to check both API and OAuth profile sources
- Made proactive swap only work for OAuth profiles (not API profiles)

This ensures that when an API profile is active, the usage monitor fetches
usage from the correct provider endpoint and displays the API profile's
usage information instead of OAuth information.

Fixes QA feedback: "The usage is not detecting that the active auth is
not oauth but api profile and is showing the oauth information when it
should be showing the active profiles information."

Co-Authored-By: Claude <noreply@anthropic.com>

* fix: Correct z.ai and ZHIPU usage endpoint implementation

Fixes from QA feedback:
- Query quota/limit endpoint instead of model-usage endpoint
- Parse limits array to extract TOKENS_LIMIT and TIME_LIMIT data
- Map TOKENS_LIMIT to session usage (5-hour window)
- Map TIME_LIMIT to monthly usage (displayed as weekly in UI)
- Ensure stats update every 30 seconds for accurate tracking

The reference implementation shows that z.ai and ZHIPU providers
require querying the /api/monitor/usage/quota/limit endpoint which
returns a limits array with type and percentage fields.

Co-Authored-By: Claude <noreply@anthropic.com>

* docs: Update implementation plan with QA fix session 1

* fix: Update z.ai and ZHIPU usage labels and reset times

- Change session window label from '5-hour window' to '5 Hours Quota'
- Change weekly window label from 'Calendar month' to 'Total Monthly Tools Quota'
- Calculate and display actual 5-hour window reset time (e.g., 'Resets in 1h 4m')
- Display monthly reset as '1st of <Month>' format

Fixes QA feedback for usage display clarity.

QA Fix Session: 2

* docs: Update implementation plan with QA fix session 2

* fix: Address QA feedback for usage monitoring UI

Fixes:
1. Removed 'Usage' word from usage labels in tooltip
   - Changed '{sessionLabel} Usage' to '{sessionLabel}'
   - Changed '{weeklyLabel} Usage' to '{weeklyLabel}'

2. Verified Anthropic usage endpoints via WebSearch research
   - Confirmed OAuth endpoint: /api/oauth/usage is correct
   - Documented that Anthropic Claude usage does not have separate tools usage endpoint (unlike z.ai)
   - Anthropic returns overall utilization percentages only

3. Added usage warning badge (>90%) to AuthStatusIndicator
   - Badge appears to left of provider badge when usage >= 90%
   - Shows higher of session/weekly usage percentage
   - Includes countdown timer showing reset time for the window with higher usage
   - Tooltip displays usage alert, percentage, and reset countdown
   - Badge uses red color scheme with animated alert icon

Also fixed TypeScript compilation errors in usage-monitor.ts:
- Moved variable declarations outside try block for catch block accessibility
- Added null checks before using profileId and profileName

QA Fix Session: 3

* fix: Address QA feedback for usage monitoring UI

Fixes:
- Remove percentage display from usage warning badge (only show icon)
- Move countdown timer from tooltip to visible badge positioned right of provider badge

Changes:
- Usage warning badge now only displays AlertTriangle icon without percentage text
- Percentage value moved to tooltip content for the warning badge
- Countdown timer now displays as a visible blue badge showing reset time
- Countdown timer positioned to the right of provider badge
- Countdown timer shows whenever usage data is available, not just during warnings

Verified:
- No TypeScript errors introduced in modified file
- Layout follows flex order: [Warning Badge] [Provider Badge] [Countdown Timer]

QA Fix Session: 3

* docs: Update implementation plan with QA fix session 3

- Fix session 3 completed
- Issues fixed: Additional percentage removal and countdown timer repositioning
- Ready for QA re-validation

* fix: Address QA feedback for usage monitoring UI

Fixes:
1. Remove duplicate 'Resets:' word in tooltips - Changed from "Resets: Resets in Xh Ym" to just "Resets in Xh Ym"
2. Replace countdown timer badge with 5 hour usage badge - Badge between provider and usage percentage now shows 5 hour usage percentage
3. Show 5 hour usage badge only when >= 90% and in red color - Badge is hidden until threshold is reached
4. Fix time synchronization issue - Store ISO timestamps and calculate relative time dynamically in UI instead of at fetch time

Changes:
- Added sessionResetTimestamp and weeklyResetTimestamp fields to ClaudeUsageSnapshot type
- Updated z.ai and ZHIPU normalization to store ISO timestamps instead of pre-calculated strings
- Updated UsageIndicator and AuthStatusIndicator components to calculate reset time dynamically from timestamps
- Removed countdown timer badge, replaced with 5 hour usage badge that only shows when >= 90%

Verified:
- Build succeeds without errors
- All UI components correctly calculate and display reset times dynamically
- Badge behavior matches QA requirements

QA Fix Session: 4

* docs: Update implementation plan with QA fix session 4

* fix: Correct 5-hour window reset time calculation

Fixed the calculation of sessionResetTimestamp for the 5-hour rolling
window to properly show time remaining until the next 5-hour interval
boundary (0:00, 5:00, 10:00, 15:00, 20:00) instead of just the next hour.

Changes:
- Updated normalizeZAIResponse to calculate reset based on 5-hour intervals
- Updated normalizeZhipuResponse to calculate reset based on 5-hour intervals
- Reset time now correctly shows time remaining in the current window

The >=90% badge is confirmed to be based on actual usage percentage
(tokensLimit.percentage) from the API, not time-based calculation.

Fixes QA feedback: "the usage badge tooltip is showing the remain time
for the 5 hour window incorrectly. It should show remaining time left
in the 5 hour window"

QA Fix Session: 5

* docs: Update implementation plan with QA fix session 5

* fix: Correct 5-hour rolling window reset time calculation

The previous implementation incorrectly calculated the reset time based on
fixed 5-hour interval marks (0:00, 5:00, 10:00, 15:00, 20:00) instead of
using a true rolling 5-hour window that resets exactly 5 hours from the
current time.

This matches the z.ai/ZHIPU provider behavior where the 5-hour window is
a sliding window, not fixed interval resets.

Changes:
- Updated normalizeZAIResponse to calculate reset as now + 5 hours
- Updated normalizeZhipuResponse to calculate reset as now + 5 hours
- Removed complex logic for finding next 5-hour interval mark

Example: At 23:51, the tooltip now correctly shows "Resets in 5h" instead
of "Resets in ~3h" (until the next 0:00, 5:00, 10:00, etc. mark).

Fixes: Incorrect time remaining display in usage tooltip

* test: Fix TypeScript errors in usage-monitor.test.ts

Fixed TypeScript compilation errors in the usage monitor test file:

1. Response mock type fixes:
   - Changed all 'as Response' casts to 'as unknown as Response'
   - Mock objects don't satisfy the full Response interface
   - Required 8 replacements across the file

2. mockLoadProfilesFile type fixes:
   - Added explicit type for profiles array to prevent 'never[]' inference
   - Added 'string | null' type annotation for activeProfileId

The TypeScript compilation now passes successfully. Remaining test
failures are pre-existing issues unrelated to these type fixes.

* fix: Use nextResetTime from z.ai/ZHIPU API for accurate reset time calculation

The quota/limit API response now includes nextResetTime as a Unix timestamp
(milliseconds) for TOKENS_LIMIT, which provides the exact reset time for the
5-hour quota window.

Changes:
- Extract nextResetTime from tokensLimit in normalizeZAIResponse
- Extract nextResetTime from tokensLimit in normalizeZhipuResponse
- Fall back to "now + 5 hours" if nextResetTime is not available
- Enhanced debug logging to show all API fields for future debugging

Verified via live API test:
- API returns nextResetTime: 1768708657242
- Correctly shows "Resets in 3h 43m" instead of incorrect "Resets in 5h"

This matches the z.ai provider's actual quota window timing and ensures
the tooltip displays accurate time remaining for the 5-hour quota.

Note: The tool-usage and model-usage endpoints provide time-series analytics
but are not needed for the tooltip display. The quota/limit endpoint provides
all necessary information (TOKENS_LIMIT + TIME_LIMIT).

* feat: Add raw usage values (xxx/xxxx format) to usage tooltip

Adds display of raw usage values in "current/total" format for both
token and tool usage in the usage indicator tooltip.

Changes:
- Added new optional fields to ClaudeUsageSnapshot type:
  - sessionUsageValue, sessionUsageLimit (tokens)
  - weeklyUsageValue, weeklyUsageLimit (tools)
- Updated normalizeZAIResponse to extract currentValue and usage from
  TOKENS_LIMIT and TIME_LIMIT in quota/limit API response
- Updated normalizeZhipuResponse with same extraction logic
- Updated UsageIndicator tooltip to display "xxx/xxxx" format alongside
  percentage, using toLocaleString() for number formatting
- Added comprehensive tests for quota/limit endpoint normalization:
  - z.ai quota/limit endpoint normalization tests
  - ZHIPU quota/limit endpoint normalization tests
  - Tests for missing nextResetTime, currentValue, usage fields

Example tooltip display:
- Session: "20,926,987/200,000,000 10%"
- Tools: "660/1,000 66%"

The raw values are only shown when both currentValue and usage are
available in the API response, providing users with more detailed
usage information.

* refactor: Format usage values with units (K, M, B) and move below progress bar

Changes:
- Added formatUsageValue function to format large numbers with units:
  - Values >= 1B: Show as "X.XX B" (e.g., "1.50 B")
  - Values >= 1M: Show as "X.XX M" (e.g., "27.76 M")
  - Values >= 1K: Show as "X.X K" (e.g., "500.5 K")
  - Values < 1K: Show as-is (e.g., "660")
- Moved raw usage values display from beside the percentage to below the progress bar
- Updated both Session (5-hour quota) and Weekly (monthly tools) sections

Before: "27,761,582/200,000,000" shown next to "10%"
After: "27.76 M / 200 M" shown below the progress bar

This makes the tooltip cleaner and the large numbers more readable.

* refactor: Rename 'Total Monthly Tools Quota' to 'Monthly Tools Quota'

Simplify the weekly window label in the usage tooltip from
'Total Monthly Tools Quota' to 'Monthly Tools Quota' for brevity.

- Updated normalizeZAIResponse weeklyWindowLabel
- Updated normalizeZhipuResponse weeklyWindowLabel
- Updated corresponding test assertions

* feat: Enhance provider tooltip with account information

Added detailed account-related information to the provider badge tooltip
for API profiles:

- Profile name (moved to dedicated row)
- Profile ID (truncated to 8 characters for readability)
- Creation date (formatted as locale date)
- API Endpoint URL (full baseUrl displayed in monospace font)
- Provider website link with external link icon

The tooltip now shows:
Authentication: API Profile
Provider: z.ai
─────────────────────────────
Profile: My z.ai Account
ID: a1b2c3d4
Created: 1/15/2026
API Endpoint
https://api.z.ai/api/anthropic
Visit z.ai ↗

This provides users with quick access to account details and provider
resources directly from the header.

* refactor: Simplify provider tooltip - remove visit link and created date

Simplified the provider badge tooltip by removing:
- Visit provider website link with external icon
- Profile creation date

The tooltip now shows a cleaner, more focused display:
- Authentication type (OAuth / API Profile)
- Provider name
- Profile name and ID (truncated)
- API Endpoint URL

Removed unused helper functions:
- formatDate()
- providerWebsites constant
- getProviderWebsite()

* fix: Add i18n translations and fix usage monitor tests

- Add i18n translation keys for all hardcoded UI strings in UsageIndicator and AuthStatusIndicator
- Fix usage-monitor tests to match quota/limit endpoint format
- Update getUsageEndpoint tests to expect quota/limit endpoint
- Update z.ai/ZHIPU normalization tests to use limits array format
- Add window.electronAPI mocks for usage functions in AuthStatusIndicator tests

* fix: Remove node_modules from version control

- Remove tracked node_modules symlinks from git index
- These should not be committed as they are in .gitignore

* fix: Add i18n support and error handling for usage indicators

- Add 'usage' namespace to useTranslation hooks
- Replace hardcoded "N/A" with i18n key (usage:notAvailable)
- Replace hardcoded aria-label with i18n key (usage:usageStatusAriaLabel)
- Replace hardcoded fallback labels (Session/Weekly) with i18n keys
- Replace hardcoded "Resets in" strings with i18n keys (resetsInHours/resetsInDays)
- Add error handling for requestUsageUpdate promises in both components
- Add corresponding translation keys to en/common.json and fr/common.json

* fix: Address remaining coderabbitai feedback

- Fix formatResetTime to handle invalid and past timestamps:
  - Return 'Unknown' for invalid dates (NaN)
  - Return 'Expired' for past dates
  - Update tests to match new behavior

- Fix resetTime fallback when formatResetTime returns undefined:
  - Use nullish-coalescing to preserve fallback values

- Reorganize misplaced test case:
  - Move Anthropic subdomain test to correct block

- Update AuthStatusIndicator.tsx:
  - Add 'usage' namespace to useTranslation
  - Add error handling for requestUsageUpdate promise

- Update UsageIndicator.tsx:
  - Add 'usage' namespace to useTranslation
  - Add error handling for requestUsageUpdate promise
  - Fix sessionResetTime and weeklyResetTime fallback

* fix: Refactor usage-monitor to use shared utilities and fix auth error handling

- Fix HIGH severity auth error handling bug:
  - Narrow try-catch scope to only wrap response.json()
  - Auth errors are now properly propagated for proactive account swapping

- Remove duplicate provider detection code:
  - Import detectProvider and ApiProvider from shared/utils/provider-detection.ts
  - Simplify local detectProvider to thin wrapper with debug logging
  - Remove duplicate PROVIDER_PATTERNS and ProviderPattern interface
  - Remove duplicate provider detection tests (covered by shared test suite)

- Fix hardcoded month names:
  - Replace hardcoded monthNames array with Intl.DateTimeFormat API
  - Uses locale-aware formatting (defaults to English)

Total: ~120 lines of duplicate code removed

* refactor: Consolidate duplicate normalization functions

- Consolidate normalizeZAIResponse and normalizeZhipuResponse into shared
  normalizeQuotaLimitResponse function with providerName parameter
- Both functions now delegate to shared implementation
- Removes ~230 lines of duplicate code

Total improvement: ~350 lines of duplicate code removed across all commits

* refactor: Extract formatResetTime to shared utility and localize provider names

- Extract formatResetTime to shared utility (src/shared/utils/format-time.ts):
  - Add formatTimeRemaining() for renderer process with i18n support
  - Add formatTimeRemainingSimple() for main process (no i18n)
  - Simplify usage-monitor.ts to use formatTimeRemainingSimple wrapper

- Update UI components to use shared formatTimeRemaining utility:
  - Remove duplicate formatResetTime implementations
  - Both components now call shared formatTimeRemaining()

- Localize provider names in AuthStatusIndicator:
  - Add translation keys for provider labels (providerAnthropic, providerZai, providerZhipu)
  - Add authenticationAriaLabel translation key with interpolation
  - Update aria-label to use localized provider name via getLocalizedProviderLabel()
  - Update visible provider label to use i18n

- Add i18n translations to en/common.json and fr/common.json

Total: 1 new shared utility, ~50 lines of duplicate code removed

* test: Fix AuthStatusIndicator test with proper i18n mocking and add format-time utility

- Mock useTranslation hook directly instead of using I18nextProvider
- Add AlertTriangle icon import to fix TypeScript error
- Fix variable shadowing issue in translation mock
- Add shared format-time.ts utility for time formatting

* test: Remove unused variable callCountAfterStart

* fix: Address coderabbitai feedback - remove unused mock, fix type safety, add date validation

- Remove unused Translation mock from AuthStatusIndicator tests
- Fix getLocalizedProviderLabel with type-safe PROVIDER_TRANSLATION_KEYS mapping
- Add fallback to getProviderLabel for unknown providers
- Add invalid date check (isNaN) to formatTimeRemaining for consistency
- Add providerUnknown translation key to en/fr locales

* test: Fix remaining coderabbitai feedback in usage-monitor tests

- Remove unused variable weeklyReset
- Replace fragile literal assertions with behavior-oriented checks
- Strengthen getCurrentUsage test with explicit type and property checks

* fix: Use correct namespace for reset-time translation keys

- Update formatTimeRemaining defaults to use 'common:usage.resetsInHours' and 'common:usage.resetsInDays'
- Update JSDoc examples to reflect correct namespace
- Keys are in common.json under usage section, not in separate usage namespace

* fix: CRITICAL - Add missing Bearer prefix for z.ai/ZHIPU API authentication

This fixes a critical bug where z.ai and ZHIPU usage monitoring requests
were failing with 401 Unauthorized due to missing 'Bearer ' prefix
in the Authorization header.

Root cause: Incorrect assumption in code comment that z.ai/ZHIPU use
raw tokens instead of Bearer authentication. All providers (Anthropic,
z.ai, ZHIPU) use standard Bearer token authentication per RFC 6750.

The conditional logic that omitted 'Bearer ' for non-Anthropic providers
has been removed. All providers now use consistent 'Bearer ${credential}'
format.

This fix restores usage monitoring functionality for users with z.ai or
ZHIPU API profiles.

Reported by: @sentry (AI agent)
Severity: CRITICAL

* refactor: Address remaining coderabbitai feedback

Test improvements:
- Replace brittle literal assertion with type checks for sessionResetTime (line 339)

Code cleanup:
- Remove unused normalizeGenericProviderResponse and helper methods (~248 lines)
- Functions were dead code since normalizeZAIResponse and normalizeZhipuResponse
  use normalizeQuotaLimitResponse instead

Documentation:
- Add JSDoc notes to formatTimeRemainingSimple about hardcoded English sentinel values
- Document ClaudeUsageSnapshot sessionResetTime/weeklyResetTime localization requirements
- Note that renderer should use sessionResetTimestamp with formatTimeRemaining() for i18n

* fix: Address remaining coderabbitai feedback

i18n fixes:
- Remove hardcoded "Claude" from usageStatusAriaLabel in en/fr locales
- Change to provider-agnostic "Usage status" / "Statut d'utilisation"
- Visible provider name already shown in badge text, aria-label doesn't need to repeat it

Bug fix:
- Guard isAPIProfile on apiKey presence to prevent OAuth swap suppression
- If activeAPIProfile exists but lacks apiKey, fall back to OAuth instead
- Added debug logging for this fallback scenario

Test improvement:
- Make getCurrentUsage test deterministic by seeding state
- No longer relies on singleton state from previous tests

* fix: Correct i18n namespace for usage translations

Fixed tooltip texts not displaying correctly by updating the i18n
namespace from 'usage:' to 'common:usage.' in components and tests.

Changes:
- UsageIndicator.tsx: Updated all usage translation keys to use
  'common:usage.xxx' namespace
- AuthStatusIndicator.tsx: Updated PROVIDER_TRANSLATION_KEYS and
  all translation calls to use 'common:usage.xxx' namespace
- AuthStatusIndicator.test.tsx: Updated translation mock to use
  new namespace format

The 'usage' translations are defined in common.json under the
'usage' key, not in a separate usage.json namespace file.

* fix: Address coderabbitai feedback

- Use providerUnknown translation key instead of skipping it and
  falling back to English getProviderLabel
- Replace hardcoded K/M/B suffixes with locale-aware Intl.NumberFormat
  using notation: "compact" and compactDisplay: "short"
- Add safe fallback to toString() if Intl is unavailable

* refactor: Extract OAUTH_FALLBACK constant to eliminate duplication

* refactor: Improve promise chain and type safety

- Use .finally() to consolidate loading-state teardown, removing
  duplicated setIsLoadingUsage(false) calls
- Add error logging in .catch() for better diagnostics
- Change getLocalizedProviderLabel to accept ApiProvider instead
  of string to avoid unsafe cast

* fix: Don't show stale reset time placeholder after window resets

The usage tooltip was incorrectly showing "Resets in ..." after the 5-hour
window had already reset. This happened because:

1. When the window resets, sessionResetTimestamp becomes a timestamp in the past
2. formatTimeRemaining() correctly returns undefined for past dates
3. But the code fell back to usage?.sessionResetTime, which contains the
   placeholder "Resets in ..." from the backend

Fix: Remove the fallback to sessionResetTime/weeklyResetTime when
formatTimeRemaining returns undefined. This prevents displaying stale
placeholder text after the window has reset.

* fix: Add timestamp fields to Anthropic OAuth usage response

The normalizeAnthropicResponse function was missing the
sessionResetTimestamp and weeklyResetTimestamp fields that the
frontend uses for dynamic countdown calculation.

This caused OAuth accounts to not display the "Resets in Xh Ym"
countdown in the usage tooltip, while API profile accounts (z.ai,
ZHIPU) worked correctly.

The fix adds the raw ISO timestamps from the API response to the
ClaudeUsageSnapshot, enabling formatTimeRemaining() to work for
OAuth accounts.

* test: Add assertions for timestamp fields in Anthropic normalization

Add test assertions for sessionResetTimestamp and weeklyResetTimestamp
in the normalizeAnthropicResponse tests. This ensures the raw ISO
timestamps are properly passed through from the API response to the
frontend for dynamic countdown calculation.

* refactor: Address coderabbitai feedback

- Fix duplicate getLocalizedProviderLabel calls in AuthStatusIndicator
- Localize backend-provided usage window labels (5-hour window, 7-day window,
  5 Hours Quota, Monthly Tools Quota) with translation keys
- Add English and French translations for usage window labels
- Create localizeUsageWindowLabel helper function to map backend labels
  to i18n translation keys

* fix: Address CI typecheck and timezone issues

- Restore truncated translation files (JSON syntax was valid but content was
  accidentally deleted during earlier edit)
- Add usage window label translation keys for i18n (window5Hour, window7Day,
  window5HoursQuota, windowMonthlyToolsQuota)
- Fix timezone bug in monthly reset calculation: use UTC methods
  (setUTCMonth, setUTCHours) instead of local timezone methods to ensure
  consistent UTC timestamps regardless of user's local timezone

* fix: Close usage section in translation files before oauth section

Fixes JSON syntax issue where the usage section was missing its closing
brace before the oauth section began.

* docs: map existing codebase

- STACK.md - Technologies and dependencies
- ARCHITECTURE.md - System design and patterns
- STRUCTURE.md - Directory layout
- CONVENTIONS.md - Code style and patterns
- TESTING.md - Test structure
- INTEGRATIONS.md - External services
- CONCERNS.md - Technical debt and issues

* docs: initialize project

PR Review System Robustness - improvements to make PR reviews trustworthy enough to replace human review

* chore: add project config

Mode: yolo
Depth: comprehensive
Parallelization: enabled

* fix: Address PR review feedback - code quality improvements

Fixes all 7 issues from PR review:

HIGH:
- useApiMethod flag now uses per-profile tracking (Map<profileId, boolean>)
  instead of a single global flag, allowing API retry for different profiles

MEDIUM:
- Added default values (95/99) for undefined threshold settings
- Fixed stale placeholder text by checking for "..." in fallback values
- Extracted duplicated localizeUsageWindowLabel to shared format-time utility
- Refactored checkUsageAndSwap method into smaller helper methods:
  * determineActiveProfile() - Detects API vs OAuth profile
  * checkThresholdsExceeded() - Evaluates usage against thresholds
  * handleAuthFailure() - Manages auth failure recovery

LOW:
- Added error logging in UsageIndicator catch block
- Fixed variable shadowing in forEach callback (failedProfileId)

* fix: Address CodeRabbitAI actionable comments for i18n compliance

Fixes all actionable comments from CodeRabbitAI review:

1. localizeUsageWindowLabel now returns localized fallback (t(defaultKey))
   instead of raw backend text for unknown labels

2. Added nullish coalescing (??) in UsageIndicator and AuthStatusIndicator
   to preserve fallback when formatTimeRemaining returns undefined

3. Weekly label now uses weekly-specific default key
   ('common:usage.weeklyDefault') instead of session default

4. Removed hardcoded English strings from main process:
   - Omitted sessionResetTime/weeklyResetTime fields (set to undefined)
   - Removed formatResetTime() method that returned 'Unknown'/'Expired'
   - Removed import of formatTimeRemainingSimple
   - Removed 'Resets in ...' placeholder
   - Removed '1st of {month}' hardcoded monthly reset format
   - Renderer now uses timestamps with formatTimeRemaining() for i18n

5. Updated tests to reflect undefined reset times and verify timestamps
   are still provided for renderer localization

* feat: Enhance usage and provider tooltips with improved visual design

- UsageIndicator: Add header with icon, gradient progress bars with shine effect, icons for each section (Clock, TrendingUp, Info, User), improved spacing and layout
- AuthStatusIndicator: Add header with Shield icon, profile details with Fingerprint/Key icons, styled monospace ID badge, bordered code block for API endpoint
- Add i18n keys: usageBreakdown, used, authenticationDetails, created (en + fr)
- Remove Calendar import after removing created date display

* fix: Handle null values in formatUsageValue for robustness

Change from strict equality (=== undefined) to loose equality (== null)
to catch both null and undefined values from API responses.
This prevents 'null' string being displayed when backend sends null.

* fix: Localize loading state in UsageIndicator

Replace hardcoded "..." with localized t('common:usage.loading') key.
Add "loading": "Loading..." (en) and "Chargement..." (fr) to usage section.

* fix: Accessibility and i18n improvements for UsageIndicator

- Use motion-safe:animate-pulse to respect prefers-reduced-motion
- Filter out hardcoded English 'Unknown' and 'Expired' strings from main process
- Add hasHardcodedText helper to check for placeholder/sentinel values

* fix: Prevent incomplete UI display when API returns null values

Change conditional checks from !== undefined to != null to catch both
null and undefined values. This prevents broken UI display like " / 5000"
or "1000 / " when formatUsageValue returns undefined for null inputs.

* refactor: Code quality improvements - shared helpers and better defensive coding

QUAL-002: Extract hasHardcodedText to shared utility (format-time.ts)
- Export hasHardcodedText function for consistent sentinel value filtering
- Update both UsageIndicator and AuthStatusIndicator to use shared helper
- Add JSDoc documentation with examples

QUAL-003: Use nullish coalescing in usage-monitor.ts
- Change || 0 to ?? 0 for utilization value defaults
- Only defaults for null/undefined, not other falsy values

QUAL-001: Document formatUsageValue behavior
- Add comprehensive JSDoc explaining undefined return behavior
- Document that caller is responsible for null checking (which they do)
- Include usage examples

* hotfix(build): disable npmRebuild for electron-builder workspace compatibility

electron-builder's @electron/rebuild cannot properly handle symlinked
node_modules directories in npm workspace setups. It fails with:
ENOENT: no such file or directory, stat 'apps/frontend/node_modules'

Setting npmRebuild: false bypasses this issue because:
1. stageRuntimePackages() already copies @lydell/node-pty to out/main/node_modules
2. @lydell/node-pty uses prebuilt binaries - no rebuild needed
3. This skips the problematic @electron/rebuild phase entirely

Fixes macOS Intel, macOS Silicon, and potentially Windows release builds.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: Implement cooldown-based API retry and motion-safe animations

HIGH: Fix permanent API failure disabling usage monitoring
- Change from boolean flag to timestamp-based cooldown mechanism
- Replace useApiMethodForProfile Map with apiFailureTimestamps
- API failures now record timestamp and retry after 2 minute cooldown
- Update shouldUseApiMethod to check cooldown expiration

TRIVIAL: Respect prefers-reduced-motion for accessibility
- Change animate-pulse to motion-safe:animate-pulse in AuthStatusIndicator warning
- Change animate-pulse to motion-safe:animate-pulse in UsageIndicator loading state

* fix(ci): handle npm workspaces partial node_modules blocking symlink

npm workspaces may create a partial node_modules directory in
apps/frontend for packages that couldn't be hoisted. This blocked
the symlink creation because the condition checked if the directory
existed before creating the symlink.

Changes:
- Remove any existing partial node_modules directory (not symlink)
- Only then create the symlink to root node_modules
- Add verification that symlink resolves correctly
- Add detailed logging for debugging

This fixes macOS release builds failing with ENOENT during
@electron/osx-sign code signing phase.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(ci): remove broken symlinks before creating node_modules link

The previous fix only removed partial directories but not broken symlinks.
CI logs showed that an existing broken symlink pointing to
"../../../../../../apps/frontend/node_modules" was skipped, causing
electron-builder to fail with ENOENT during macOS code signing.

Changes:
- Check if existing symlink points to correct target (../../node_modules)
- Remove incorrect or broken symlinks before creating new one
- Add strict verification that symlink exists AND resolves correctly
- Fail fast with clear error if verification fails

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(ci): remove broken symlinks before creating node_modules link

The previous fix only removed partial directories but not broken symlinks.
CI logs showed that an existing broken symlink pointing to
"../../../../../../apps/frontend/node_modules" was skipped, causing
electron-builder to fail with ENOENT during macOS code signing.

Changes:
- Check if existing symlink points to correct target (../../node_modules)
- Remove incorrect or broken symlinks before creating new one
- Add strict verification that symlink exists AND resolves correctly
- Fail fast with clear error if verification fails

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(ci): handle Windows junction verification correctly

Windows junctions don't appear as symlinks to bash's -L test, causing
the verification step to fail even when the junction was created
successfully.

Changes:
- Skip symlink check (-L) on Windows since junctions are different
- Verify link works by checking electron package is accessible
- Add more diagnostic output on failure

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(ci): use absolute path for Windows junction target

Windows mklink /J resolves relative paths from CWD, not from the
junction's location. This caused the junction to point to the wrong
directory (D:\a\node_modules instead of D:\a\Auto-Claude\Auto-Claude\node_modules).

Fix: Use pwd -W to get the Windows-style absolute path for the target.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(ci): use cygpath for proper Windows junction path format

pwd -W output was being mangled when passed to cmd.exe, resulting in
paths like \D:/a/... instead of D:\a\...

Use cygpath -w which properly converts to Windows path format with
backslashes.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(ci): use PowerShell for Windows junction creation

cmd.exe's mklink was creating junctions with malformed paths (leading
backslash before drive letter). PowerShell's New-Item -ItemType Junction
handles Windows paths more reliably.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(ci): fix yq command multiline parsing in merge-macos-manifests

The multiline yq expression was being incorrectly parsed by the shell,
causing 'invalid input text' error. Put the expression on a single line.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(ci): use heredoc for yq expression to avoid shell escaping

The yq expression with special characters (brackets, braces, pipes) was
being mangled by shell expansion. Write it to a file using heredoc with
quoted delimiter to prevent any interpretation.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(ci): use two-step yq approach for manifest merging

The 'add' function doesn't exist in yq v4, causing parse errors.
Use a two-step approach that was tested locally:
1. Collect all files with '[.files] | flatten'
2. Load merged files into first manifest with 'load()'

Tested locally with yq v4.50.1

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: Prevent race condition in profile detection during usage fetch

MEDIUM: Fix potential credential/basUrl mismatch from profile changes

The active profile is now determined once in checkUsageAndSwap and passed
down through fetchUsage to fetchUsageViaAPI. This prevents race conditions
where the profile could change between determineActiveProfile() and the
later getAPIProfile() call in fetchUsageViaAPI.

Changes:
- Add activeProfile parameter to fetchUsage() and fetchUsageViaAPI()
- Pass pre-determined activeProfile from checkUsageAndSwap()
- Use passed profile info in fetchUsageViaAPI when available
- Fallback to getAPIProfile() for backward compatibility

* test: Add tests for cooldown retry and race condition fixes

- Add cooldown-based API retry tests:
  - Record API failure timestamp on error
  - Allow API retry after cooldown expires (2 minutes)
  - Prevent API retry during cooldown period
  - Allow API call when no previous failure recorded
  - Handle edge case exactly at cooldown boundary
  - Track failures independently for different profiles

- Add race condition prevention tests:
  - Use passed activeProfile instead of re-detecting
  - Fall back to profile detection when activeProfile not provided
  - Handle OAuth profile in activeProfile parameter

- Add shared utility hasHardcodedText tests:
  - Return true for empty string, null, undefined
  - Return true for 'Unknown' and 'Expired'
  - Return false for valid time strings
  - Case-sensitive filtering
  - Handle whitespace-only strings

- Fix 'should handle unknown provider gracefully' test to pass activeProfile parameter
  so it correctly tests unknown provider path instead of OAuth fallback path

* fix: Address CodeRabbitAI actionable comments

1. Remove unused getAPIProfile() method (dead code)
   - The method was defined but never called
   - fetchUsageViaAPI() calls loadProfilesFile() directly instead
   - No other references to getAPIProfile exist in the codebase

2. Fix hardcoded English strings in usageWindows (i18n violation)
   - Changed normalizeAnthropicResponse to use 'common:usage.window5Hour' and 'common:usage.window7Day'
   - Changed normalizeQuotaLimitResponse to use 'common:usage.window5HoursQuota' and 'common:usage.windowMonthlyToolsQuota'
   - Updated localizeUsageWindowLabel() to handle translation keys from backend
   - Maintains backward compatibility for legacy hardcoded strings via USAGE_WINDOW_LABEL_MAP
   - Updated test expectations to expect translation keys instead of hardcoded strings

* test: Fix hasHardcodedText import usage

- Changed from require() to ES6 import at top of file
- Removed duplicate require statements from each test
- Import path: ../../shared/utils/format-time

* fix: Address CodeRabbitAI test failures

1. Fix hasHardcodedText to trim whitespace before checking
   - Now treats whitespace-only strings like '   ' as empty
   - Uses text?.trim() before falsy/Unknown/Expired checks

2. Fix shouldUseApiMethod cooldown boundary comparison
   - Changed from > to >= for exact boundary handling
   - Now allows retry when elapsed time >= API_FAILURE_COOLDOWN_MS

3. Fix unknown provider handling in fetchUsageViaAPI
   - Use activeProfile.baseUrl directly when isAPIProfile is true
   - Avoids race condition from re-fetching profiles file
   - Prevents falling through to OAuth path when profile lookup fails

4. Record API failure timestamp on all error paths
   - Added timestamp recording before return null in parse error path
   - Added timestamp recording before return null in non-auth error path
   - Added timestamp recording in catch block for network errors
   - Added timestamp recording for normalization failures

* fix: TypeScript type errors for ActiveProfileResult

- Added baseUrl and credential properties to ActiveProfileResult interface
- Updated determineActiveProfile() to return baseUrl in ActiveProfileResult
- Fixed isAPIProfile reference in debug logging (computed locally)
- Removed credential property from test objects (not required by interface)

* test: Fix console.warn expectation for unknown provider test

- Updated test to match actual console.warn call with two arguments
- First argument is the message string, second is the details object
- Changed from expect.stringContaining to expect.objectContaining for proper matching

* fix: Use profileId parameter instead of activeProfile?.profileId in fallback path

When activeProfile is not provided (falsy), the code was using
activeProfile?.profileId which always evaluates to undefined. The correct
approach is to use the profileId parameter which is available in the
function scope.

This fixes the bug where the fallback profile detection would never find
the correct profile when invoked without an activeProfile parameter.

---------

Co-authored-by: StillKnotKnown <stillknotknown@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Test User <test@example.com>
Co-authored-by: AndyMik90 <andre@mikalsenutvikling.no>
Co-authored-by: Andy <119136210+AndyMik90@users.noreply.github.com>

2026-01-21 20:48:13 +01:00

4.5 KiB

Raw Blame History

Technology Stack

Analysis Date: 2026-01-19

Languages

Primary:

TypeScript 5.9.3 - Electron frontend (desktop UI, IPC handlers, state management)
Python 3.12+ - Backend agents, CLI, integrations, security

Secondary:

JavaScript (ES modules) - Build scripts, configuration
JSON - Configuration, data storage, IPC communication

Runtime

Environment:

Node.js >= 24.0.0 (Electron main/renderer processes)
Python 3.12+ (required for LadybugDB/Graphiti memory system)

Package Manager:

npm 10.0.0+ (root monorepo, frontend)
uv (Python backend - fast pip alternative)
Lockfiles: package-lock.json (present), Python deps in requirements.txt

Frameworks

Core:

Electron 39.2.7 - Cross-platform desktop application shell
React 19.2.3 - UI components and state management
Claude Agent SDK >= 0.1.19 - AI agent orchestration (CRITICAL: NOT raw Anthropic API)

Testing:

Vitest 4.0.16 - Frontend unit tests
Playwright 1.52.0 - E2E testing for Electron
pytest 7.0.0+ - Backend Python tests
pytest-asyncio 0.21.0+ - Async test support

Build/Dev:

electron-vite 5.0.0 - Electron build toolchain
Vite 7.2.7 - Frontend bundler
electron-builder 26.4.0 - Cross-platform packaging (dmg, exe, AppImage, deb, flatpak)

Key Dependencies

Critical (AI/Agent):

claude-agent-sdk >= 0.1.19 - Core AI agent SDK (replaces direct Anthropic API)
@anthropic-ai/sdk 0.71.2 - Anthropic client (used by Graphiti providers)

Infrastructure:

@lydell/node-pty 1.1.0 - Terminal emulation (native module)
@xterm/xterm 6.0.0 - Terminal rendering
electron-updater 6.6.2 - Auto-update mechanism
chokidar 5.0.0 - File system watching
zustand 5.0.9 - React state management

UI Components:

@radix-ui/* - Accessible UI primitives (dialogs, dropdowns, tabs, etc.)
tailwindcss 4.1.17 - Utility-first CSS
lucide-react 0.562.0 - Icons
motion 12.23.26 - Animations

Memory/Database:

real_ladybug >= 0.13.0 - Embedded graph database (Python 3.12+, no Docker)
graphiti-core >= 0.5.0 - Knowledge graph memory layer

Observability:

@sentry/electron 7.5.0 - Error tracking (optional, requires SENTRY_DSN)
electron-log 5.4.3 - Structured logging

Internationalization:

i18next 25.7.3 + react-i18next 16.5.0 - Multi-language support (en, fr)

Configuration

Environment:

Backend: apps/backend/.env (OAuth tokens, integrations, memory config)
Frontend: apps/frontend/.env (debug settings, Sentry DSN)
Example files: .env.example in both directories

Key Backend Env Vars:

CLAUDE_CODE_OAUTH_TOKEN      # Required: OAuth token (or use system keychain)
ANTHROPIC_BASE_URL           # Optional: Custom API endpoint
GRAPHITI_ENABLED             # Required: true to enable memory
GRAPHITI_LLM_PROVIDER        # openai|anthropic|azure_openai|ollama|google|openrouter
GRAPHITI_EMBEDDER_PROVIDER   # openai|voyage|azure_openai|ollama|google|openrouter
LINEAR_API_KEY               # Optional: Linear integration
ELECTRON_MCP_ENABLED         # Optional: E2E testing via Electron MCP

Build:

apps/frontend/electron.vite.config.ts - Electron/Vite build config
apps/frontend/vitest.config.ts - Test configuration
apps/frontend/package.json (build section) - electron-builder config
ruff.toml - Python linting/formatting

Platform Requirements

Development:

macOS, Windows, or Linux
Node.js 24+, Python 3.12+
Git (required for worktree isolation)
Git Bash (Windows only, for Claude Code CLI)

Production:

macOS: DMG/ZIP (arm64 + x64)
Windows: NSIS installer/ZIP
Linux: AppImage, DEB, Flatpak
Bundled Python runtime (downloaded via scripts/download-python.cjs)

CI/CD:

GitHub Actions (.github/workflows/ci.yml)
Matrix testing: Linux, Windows, macOS
Python 3.12 + 3.13 (Linux only)

Monorepo Structure

autonomous-coding/
├── apps/
│   ├── backend/           # Python (uv, requirements.txt)
│   └── frontend/          # Electron/React (npm, package.json)
├── tests/                 # Shared test suite
├── scripts/               # Build/release scripts
└── package.json           # Root workspace config

Workspace Commands:

npm run install:all        # Install both frontend and backend
npm run dev                # Start Electron in dev mode
npm run build              # Build frontend
npm run package            # Package for current platform
npm run test:backend       # Run Python tests

Stack analysis: 2026-01-19

4.5 KiB Raw Blame History