Building Block View

Whitebox Overall System

bbv level1
Motivation

The system separates the two front ends (CLI, ACP) and the first-run wizard (Setup) from a shared core engine. Inside the engine the Agent Loop is the orchestrator; the Tool Subsystem, LLM Backend Layer, Config Subsystem and Session Persistence are the capabilities it composes. The Remote block is an optional path that hands a session off to the cloud.

Contained Building Blocks

The nine blocks below. The external systems are the same set named in [section-context-and-scope].

Important Interfaces

AgentLoop.act() is the engine’s entry point; BackendLike is the LLM port; BaseTool.run() is the tool contract; ConfigOrchestrator builds configuration.

Agent Loop

Responsibility: Orchestrate one conversation turn — run middleware, call the LLM, parse and execute tool calls concurrently, update stats, repeat until the assistant emits no tool call.
Interface: AgentLoop.act() [vibe/core/agent_loop.py:632-649].
Source: vibe/core/agent_loop.py, vibe/core/loop.py, vibe/core/middleware.py.
Runtime scenarios: all of [section-runtime-view].

LLM Backend Layer

Responsibility: Present a uniform BackendLike protocol — complete, complete_streaming, count_tokens — over Mistral and OpenAI-compatible providers, with API-style adapters for OpenAI, Anthropic and Vertex.
Interface: BackendLike [vibe/core/llm/backend/base.py:13-126], selected by BACKEND_FACTORY [vibe/core/llm/backend/factory.py:7].
Source: vibe/core/llm/.
Runtime scenarios: Conversation Turn, LLM Rate-Limit.

Tool Subsystem

Responsibility: Discover, filter, instantiate and permission-check tools — builtin, MCP and connector — and expose them to the loop.
Interface: ToolManager.available_tools / .get() [vibe/core/tools/manager.py:72-447]; BaseTool.run() [vibe/core/tools/base.py:122-152].
Source: vibe/core/tools/.
Runtime scenarios: Conversation Turn, Tool Approval.

Config Subsystem

Responsibility: Discover config layers (project .vibe/ then ~/.vibe/), merge them field-by-field into a validated VibeConfig.
Interface: ConfigOrchestrator [vibe/core/config/orchestrator.py:10-46].
Source: vibe/core/config/, vibe/core/paths/.
Runtime scenarios: Startup & Resume.

Session Persistence

Responsibility: Persist a session as meta.json + messages.jsonl, load and migrate past sessions, support --continue/--resume and rewind-to-message.
Interface: SessionLogger, SessionLoader, RewindManager [vibe/core/session/session_logger.py:36-97, vibe/core/rewind/manager.py:35-165].
Source: vibe/core/session/, vibe/core/rewind/.
Runtime scenarios: Startup & Resume, Context Auto-Compaction.

CLI / Textual UI

Responsibility: Render the interactive chat TUI, route key bindings, dispatch the 23 slash commands; also host the non-interactive runner.
Interface: VibeApp [vibe/cli/textual_ui/app.py:322-558]; run_programmatic() [vibe/core/programmatic.py:27].
Source: vibe/cli/.
Runtime scenarios: Conversation Turn, Tool Approval, User Interruption.

ACP Bridge

Responsibility: Expose the engine over the Agent Client Protocol, with ACP-specific tools that delegate file and terminal operations to the ACP client.
Interface: VibeAcpAgentLoop [vibe/acp/acp_agent_loop.py:267-289].
Source: vibe/acp/.
Runtime scenarios: ACP Session.

Remote (Teleport + Nuage)

Responsibility: Validate the git repo, ensure the commit is pushed, start a remote Vibe Code workflow, and stream its events back.
Interface: TeleportService, WorkflowsClient, RemoteEventsSource [vibe/core/teleport/teleport.py:46-150, vibe/core/nuage/remote_events_source.py:33-120].
Source: vibe/core/teleport/, vibe/core/nuage/.
Runtime scenarios: Teleport to Cloud.

Setup / Onboarding

Responsibility: Walk a first-run user through Welcome → auth-method → (browser sign-in or manual API key) and persist the key.
Interface: OnboardingScreen flow [vibe/setup/onboarding/base.py:6-14].
Source: vibe/setup/.
Runtime scenarios: First-Run Onboarding.

Level 2 — White Box: Tool Subsystem

bbv tools

The ToolManager scans search paths for BaseTool subclasses and merges in MCP and connector proxy tools [vibe/core/tools/manager.py:120-383]. Each tool declares a BaseToolConfig permission tier; before execution the loop resolves a PermissionContext and consults the PermissionStore for session-remembered approvals [vibe/core/tools/base.py:83-113, vibe/core/tools/permissions.py:47-68]. The numeric limits each builtin tool enforces are listed as system use cases in ../../use-cases-vibe.adoc and as quality scenarios in [section-quality-scenarios].