Quelle: ddx-documentation/realtime.md
Centrifugo is the only browser realtime path (plan osprey-engine, owner D7). The template SSE gateway, the inbound webhook route, `lib/sse` and the SSE event catalog are removed. Postgres `osprey.event` is the authority: Centrifugo only delivers. ## Path ``` engine lane --append--> osprey.event + osprey.outbox (one transaction, revision under a row lock) osprey.outbox --relay--> Centrifugo HTTP API (127.0.0.1:9651) --> browser SDK (127.0.0.1:9650) browser --token--> ddx-web BFF /api/v1/realtime/* --> ddx-api /realtime/* (ownership check, JWT) browser --snapshot--> ddx-web BFF /api/v1/osprey/sessions/:id/snapshot --> ddx-api --> engine --> Postgres ``` - **Event log.** `ddx-osprey-engine/src/events/event-log.ts` locks the session row, assigns contiguous revisions and inserts the event rows and one outbox row per event per channel in the same transaction. Every envelope is validated with `@ddx/contracts/osprey-events` first. - **Outbox relay.** `src/events/outbox-relay.ts` claims rows under a lease (8 groups, 15 s lease, 200 rows per tick) and publishes them in `(channel, revision)` order. A failed row backs off and is retried; the channel never skips ahead. A crash between publish and `published_at` gives a duplicate delivery, which the browser drops by `eventId` / revision. - **Wake.** `append()` runs `pg_notify('osprey_outbox', relayPool)` inside its transaction (delivered on commit only). The relay LISTENs on a dedicated `pg.Client` and the notify ends the idle sleep; a commit signalled mid-tick skips the next sleep. A lost LISTEN connection is logged and retried every 1 s. The 250 ms poll stays as the delivery fallback. - **4-way publish.** Rows are grouped by channel; up to 4 channels publish side by side. Inside one channel publishing stays serial, with the `published_at` mark pipelined (at most 1 in flight, always after its publish), so per-channel order holds. - **Measured** (plan osprey-playground-v2 task 003, `findings/osprey-playground-v2/stream-latency.md`): commit to publish p50 / p95 fell from 187 / 364 ms to 10 / 26 ms; engine event timestamp to browser EventSource p50 / p95 is 43 / 96 ms. - **Persisted coalesced deltas.** Rows stay token-level (about 330 rows per 300-token answer). `run-stream.ts` buffers `text.delta`, `reasoning.delta` and `tool.input.delta` for at most 40 ms; the first delta of a stream, the first `text.delta` and any non-delta event flush at once (first-token latency). A part closes with `text.end` / `reasoning.end`, which carries the full text. The plan called this event `text.final`; it shipped as `text.end`. At most 25 appends per second per run (measured maximum 15). - **Channels.** `session:<sessionId>` (contiguous revisions) and `run:<runId>` (not contiguous). Ids carry no tenant or user data. `user:<id>` and `org:<id>` carry delivery-only hints from ddx-api (`entity.changed`, `notification`, `settings.changed`); a hint holds no state a client trusts. - **Centrifugo config** (`ddx-docker-centrifugo/config.json`): namespaces `session` (history 300, 24 h), `run` (history 1000, 24 h), `user` and `org` (history 100, 1 h); `force_recovery` on all, `force_positioning` on `session` and `run`; SSE and `http_stream` enabled; subscription tokens on. History and offsets speed up recovery. They are never read as authority. ## Transport: SSE first, WebSocket fallback The browser SDK uses `/connection/sse` with `/emulation` for client-to-server calls, and falls back to WebSocket. It never uses `/connection/uni_sse` (no recovery). One connection per tab. The SDK owns the transports; no widget calls `new EventSource`. `NEXT_PUBLIC_REALTIME_URL` (dev: `http://127.0.0.1:9650`) unset means the manager stays `unconfigured` and nothing connects. Client code: `ddx-web/src/lib/realtime/` (`client.ts`, `tokens.ts`, `manager.ts`, `reconciler.ts`, `status.ts`), provider `components/providers/RealtimeProvider.tsx`, hint mount `RealtimeHintScope.tsx`. Contract: `ddx-web/src/lib/realtime/CLAUDE.md`. ## Resnapshot by revision The reconciler runs per channel: authorizing, subscribing, buffering, live, recovering, resync, plus denied. Publications are buffered until the Postgres snapshot (`GET /api/v1/osprey/sessions/:id/snapshot?afterRevision=n`) is applied. Then only `revision > lastRevision` applies, deduplicated by `eventId`. A resync starts on: a `subscribed` event with `wasRecovering && !recovered`, a revision gap, a buffer over 500 events, and a page `visibility` or `online` change. Snapshot retries back off up to 5 times, then wait for the next trigger. Each tab keeps its own position; there is no cross-tab cursor. ### Snapshot paging and compaction `GET /api/v1/osprey/sessions/:id/snapshot` takes `afterRevision` plus two optional fields (`@ddx/contracts/osprey-commands` `SnapshotQuerySchema`): - `tailTurns` (1 to 500): only the newest N turns. The window start is computed and `afterRevision` is ignored. The answer adds `hasOlder` and `olderBeforeRevision`. - `beforeRevision`: exclusive upper bound, in both modes. - A full answer can be paged: `hasMore` plus `nextAfterRevision`. Browser order (`getSnapshotAllPages` in `ddx-web/src/lib/osprey/commands.ts`): first load `?tailTurns=100`; a page caps at 500 rows, so page forward with `afterRevision = nextAfterRevision` and the same `beforeRevision`, WITHOUT `tailTurns` (tail mode recomputes the window and ignores `afterRevision`), while `hasMore`. "Load earlier": `?tailTurns=100&beforeRevision=<olderBeforeRevision>`, merged in front of the held turns (`mergeEarlierTurns` in `ddx-web/src/lib/osprey/reducer.ts`; the live reducer rejects `revision <= lastRevision`). Stop when `hasOlder` is false. Compaction (`ddx-osprey-engine/src/events/snapshot.ts`, default on): a part closed by `text.end` or `reasoning.end` ships its end row only (its start and delta rows are dropped; a `reasoning.start` with `level` is kept); only the newest `progress` row per run is kept; every other row is kept. A part still open keeps all its rows. The log in Postgres is never rewritten. Measured on a 500-turn seed: rows 23037 to 3585, bytes 8.68 MB to 1.50 MB; the rebuilt turns equal the uncompacted rebuild. The size control for a long session is the tail window, not compaction alone. ## Run graph (plan osprey-run-graph) The run graph is NOT a new realtime path and adds no endpoint, no channel and no event type. It is a second projection of the SAME `osprey.event` rows the panel already receives: the web projector (`ddx-web/src/lib/osprey/projector.ts`) calls the pure `projectRunGraph` (`ddx-web/src/lib/osprey/run-graph.ts`) and stores the result in `SessionView.runGraphs`, one graph per run. Live rows and a compacted snapshot fold deep-equal, because the fold reads no `text.*` / `reasoning.*` event and the snapshot drops only those rows plus superseded `progress` rows. The graph therefore survives a resnapshot, a reconnect and a fork like every other turn state, and it adds nothing to outbox size. - **Nodes.** A plan run: one node per plan node of the last `plan.drafted` (final or legacy) or `plan.mutated`, with `dependsOn` and container edges. A react run: one `llm-step` node per `llm.step.started`, one leaf per `toolCallId`. Node keys are `${runId}:${nodeId}`, `${runId}:llm:${stepIndex}`, `${runId}:call:${toolCallId}` and `${runId}:unattributed`. - **Parent of a call.** `tool.call` / `tool.result` carry the plan node id in the optional `stepId`; a react call hangs under the last `llm.step.started` of its run; an ambiguous old row joins the `unattributed` group. - **Layout.** Keyed by a topology signature of node and edge keys, so a status-only event re-renders the node and keeps the layout object. `@xyflow/react` is loaded through `next/dynamic` when the Run tab opens, never before. - **What it does not carry.** No tool input or output payload is copied into the graph — a call leaf holds `toolCallId` and the detail panel reads the `ToolPart` of the turn (outbox size, PII). ## Event protocol mapping `OspreyEvent` plus the Postgres `revision` is the only authority. AI SDK UI and AG-UI shapes are edge adapters; the web reducer (`ddx-web/src/lib/osprey/turns.ts`) is the AI SDK edge, with part names equal to AI SDK names. The AG-UI endpoint is deferred. Union and fields: `packages/ddx-contracts/src/osprey-events.ts` (closed; an unknown type is counted and dropped by the browser). Every field added to an existing type is optional, so old rows still parse; an old row with no `partId` opens one implicit part per run segment. | Osprey event | Data | AI SDK UI part | AG-UI (deferred) | Mastra chunk | |---|---|---|---|---| | `text.start` / `text.delta` / `text.end` | `{partId}` / `{partId?, delta}` / `{partId, text}` | `text`, streaming to done | `TEXT_MESSAGE_START/CONTENT/END` | `text-start/delta/end` | | `reasoning.start` / `.delta` / `.end` | same, `level?` on start | `reasoning` | `REASONING_MESSAGE_*` | `reasoning-start/delta/end` | | `llm.step.started` / `llm.step.finished` | `{stepIndex}` / `{stepIndex, finishReason, rawReason?}` | `step-start` | `STEP_STARTED/FINISHED` | `step-start` / `step-finish` | | `tool.input.started` / `tool.input.delta` | `{toolCallId, toolId}` / `{toolCallId, delta}` | tool part `input-streaming` | `TOOL_CALL_START/ARGS` | `tool-call-input-streaming-start`, `tool-call-delta` | | `plan.bound` / `plan.rejected` | `{planId, version, ok, bindings[], clarify?}` / `{planId, version, attempt, stage, issues[]}` | build strip (`data-graph-build`) | not mapped | engine plan lane | | `plan.drafted` / `plan.mutated` | `{plan, phase?, attempt?}` / `{plan, diff}` | build strip and version stepper | not mapped | engine plan lane | | `tool.call` / `tool.result` | unchanged, plus `stepId?` (plan node id) | `input-available` / `output-available` or `output-error` | `TOOL_CALL_END` / `TOOL_CALL_RESULT` | `tool-call` / `tool-result`, `tool-error` | | `run.suspended` | adds `toolCallId?`, `binding?` `{toolCallId?, nodeId?, toolId, fingerprint, summary, expiresAt?}` | `approval-requested` | `RUN_FINISHED` outcome interrupt | `tool-call-approval`, `tool-call-suspended` | | `tool.resumed` | `{toolCallId, kind: approval or suspension}` | `approval-responded` | `RUN_STARTED` with resume | `tool-call-resumed` | | `tool.denied` | `{toolCallId, reason?}` | `output-denied` | `TOOL_CALL_RESULT` with error | `tool-output-denied` | | `approval.invalidated` | `{stepId, reason, previous}` | tool part back to `approval-requested` | new interrupt | engine policy | | `guard.tripwire` | `{processorId, reason, retry}` | `data-osprey-guard` | `CUSTOM` | `tripwire` | | `run.failed` | adds `kind?` (`provider`, `timeout`, `policy`, `internal`), `rawReason?` | `error` | `RUN_ERROR` | `finish` rawReason, `error` | | `run.cancelled` | `{by: user, reason?}` | `abort` | `RUN_ERROR` code cancelled | `abort` | | `session.titled` | `{title, source: first-turn, model or user}` | `data-thread-title` | `CUSTOM` | engine summariser | | `session.forked` | `{fromSessionId, uptoTurnId, uptoRevision}` (first live row of a fork) | marker | marker | engine fork | | `turn.regenerated` | `{turnId, ofTurnId}` | marker | marker | engine regenerate | | `attachment.ingested` | `{mediaId, status}` (scope session) | marker | marker | engine file ingest | | `voice.reply` | `{mode: tagged or fallback, length?: short, normal or long, speakable, readable, sentences, chars, capped}` (scope turn, no runId; one per voice turn) | marker (`turn.voice`) | `CUSTOM` | engine voice session | | `ui.block` | `blockId` replaces in place | `data-osprey-block` | `ACTIVITY_SNAPSHOT` | `data-osprey` | Terminal run events: `run.finished`, `run.failed`, `run.stalled`, `run.cancelled`. The event log drops any draft that follows a terminal event of the same run (`dropAfterTerminal`, under the session row lock). ## Deep-content progress and card A background deep-content run (module `osprey-deep-content`, `@ddx/contracts/osprey-deep-content`) adds no event type. Its progress rides the existing `progress` event in the optional `data.deep` field (`DeepContentProgress`: `runId`, `phase`, `value` 0..1, `sectionIndex`, `sectionCount`, `sectionTitle`, `delta` markdown chunk, `sourcesFound`, `documentId`, `error`). `DeepEmitter` (`ddx-osprey-engine/src/deep-content/emit.ts`) appends it through `event-log.ts` only: section deltas are batched at 400 chars or 750 ms, and a run ends with exactly one terminal phase (`done`, `failed` or `cancelled`). A deep progress row carries no `turnId`. Snapshot compaction keeps the newest `progress` row per run, so a replay shows the latest phase; the full text comes from `GET /deep-runs/:id/document`. The chat shows the run as a `ui.block` of kind `deep-content` (`runId` = `dcr_<id>`), emitted by the engine `start_deep_content` tool; the web reducer keeps the live state in `deepRuns`, keyed by the deep run id. ## Token routes (ddx-api) Browser path `/api/v1/realtime/*`; the BFF strips `/api/v1`. Session JWT only. Full shapes: [api/osprey-api.openapi.yaml](./api/osprey-api.openapi.yaml). | Route | Purpose | |---|---| | `GET /realtime/connection-token` | Connection JWT for the SDK | | `GET /realtime/subscription-token?channel=` | Subscription JWT for one channel, after an ownership check | - Both answers carry `Cache-Control: no-store`; the BFF fetches with `cache: 'no-store'` and the browser never stores a token. - The connection key and the subscription key differ; boot refuses equal keys. Claims: `sub`, `iss=ddx-api`, `aud=osprey-centrifugo`, `iat`, `exp` (at most 600 s by contract); subscription tokens add `channel`. No `info`, no publish, history or presence grant. - Access: `user:<id>` is the caller only; `org:<id>` is the signed active org with at least one role; `session:` and `run:` resolve through `OspreySession` / `OspreyRunRef` ownership. An unregistered namespace is 403 (fail closed). A channel name never grants access. - Refresh is a new token request; the guard and the policy run again each time. - Revocation: sign-out calls `revokeUser` (targeted disconnect). Open item from the lead notes: a stolen session JWT can still mint a token for up to 900 s after sign-out, because `CredentialGuard` has no liveness check. It is assigned to a security review and is not fixed. - Centrifugo down gives 503 (3 s bound, no retry). The API key and both HMAC secrets stay in ddx-api. Env keys (ddx-api): `DDX_API_CENTRIFUGO_API_URL`, `DDX_API_CENTRIFUGO_HTTP_API_KEY`, `DDX_API_CENTRIFUGO_TOKEN_HMAC_SECRET`, `DDX_API_CENTRIFUGO_SUB_TOKEN_HMAC_SECRET`, `DDX_API_REALTIME_TOKEN_TTL_S`. Engine keys: `CENTRIFUGO_API_URL`, `CENTRIFUGO_HTTP_API_KEY`. Browser key: `NEXT_PUBLIC_REALTIME_URL`. Names only; values never go in the docs. ## Voice audio transport Binary voice audio never rides Centrifugo. [ADR 0020](/de/docs/adr/0020-voice-audio-transport) decides the path: engine voice gateway WebSocket on 127.0.0.1:9631 <- ddx-api relay `/osprey/voice` (session JWT, ownership, single-use voice ticket) <- browser through the ddx-web BFF route class `stream-voice` (streamed GET down, sequenced POST frames up). Final transcripts, speak segments, tool and UI-control events are appended to `osprey.event` and reach the browser on Centrifugo as above; interim captions and playback control stay on the voice path. `voice.reply` is the one durable row a voice turn adds: a normal `osprey.event` row (scope `turn`, no `runId`, so the terminal-run guard never drops it), relayed like every other row. `speakable` is the text the user saw spoken (the admitted caption display sentences), `readable` the screen markdown, `capped` true when the speech budget cut the reply. The web projector turns it into `TurnView.voice` and `OspreyTurn` shows a "spoken" disclosure; it never opens a turn. Caption frames (voice path only, not durable): `text` is the DISPLAY text of the chunk ("115/95 mmHg"), the optional `spoken` field is the TTS text sent to the voice ("one hundred fifteen over ninety-five mmHg"). Clients show `text`. Browser down-leg frames (length-prefixed, `GET /osprey/voice/:streamId`): kind 1 = PCM16 24 kHz audio, kind 2 = control JSON, kind 3 = `open` (empty; ddx-api writes it first so the Next BFF flushes the response headers). The up leg (`POST /osprey/voice/:streamId/frames`, header `x-osprey-voice-seq`) carries PCM16 16 kHz frames of at most 100 ms. Both legs are pinned to one node (`STREAM_CLASSES`). Engine and port: [osprey-engine.md](/de/docs/osprey-engine) §Voice, [ports.md](/de/docs/ports). ## CSP `ddx-web/next.config.ts` builds `connect-src` with the `NEXT_PUBLIC_REALTIME_URL` origin in both `http` and `ws` form. Without it the browser could not reach Centrifugo (found in the task 037 browser proof and fixed there). ## Not realtime The BFF cluster node watch (`ddx-web/src/lib/bff/bff-node-registry.server.ts` and ddx-api `/cluster/nodes/watch`) still uses `text/event-stream`. It is server-to-server control plane, not browser realtime. The lead kept it as the one exception to "no SSE in ddx-api"; a poll-only redesign is deferred. ## Verification evidence Two-tab convergence, Centrifugo restart recovery and engine reboot are recorded in `findings/osprey-engine/judge/` (`two-tab.md`, `centrifugo-restart.md`, `engine-reboot-browser.md`). The engine acks each `actionId` once (advisory lock plus existence check in `ackUiAction`); rows written before that fix in dev session `ses_23b5bc84` keep their duplicate because the log is append-only. --- Last reconciled: 2026-11-16 · plan osprey-run-graph task 010 (run graph fold, build events, stepId)
Centrifugo is the only browser realtime path (plan osprey-engine, owner D7). The template SSE
gateway, the inbound webhook route, lib/sse and the SSE event catalog are removed. Postgres
osprey.event is the authority: Centrifugo only delivers.
ddx-osprey-engine/src/events/event-log.ts locks the session row, assigns
contiguous revisions and inserts the event rows and one outbox row per event per channel in the
same transaction. Every envelope is validated with @ddx/contracts/osprey-events first.src/events/outbox-relay.ts claims rows under a lease (8 groups, 15 s lease,
200 rows per tick) and publishes them in (channel, revision) order. A failed row backs off and is
retried; the channel never skips ahead. A crash between publish and published_at gives a duplicate
delivery, which the browser drops by eventId / revision.
append() runs pg_notify('osprey_outbox', relayPool) inside its transaction (delivered on
commit only). The relay LISTENs on a dedicated pg.Client and the notify ends the idle sleep; a commit
signalled mid-tick skips the next sleep. A lost LISTEN connection is logged and retried every 1 s. The
250 ms poll stays as the delivery fallback.published_at mark pipelined (at most 1 in flight, always after its
publish), so per-channel order holds.findings/osprey-playground-v2/stream-latency.md):
commit to publish p50 / p95 fell from 187 / 364 ms to 10 / 26 ms; engine event timestamp to browser
EventSource p50 / p95 is 43 / 96 ms.run-stream.ts
buffers text.delta, reasoning.delta and tool.input.delta for at most 40 ms; the first delta of a stream,
the first text.delta and any non-delta event flush at once (first-token latency). A part closes with
text.end / reasoning.end, which carries the full text. The plan called this event text.final; it shipped
as text.end. At most 25 appends per second per run (measured maximum 15).session:<sessionId> (contiguous revisions) and run:<runId> (not contiguous).
Ids carry no tenant or user data. user:<id> and org:<id> carry delivery-only hints from
ddx-api (entity.changed, notification, settings.changed); a hint holds no state a client trusts.ddx-docker-centrifugo/config.json): namespaces session (history 300,
24 h), run (history 1000, 24 h), user and org (history 100, 1 h); force_recovery on all,
force_positioning on session and run; SSE and http_stream enabled; subscription tokens on.
History and offsets speed up recovery. They are never read as authority.The browser SDK uses /connection/sse with /emulation for client-to-server calls, and falls back
to WebSocket. It never uses /connection/uni_sse (no recovery). One connection per tab. The SDK owns
the transports; no widget calls new EventSource. NEXT_PUBLIC_REALTIME_URL (dev:
http://127.0.0.1:9650) unset means the manager stays unconfigured and nothing connects.
Client code: ddx-web/src/lib/realtime/ (client.ts, tokens.ts, manager.ts, reconciler.ts,
status.ts), provider components/providers/RealtimeProvider.tsx, hint mount RealtimeHintScope.tsx.
Contract: ddx-web/src/lib/realtime/CLAUDE.md.
The reconciler runs per channel: authorizing, subscribing, buffering, live, recovering, resync,
plus denied. Publications are buffered until the Postgres snapshot
(GET /api/v1/osprey/sessions/:id/snapshot?afterRevision=n) is applied. Then only
revision > lastRevision applies, deduplicated by eventId.
A resync starts on: a subscribed event with wasRecovering && !recovered, a revision gap, a
buffer over 500 events, and a page visibility or online change. Snapshot retries back off up to
5 times, then wait for the next trigger. Each tab keeps its own position; there is no cross-tab cursor.
GET /api/v1/osprey/sessions/:id/snapshot takes afterRevision plus two optional fields
(@ddx/contracts/osprey-commands SnapshotQuerySchema):
tailTurns (1 to 500): only the newest N turns. The window start is computed and afterRevision is ignored.
The answer adds hasOlder and olderBeforeRevision.beforeRevision: exclusive upper bound, in both modes.hasMore plus nextAfterRevision.Browser order (getSnapshotAllPages in ddx-web/src/lib/osprey/commands.ts): first load ?tailTurns=100; a page caps at 500 rows, so
page forward with afterRevision = nextAfterRevision and the same beforeRevision, WITHOUT tailTurns (tail mode recomputes the
window and ignores afterRevision), while hasMore.
"Load earlier": ?tailTurns=100&beforeRevision=<olderBeforeRevision>, merged in front of the held turns
(mergeEarlierTurns in ddx-web/src/lib/osprey/reducer.ts; the live reducer rejects revision <= lastRevision).
Stop when hasOlder is false.
Compaction (ddx-osprey-engine/src/events/snapshot.ts, default on): a part closed by text.end or reasoning.end
ships its end row only (its start and delta rows are dropped; a reasoning.start with level is kept); only the
newest progress row per run is kept; every other row is kept. A part still open keeps all its rows. The log in
Postgres is never rewritten. Measured on a 500-turn seed: rows 23037 to 3585, bytes 8.68 MB to 1.50 MB; the rebuilt
turns equal the uncompacted rebuild. The size control for a long session is the tail window, not compaction alone.
The run graph is NOT a new realtime path and adds no endpoint, no channel and no event type. It is a
second projection of the SAME osprey.event rows the panel already receives: the web projector
(ddx-web/src/lib/osprey/projector.ts) calls the pure projectRunGraph
(ddx-web/src/lib/osprey/run-graph.ts) and stores the result in SessionView.runGraphs, one graph per
run. Live rows and a compacted snapshot fold deep-equal, because the fold reads no text.* /
reasoning.* event and the snapshot drops only those rows plus superseded progress rows. The graph
therefore survives a resnapshot, a reconnect and a fork like every other turn state, and it adds
nothing to outbox size.
plan.drafted (final or legacy) or
plan.mutated, with dependsOn and container edges. A react run: one llm-step node per
llm.step.started, one leaf per toolCallId. Node keys are ${runId}:${nodeId},
${runId}:llm:${stepIndex}, ${runId}:call:${toolCallId} and ${runId}:unattributed.tool.call / tool.result carry the plan node id in the optional stepId;
a react call hangs under the last llm.step.started of its run; an ambiguous old row joins the
unattributed group.@xyflow/react is loaded through next/dynamic when the Run
tab opens, never before.toolCallId and the detail panel reads the ToolPart of the turn (outbox size, PII).OspreyEvent plus the Postgres revision is the only authority. AI SDK UI and AG-UI shapes are edge adapters; the
web reducer (ddx-web/src/lib/osprey/turns.ts) is the AI SDK edge, with part names equal to AI SDK names. The AG-UI
endpoint is deferred. Union and fields: packages/ddx-contracts/src/osprey-events.ts (closed; an unknown type is
counted and dropped by the browser). Every field added to an existing type is optional, so old rows still parse; an
old row with no partId opens one implicit part per run segment.
Terminal run events: run.finished, run.failed, run.stalled, run.cancelled. The event log drops any draft
that follows a terminal event of the same run (dropAfterTerminal, under the session row lock).
A background deep-content run (module osprey-deep-content, @ddx/contracts/osprey-deep-content) adds no event type.
Its progress rides the existing progress event in the optional data.deep field (DeepContentProgress: runId,
phase, value 0..1, sectionIndex, sectionCount, sectionTitle, delta markdown chunk, sourcesFound,
documentId, error). DeepEmitter (ddx-osprey-engine/src/deep-content/emit.ts) appends it through
event-log.ts only: section deltas are batched at 400 chars or 750 ms, and a run ends with exactly one terminal phase
(done, failed or cancelled). A deep progress row carries no turnId. Snapshot compaction keeps the newest
progress row per run, so a replay shows the latest phase; the full text comes from GET /deep-runs/:id/document.
The chat shows the run as a ui.block of kind deep-content (runId = dcr_<id>), emitted by the engine
start_deep_content tool; the web reducer keeps the live state in deepRuns, keyed by the deep run id.
Browser path /api/v1/realtime/*; the BFF strips /api/v1. Session JWT only. Full shapes:
.
Cache-Control: no-store; the BFF fetches with cache: 'no-store' and the
browser never stores a token.sub,
iss=ddx-api, aud=osprey-centrifugo, iat, exp (at most 600 s by contract); subscription
tokens add channel. No info, no publish, history or presence grant.user:<id> is the caller only; org:<id> is the signed active org with at least one
role; session: and run: resolve through OspreySession / OspreyRunRef ownership. An
unregistered namespace is 403 (fail closed). A channel name never grants access.revokeUser (targeted disconnect). Open item from the lead notes: a stolen
session JWT can still mint a token for up to 900 s after sign-out, because CredentialGuard has no
liveness check. It is assigned to a security review and is not fixed.Env keys (ddx-api): DDX_API_CENTRIFUGO_API_URL, DDX_API_CENTRIFUGO_HTTP_API_KEY,
DDX_API_CENTRIFUGO_TOKEN_HMAC_SECRET, DDX_API_CENTRIFUGO_SUB_TOKEN_HMAC_SECRET,
DDX_API_REALTIME_TOKEN_TTL_S. Engine keys: CENTRIFUGO_API_URL, CENTRIFUGO_HTTP_API_KEY.
Browser key: NEXT_PUBLIC_REALTIME_URL. Names only; values never go in the docs.
Binary voice audio never rides Centrifugo. decides
the path: engine voice gateway WebSocket on 127.0.0.1:9631 <- ddx-api relay /osprey/voice
(session JWT, ownership, single-use voice ticket) <- browser through the ddx-web BFF route class
stream-voice (streamed GET down, sequenced POST frames up). Final transcripts, speak segments,
tool and UI-control events are appended to osprey.event and reach the browser on Centrifugo as
above; interim captions and playback control stay on the voice path.
voice.reply is the one durable row a voice turn adds: a normal osprey.event row (scope turn, no runId, so the
terminal-run guard never drops it), relayed like every other row. speakable is the text the user saw spoken (the
admitted caption display sentences), readable the screen markdown, capped true when the speech budget cut the reply.
The web projector turns it into TurnView.voice and OspreyTurn shows a "spoken" disclosure; it never opens a turn.
Caption frames (voice path only, not durable): text is the DISPLAY text of the chunk ("115/95 mmHg"), the optional
spoken field is the TTS text sent to the voice ("one hundred fifteen over ninety-five mmHg"). Clients show text.
Browser down-leg frames (length-prefixed, GET /osprey/voice/:streamId): kind 1 = PCM16 24 kHz audio, kind 2 = control
JSON, kind 3 = open (empty; ddx-api writes it first so the Next BFF flushes the response headers). The up leg
(POST /osprey/voice/:streamId/frames, header x-osprey-voice-seq) carries PCM16 16 kHz frames of at most 100 ms.
Both legs are pinned to one node (STREAM_CLASSES). Engine and port: §Voice,
.
ddx-web/next.config.ts builds connect-src with the NEXT_PUBLIC_REALTIME_URL origin in both
http and ws form. Without it the browser could not reach Centrifugo (found in the task 037
browser proof and fixed there).
The BFF cluster node watch (ddx-web/src/lib/bff/bff-node-registry.server.ts and ddx-api
/cluster/nodes/watch) still uses text/event-stream. It is server-to-server control plane, not browser
realtime. The lead kept it as the one exception to "no SSE in ddx-api"; a poll-only redesign is deferred.
Two-tab convergence, Centrifugo restart recovery and engine reboot are recorded in
findings/osprey-engine/judge/ (two-tab.md, centrifugo-restart.md, engine-reboot-browser.md).
The engine acks each actionId once (advisory lock plus existence check in ackUiAction); rows written
before that fix in dev session ses_23b5bc84 keep their duplicate because the log is append-only.
Last reconciled: 2026-11-16 · plan osprey-run-graph task 010 (run graph fold, build events, stepId)
adr/
deploy/
research/
engine lane --append--> osprey.event + osprey.outbox (one transaction, revision under a row lock)osprey.outbox --relay--> Centrifugo HTTP API (127.0.0.1:9651) --> browser SDK (127.0.0.1:9650)browser --token--> ddx-web BFF /api/v1/realtime/* --> ddx-api /realtime/* (ownership check, JWT)browser --snapshot--> ddx-web BFF /api/v1/osprey/sessions/:id/snapshot --> ddx-api --> engine --> Postgres