Build Mode Overview

​

Request lifecycle

SSE / WS request
  └─ src/routes/vibe.ts
       └─ handleVibeStream()                        src/orchestrator/orchestrator.ts
            ├─ credit / budget / entitlement gates
            ├─ resolve provider + model
            ├─ get-or-create sandbox                (WorkspaceManager.getOrCreate)
            ├─ restore project files from DB
            ├─ start dev server EARLY → emit preview_url
            └─ run agent loop                       src/agent/agent-loop.ts
                  while turnCount < maxTurns:
                    streamText({ maxSteps: 1, tools, messages })
                    execute returned tool-calls in Promise.all
                    yield events (text, tool-call, file_streaming_chunk, …)
                    route up at 75 % context, compact at 90 %
                    self-heal at most 3× per error

​

Two project types

​

Hard rules (load-bearing — don’t “simplify”)

1. One while loop, one agent. The build loop is a single agent, not a swarm — parallel tool calls go through Promise.all. The one delegation that exists is bounded and read-only: spawn_subagent hands an investigation to up to four research agents that cannot write. See Subagents.
2. Stream everything — tool-call start, file write chunks, thinking, status.
3. ask_user stores a resolve and fires when the frontend POSTs /vibe/answer.
4. Route to a larger-context model at 75 %, compact at 90 %. Compacting earlier thrashes memory; later trips provider context-overflow rejections.
5. .mana/memory.md survives compaction — it lives on disk in the sandbox.
6. 3-attempt cap per error in self-heal. Past that, the error surfaces.
7. No placeholder text. Real content only.
8. Templates come from GitHub via git clone --depth 1.
9. Dev server is started by the orchestrator, not the agent. bash short-circuits npm run dev.
10. toolCalls.clear() fires on finish_reason of "tool_calls" OR "stop" — some providers send tool calls with stop.
11. Failover only activates for the default provider. Explicitly chosen models are not silently swapped on failure.

​

Where to look first when something breaks