Architecture: Merge 13836737 — What is the correct service boundary for sa...

Documentation for Sessions

🏗️ Architecture: Merge 13836737 — What is the correct service boundary for sa...

Date: 2026-03-26
Time: 17:16:03 UTC
Session: gspace1-271.22
Agent: backend
Confidence: 94%
Status: ✅ Documented

📋 Decision Context

Question:

Merge 13836737 — What is the correct service boundary for sandbox/VM lifecycle so Vitto stays reliable and maintainable?

Task: S271 institutional doc merge 13836737

🎯 Decision Made

Chosen:

Single implementation owner: backend-ai-api exposes /infrastructure/sandbox/*; backend-vitto-api VmApiClientService calls it over HTTP with BACKEND_AI_API_URL and BACKEND_API_INTERNAL_TOKEN Bearer auth; remove in-process SandboxVmOperationsService from vitto and delete the sandbox-orchestration lib coupling from this path; inline SandboxHandle types in vm-api-client.

Options Considered:

  1. In-process vitto sandbox stack
  2. Shared package only
  3. HTTP delegation to backend-ai-api (chosen)

💭 Reasoning

What broke: Two stacks could diverge (vitto-local vs ai-api), risking inconsistent sandbox state, duplicated fixes, and security review surface. Root cause: Organizational split copied sandbox logic instead of a single network boundary. Alternatives: (A) Keep all ops in vitto — fastest locally but doubles maintenance and diverges from proxy already on ai-api; (B) Shared npm package without HTTP — still runs two runtime deployments with different configs; (C) HTTP to ai-api single owner — one codepath for providers/E2B/playwright. Superior because operational truth matches architecture: ai-api already hosts sandbox-proxy; internal token pattern matches other infra clients. Decision wrong if: ai-api uptime is worse than vitto or network latency dominates UX (then need colocation or circuit-break UX). Early signals: divergent sandbox IDs between services, bugfixes only applied to one backend, rising 401/5xx on /infrastructure/sandbox, env drift between BACKEND_AI_API_URL instances.

📁 Files Involved

🔗 Related

Auto-generated by MCP Smart Consolidation