wehub-resource-sync
240 lines
7.8 KiB
Markdown
240 lines
7.8 KiB
Markdown
---
|
|
summary: "Design notes for unified provider session keepalive scheduling and refresh control."
|
|
read_when:
|
|
- 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:**
|
|
1. **Session expiration during idle time** - User comes back to expired session
|
|
2. **No proactive refresh** - We only react to expiration, don't prevent it
|
|
3. **Provider-specific logic** - Each provider needs custom keepalive code
|
|
4. **No user control** - Can't configure refresh intervals or disable keepalive
|
|
|
|
---
|
|
|
|
## Proposed Solution: Unified Session Keepalive System
|
|
|
|
### Alternative Names (Better than "Warmup")
|
|
1. **Session Keepalive** ✅ (current Augment terminology)
|
|
2. **Session Refresh** (more accurate - we're refreshing, not warming)
|
|
3. **Auto-Refresh** (simple, user-friendly)
|
|
4. **Session Maintenance** (professional, clear intent)
|
|
5. **Stay Alive** (casual, friendly)
|
|
|
|
**Recommendation:** **"Session Keepalive"** - already used in codebase, technically accurate
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
### 1. Core Components
|
|
|
|
#### `SessionKeepaliveManager` (New)
|
|
```swift
|
|
@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)
|
|
```swift
|
|
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)
|
|
1. Create `SessionKeepaliveManager` actor
|
|
2. Define `KeepaliveConfig` model
|
|
3. Add UserDefaults persistence for per-provider configs
|
|
4. Create Settings UI for keepalive configuration
|
|
|
|
### Phase 2: Provider Integration (Week 2)
|
|
1. **Augment:** Refactor existing `AugmentSessionKeepalive` to use new manager
|
|
2. **Claude:** Implement CLI-based keepalive
|
|
3. **Codex:** Implement OAuth token refresh keepalive
|
|
|
|
### Phase 3: UI & Polish (Week 3)
|
|
1. Settings → Providers → [Provider] → "Session Keepalive" section
|
|
2. Toggle: Enable/Disable
|
|
3. Mode picker: Interval / Daily / Before Expiry
|
|
4. Status indicator: Last refresh time, next scheduled refresh
|
|
5. 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
|
|
1. **No more "session expired" errors** during active work
|
|
2. **Seamless experience** - auth just works
|
|
3. **Configurable** - control refresh frequency per provider
|
|
4. **Transparent** - see when last refresh happened
|
|
|
|
### For Developers
|
|
1. **Unified system** - one manager for all providers
|
|
2. **Extensible** - easy to add new providers
|
|
3. **Testable** - clear separation of concerns
|
|
4. **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
|
|
|
|
1. **Review this design** - Get feedback on architecture
|
|
2. **Prototype core manager** - Build `SessionKeepaliveManager`
|
|
3. **Integrate Augment** - Refactor existing keepalive
|
|
4. **Add Claude support** - Implement CLI-based refresh
|
|
5. **Build Settings UI** - Per-provider configuration
|
|
6. **Test & iterate** - Ensure reliability
|
|
|
|
---
|
|
|
|
## Open Questions
|
|
|
|
1. **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
|
|
|
|
2. **What's the default refresh interval?**
|
|
- Augment: 5min before expiry (existing)
|
|
- Claude: 30min interval
|
|
- Codex: 60min interval
|
|
- **Recommendation:** Conservative defaults, user-configurable
|
|
|
|
3. **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
|
|
|