98 VITTO SUPER AGENT REBUILD

Documentation for Sessions

Session 98: Vitto Super-Agent Separation & Rebuild

Overview

Rebuilt Vitto from a 2119-line god-class embedded inside backend-ai-api into a standalone super-agent API (backend-vitto-api) running on port 3003 with its own Mind database, provider-agnostic LLM abstraction, and 4-phase workflow.

Problem

The old VittoOrchestratorService was a monolithic class that:

Auto-claimed every handoff within 60s
"Completed" them by generating text — no tools, no real execution
Had no quality checks or cost controls
Was hardcoded to Anthropic only
Actively harmed the multi-agent system by auto-claiming handoffs meant for other agents

Solution

Part A: Decouple from backend-ai-api

Files modified:

apis/backend-ai-api/src/app/chat/chat.service.ts — NEW: Extracted processDirectChat + loadUserContext
apis/backend-ai-api/src/app/chat/chat.module.ts — Removed VittoModule dependency
apis/backend-ai-api/src/app/chat/chat.controller.ts — Swapped to ChatService
apis/backend-ai-api/src/app/app.module.ts — Removed VittoModule import

Key insight: Only 3 files outside vitto/ referenced it. The entire agentic process (HandoffService, AgentService, NativeWsGateway, HandoffTimeoutService, MCP Gateway) has zero Vitto dependencies.

Part B: New Standalone `backend-vitto-api`

Architecture (7 modules, ~40 files, ~5,100 lines):

Module	Purpose
Engine	Task queue, 4-phase workflow (ANALYZE->PLAN->EXECUTE->VERIFY), SSE events
Mind	Own MongoDB (`vitto-mind`) — execution traces, strategy memory, agent performance, user patterns
LLM	Provider-agnostic — BaseLLMProvider + Claude/OpenAI/Gemini + ProviderFactory with fallback chains
Tools	10 tools: read_file, write_file, run_command, http_request, create_handoff, check_handoff_status, recall_memory, search_decisions, query_docs, task_complete
Strategy	RequestClassifier, CostGuard (25 iter/100K tokens/5min), QualityGate
Connectivity	HTTP clients to all 3 backends + WebSocket for handoff events + native notifications
Prompts	Template loading with {{variable}} interpolation, .prompt.md files per phase

Part C: Deployment Readiness

Procfile — Railway process definition
railway.json — Railway deployment config
deployment/Dockerfile.railway.backend-vitto — Docker build following exact backend-ai-api pattern
dev-serve.js — Updated with backend-vitto-api entry
.env.local — 8 VITTO_ environment variables
package.json — serve:backend-vitto and updated serve:all-backends

Cleanup

Deleted apis/backend-ai-api/src/app/vitto/ (7 files, ~3,100 lines)
Deleted apis/backend-ai-api/src/vitto-standalone.ts
Updated ecosystem.config.js

Key Design Decisions

Standalone API (port 3003) — Process isolation, independent scaling, own database
Own Mind database (vitto-mind MongoDB) — Execution traces, strategy memory, agent performance. Platform shared knowledge stays in backend-ai-api accessed via HTTP.
Provider-agnostic LLM — Switch via VITTO_LLM_PROVIDER=claude|openai|gemini. ProviderFactory with health checks and fallback chains.
4-phase workflow — Adopted from gmodules1's PhaseExecutor: ANALYZE classifies, PLAN creates steps, EXECUTE runs tool-use agentic loop, VERIFY validates output quality.
Full data access — HTTP clients to all 3 backends (api:3000, ai-api:3001, docs-api:3002). Same Bearer token auth pattern.
No auto-claiming — Unlike old Vitto, new one doesn't auto-claim handoffs. Tasks are submitted directly or assigned explicitly.

Running

# Development
yarn serve:backend-vitto

# All backends including Vitto
yarn serve:all-backends

# Direct NX
npx nx serve backend-vitto-api

Port Reference

Service	Port	Health Endpoint
backend-api	3000	/api/health
backend-ai-api	3001	/ai-api/health
backend-docs-api	3002	/docs-api/health
backend-vitto-api	3003	/vitto-api/health

Environment Variables

VITTO_API_PORT=3003
VITTO_MONGODB_URI=mongodb://localhost:27017/vitto-mind
VITTO_LLM_PROVIDER=claude
VITTO_LLM_MODEL=claude-sonnet-4-20250514
VITTO_MAX_CONCURRENT=3
VITTO_MAX_ITERATIONS=25
VITTO_MAX_TOKENS=100000
VITTO_TASK_TIMEOUT_MS=300000

Files Created/Modified

New files (~40):

apis/backend-vitto-api/ — Entire new NX app
apis/backend-ai-api/src/app/chat/chat.service.ts — Extracted chat service
deployment/Dockerfile.railway.backend-vitto — Docker deployment

Modified files:

apis/backend-ai-api/src/app/chat/chat.module.ts
apis/backend-ai-api/src/app/chat/chat.controller.ts
apis/backend-ai-api/src/app/app.module.ts
apis/backend-ai-api/ecosystem.config.js
tools/scripts/dev-serve.js
package.json
.env.local

Deleted files (cleanup):

apis/backend-ai-api/src/app/vitto/ (7 files)
apis/backend-ai-api/src/vitto-standalone.ts

Next Steps

Wire SSE streaming to frontends for real-time task monitoring
Implement AgentDeploymentService for multi-agent orchestration decisions
Add execute.prompt.md for layer-specific execution prompts
Connect to production MongoDB Atlas (vitto-mind database)
Deploy to Railway via deploy/vitto-api branch