Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Workbench Dispatch Architecture · Design Document
Branches:
feature/workbench-shell— commit 01..13 (workbench UI + adapters + mirror)refactor/services-layer(new) — Plan 1 + Plan 2 implementationStatus: Implemented (2026-05-31, PR #351). The sections below are the original accepted design; the Implementation update immediately following records where the shipped code diverged.
Owner: cyhhao
Related show page: dispatch-architecture.html (decision tracker, kept until shipped)
0. Implementation update (2026-05-31, PR #351)
What actually shipped differs from the original "C4/C5 streaming" plan in three material ways. This block is authoritative where it conflicts with the design sections below.
Streaming model: per-turn SSE → session/page-scoped stream. The plan streamed one turn's reply back over the
POST /api/sessions/<id>/messages?stream=1response (C5) via a streaming/internal/dispatchendpoint. Shipped instead: the browser loads history once and subscribes to the session'smessage.newfor as long as the page is open, so every message lands live — including scheduled-task / watch turns the user never triggered. Send is now fire-and-forget:POST .../messages→/internal/dispatch_async(202), reply arrives over the stream. A closed tab can't cancel an in-flight turn.Legacy per-turn dispatch stream retired (Step 6, completed for Show in 2026-07). The Chat page's
?stream=1proxy was removed: the ui_server?stream=1route branch (the Chat page is now fire-and-forget). The turn-sink /on_chunkmachinery stays —dispatch_asyncdrives it with a no-opon_chunkto keepin_flightpopulated (Stop) and to flush the send-while-busy queue on settle. Show annotations now use the samePOST /internal/dispatch_asyncentry with their reserved transcriptmessage_id.SessionTurnManager.submitdecides start versus enqueue; replies arrive on the session-scopedmessage.newstream.internal_client.stream_dispatch,POST /internal/dispatch, and the unconsumedshow.dispatchrepublishing path are removed.turn_tokenis load-bearing — NOT rolled back. The plan treated the per-turn token as scaffolding. It is now the completion guard:_stream_chunkandController.mark_turn_completeonly set a sink'sdone_eventwhen the emit'sturn_tokenmatches the sink's, so a lateresultfrom a stopped / timed-out turn can't end the active turn (popin_flight/ publishturn.end/ flush the queue) while its backend still runs.
Known trade-offs (intentional)
- Reused-receiver completion (Claude). Claude runs one long-lived receiver per session, so its emit context carries the first turn's token. The result path adopts the FIFO-matched pending request's token before emitting, so the current turn completes; a turn that fails (auth error) retires its pending request so the next turn isn't desynced.
- No turn-duration timeout (Phase 1a, see
avibe-turn-lifecycle-fsm.md). An agent turn may legitimately run for hours, so the controller never kills it on a timer:dispatch_turnholds the stream open with a plainawait done.wait()until the agent's REAL terminal result. A genuinely wedged turn blocks only its own session until the user's Stop ends it or a restart resets stale state. Plain Stop is no-flush.
Provenance + queue (added beyond the original plan)
- Every
messagesrow carriessource(user/agent/harness), distinct from author role, plusauthor_name/author_id. Harness turns render a Scheduled-task / Watch badge. - Send-while-busy queue + cross-device draft reuse the
messagestable (no new queue table). A transcript reservation is hidden aspending; the unified entry either starts the turn so its caller renders the row asuser, or moves it toqueuedfor the shared drain. For Show events, dispatch lifecycle is stored independently on the stableshow_session_eventsrow asnone/in_flight/accepted/failed, so rendering changes and queue replacement cannot erase acceptance or make a retry ambiguous. Stop keeps the queue; "立即发送" interrupts + flushes.
1. Why This Document Exists
The workbench UI rewrite (commits 01-13 on feature/workbench-shell) added an Agent-Workbench mode
that reads from the shared SQLite store. The next step is send/compose — letting the user type
a message in the web Chat surface and trigger a real agent turn.
Implementing this surfaces two structural problems that have been quietly accumulating:
Data-control duplication — UI server and CLI both directly import
storage/*_service.pymodules. For theagent_sessionstable specifically, two wrappers exist with diverging APIs (storage/workbench_sessions_service.pyfor the UI,storage/sessions_service.py::SQLiteSessionsServicefor IM/CLI). Same table, two business APIs. Every new feature that touches sessions has to pick a side.No cross-process trigger from Web UI to Controller — UI server and Controller run as separate subprocesses (per
vibe/runtime.py::spawn_background). When the user clicks "send" in the web Chat surface, there is no path for the UI server process to ask the Controller process to run an agent turn. IM adapters (Slack/Discord/Telegram/Lark/WeChat) are in-process with Controller and callmessage_handler.handle_user_messagedirectly. CLI uses theagent_runsqueue (async, ~2s scheduler poll, batch JSON output).
These are two independent concerns but they collapse onto one shared abstraction: a
dispatch_turn() entry point that all three callers (IM adapters, CLI, Web UI) converge on.
Solve them together and the architecture stays clean. Solve only one and the other festers.
2. Goal
When this design lands:
- A user can compose a message in the web Chat surface, hit send, and see the agent's reply stream in token-by-token (or chunk-by-chunk) — comparable latency to talking to the bot from Slack/Discord.
- IM adapters, CLI, and Web UI all funnel through a single
dispatch_turn()function that encapsulates the agent-turn lifecycle. Behavior changes there propagate to all three callers without copy-paste. - The UI server process never imports
storage/sessions_service.pydirectly — it goes throughcore/services/sessions.py. Same for the CLI. Contract tests pin the shape so the two callers cannot drift again. ~/.vibe_remote/state/dispatch.sockexists at runtime and exposes a minimum set of internal RPC endpoints over which the UI server can trigger Controller-side runtime side-effects (turn dispatch, cancel). The socket is0o600and local-only.- Pure data CRUD (list projects, update session title, mark read) does not go through the socket. The boundary rules (§7) are enforced by code review.
3. Non-Goals (Explicit)
- Process merge (combining UI server + Controller into one process) is out of scope and rejected. The two-process model is intentional (separate reload lifecycles) and changing it would also conflict with the IM thread / uvicorn worker model.
- WebSocket is rejected in favor of SSE chunked over Unix socket. Rationale: SSE rides on
plain HTTP, auto-reconnects via
EventSource, and matches the existing/api/eventspattern invibe/sse_broker.py. Cloudflare Tunnel research from 2026-05-24 also favored SSE. - Polling-only mode for send/compose (the original "enqueue
agent_runs" approach) is rejected as the primary path. ~2s scheduler delay and no streaming would lock us out of the streaming UX. The queue path stays as a fallback when the socket is unreachable. - gRPC, JSON-RPC, or any structured RPC framework is out of scope. RESTful endpoints on a Unix socket suffice for ~5-10 RPC verbs.
4. Current State (Post-Master 2026-05-26)
Authoritative inventory. Verified against the current feature/workbench-shell head.
4.1 Data domains and their access paths
| Domain | Underlying table | Storage layer (CRUD) | Business layer (UI / CLI / IM) | Status |
|---|---|---|---|---|
| Agents | vibe_agents |
core/vibe_agents.py::VibeAgentStore |
shared across UI + CLI | Unified |
| Sessions | agent_sessions |
SQLAlchemy table | UI: workbench_sessions_service; IM/CLI: SQLiteSessionsService |
Split (target of Plan 1) |
| Messages | messages |
messages_service |
UI + commit 13 mirror both go through service | Unified |
| Projects | scopes + scope_settings |
projects_service |
UI only | Unified |
| Runs / Tasks queue | agent_runs + run_definitions |
storage/background.py::SQLiteBackgroundTaskStore |
core/scheduled_tasks.py::TaskExecutionStore delegates to storage layer |
Properly layered |
| Watches | watches (runtime records) |
core/watches.py |
CLI writes, UI reads via background store | Partial |
| Settings / Config | JSON file + scope_settings |
settings_service |
UI reads config.json directly; CLI uses SettingsStore |
Split (Plan 1 phase 2 target) |
| Auth codes | auth_codes |
settings_service |
shared | Unified |
The actual duplication is only Sessions and Settings. Everything else is either already unified or layered correctly. This was misjudged in the v1 exploration of this design; verified again on 2026-05-26.
4.2 Cross-process facts
- UI server runs as a subprocess started by
vibe/runtime.py::spawn_background(line 835). - Controller runs in a separate process (
main.py:165 controller.run()), holding the IM thread and the agent-runtime asyncio loop. - SSE broker (
vibe/sse_broker.py) is in-process — UI server and Controller each have their ownSSEBroker()singleton, not shared. agent_runsqueue is the only existing cross-process trigger path. It is consumed bycore/scheduled_tasks.py::ScheduledTaskService._drain_requestson a ~2s poll. Already supportsrequest_type="agent_run"which routes tomessage_handler.handle_scheduled_message.- Process merge is documented as forbidden in
docs/CLI.md:262-276("Vibe Remote manages two types of processes" with independent reload lifecycles).
5. Architecture (Target State)
+-------------------+ +-------------------+
| Web UI (Chrome) | | vibe agent run |
+---------+---------+ +---------+---------+
| |
| POST + EventSource | --async --sync
v | (queue) (socket)
+-------------------+ | | |
| UI server proc | | v v
| - SSE proxy | <----- HTTP+SSE chunked --->|
| - /api/* | over ~/.vibe_remote/state/dispatch.sock
| - core/services | | |
+---------+---------+ | |
| | |
| (data layer) | |
v v v
+------------------------------------------------------------+
| core/services/ |
| sessions.py messages.py dispatch.py ... |
| (shared business API) |
+------------------------------------------------------------+
| | |
v v v
+------------------------------------------------------------+
| storage/ (SQLAlchemy CRUD) |
| + core/internal_server.py (Controller-only unix sock) |
+------------------------------------------------------------+
|
| IM adapters (same process as Controller)
| call dispatch_turn() directly (no socket)
v
+---------------+
| Controller |
| + IM thread |
| + asyncio |
| + scheduled |
+---------------+
Key insight: core/services/dispatch.py::dispatch_turn(context, text, *, on_chunk=None) is
the single shared entry. Three callers reach it differently:
- IM adapter (Slack, Discord, …): same Python process as Controller →
await dispatch_turn(...)directly. Zero IPC overhead. Unchanged from today's behavior; the entry point just moves intocore/services/. - Web UI: separate process →
httpx.stream("POST", "http+unix://.../internal/dispatch", json=...)→ Controller'score/internal_server.pycallsdispatch_turn(...)and yields SSE chunks back over the same socket. UI server proxies the chunks to the browser'sEventSource. - CLI (
vibe agent run --sync): also through the socket.--asynckeeps using theagent_runsqueue for cron/hook use cases that should not block.
6. Plan 1 · Data Control Layer
6.1 Target
A new package core/services/ holds business-level APIs that take a SQLAlchemy Connection
(or transaction context) and never own engines or process-level state. UI server, CLI, and
Controller all import from there. Storage layer (storage/) stays as pure CRUD.
6.2 Scope
- In scope (Phase 1A):
core/services/sessions.py— mergesworkbench_sessions_service+SQLiteSessionsService.core/services/dispatch.py— extractsdispatch_turn()frommessage_handler._handle_turn. This is also Plan 2's dependency.
- In scope (Phase 1B):
core/services/settings.py— unifies CLISettingsStore↔ UI directconfig.jsonreads.
- Out of scope (already unified):
- Agents, Messages, Projects, Runs — no work needed.
- Out of scope (later phase):
- Watches, vaults, skills — UI hasn't fully wired them, defer until UX direction settles.
6.3 Service API conventions
- All public functions take
conn: Connectionas their first argument. Never construct engines inside the service. - Return shapes are plain
dict[str, Any]matching the existing_row_to_payloadstyle inmessages_service. No ORM mappers leaking out. - Errors raise
LookupError,ValueError, or domain-specific exceptions defined incore/services/errors.py. Routes / CLI translate them to HTTP status / exit codes. - No side effects (SSE publish, log writes) inside service functions. Side effects belong in the calling layer (routes for UI, controller for IM, CLI for terminal output).
6.4 Commit breakdown
- C1 · Extract
core/services/sessions.py+core/services/dispatch.py+ contract tests. IM adapter and UI server changeimportpaths; CLI unchanged. - C2 · Migrate CLI
_session_service()tocore/services/sessions.py. Verifyvibe agent run --jsonoutput schema is byte-identical (pinned in test). - C3 · Extract
core/services/settings.py. UI server directconfig.jsonreads and CLISettingsStoreboth go through it.
6.5 Risks
- CLI
--jsonschema stability (decision Q8: strict). Mitigated by snapshot test in C2. SQLiteSessionsServicecarries a lot of legacy semantics (session reservation, anchor resolution). These need to move with the API; some are IM-only and should remain hidden behind helper functions insidesessions.py, not exposed as the public surface.
7. Plan 2 · Cross-Process Dispatch (N3)
7.1 Target
Controller process binds a Unix socket at ~/.vibe_remote/state/dispatch.sock and runs a
minimal FastAPI app on it. UI server uses httpx.AsyncClient(transport=AsyncHTTPTransport(uds=...))
to stream RPC calls over the socket. SSE chunked responses flow turn output back to UI server,
which proxies it to the browser's EventSource.
7.2 Why N3 over alternatives
| Candidate | Decision | Reason |
|---|---|---|
N1 · agent_runs queue + polling |
Fallback only | ~2s scheduler delay, no streaming. Future streaming would require recreating this path. |
| N2 · Process merge | Rejected | docs/CLI.md explicitly enforces separate processes. Also conflicts with IM thread / uvicorn worker model. |
| N3 · Unix socket SSE | Selected | ~5ms trigger latency, native streaming via SSE chunked, shares dispatch_turn() with IM and CLI, doesn't break process boundaries. |
7.3 Component changes
- New ·
core/internal_server.py— FastAPI app bound to a unix domain socket. Exposes:POST /internal/dispatch(body: session_id, text, scope_id, agent_overrides) → SSE chunked response. Eachemit_agent_messagechunk produced bydispatch_turnis yielded asdata: {...}\n\n.POST /internal/cancel/<run_id>→ marks the in-flight turn for cancellation, returns when the cancel hook fires.
- New ·
vibe/internal_client.py—httpxwrapper for UI server. Handles connection setup, reconnect on transient drops, and SSE parsing intoAsyncIterator[dict]. - Modified ·
core/controller.py—controller.run()starts the internal server as a background asyncio task. Same event loop, no separate thread. - Modified ·
vibe/ui_server.py—POST /api/sessions/<id>/messages?stream=1becomes aStreamingResponse(text/event-stream)that streams from the internal client. - Modified ·
core/message_dispatcher.py::emit_agent_message— adds an optionalon_chunkcallback thatdispatch_turnpasses in. When present, every emit also feedson_chunk(envelope). When absent, behavior is unchanged for IM adapters (which don't need the stream-out side channel). - Modified ·
ui/src/components/workbench/ChatPage.tsx— adds compose textarea, send button, Cmd/Ctrl+Enter binding, optimistic user-message append, and afetch+ReadableStreamconsumer that appends agent chunks to the transcript as they arrive.
7.4 Endpoint catalog (v1 + v2)
| Endpoint | Type | Purpose | Phase |
|---|---|---|---|
POST /internal/dispatch |
B | Trigger a turn, SSE chunked response | v1 |
POST /internal/cancel/<run_id> |
B | Cancel in-flight turn | v1 |
POST /internal/platform/<name>/start|stop |
B | Start / stop an IM platform adapter | v2 |
POST /internal/backend/<name>/restart |
B | Restart agent backend (replaces RuntimeCommandWatcher markers) |
v2 |
POST /internal/config/reload |
B | Controller reloads V2Config |
v2 |
GET /internal/events |
C | Long-lived SSE: Controller pushes non-request-driven events to UI server | v2 |
v1 is the smallest set that unblocks send/compose. v2 work doesn't block v1 release.
7.5 Commit breakdown
- C4 ·
core/internal_server.py+vibe/internal_client.py+ dispatch endpoint. Tests cover socket up/down, basic dispatch round-trip, and SSE chunked framing. - C5 · UI server POST route emits via internal client; ChatPage compose UI; en/zh i18n; fallback to N1 queue when socket is unreachable.
- C6 ·
POST /internal/cancelendpoint + UI "stop" button on running turn.
7.6 Boundary rules (R1 / R2 / R3)
These are enforced by code review. PR descriptions must state which rule each new endpoint or function falls under.
- R1 · Type A (pure data CRUD) never goes through the socket. If the operation can
be completed in the UI server process by reading/writing SQLite, it must use
core/services/*directly. Examples: list projects, create session, update session title, mark messages read. - R2 · Type B (Controller runtime side effects) uniformly goes through N3 socket. Examples: trigger a turn, cancel a turn, restart a backend, start/stop an IM platform, reload config. One transport, one mental model.
- R3 · Type C (Controller → UI async push) goes through SSE. First version: only
in-call SSE chunked response (already covered by N3
dispatch). Future: a long-livedGET /internal/eventsSSE if non-request-triggered pushes are needed.
7.7 Anti-examples (must not go through socket)
- Listing projects / sessions / messages / agents — pure queries.
- Updating session title / model / effort — pure UPDATE on
agent_sessions. - Marking messages read — pure UPDATE.
- Listing watches / logs / runs — pure queries.
If a Type-A operation is found going through the socket during code review, that PR is
blocked until it's moved to core/services/.
7.8 Failure modes
- Socket unavailable on UI server startup — UI server logs a warning and falls back to
N1 queue mode for
dispatch. Cancel returns 503. UI surfaces "high-latency mode" badge. - Controller crashes mid-turn — Internal server shutdown triggers cleanup of pending
responses; UI server
httpx.streamraises, caught, surfaced to ChatPage as "agent disconnected". User can retry; turn state in DB is left inrunning(next controller boot reclaims via existingrecover_processing_runs). - UI server restarts mid-turn — Browser
EventSourceauto-reconnects to the new UI server; in-flight messages on the Controller side complete and write to messages table; the reconnected browser refetches the transcript and shows the now-completed agent reply. - Socket file permissions wrong — Refuse to start UI server with explicit error pointing to the socket path.
8. Resolved Decisions (from Q1..Q10)
| # | Question | Decision |
|---|---|---|
| Q1 | Cross-process candidate | N3 Unix Socket SSE |
| Q2 | Plan 1 / Plan 2 order | Co-implemented (Plan 1 extracts dispatch_turn, Plan 2 uses it) |
| Q3 | Service layer location | core/services/ |
| Q4 | First domain to slice | Sessions + dispatch_turn together |
| Q5 | Socket path | ~/.vibe_remote/state/dispatch.sock with 0o600 perms |
| Q6 | Fallback path | UI server falls back to N1 queue when socket unreachable |
| Q7 | session_id resolution | UI server auto-creates avibe session when missing |
| Q8 | CLI schema stability | Strict — vibe agent run --json schema unchanged, pinned in test |
| Q9 | Existing 13 commits | Open PR now into Codex review; new work on a separate branch |
| Q10 | Refactor branch | New refactor/services-layer worktree |
9. Execution Order
- PR-A — Open PR from
feature/workbench-shell(commits 01-13 + this document = 14 commits) intomasterfor Codex review. Keep the review loop running viabackground-watch-hook. - Worktree setup — Create
~/vibe-remote-project/.worktrees/avibe/refactor/services-layer/from latest master once PR-A merges (or branch fromfeature/workbench-shellif we want to start before merge — to be decided based on PR-A timing). - C1 — Extract
core/services/sessions.py+core/services/dispatch.py+ contract tests. IM adapterimportchange. No behavior change. Open PR-B for Codex review. - C2 — Migrate CLI
_session_service()to the new service.vibe agent run --jsonschema snapshot test. PR-C. - C3 —
core/services/settings.py. PR-D. - C4 —
core/internal_server.py+vibe/internal_client.py+POST /internal/dispatch. PR-E. - C5 — UI server
POST /api/sessions/<id>/messages?stream=1+ ChatPage compose UI + fallback to N1. PR-F. - C6 —
POST /internal/cancel+ UI stop button. PR-G.
Each PR is independently reviewable. The chain of dependencies is C1 → (C2, C4) → C5 → C6. C3 can land anywhere after C1.
10. Test Strategy
- Contract tests in
tests/contract/test_services_*.py— assert that the same business call (e.g.services.sessions.create()) produces identical row shape regardless of caller. Pin field names, types, default values. - Snapshot tests for
vibe agent run --jsonoutput. Test diffs on schema change. - Integration test for the socket round-trip: spawn a fake controller, send a dispatch, assert SSE chunks arrive in order and the transcript matches.
- Existing tests (
test_message_dispatcher_*,test_message_handler_*, etc.) must continue to pass without modification — IM adapter behavior is the regression backstop. - No new test framework introduced. Pytest only.
11. Open Items (Not Blocking)
- Whether
vibe agent run --syncshould become the default once the socket path is reliable. Defer to a separate UX discussion. - Whether the long-lived
GET /internal/eventsSSE for Controller→UI push (v2) should replacevibe/sse_broker.pyentirely or complement it. Defer to v2. - Cancellation semantics: should a cancelled run leave a
cancelledrow inagent_runsor delete the row? Currentstorage/background.pysupportscancelledstatus; reuse it.
12. Out of Scope, Recorded for Future
- gRPC / Protobuf — would force schema versioning overhead. Reconsider if endpoint count exceeds ~15.
- Replacing
RuntimeCommandWatcher(core/runtime_commands.py) entirely with the new internal endpoints. Listed as v2 work above; not blocking v1. - Web UI sending messages to other IM platforms (e.g. Web UI → Slack channel) — this is a product decision, not a transport decision; current scope keeps web Chat strictly avibe-platform.