vh/ratatoskr
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity

Presenter contract semantics amendment: stateful event coalescing + telemetry demotion #12

New Issue
Closed
opened 2026-05-23 15:11:11 -07:00 by vh · 1 comment
vh commented 2026-05-23 15:11:11 -07:00
Owner
Copy Link
Copy Source

Context

A 2026-05-23 mimir smoke against personal Worldtree (post-issues #5 + #6 commit 804c2df / v0.1.0) exposed multiple presenter UX issues that materially degrade the observability surface ratatoskr is supposed to provide.

Headline problem: thinking tokens render one-per-line. Worldtree streams thinking as token-deltas (just like text), but the current renderers (cli._render_event and tui._render_event_to_log) write [thinking] '<token>'\n per delta. A 50-token thinking phase = 50 lines of [thinking] spam.

Broader scope: every demoted-telemetry event renders with the same visual weight as actual model output, drowning the load-bearing signal. Specific issues:

  • thinking deltas: 50-line spam (above)
  • text_boundary: appears inline mid-text, breaking sentences visually
  • worker_phase: in-transcript with no visual demotion
  • ToolStart / ToolResult: same telemetry-vs-transcript tension
  • duration_ms / usage dict: unformatted (duration_ms=5467, usage={'prompt_tokens': ..., ...})
  • [done] on stderr interleaves with stdout text in a real terminal

Mission constraint

Per persistent-memory: "the product IS the observability surface; chat is the input mechanism." Suppressing events is the wrong direction. The right direction is rendering them cleanly, with editorial judgment about what's load-bearing transcript (Text / Done / Error / Cancelled) vs demoted telemetry (WorkerPhase / Thinking / TextBoundary / ToolStart / ToolResult).

A refined mission lens emerged from this smoke: "the observability surface presented at the right zoom level for the operator's task." Per-event raw streaming is the wrong zoom for normal debugging; coalesced thinking + demoted telemetry is the right zoom.

Scope

  • Both presenters (cli --send + Textual TUI).
  • Editorial demotion of telemetry events.
  • Thinking-coalesce (single growing line in cli; single growing widget in tui).
  • Duration + usage formatting.
  • TTY-interleave fix between stdout (text) and stderr (meta).
  • Dedicated TUI Static(id="thinking-current") widget for live thinking state (chronological-in-RichLog + always-visible-in-widget = two views same data).

Out of scope

  • New public flags (--quiet, --verbose, --debug). Decision: ship flag-less; revisit if a real pipe-to-jq use case appears.
  • Side-pane work (AdminEvents, Persona, Tools, BifrostState, ServerLog per design-brief §5). The dedicated thinking widget added here is the foundation, but it's not a "Persona pane" or "AdminEvents pane" yet.
  • i18n / locale-aware duration formatting. English-only Vuong-only.
  • Cross-process resume / transcript persistence. Per design-brief §8d, deferred to v2.

Design pass

Sent the design questions to eitri-smithy-dev for a cross-frontier-model technical pass before contract authoring. Thread 01KSBE52YZR5E3SPTKA672JE43. Tactical calls (closure trigger, formatting, edge cases) will be applied directly to the contract; architectural-shape calls (mission refinement, widget yes/no, flag policy, editorial promotion line) will route through the operator.

Acceptance

  • Two parallel contract amendments to issues #3 (cli) and #4 (tui) landing in one commit.
  • Mid-conversation mimir smoke produces a transcript where:
    • Thinking renders as one coalesced growing line/widget (not N lines).
    • Telemetry events visually demoted (· prefix in cli, dim style in tui).
    • duration_ms displayed as 5.5s / 347ms / 1.2m.
    • usage displayed as natural-language flow.
    • [done] line lands on its own line after a clean stdout flush.
  • TUI: dedicated Static(id="thinking-current") widget shows current thinking state, mirrors content into RichLog as chronological dimmed entries.
  • All existing tests + new rendering tests GREEN under uv run pytest tests/.
  • uv run ruff check src/ tests/ clean.

Version posture

v0.1.0 → v0.2.0 (minor). Output shape changes; scripts grepping [thinking] '<token>' would break. Pre-v1.x means breaking changes are minor.

## Context A 2026-05-23 mimir smoke against personal Worldtree (post-issues #5 + #6 commit `804c2df` / v0.1.0) exposed multiple presenter UX issues that materially degrade the observability surface ratatoskr is supposed to provide. **Headline problem:** thinking tokens render one-per-line. Worldtree streams thinking as token-deltas (just like text), but the current renderers (`cli._render_event` and `tui._render_event_to_log`) write `[thinking] '<token>'\n` per delta. A 50-token thinking phase = 50 lines of `[thinking]` spam. **Broader scope:** every demoted-telemetry event renders with the same visual weight as actual model output, drowning the load-bearing signal. Specific issues: - thinking deltas: 50-line spam (above) - text_boundary: appears inline mid-text, breaking sentences visually - worker_phase: in-transcript with no visual demotion - ToolStart / ToolResult: same telemetry-vs-transcript tension - duration_ms / usage dict: unformatted (`duration_ms=5467`, `usage={'prompt_tokens': ..., ...}`) - [done] on stderr interleaves with stdout text in a real terminal ## Mission constraint Per persistent-memory: "the product IS the observability surface; chat is the input mechanism." Suppressing events is the wrong direction. The right direction is rendering them cleanly, with editorial judgment about what's load-bearing transcript (Text / Done / Error / Cancelled) vs demoted telemetry (WorkerPhase / Thinking / TextBoundary / ToolStart / ToolResult). A refined mission lens emerged from this smoke: "the observability surface presented at the right zoom level for the operator's task." Per-event raw streaming is the wrong zoom for normal debugging; coalesced thinking + demoted telemetry is the right zoom. ## Scope - Both presenters (cli `--send` + Textual TUI). - Editorial demotion of telemetry events. - Thinking-coalesce (single growing line in cli; single growing widget in tui). - Duration + usage formatting. - TTY-interleave fix between stdout (text) and stderr (meta). - Dedicated TUI `Static(id="thinking-current")` widget for live thinking state (chronological-in-RichLog + always-visible-in-widget = two views same data). ## Out of scope - New public flags (`--quiet`, `--verbose`, `--debug`). Decision: ship flag-less; revisit if a real pipe-to-jq use case appears. - Side-pane work (AdminEvents, Persona, Tools, BifrostState, ServerLog per design-brief §5). The dedicated thinking widget added here is the foundation, but it's not a "Persona pane" or "AdminEvents pane" yet. - i18n / locale-aware duration formatting. English-only Vuong-only. - Cross-process resume / transcript persistence. Per design-brief §8d, deferred to v2. ## Design pass Sent the design questions to eitri-smithy-dev for a cross-frontier-model technical pass before contract authoring. Thread `01KSBE52YZR5E3SPTKA672JE43`. Tactical calls (closure trigger, formatting, edge cases) will be applied directly to the contract; architectural-shape calls (mission refinement, widget yes/no, flag policy, editorial promotion line) will route through the operator. ## Acceptance - Two parallel contract amendments to issues #3 (cli) and #4 (tui) landing in one commit. - Mid-conversation mimir smoke produces a transcript where: - Thinking renders as one coalesced growing line/widget (not N lines). - Telemetry events visually demoted (`· ` prefix in cli, dim style in tui). - duration_ms displayed as `5.5s` / `347ms` / `1.2m`. - usage displayed as natural-language flow. - [done] line lands on its own line after a clean stdout flush. - TUI: dedicated `Static(id="thinking-current")` widget shows current thinking state, mirrors content into RichLog as chronological dimmed entries. - All existing tests + new rendering tests GREEN under `uv run pytest tests/`. - `uv run ruff check src/ tests/` clean. ## Version posture v0.1.0 → v0.2.0 (minor). Output shape changes; scripts grepping `[thinking] '<token>'` would break. Pre-v1.x means breaking changes are minor.
vh added the blocked-needs-contractobservabilitytaskclituienhancement labels 2026-05-23 15:11:11 -07:00
vh changed title from Presenter rendering polish: thinking-coalesce + telemetry demotion + formatting to Presenter contract semantics amendment: stateful event coalescing + telemetry demotion 2026-05-23 15:18:11 -07:00
vh removed the blocked-needs-contract label 2026-05-23 15:21:57 -07:00
vh commented 2026-05-29 23:27:18 -07:00
Author
Owner
Copy Link
Copy Source

Closed — shipped. Presenter contract semantics amendment (stateful coalescing + telemetry demotion) implemented via TDD (commit 3b9c610, v0.2.0). CliPresenterState + TuiPresenterState; thinking deltas coalesce to one growing line.

Closed — shipped. Presenter contract semantics amendment (stateful coalescing + telemetry demotion) implemented via TDD (commit 3b9c610, v0.2.0). CliPresenterState + TuiPresenterState; thinking deltas coalesce to one growing line.
vh closed this issue 2026-05-29 23:27:33 -07:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
blocked-needs-contract
Sleipnir refuses dispatch — issue-scoped contract missing
 blocked-needs-dependency
Sleipnir holds dispatch — INV-029 dependency-aware gate
 bug
Something is not working
 cli
Command-line surface (--send, --new, --session, etc.)
 documentation
Docs / contract / spec work
 duplicate
Duplicate of another issue
 enhancement
New feature or improvement
 invalid
Not a real issue
 needs-architect-decision
Escalated for a design call
 needs-info
More info required from reporter
 needs-triage
Newly filed, not yet sorted
 observability
Log-pane / debug-surface work (persona, admin events, Bifrost, tools)
 ready-for-agent
Gates AFK dispatch via Sleipnir (applied by /sleipnir-preflight)
 sse-client
SSE consumer module (src/ratatoskr/sse_client.py)
 task
Implementation task
 tui
Textual app shell + presenters
 wontfix
Accepted as not-fixing
No Label cli enhancement observability task tui
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
vh
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: vh/ratatoskr#12
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?