wehub/steipete--codexbar

Fork 0

Files

T

wehub-resource-sync fc4fcbab58 chore: import upstream snapshot with attribution

2026-07-13 12:22:33 +08:00

7.8 KiB

Raw Permalink Blame History

summary, read_when

summary

read_when

Design notes for unified provider session keepalive scheduling and refresh control.

Planning provider session keepalive work

Refactoring Augment keepalive behavior

Designing background session refresh scheduling

Session Keepalive Enhancement Design

Date: 2026-01-04
Feature: Proactive session management for all providers
Inspiration: Quotio's "Auto-Warmup" feature

Problem Statement

Current State:

Augment has reactive keepalive (checks every 5min, refreshes when cookies near expiry)
Other providers (Claude, Codex) have no automatic session management
Users experience auth failures when sessions expire during idle periods
Manual re-authentication is disruptive to workflow

Pain Points:

Session expiration during idle time - User comes back to expired session
No proactive refresh - We only react to expiration, don't prevent it
Provider-specific logic - Each provider needs custom keepalive code
No user control - Can't configure refresh intervals or disable keepalive

Proposed Solution: Unified Session Keepalive System

Alternative Names (Better than "Warmup")

Session Keepalive ✅ (current Augment terminology)
Session Refresh (more accurate - we're refreshing, not warming)
Auto-Refresh (simple, user-friendly)
Session Maintenance (professional, clear intent)
Stay Alive (casual, friendly)

Recommendation: "Session Keepalive" - already used in codebase, technically accurate

Architecture

1. Core Components

`SessionKeepaliveManager` (New)

@MainActor
public final class SessionKeepaliveManager {
    // Unified scheduler for all providers
    private var scheduledTasks: [Provider: Task<Void, Never>] = [:]
    
    // Per-provider configuration
    private var configs: [Provider: KeepaliveConfig] = [:]
    
    // Start keepalive for a provider
    func start(provider: Provider, config: KeepaliveConfig)
    
    // Stop keepalive for a provider
    func stop(provider: Provider)
    
    // Force immediate refresh
    func forceRefresh(provider: Provider) async
}

`KeepaliveConfig` (New)

public struct KeepaliveConfig {
    enum Mode {
        case interval(TimeInterval)  // Every X seconds
        case daily(hour: Int, minute: Int)  // Daily at specific time
        case beforeExpiry(buffer: TimeInterval)  // X seconds before expiry
    }
    
    let mode: Mode
    let enabled: Bool
    let minRefreshInterval: TimeInterval  // Rate limiting
}

2. Provider Integration

Augment (Existing - Refactor)

Current: AugmentSessionKeepalive (standalone actor)
New: Integrate with SessionKeepaliveManager
Strategy: beforeExpiry(buffer: 300) - refresh 5min before cookie expiry
Action: Ping session endpoint + re-import cookies

Claude (New)

Strategy: interval(1800) - refresh every 30 minutes
Action: Run /status command via CLI to keep session alive
Fallback: OAuth token refresh if CLI unavailable

Codex (New)

Strategy: interval(3600) - refresh every hour
Action: OAuth token refresh using refresh token
Benefit: Prevents "session expired" errors during long coding sessions

Cursor, Gemini, etc. (Future)

Strategy: TBD based on provider auth mechanism
Extensible: Protocol-based design allows easy addition

Implementation Plan

Phase 1: Core Infrastructure (Week 1)

Create SessionKeepaliveManager actor
Define KeepaliveConfig model
Add UserDefaults persistence for per-provider configs
Create Settings UI for keepalive configuration

Phase 2: Provider Integration (Week 2)

Augment: Refactor existing AugmentSessionKeepalive to use new manager
Claude: Implement CLI-based keepalive
Codex: Implement OAuth token refresh keepalive

Phase 3: UI & Polish (Week 3)

Settings → Providers → [Provider] → "Session Keepalive" section
Toggle: Enable/Disable
Mode picker: Interval / Daily / Before Expiry
Status indicator: Last refresh time, next scheduled refresh
Manual "Refresh Now" button

Settings UI Design

Settings → Providers → Augment

┌─────────────────────────────────────────┐
│ Session Keepalive                       │
├─────────────────────────────────────────┤
│ ☑ Keep session alive automatically      │
│                                         │
│ Mode: ⦿ Before Expiry                   │
│       ○ Every 30 minutes                │
│       ○ Daily at 9:00 AM                │
│                                         │
│ Last refresh: 2 minutes ago             │
│ Next refresh: in 3 minutes              │
│                                         │
│ [Refresh Now]                           │
└─────────────────────────────────────────┘

Key Differences from Quotio's "Warmup"

Aspect	Quotio Warmup	CodexBar Keepalive
Purpose	Trigger 1-token API calls to reset quota counters	Refresh auth sessions to prevent expiration
Target	Antigravity only (quota reset)	All providers (session management)
Action	Make minimal API request (costs 1 token)	Refresh auth tokens/cookies (free)
Benefit	Faster quota resets during peak hours	Uninterrupted access, no auth failures
Cost	Consumes tokens	No cost (just auth refresh)

Why different?

Quotio has a proxy server that routes requests → warmup keeps quota fresh
CodexBar monitors providers directly → keepalive prevents auth expiration

Benefits

For Users

No more "session expired" errors during active work
Seamless experience - auth just works
Configurable - control refresh frequency per provider
Transparent - see when last refresh happened

For Developers

Unified system - one manager for all providers
Extensible - easy to add new providers
Testable - clear separation of concerns
Maintainable - centralized keepalive logic

Technical Considerations

Rate Limiting

Minimum 2-minute interval between refreshes (prevent API abuse)
Exponential backoff on failures
Max 3 retry attempts before disabling

Error Handling

Log failures but don't crash
Notify user if keepalive fails repeatedly
Automatic disable after 5 consecutive failures

Performance

Background tasks use .utility priority
No blocking of main thread
Minimal memory footprint

Privacy

No data sent to external servers
All refresh actions are local (CLI, OAuth, cookie import)
User can disable entirely

Next Steps

Review this design - Get feedback on architecture
Prototype core manager - Build SessionKeepaliveManager
Integrate Augment - Refactor existing keepalive
Add Claude support - Implement CLI-based refresh
Build Settings UI - Per-provider configuration
Test & iterate - Ensure reliability

Open Questions

Should keepalive be enabled by default?
- Pro: Better UX out of the box
- Con: Users might not want automatic refreshes
- Recommendation: Enabled by default, easy to disable
What's the default refresh interval?
- Augment: 5min before expiry (existing)
- Claude: 30min interval
- Codex: 60min interval
- Recommendation: Conservative defaults, user-configurable
Should we show keepalive status in menu bar?
- Pro: Transparency, user knows it's working
- Con: Clutters UI
- Recommendation: Show in Settings only, not menu bar

7.8 KiB Raw Permalink Blame History