Commit 00005f89 — Sandbox orchestration library, Vitto VM proxy migration, backend-api cleanup

Comprehensive retrospective for feat commit integrating @libs-api/sandbox-orchestration and moving sandbox HTTP surface from backend-ai-api to backend-vitto-api.

Commit 00005f89 — Sandbox orchestration and module structure

Author: fguijarro
Date: 2026-03-26 (Thu Mar 26 11:54:40 2026 -0500)
Short hash: 00005f89
Scope: 35 files, ~968 insertions, ~1881 deletions (net removal of dead/stub code and duplicated HTTP bridge).

This document is scoped to session 271 (see sessions/manifests/S271.json). It does not attribute work to other session numbers.

1. Executive summary

The commit introduces a shared Nx library @libs-api/sandbox-orchestration that owns the self-hosted sandbox client, placement routing, and core types. backend-ai-api stops exposing the sandbox HTTP proxy (SandboxProxyController) and instead consumes types from the new package. backend-vitto-api gains a new InfrastructureExecutionModule that hosts the sandbox proxy under /vitto-api/infrastructure/sandbox/* (global prefix depends on deployment), and VmApiClientService switches from HTTP calls to backend-ai-api to in-process calls into SandboxVmOperationsService.

Net architectural effect: Sandbox VM operations for Vitto are colocated with Vitto (same process, shared provider factory), removing a network hop and internal-token coupling to the AI API for that path. Computer Use and full provider chains (E2B, Playwright) remain on backend-ai-api with its existing SandboxProviderFactory.

Important: An earlier session-271 decision doc (271.17) described routing VmApiClient through HTTP to backend-ai-api. This commit supersedes that direction for the code paths it touches: Vitto now uses local SandboxVmOperationsService instead of BACKEND_AI_API_URL + Bearer token for sandbox calls.

2. Commit message vs. actual diff (discrepancy)

The commit body lists:

No files under .cursor/, settings.json, or MongoDB-related config appear in git show --name-only for this commit. Treat that bullet as not evidenced by this tree (it may refer to a squashed narrative, a follow-up change, or a mistake in the message). Do not rely on it when reasoning about this commit.

3. New library: @libs-api/sandbox-orchestration

Path: libs/libs-api/sandbox-orchestration/

Artifact Purpose
package.json Package name @libs-api/sandbox-orchestration, CommonJS, peer deps on NestJS common, reflect-metadata, rxjs.
project.json Nx @nx/js:tsc build to dist/libs/libs-api/sandbox-orchestration.
tsconfig.json / tsconfig.lib.json Strict TS, declarations, Node types.
src/index.ts Public exports: sandbox provider interface types, SandboxServerClient + config types, SelfHostedProvider, SandboxPlacementRouter.

Files moved (rename-only) from backend-ai-api into the lib:

Monorepo wiring: tsconfig.base.json adds:

Note: Project rules elsewhere prefer adding path aliases via config/tsconfig-paths/modules/*.paths.json and yarn paths:merge. This commit edits tsconfig.base.json directly for these entries; future maintenance should follow the repo’s tsconfig path protocol if policy requires migration.

4. backend-ai-api changes

4.1 Removed sandbox HTTP proxy

Rationale (inferred): The HTTP surface for /infrastructure/sandbox/* is no longer owned by AI API; Vitto becomes the service boundary for external/internal callers that used that contract against Vitto’s base URL instead.

4.2 Imports switched to @libs-api/sandbox-orchestration

Behavioral note: AI API’s SandboxProviderFactory still wires E2B, Playwright, and self-hosted/placement for Computer Use; only the proxy controller and duplicate type locations are gone.

5. backend-vitto-api changes

5.1 New module: InfrastructureExecutionModule

Path: APIs/backend-vitto-api/src/app/infrastructure-execution/

5.2 VmApiClientService — local delegation (no HTTP to AI API)

Files: engine/vm/vm-api-client.service.ts, vm-api-client.service.spec.ts

5.3 EngineModule

5.4 Tests adjusted

5.5 Jest configuration

File: APIs/backend-vitto-api/jest.config.ts

5.6 Minor test expectation tweaks

5.7 Documented technical debt (from source)

In sandbox-vm-operations.service.ts, a long comment explains a pre-existing mismatch: HTTP route uses sandboxId for snapshotAndSuspend, while SandboxPlacementRouter may key by sessionId; if placement routing is enabled for snapshot, a sandboxId → sessionId lookup may be required. Confidence: high that this is a real edge case for multi-server fleets.

6. backend-api (core API) — removed stub controllers

Deleted (large stub/demo controllers under app/controllers/):

Inferred rationale: Dead or experimental routes not wired to production behavior; removal reduces noise and attack surface. Verify in your branch that nothing still imported these paths (this commit does not show app.module edits — if the repo already had no registrations, deletion is safe).

7. Operational and configuration implications

Topic Detail
Vitto base URL Callers that previously hit AI API for sandbox must now target Vitto for the same route shape under the Vitto global prefix.
Auth Proxy remains @CallerType('service', 'dev') — same class of access as before; confirm gateway and internal clients point at the correct host.
Env vars Vitto sandbox selection uses SANDBOX_SERVERS_JSON and/or SANDBOX_SERVER_URL (see VittoSandboxProviderFactory). AI API env for sandbox still applies to Computer Use.
No cross-service HTTP Vitto no longer needs BACKEND_AI_API_URL for VmApiClientService sandbox calls; internal token for that path is obsolete for this bridge.

8. Session tooling notes (this workspace)

9. Suggested MCP gograb-ai payloads (session 271, sub 30)

Use when preflight / log_decision / report_outcome are available. Do not mix session numbers; user confirmed 271.

9.1 preflight (example)

{
  "task": "Retrospective documentation for commit 00005f89 — sandbox orchestration lib + Vitto infrastructure execution module",
  "sessionNumber": 271,
  "subSessionNumber": 30
}

9.2 log_decision — canonical architecture choice

Problem: Duplicated sandbox orchestration and an extra HTTP hop between Vitto and AI API increased latency, configuration burden (BACKEND_AI_API_URL + internal token), and drift risk.

Alternatives considered:

  1. Keep HTTP delegation from Vitto to AI API (previous direction in some docs).
  2. Shared library only — still call AI API over HTTP.
  3. Chosen: Shared @libs-api/sandbox-orchestration plus execute VM/sandbox operations inside Vitto via SandboxVmOperationsService and a Vitto-hosted SandboxProxyController.

Why chosen: Single orchestration types in one lib; Vitto owns the agent/runtime loop and VM bridge — colocating sandbox ops removes a failure domain and aligns deployment scaling with Vitto. AI API retains richer provider mix where Computer Use needs it.

Would be wrong if: External integrations must enforce sandbox policy only inside AI API (e.g. centralized rate limits), or if Vitto cannot reach SANDBOX_SERVER_URL / fleet where AI API could — then HTTP delegation would remain justified.

Early warnings: Misconfigured Vitto env vars; callers still targeting AI API for /infrastructure/sandbox/*; snapshot/placement mismatch on multi-server (see code comment).

Calibrated confidence: 0.92 (domain: backend service boundaries).

Files: libs/libs-api/sandbox-orchestration/**, APIs/backend-vitto-api/src/app/infrastructure-execution/**, APIs/backend-vitto-api/src/app/engine/vm/vm-api-client.service.ts, APIs/backend-ai-api/src/app/infrastructure/infrastructure.module.ts

9.3 report_outcome (example)

{
  "action": "report",
  "decisionId": "<fill from log_decision response>",
  "wasSuccessful": true,
  "feedback": "Commit 00005f89 merged: lib extracted, Vitto hosts proxy, VmApiClient local delegation, AI API proxy removed, tests added. Session check in editor2 workspace still requires history.json repair."
}

10. Related reading

Generated for session 271 documentation; aligned to git commit 00005f89ab161ea03fa1baf307104c3fa15c3f4e.