🏗️ Architecture: How should Vitto route tasks between API execution ($0, 0.1s...

Date: 2026-03-31
Time: 19:05:58 UTC
Session: gspace1-290.24
Agent: backend
Confidence: 93%
Status: ✅ Documented

📋 Decision Context

Question:

How should Vitto route tasks between API execution ($0, 0.1s) and Computer Use VMs ($2-5, 120s)?

Task: S289: OAuth-First Intelligent Task Execution

🎯 Decision Made

Chosen:

3-tier execution hierarchy: Tier 1 (OAuth API, $0) → Tier 2 (Persistent VM snapshot, $0.50) → Tier 3 (Cold boot VM, $2-5). OAuthRouterService intercepts in ComputerUseSupervisorService.startSupervised() BEFORE VM launch. Falls through silently on any failure.

Options Considered:

1. 1. LLM-based intent classification (high accuracy but adds latency + cost per request)
2. 2. Regex-based intent parser with confidence threshold (fast, free, conservative fallback)
3. 3. Profile-based routing only (if profile=gmail, always try API — no NLP needed)
4. 4. User-selected execution mode (manual toggle between API and VM)

💭 Reasoning

The existing ComputerUseSupervisorService always launches a Firecracker VM for every task — even trivially simple ones like "send an email" that could be done via a 100ms API call. The platform already had OAuth infrastructure (S234: OAuthService, PKCE, token encryption, proxyApiCall, health cron) but it was never wired into the execution path. The 3-tier model preserves all existing behavior (Tiers 2-3 are unchanged) while adding a zero-cost fast path. The intercept is wrapped in try-catch so ANY failure (OAuth down, intent unclear, proxy error) gracefully falls through to Computer Use. This means the feature cannot degrade the existing experience — it can only improve it. The insertion point is AFTER vault credential resolution but BEFORE infra.computerUseExecute(), because we need credentialType info from the resolution to know if OAuth is available.

📁 Files Involved

• APIs/backend-vitto-api/src/app/engine/computer-use-supervisor.service.ts
• APIs/backend-vitto-api/src/app/engine/oauth-router.service.ts
• APIs/backend-vitto-api/src/app/engine/task-intent-parser.service.ts
• APIs/backend-vitto-api/src/app/engine/api-executors/api-executor.registry.ts

🔗 Related

• Decision ID: dev_1774983958419_ijrw3ww
• Session: 290
• Workspace: gspace1

Auto-generated by MCP Smart Consolidation