Files

T

vh 78bfcadb9e feat(sse,tui): bump spec pin to v0.29.0 + AwaitingLlmFirstToken (v0.14.0)

Spec pin moved da93ca7 (v0.28.0) → 562001a (v0.29.0); vendored
conversation-api-spec.md + conversation_api.contract.md re-snapshotted.
The only material delta is Worldtree #201's awaiting_llm_first_token
SSE heartbeat — a top-level event (NOT a worker_phase extension, per
INV-053's three-field stability) that fires at a configurable interval
(default 5s) during the BuildingPrompt → CallingLLM gap.

Wire layer (sse_client.py):
- New `AwaitingLlmFirstToken` dataclass: sse_id / turn_id /
  elapsed_ms_since_building_prompt (server-authoritative monotonic)
- Added to Event union + _envelope_for_type dispatch branch
- Without this, ratatoskr would crash on any slow-first-token turn
  from a v0.29.0 server (unknown SSE event type → ValueError)

TUI layer (tui.py):
- Audit pipeline: per-event debug-pane line with elapsed in seconds
- Live transcript indicator: first heartbeat mounts a Static
  ("awaiting first token · 5.0s"); subsequent heartbeats update it
  in place; any non-heartbeat event removes it (the gap closed)
- Turn-summary line now carries heartbeat count
- Indicator demoted via .awaiting-label CSS so it reads as ambient
  progress, not content

Tests: 2 wire-layer (single + monotonic sequence) + 3 presenter
(audit line shape, single-mount semantic, indicator removal on gap
close). Suite: 318 passing.

2026-05-25 22:57:33 -07:00

4.9 KiB

Raw Permalink Blame History

Worldtree spec pin

Ratatoskr is built against a specific Worldtree commit. This file documents the pin, the vendored artifacts, and the bump procedure.

Current pin

Field	Value
Worldtree git SHA	`562001af28d752c3a60d449c7ddd09f44fa9dc9a`
Worldtree HEAD message	`feat(#201): v0.29.0 — awaiting_llm_first_token SSE heartbeat`
Pinned on	2026-05-26
Pinned by	ratatoskr-dev (bump for #201 awaiting_llm_first_token SSE)
Worldtree version at pin	`v0.29.0`

Pin history

Date	SHA	Version	Notable deltas consumed
2026-05-26	`562001a`	v0.29.0	#201 — new SSE event `awaiting_llm_first_token` (heartbeat during BuildingPrompt → CallingLLM gap, default 5s interval)
2026-05-25	`da93ca7`	v0.28.0	#204 — new SSE event `affect_update` (current/scheduled), new endpoint `GET /agents/{id}/persona_state`, auth-model doc edits
2026-05-20	`55101e9`	v0.19.0	initial scaffold pin

Vendored artifacts

docs/conversation-api-spec.md — copy of Worldtree/docs/conversation-api-spec.md at the pinned SHA. This is the client-facing interface contract Ratatoskr is built against.
docs/conversation_api.contract.md — copy of Worldtree/docs/contracts/conversation_api.contract.md at the pinned SHA. The server-side contract including INV-001..INV-052 and amendments. Useful for understanding load-bearing server invariants (e.g., INV-014 turn-id-public, INV-046 admin-events-envelope-stable, INV-049 admin-events-pii-discipline) when designing client behavior against them.

Both files are vendored — they reflect Worldtree at the pinned SHA, not the live ~/development/Worldtree checkout. Update them only when bumping the pin (see procedure below).

Why pin?

Ratatoskr's dev team is decoupled from Worldtree's dev team. The spec that Ratatoskr is built against can drift from live Worldtree without either team noticing. Pinning makes the version-mismatch explicit:

The pin SHA is what we built against.
When live Worldtree advances, our pin is stale until we explicitly bump.
A bump is a conscious action that triggers the re-recording of snapshot tests and a manual review of spec deltas.

Bump procedure

When you bump the pin, do all five steps in one commit:

Pick the new target SHA. Usually live Worldtree HEAD. Run:
```
git -C ~/development/Worldtree rev-parse HEAD
git -C ~/development/Worldtree log --oneline <old-sha>..HEAD -- docs/conversation-api-spec.md docs/contracts/conversation_api.contract.md
```
The second command shows every change to the spec files since the old pin. If it returns nothing, the spec hasn't changed and the bump is trivial (just update the SHA in this file + pyproject.toml).

Re-vendor the spec files. From ~/development/ratatoskr/:

cp ~/development/Worldtree/docs/conversation-api-spec.md docs/conversation-api-spec.md
cp ~/development/Worldtree/docs/contracts/conversation_api.contract.md docs/conversation_api.contract.md

Diff-review the vendored files. Look for breaking changes — renamed endpoints, changed SSE event shapes, removed fields, new required parameters, new invariants that affect client behavior, etc. Anything that breaks Ratatoskr should result in a corresponding code change in this commit OR a deliberate "don't support new feature yet" decision recorded in persistent-memory.md.

Re-record SSE snapshot tests. From ~/development/ratatoskr/:

# Boot a local Worldtree at the new SHA
( cd ~/development/Worldtree && python -m core.conversation_api ) &
# Re-record (specific command depends on the snapshot harness — TBD by dev team)
uv run pytest --record-snapshots tests/snapshots/

Update pyproject.toml and this file. Bump worldtree-spec-rev in pyproject.toml; update the "Current pin" table above with the new SHA, the new HEAD message, today's date, and your handle.

Commit with a message of this shape:

pin: bump Worldtree spec to <short-sha>

<summary of material spec deltas, or "no client-facing changes" if trivial>

- <bullet for each notable change that affected Ratatoskr code>

Conformance smoke check

Independent of the pin, Ratatoskr's CI runs a conformance smoke test that boots Worldtree (via Docker compose) and runs a one-turn happy path. This catches integration-level drift that snapshot replay misses — e.g., a Worldtree config change that breaks the auth handshake or the SSE framing without changing the spec docs.

If the smoke test fails while the snapshot tests pass, the discovery should route to worldtree-dev via althing (the spec didn't change but Worldtree's behavior did — that's a worldtree-side concern).

History

Date	SHA	Note
2026-05-20	`55101e9`	Initial pin (scaffold). Worldtree v0.19.0 — #177 Vili v1 + persona async-decouple.

4.9 KiB Raw Permalink Blame History