Open sourceMIT · One protocol, four surfaces · Event-sourced
Streaming chat, tool-call visualization, fail-closed human approval. 27 event types drive four surfaces in real time; sessions persist as append-only JSONL — replayable, forkable, rollback-safe.
MIT License · Node.js ≥ 24 · Binds to 127.0.0.1:4318 · Data in ~/.spark
Why is the session file append-only?
append-only JSONL: line 0 is the header, each following line is one event envelope, and seq equals the file line number. Append-only means replayable, forkable and rollback-safe.
How does the UI recover after a disconnect?
Replay: durable events are refetched by since=seq and recomputed; live-only deltas are never persisted — assistant.message rebuilds the final state.
>
The engine wants to modify workspace files and waits for human confirmation:
bash command request
git commit -m "feat: bash pool"
✓ Approved (once) · An unanswered ask settles to reject (fail-closed)
SURFACES
One applyEvent reducer projects all four surfaces — not four separately written clients.
Read first, then edit — every change goes through approval. Write-class tools and bash require human confirmation — once / always / reject; an unanswered ask settles to reject (fail-closed).
permission.resolved { reply } · fail-closed
For developers
The event vocabulary, zod schemas, applyEvent reducer and Transport all live in @spark/protocol — runtime code, not a types package. Reconnects resume by seq; a replay rebuilds the full UI.
import { createClient } from "@spark/sdk";// HTTP client: assembles HttpTransport + convenience groups (ADR D30)const client = createClient("http://127.0.0.1:4318");// The event stream is the single source of UI state: SSE resumes by seqclient.events.subscribe((envelope) => { // 27 event types fold into UI state via applyEvent});Four capabilities share one event vocabulary: streaming render, the tool state machine, the approval card and four-surface sync are all branches of the same reducer.
Model output is pushed as assistant.delta events, token by token; each surface folds the stream into UI state with the same applyEvent reducer. Delta events are live-only: never persisted, and the durable assistant.message rebuilds the final state after reconnect.
assistant.delta · reasoning.delta · tool.progress = live-only
The tool state machine started → progress → completed renders end to end: input, output, duration (durationMs) and error flag (isError) are all event fields. Failures surface error codes (E_PATH_OUTSIDE, E_SANDBOX_UNAVAILABLE and friends) on the same screen.
tool.started { input } → tool.completed { output, isError, durationMs }
permission.asked raises a card; the only replies are once / always / reject. Timeouts, errors and interrupts always settle to reject (fail-closed). Approval events are log-only: never in model history, but durably persisted so every decision can be replayed.
permission.resolved { reply: 'once' | 'always' | 'reject' }
Web, Desktop, CLI and Mobile (mini app included) share the 27-event vocabulary and the Transport interface of @spark/protocol. The vocabulary grows via declaration merging with the schema registry as the single source, so the four surfaces cannot drift apart.
@spark/protocol · 27 events · Web / Desktop / CLI / Mobile
Five layers: surface UIs / protocol / server / engine / session files.
↓ data flow: user input → engine → events → UI
Loopback by default; approval timeouts, errors and interrupts all settle to reject; out-of-root paths are blocked before approval; events persist append-only end to end.
The server listens on the loopback address only; all session data stays in ~/.spark/. When external exposure is needed (non-loopback binding), pairing auth is mandatory: a 6-digit short code exchanges for a long-lived token.
server: { host: '127.0.0.1', port: 4318 }Write-class tools and bash require human confirmation with exactly three replies: once / always / reject. Timeouts, errors, interrupts, cascades and mode switches all settle to reject, audited as system; bash is fully approved by default.
timeout → permission.resolved { reply: 'reject' }The allowed root is the cwd; a path that resolves outside throws E_PATH_OUTSIDE before approval, not after it in an audit log. The optional bash sandbox prefixes platform wrappers (Linux bwrap / macOS Seatbelt) — unavailable wrapper means refused, never a bare run.
resolveInRoot → E_PATH_OUTSIDEappend-only JSONL: line 0 is the header, each following line is one event envelope, and seq equals the file line number. Append-only means replayable, forkable and rollback-safe (checkpoint).
~/.spark/sessions/<mungeDir(cwd)>/<ts>_<id>.jsonlBefore the npm release lands, clone the source: install once, build one server bundle, one command into the TUI.
Start from the protocol package: the event vocabulary and Transport are the shared runtime core of all four surfaces.
MIT license · binds to 127.0.0.1 only · no account system