Architecture
One process, one SQLite file, one URL. Everything below follows from that sentence: if a piece needs a second daemon, a message broker or a cloud account, it does not belong in Beeper.
1. The picture (A.9)
Kiro IDE / CLI ── hook "before tool" ─────┐
Kiro Crew ────── app (event) ─────────────┤
MCP client ───── page_human ──────────────┼─ HTTP ─▶ ┌────────────────┐ ◀─ WebSocket ─▶ ┌──────────┐
Scripts ──────── SNPP :4440, bip ─────────┘ │ Central │ Web Push │ Beeper │
│ rules · queue │ ◀─ signed ──── │ (PWA) │
│ audit · SQLite │ decision └──────────┘
└────────────────┘
Read it in three columns:
| Column | What it is | What it may not do |
|---|---|---|
| Left — the sources | A Kiro session, a Crew app, an MCP client, a shell script speaking SNPP or bip |
Compose a line, declare a risk level, decide anything |
| Middle — the Central | One Node process: rules, line composer, queue, budget, audit, store | Launch an agent, keep state in memory that is not in SQLite |
| Right — the human | The pager: a PWA on the phone, a lock screen, a memory of 50 pages | Decide anything the Central did not propose |
2. The packages
| Package | Role | Depends on |
|---|---|---|
packages/core |
The shared contract. Line composer, code families, state machine, budget, rules engine, decision claims, wire schemas. Pure functions; src/index.ts is browser-safe, @bipeur/core/node adds hashing and ECDSA verification. |
yaml, zod |
packages/central |
Hono API, node:sqlite store, WebSocket stream, Web Push, audit log, digest, simulator, dashboard. |
core, hono, ws, web-push |
packages/pager |
React 19 + Vite PWA: the screen, the keys, pairing, the signed decision, offline behaviour, memory, settings. | core, react |
packages/hook |
bip-hook (Kiro PreToolUse) and bip-notice (end of turn). |
core |
packages/mcp-server |
page_human, page_wait, page_cancel over stdio. |
core, MCP SDK |
packages/snpp |
RFC 1861 gateway over plain TCP. | core |
packages/cli |
bip ask "…" --yes-no --ttl 10m → exit 0 / 1 / 3. |
core |
packages/crew-app |
Kiro Crew app: relays approval events, resolves them from a signed decision. | core, ws |
Rule of the house: a package that needs a piece of product logic imports it from
core. Two implementations of composeLine would be two products.
3. Data model, table by table
SQLite, one file (BIPEUR_DB), behind packages/central/src/store/ so the driver
can change without touching the API.
sources
| Column | Why |
|---|---|
id, alias (≤ 6 chars) |
The alias is what the page prints; it is normalised, never truncated at display time |
kind |
kiro-hook, mcp, crew, snpp, cli, simulator — used for metrics, never for trust |
token_hash |
hashToken(token), compared in constant time; the clear token exists only in the station's environment |
last_seen_at, rate_limit_per_minute |
Rate limiting is per station, server-side |
devices
id, name, public_key_jwk, push_subscription, paired_at, revoked_at,
mask_on_lock_screen. Rows are never deleted: revocation sets revoked_at, so
an old audit row still points at a device that exists.
pages
| Column | Why |
|---|---|
id, source_id, kind |
tool or question — decides whether the line comes from the payload or from a written question |
code, risk, line |
Computed once, at creation, and stored: what the human saw is what is audited |
detail (JSON) |
Screens 2…N, 80 characters each: three is what a page usually needs, and a long text continues on the extra screens instead of being cut |
payload (JSON), payload_sha256 |
The hook needs the payload back on resumption; the hash is the fingerprint used by the decision |
options (JSON) |
Up to four pre-seeded replies (A–D) |
state |
queued, delivered, read, decided, expired, cancelled |
created_at, delivered_at, read_at, expires_at |
Every latency in the product is a subtraction of two of these |
dedupe_key |
Idempotency: same key + same station + pending ⇒ one page |
callback_url |
The only clickable address, declared by the station, validated http(s) |
decisions
page_id (UNIQUE), device_id, verdict, choice_code, nonce,
signature, decided_at, latency_ms. The unique index is half of "at most one
accepted decision" (BIP-P-04); the in-process guard is the other half.
events — append-only
id, ts, type, page_id, source_id, device_id, fingerprint, data.
No UPDATE, no DELETE before retention (30 days by default). This table is the
only source of metrics: no counter lives in memory, so a restart never resets a
number and the video can quote a SELECT.
digest
id, source_id, ts, line — the events that did not deserve a page
(BIP-F-13). Same 80-character ASCII rule.
nonces
nonce, device_id, seen_at. The insert fails on replay, which is exactly the
check we want; rows older than the decision TTL are pruned.
4. State transitions
queued ──▶ delivered ──▶ read ──▶ decided
│ │ │
├─▶ expired ├─▶ decided │
├─▶ cancelled├─▶ expired │
│ ├─▶ cancelled
│ └─▶ read
packages/core/src/states.ts owns the table; applyTransitions folds a sequence
of requested moves and ignores illegal ones, so a duplicated WebSocket frame
cannot corrupt a page. stateGraphDot() produces the diagram in the README, and
the state-machine-guard hook regenerates it from the same source — the diagram
is never hand-edited.
A final state never changes again. An expired page is a refusal: on_expire is
deny, and nothing in the pipeline can turn an expiry into an approval.
5. One signed decision, end to end
1. Agent bip-hook reads {hook_event_name, cwd, tool_name, tool_input}
2. Hook rules.yaml → allow (exit 0) | deny (exit 2) | page
3. Hook ──POST /v1/pages──▶ Central
4. Central canonicalize(payload) → sha256 → fingerprint
classify → code + risk (max of segments)
composeLine(code, station, verb, subject, #fp)
budget + quiet hours (red and 9xx bypass)
INSERT pages, INSERT events(page.created)
5. Central ──WS/Push──▶ Pager "310 a PUSH main>origin 3 commits #07c2"
6. Human reads the line, presses ✔ (red: one-second hold)
7. Pager claims = {page_id, fingerprint, verdict, choice, nonce,
expires_at, device_id}
sig = ECDSA-P256(deviceKey, canonicalize(claims))
8. Pager ──POST /v1/pages/{id}/decision {claims, sig}──▶ Central
9. Central verify signature → device known and not revoked
→ claim fingerprint == page fingerprint
→ deadline not passed → nonce never seen
any failure ⇒ events(decision.rejected), nothing changes
success ⇒ INSERT decisions, events(page.decided, latency)
10. Hook long poll returns; re-checks the fingerprint; exit 0
11. Agent the tool runs, or does not, with a reason
Step 10 is the detail that makes the whole thing safe: the hook is the component that resumes a real command, so it verifies again rather than trusting the Central's word. An approval can therefore never be applied to another action than the one displayed — the orphan approvals metric is zero by construction, not by testing.
6. What is deliberately absent
No message broker, no second database, no cloud dependency, no account, no
microservice. The failure mode we optimised for is "the Central is down": hooks
fail closed, the pager shows OFFLINE, and nothing is silently approved.