adiuva/AI_REFACTOR_PLAN.md

# AI Refactor Plan — Adiuva Electron App

> **Objective:** Transform the Electron app from a single-process AI integration into a local-first multi-agent client with plugin-based batch agents, multi-provider LLM support, E2E encrypted backup, granular permissions, and cloud backend integration.
>
> **Backend:** Lives in a separate repository. See `BACKEND_PLAN.md` for the API contract and backend implementation guide.
>
> **Protocol:** Execute steps sequentially. Each step is atomic and committable. Mark `[x]` when done.

---

## Phase 0 — API Contracts & Types

### Step 0.1 — Define backend API contract types
- [ ] Create `src/shared/api-types.ts` with all interfaces the Electron app needs to communicate with the backend:
  - `ExecutionPlan`, `PlanStep`, `PlanAction` (action types: `create_record`, `update_record`, `delete_record`, `index_document`, `send_notification`)
  - `ChatRequest` (message, context, execution_mode: `'direct'` | `'plan'`)
  - `ChatResponse` (response, actions)
  - `ChatContext` (user_profile, relevant_documents, recent_tasks, conversation_history)
  - `AgentManifest` (name, description, permissions, schedule)
  - `PermissionGrant` (plugin, permission type, resource path, granted_at)
  - `BackupMetadata` (version, timestamp, checksum, chunk_count)
  - `BillingTier` enum (`free`, `pro`, `power`, `team`)
  - `AuthTokens` (access_token, refresh_token, expires_at)
  - `UserProfile` (id, email, tier)
- [ ] Update `tsconfig.json` paths if needed to include `src/shared/`
- **Files:** `src/shared/api-types.ts`, `tsconfig.json`
- **Outcome:** Type-safe contracts for all backend communication. Backend repo mirrors these as Pydantic schemas.

---

## Phase 1 — LiteLLM Multi-Provider Client

### Step 1.1 — Create unified LLM client wrapper
- [ ] Create `src/main/llm/litellm-client.ts`:
  - `LiteLLMClient` class with unified interface:
    - `complete(messages: Message[], options?: CompletionOptions): Promise<CompletionResponse>`
    - `stream(messages: Message[], options?: CompletionOptions): AsyncGenerator<string>`
    - `embed(text: string): Promise<number[]>`
  - `CompletionOptions`: model override, temperature, max_tokens, tools
  - Provider-agnostic: internally maps to the correct provider SDK
  - Fallback chain: tries primary provider, on failure tries secondary, logs each attempt
  - Timeout handling: per-provider configurable timeouts
- [ ] Create `src/main/llm/providers.ts`:
  - `ProviderConfig` interface: name, apiKey, model, endpoint (for Ollama), timeout, isLocal
  - `ProviderRegistry`: manages configured providers, persists to electron-store
  - `getActiveProvider()`, `setActiveProvider(name)`, `addProvider(config)`, `removeProvider(name)`
  - `getFallbackChain(): ProviderConfig[]`
  - Supported providers: OpenAI, Anthropic, Google (Gemini), Mistral, Groq, Ollama (local)
- [ ] Create `src/main/llm/embeddings.ts` (refactored):
  - Support multiple embedding providers (OpenAI text-embedding-3-small, local ONNX with all-MiniLM-L6-v2)
  - Auto-select: use local ONNX if available, fall back to API
  - Same `embedText(text): Promise<number[]>` interface
- **Files:** `src/main/llm/litellm-client.ts`, `src/main/llm/providers.ts`, `src/main/llm/embeddings.ts`
- **Outcome:** Single LLM interface that all local components use. Supports 6+ providers with fallback.

### Step 1.2 — Migrate existing AI code to use new LLM client
- [ ] Update `src/main/ai/orchestrator.ts`:
  - Replace direct `getLLM()` calls with `LiteLLMClient.complete()` / `LiteLLMClient.stream()`
  - Keep local orchestration working with the new client (backend delegation comes in Phase 3)
- [ ] Update `src/main/ai/llm.ts`:
  - Deprecate. Redirect `getLLM()` to instantiate via `LiteLLMClient` as a thin compatibility shim
- [ ] Update `src/main/ai/embeddings.ts` to delegate to `src/main/llm/embeddings.ts`
- [ ] Update `src/main/ai/token.ts`:
  - Add `listStoredProviders(): Promise<string[]>` to enumerate which providers have tokens
- [ ] Ensure all existing AI features (chat, daily brief, tool calling) continue to work
- **Files:** `src/main/ai/orchestrator.ts`, `src/main/ai/llm.ts`, `src/main/ai/embeddings.ts`, `src/main/ai/token.ts`
- **Outcome:** Existing AI features work identically but go through the new unified LLM client.

---

## Phase 2 — Local Plugin System & Batch Agents

### Step 2.1 — Create plugin manifest system and permission manager
- [ ] Create `src/main/permissions/manifest-validator.ts`:
  - `PluginManifest` interface: `name`, `description`, `version`, `permissions: PermissionRequest[]`, `schedule?: string` (cron), `entryPoint: string`
  - `PermissionRequest`: `type` (read_folder, read_email, read_calendar, read_browser_history), `resource?: string` (path, account), `reason: string`
  - `validateManifest(manifest): ValidationResult` — validates structure, checks for dangerous permissions
- [ ] Create `src/main/permissions/permission-manager.ts`:
  - `PermissionManager` class (singleton):
    - `grantPermission(pluginName, permission): void` — persists to SQLite
    - `revokePermission(pluginName, permission): void`
    - `checkPermission(pluginName, permission): boolean`
    - `getPluginPermissions(pluginName): PermissionGrant[]`
    - `getAllGrants(): PermissionGrant[]`
    - `logAccess(pluginName, permission, resource, timestamp): void` — activity log
    - `getActivityLog(pluginName?, limit?): ActivityLogEntry[]`
  - Permission grants stored in a new `plugin_permissions` SQLite table
  - Activity log stored in a new `plugin_activity_log` SQLite table
- [ ] Add `plugin_permissions` and `plugin_activity_log` tables to `src/main/db/schema.ts`
- [ ] Generate and apply migration
- **Files:** `src/main/permissions/manifest-validator.ts`, `src/main/permissions/permission-manager.ts`, `src/main/db/schema.ts`, `src/main/db/migrations/`
- **Outcome:** Granular, opt-in permission system for plugins. Every access is logged.

### Step 2.2 — Create worker pool and batch runner
- [ ] Create `src/main/workers/worker-pool.ts`:
  - `WorkerPool` class:
    - Manages a pool of Node.js `worker_threads`
    - `runPlugin(manifest, context): Promise<PluginResult>` — spawns or reuses a worker, sends manifest + context, receives result
    - Worker lifecycle: create, send message, receive result, terminate on timeout
    - Max concurrent workers: configurable (default 4)
    - Error isolation: worker crash doesn't affect main process
- [ ] Create `src/main/workers/batch-runner.ts`:
  - `BatchRunner` class:
    - `registerPlugin(manifest): void` — validates manifest, stores in registry
    - `startScheduler(): void` — cron-based scheduler using `node-cron` or simple setInterval
    - `runPlugin(name, triggerContext?): Promise<PluginResult>` — manual trigger
    - `stopAll(): void` — graceful shutdown of all scheduled plugins
    - Scheduler checks permissions before each run; skips if revoked
    - Results logged to activity log
- [ ] Create `src/main/workers/plugin-worker.ts`:
  - Worker thread entry point
  - Receives plugin config + context via `parentPort.on('message')`
  - Dynamically imports the plugin entry point
  - Executes `run(context)` with sandboxed access (only permitted resources)
  - Posts result back via `parentPort.postMessage()`
- **Files:** `src/main/workers/worker-pool.ts`, `src/main/workers/batch-runner.ts`, `src/main/workers/plugin-worker.ts`
- **Outcome:** Isolated plugin execution environment with scheduling, permissions enforcement, and error isolation.

### Step 2.3 — Implement batch agent plugins
- [ ] Create `src/plugins/email-scanner.ts`:
  - Manifest: requires `read_email` permission
  - Connects to IMAP via `imapflow` (account configured in settings)
  - Scans for new emails since last run
  - Uses `LiteLLMClient` to classify each email (has actionable task? extract title, priority, description)
  - Returns extracted task metadata (never raw email content) for execution via backend or local playbook
- [ ] Create `src/plugins/file-watcher.ts`:
  - Manifest: requires `read_folder` permission for each watched path
  - Uses `chokidar` to watch approved directories
  - On new/modified file: reads content, generates embedding, upserts into vector store
  - Supports: .txt, .md, .pdf (text extraction), .docx (basic extraction)
- [ ] Create `src/plugins/calendar-sync.ts`:
  - Manifest: requires `read_calendar` permission
  - Parses ICS files or connects to CalDAV endpoint
  - Detects scheduling conflicts
  - Suggests reorganizations via LLM analysis
  - Returns calendar events + conflict reports
- [ ] Create `src/plugins/browser-agent.ts`:
  - Manifest: requires `read_browser_history` permission (explicit opt-in)
  - Reads browser bookmarks and history from known browser paths (Chrome, Firefox, Edge)
  - Indexes relevant entries into vector store
  - Privacy-first: only indexes URLs and titles, not page content
- **Files:** `src/plugins/email-scanner.ts`, `src/plugins/file-watcher.ts`, `src/plugins/calendar-sync.ts`, `src/plugins/browser-agent.ts`
- **Outcome:** Four local batch agents running as isolated worker threads, using LiteLLM for analysis.

---

## Phase 3 — Backend Integration

### Step 3.1 — Create backend HTTP/WebSocket client
- [ ] Create `src/main/api/backend-client.ts`:
  - `BackendClient` class:
    - `baseUrl` configurable (default: production cloud URL, overridable for dev)
    - `setAuthToken(jwt: string): void`
    - `chat(request: ChatRequest): Promise<ChatResponse>` — POST /api/v1/chat
    - `chatStream(request: ChatRequest): AsyncGenerator<string>` — WebSocket /api/v1/chat/stream
    - `getPlaybooks(): Promise<ExecutionPlan[]>` — GET /api/v1/plans/playbook
    - `uploadBackup(blob: Buffer, metadata: BackupMetadata): Promise<void>` — PUT /api/v1/backup
    - `downloadBackup(): Promise<{ blob: Buffer, metadata: BackupMetadata }>` — GET /api/v1/backup
    - Automatic retry with exponential backoff (max 3 attempts)
    - Offline detection: returns cached playbook responses when offline
  - `isOnline(): boolean` — connectivity check
- [ ] Create `src/main/api/plan-runner.ts`:
  - `PlanRunner` class:
    - `execute(plan: ExecutionPlan): Promise<PlanResult>` — executes plan steps locally
    - Step handlers: `create_record` (inserts into SQLite), `update_record`, `delete_record`, `index_document` (upserts into vector store), `send_notification` (Electron notification API)
    - Each step logs to activity log
    - Supports `data_from_step` references (pipeline execution)
    - Validates plan structure before execution
- **Files:** `src/main/api/backend-client.ts`, `src/main/api/plan-runner.ts`
- **Outcome:** Electron can communicate with the cloud backend and execute returned plans locally.

### Step 3.2 — Refactor orchestrator to delegate to backend
- [ ] Update `src/main/ai/orchestrator.ts`:
  - When online: forward chat requests to backend via `BackendClient.chatStream()`
  - Build `ChatRequest` from local context: query SQLite for user profile, relevant documents (from vector store), recent tasks, conversation history
  - Stream backend response tokens to renderer via existing `ai:stream` IPC channel
  - Execute any returned actions via `PlanRunner`
  - When offline: fall back to local orchestration (existing LangGraph pipeline) with degraded capabilities
  - Remove direct agent logic (project agent, knowledge agent, general agent tool definitions) — these now live on the backend
  - Keep `buildProjectContext()` and `buildGlobalContext()` as context builders for the request payload
- [ ] Update `src/main/router/index.ts` `ai` sub-router:
  - `chat` mutation: call refactored orchestrator (which now delegates to backend)
  - Add `getPlaybooks` query: fetches cached playbooks
  - Keep `dailyBrief` mutation: sends daily brief request to backend
- [ ] Add IPC handler for plan execution results
- **Files:** `src/main/ai/orchestrator.ts`, `src/main/router/index.ts`, `src/main/ipc.ts`
- **Outcome:** Chat intelligence lives on the backend; Electron is the execution layer.

### Step 3.3 — Implement Shared Memory (three-tier local memory)
- [ ] Create `src/main/database/shared-memory.ts`:
  - **Short-term memory**: In-memory conversation buffer
    - `ConversationBuffer` class: stores last N messages per session
    - `addMessage(sessionId, role, content)`, `getHistory(sessionId, limit?) -> Message[]`
    - Cleared on session end
  - **Long-term KV store**: SQLite-backed key-value store
    - New `agent_memory` table: `id`, `namespace` (agent name), `key`, `value` (JSON text), `updated_at`
    - `AgentMemoryStore` class: `get(namespace, key)`, `set(namespace, key, value)`, `delete(namespace, key)`, `listKeys(namespace)`
    - Used by agents to persist learned facts, user preferences
  - **Vector store**: Already exists (LanceDB). Enhance with:
    - Multi-collection support: separate tables for notes, emails, files, calendar
    - `searchByCollection(collection, query, limit) -> SearchResult[]`
- [ ] Add `agent_memory` table to `src/main/db/schema.ts`
- [ ] Generate migration
- **Files:** `src/main/database/shared-memory.ts`, `src/main/db/schema.ts`, `src/main/db/migrations/`
- **Outcome:** Three-tier memory system supporting short-term conversation, long-term agent facts, and semantic search.

---

## Phase 4 — Security: E2E Backup & Offline Mode

### Step 4.1 — Implement E2E encrypted backup
- [ ] Create `src/main/backup/e2e-crypto.ts`:
  - `generatePassphrase(): string` — BIP39-compatible 12-word recovery phrase
  - `deriveKey(passphrase: string, salt: Buffer): Promise<Buffer>` — Argon2id key derivation (time cost 3, memory 64MB, parallelism 1)
  - `encrypt(data: Buffer, key: Buffer): { ciphertext: Buffer, iv: Buffer, authTag: Buffer }` — AES-256-GCM
  - `decrypt(ciphertext: Buffer, key: Buffer, iv: Buffer, authTag: Buffer): Buffer`
  - Uses `node:crypto` for AES and `argon2` npm package for key derivation
- [ ] Create `src/main/backup/backup-manager.ts`:
  - `BackupManager` class:
    - `createBackup(passphrase: string): Promise<BackupBlob>` — Exports SQLite DB, encrypts, returns blob + metadata
    - `restoreBackup(blob: Buffer, passphrase: string): Promise<void>` — Decrypts blob, replaces local DB, re-initializes
    - `uploadBackup(passphrase: string): Promise<void>` — Creates backup, uploads via `BackendClient`
    - `downloadAndRestore(passphrase: string): Promise<void>` — Downloads from backend, decrypts, restores
    - Incremental backup: chunks DB into segments, encrypts each separately, tracks content hashes to skip unchanged chunks
    - Metadata header: version, timestamp, checksum (SHA-256 of plaintext), chunk count
- **Files:** `src/main/backup/e2e-crypto.ts`, `src/main/backup/backup-manager.ts`
- **Outcome:** User data never leaves the device unencrypted. Backend stores only opaque blobs.

### Step 4.2 — Implement offline sync queue
- [ ] Create `src/main/backup/sync-queue.ts`:
  - `SyncQueue` class:
    - `enqueue(action: QueuedAction): void` — Adds action to persistent queue (SQLite table `sync_queue`)
    - `processQueue(): Promise<void>` — Processes queued actions in FIFO order when online
    - `getQueueSize(): number`
    - `clearQueue(): void`
    - Conflict resolution: last-write-wins with timestamps
  - New `sync_queue` table: `id`, `action_type`, `payload` (JSON), `created_at`, `status` (pending/processing/failed), `retry_count`, `last_error`
  - Auto-drain: watches connectivity, starts processing when online
  - Failed actions: retry up to 3 times with exponential backoff, then mark as `failed` for user review
- [ ] Add `sync_queue` table to schema
- [ ] Integrate with `BackendClient`: when offline, chat/backup calls enqueue instead of failing
- **Files:** `src/main/backup/sync-queue.ts`, `src/main/db/schema.ts`, `src/main/api/backend-client.ts`
- **Outcome:** App works offline; queued actions sync automatically when connectivity returns.

---

## Phase 5 — Auth Integration & Database Encryption

### Step 5.1 — Integrate auth into Electron app
- [ ] Create `src/main/auth/auth-manager.ts`:
  - `AuthManager` class:
    - `login(email, password): Promise<void>` — Calls backend POST /api/v1/auth/login, stores JWT in secure storage (via token.ts)
    - `register(email, password): Promise<void>` — Calls POST /api/v1/auth/register
    - `logout(): void` — Clears stored JWT
    - `getToken(): string | null` — Returns current JWT
    - `refreshToken(): Promise<void>` — Auto-refresh before expiry
    - `isAuthenticated(): boolean`
    - `getCurrentTier(): BillingTier`
  - Auto-refresh: checks token expiry every 5 minutes, refreshes if < 10 minutes remaining
- [ ] Add tRPC procedures: `auth.login`, `auth.register`, `auth.logout`, `auth.status`, `auth.tier`
- [ ] Wire `BackendClient` to use `AuthManager.getToken()` for all requests
- **Files:** `src/main/auth/auth-manager.ts`, `src/main/router/index.ts`, `src/main/api/backend-client.ts`
- **Outcome:** Electron app has full auth flow; backend requests are authenticated.

### Step 5.2 — Migrate from better-sqlite3 to SQLCipher
- [ ] Add `@journeyapps/sqlcipher` to dependencies (replaces `better-sqlite3`)
- [ ] Update `src/main/db/index.ts`:
  - Replace `better-sqlite3` import with `@journeyapps/sqlcipher`
  - On first launch: derive DB key from OS keychain or prompt user
  - `initDb(password)`: opens DB with `PRAGMA key = 'password'`
  - Migration path for existing unencrypted DBs: detect → export → create encrypted → import → delete old
  - WAL mode still enabled after keying
- [ ] Update `src/main/index.ts`: pass password to `initDb()`
- [ ] Test that all existing Drizzle operations work with SQLCipher
- **Files:** `package.json`, `src/main/db/index.ts`, `src/main/index.ts`
- **Outcome:** All local data encrypted at rest with SQLCipher.

---

## Phase 6 — Renderer UI Updates

### Step 6.1 — Update Settings page for multi-provider config
- [ ] Add provider management UI to Settings:
  - List of configured providers with status (active/inactive/error)
  - Add provider form: name dropdown (OpenAI, Anthropic, Google, Mistral, Groq, Ollama), API key input, model selection, endpoint (for Ollama)
  - Set primary and fallback providers
  - Test connection button per provider
- [ ] Add auth section to Settings:
  - Login/register form
  - Current tier display with upgrade CTA
  - Logout button
- [ ] Add backup section to Settings:
  - Create/view recovery passphrase
  - Manual backup trigger
  - Backup history with restore points
  - Auto-backup schedule toggle
- **Files:** `src/renderer/components/settings/` (new), route file
- **Outcome:** Users can manage AI providers, auth, and backups from Settings.

### Step 6.2 — Add Permission Dialog and Activity Log
- [ ] Create `src/renderer/components/permissions/PermissionDialog.tsx`:
  - Modal shown when a plugin requests new permissions
  - Lists requested permissions with reasons
  - Per-permission approve/deny toggles
  - Shows plugin manifest info (name, description, version)
- [ ] Create `src/renderer/components/permissions/ActivityLog.tsx`:
  - Filterable table of all plugin activity
  - Columns: timestamp, plugin name, action type, resource, status
  - Filter by plugin, date range, action type
  - Export as CSV
- [ ] Add tRPC procedures for permission management and activity log queries
- **Files:** `src/renderer/components/permissions/PermissionDialog.tsx`, `src/renderer/components/permissions/ActivityLog.tsx`, `src/main/router/index.ts`
- **Outcome:** Transparent permission system with full activity audit trail.

### Step 6.3 — Update AIChatPanel for backend-powered chat
- [ ] Update `src/renderer/hooks/useAIChat.ts`:
  - Support WebSocket streaming from backend (when online)
  - Fall back to IPC streaming (when offline, using local orchestrator)
  - Add connection status indicator (online/offline/reconnecting)
  - Support execution plan responses: show plan preview, allow user to approve/modify before execution
- [ ] Update `src/renderer/components/ai/AIChatPanel.tsx`:
  - Add connection status badge
  - Add tier indicator (shows current plan limitations)
  - Plan approval UI: expandable plan steps with approve/reject buttons
  - Enhanced error states: differentiate between offline, auth expired, rate limited, server error
- [ ] Update `src/renderer/components/ai/FloatingChat.tsx`:
  - Same streaming changes as AIChatPanel
  - Compact plan approval for inline context
- **Files:** `src/renderer/hooks/useAIChat.ts`, `src/renderer/components/ai/AIChatPanel.tsx`, `src/renderer/components/ai/FloatingChat.tsx`
- **Outcome:** Chat UI seamlessly handles both online (backend) and offline (local) modes.

---

## Phase 7 — Cleanup & Hardening

### Step 7.1 — Remove deprecated AI code
- [ ] Delete `src/main/ai/copilot.ts` (Copilot SDK replaced by LiteLLM)
- [ ] Delete `src/main/ai/chat-copilot.ts` (LangChain adapter no longer needed)
- [ ] Delete or archive `src/main/ai/llm.ts` (replaced by `src/main/llm/litellm-client.ts`)
- [ ] Remove `@github/copilot-sdk`, `@langchain/langgraph` from dependencies (if unused)
- [ ] Clean up `src/main/ai/provider.ts`: simplify to delegate to `src/main/llm/providers.ts`
- [ ] Remove `currentSender` module-level mutable state from orchestrator (proper context passing)
- [ ] Update `src/main/index.ts` startup: remove `import './ai/copilot'`, add `BatchRunner.startScheduler()`, add `AuthManager` init
- **Files:** Multiple files under `src/main/ai/`, `package.json`, `src/main/index.ts`
- **Outcome:** No dead code; clean, maintainable codebase.

### Step 7.2 — Add error handling and logging
- [ ] Implement structured logging in main process:
  - Log levels: debug, info, warn, error
  - Log destinations: console (dev), file (production, rotated)
  - Correlation IDs for request tracing across IPC → backend → response
- [ ] Add error boundaries in renderer:
  - Per-route error boundaries
  - AI chat error boundary (graceful degradation)
  - Plugin error boundary (shows which plugin failed)
- **Files:** `src/main/utils/logger.ts` (new), `src/renderer/components/ErrorBoundary.tsx` (new)
- **Outcome:** Production-ready error handling and observability.

### Step 7.3 — Electron integration tests
- [ ] Test BackendClient with mocked HTTP responses
- [ ] Test PlanRunner with sample execution plans
- [ ] Test SyncQueue offline → online transition
- [ ] Test BackupManager encrypt → decrypt round-trip
- [ ] Test PermissionManager grant → check → revoke cycle
- **Files:** `src/main/__tests__/` (new test directory)
- **Outcome:** Confidence that all Electron-side components work correctly.

---

## New Dependencies (package.json)

| Package | Purpose |
|---|---|
| `@journeyapps/sqlcipher` | Encrypted SQLite (replaces `better-sqlite3`) |
| `argon2` | Key derivation for E2E backup |
| `node-cron` | Batch agent scheduling |
| `chokidar` | File watching (FileWatcher plugin) |
| `imapflow` | IMAP client (EmailScanner plugin) |
| `onnxruntime-node` | Local embeddings (optional) |

---

## Execution Notes

- **Each step is independently committable** and produces working code.
- **Phases 1-2** (LLM client + plugins) are independent of the backend — can start immediately.
- **Phase 3** (backend integration) requires the backend repo to have the `/api/v1/chat` endpoint ready.
- **Phase 5.2** (SQLCipher) is intentionally late to avoid encryption overhead during active schema changes.
- **The existing app continues to work** throughout the migration. Local orchestration is preserved until backend is ready (Step 3.2).