vh/ratatoskr
1
0
Fork 0
Code Issues 4 Pull Requests Actions Packages Projects Releases Wiki Activity
36 Commits 5 Branches 114 Tags
v0.6.4
Commit Graph

15 Commits

Author SHA1 Message Date
vh 82437bd4b9 style(tui): picker highlighted item → Aurora blue (v0.6.4) 
Operator request: the agent picker's highlighted selection should
get the brand-color treatment — Aurora blue background — instead of
the v0.6.1 dark-30 muted bg.

## Two-fix landing

**The selector**: v0.6.1's `ListView > ListItem.--highlight` (double
dash) never actually matched. Textual's class is `-highlight` (single
dash). The v0.6.1 "fix" silently fell through to Textual's defaults,
which happened to be invisible because $block-cursor-background was
configured but the selector path didn't reach the rendered widget.

Probed live: `item.classes = frozenset({'-highlight'})`. Selector
corrected, plus dropped the `>` combinator since Textual's internal
DOM puts wrappers between `ListView` and `ListItem`.

**The background**: explicit `#agent-list:focus ListItem.-highlight
{ background: $primary }` — Aurora blue (#6388D8) for the focused-
list highlight band.

**The contrast**: bright-blue id-line text on Aurora-blue background
would be unreadable. Highlighted-state child overrides:

  .agent-id-line  →  $au-bright-white (#cce7ec) + bold
  .agent-desc     →  $au-bright-80    (#b3cbcf)

Non-highlighted items keep their default colors (bright-blue id +
bright-70 desc on App bg).

## Verified live

13 fill rects of `#6388d8` in the picker SVG export (was 0
before this commit). Other Australis brand colors intact:
chrome surface #373b46, dark-50 #6e7882, dark-30 #414751.

## Tests

241/241 GREEN; ruff clean. No test rewrites needed — picker tests
assert structure (widget tree, key bindings), not colors.

Patch bump (v0.6.3 → v0.6.4) — cosmetic; no public-API change.
 2026-05-24 18:33:53 -07:00
vh ac690c11d5 style(tui): restore Australis, $background → pure black (v0.6.3) 
Reverts v0.6.2's over-correction. The operator clarified: the
complaint was specifically about the APP BACKGROUND going from
black to a shade of blue, not about the cumulative cast across
all Australis dark surfaces. v0.6.2 globally neutralized Ice + Sea
darks → too far.

## v0.6.3 = v0.6.1 palette + $background override only

Restored verbatim from v0.6.1:

  $foreground       #a9bcc3 (Ice white)
  $surface          #373b46 (Sea bright-black, chrome bg)
  $panel            #414751 (Sea dark 30, borders)
  $au-dark-30..60   Australis Sea palette
  $au-bright-70/80  Australis Sea brights
  $au-bright-white  #cce7ec (Ice highlight)
  Aurora accents    bright-blue/cyan/green — verbatim
  Dawn accents      red/yellow — verbatim
  _AU_DEMOTED       #86929d (Sea dark 60)
  _AU_DEMOTED_FAINT #6e7882 (Sea dark 50)

ONE deviation from Australis spec:

  $background  #222531 (Ice black) → #000000 (pure black)

Rationale: Ice black is RGB(34, 37, 49) — blue +44% over red. At
App-wide scale (the dominant fill across the entire screen) the
cumulative cast reads as "the app is blue" even though no single
rect is in the conventional-blue range. Other dark surfaces are
smaller chrome bands where the cool lean reads as character not
background; only $background gets the override.

## What stayed Australis

Every cosmetic element where the operator hasn't pushed back:
identity widget (Aurora bright-blue), pane-name (Aurora bright-cyan),
[done]/[error]/[cancelled] labels (Aurora green / Dawn red/yellow),
focus borders (Aurora blue / accent cyan), demoted telemetry text
(Sea dark-60), placeholder lines (Sea dark-50), Header/Footer chrome
(Sea bright-black bg + Ice white-blue fg), separators (Sea dark-30).

Brand fidelity preserved; only the dominant background surface
neutralized.

## Tests + smoke

241/241 GREEN; ruff clean. Live screenshot export:
- $background = #000000 (230 fill rects — dominant surface)
- $surface = #373b46 (29 fill rects — Australis Sea bright-black)
- Sea panels + dark-50 still present in chrome
- Aurora #6388D8 still primary

Patch bump (v0.6.2 → v0.6.3) — cosmetic refinement; no public-API
change.
 2026-05-24 18:20:57 -07:00
vh d845b20efd style(tui): neutralize Australis dark palette (v0.6.2) 
Operator-flagged third pass: "overall background for the whole app is
blue." The previous "zero blue rects" investigations missed the
structural cause — Australis's design principle "all colors are
cooler than neutral" bakes a blue cast into every dark surface:

  Ice black    #222531 = RGB(34, 37, 49)   — blue +44% over red
  Sea bright   #373b46 = RGB(55, 59, 70)   — blue +27% over red
  Sea dark-30  #414751 = RGB(65, 71, 81)   — blue +25% over red
  Sea dark-60  #86929d = RGB(134,146,157)  — blue +17% over red

Every chrome surface inherits the lean. The user reading "the whole
app is blue" is correct — the SVG export just rendered hex values
that aren't named "blue" but ARE measurably blue-tinted.

## Fix: keep accents, neutralize darks

Australis brand signature lives in the ACCENTS — Aurora blue, cyan,
green; Dawn red, yellow. Those are unchanged. The Ice/Sea dark
palette is replaced with LAB-matched neutral grays (R=G=B) so the
chrome reads truly neutral:

  $background  #222531 → #1a1a1a   (neutral near-black)
  $surface     #373b46 → #2a2a2a   (neutral dark gray)
  $panel       #414751 → #3a3a3a   (neutral mid gray)
  $foreground  #a9bcc3 → #bdbdbd   (neutral light gray)
  $au-dark-30  #414751 → #3a3a3a
  $au-dark-40  #565f69 → #4f4f4f
  $au-dark-50  #6e7882 → #6b6b6b
  $au-dark-60  #86929d → #878787
  $au-bright-70 #9daeb6 → #9e9e9e
  $au-bright-80 #b3cbcf → #bdbdbd
  $au-bright-white #cce7ec → #e0e0e0

`_AU_DEMOTED` and `_AU_DEMOTED_FAINT` constants (Rich Text styling
for demoted telemetry + placeholders) updated to the neutral
equivalents. The Aurora bright variants (`$au-bright-blue`,
`$au-bright-cyan`, `$au-bright-green`) stay verbatim — those are
where the brand voice lives.

## What this preserves vs sacrifices

**Preserved**:
- Aurora accents: focus borders, active-tab indicator, pane-name
  widget, user-prompt echo all still render in cyan/blue/green.
- Done/Error/Cancelled labels still tinted in Aurora green / Dawn
  red / Dawn yellow.
- Identity widget still Aurora bright-blue.
- The "Australis" theme name + variable slugs ($au-*) — downstream
  CSS rules don't have to change.

**Sacrificed**:
- The "all colors cooler than neutral" Australis design principle.
  Deliberate per-operator-feedback deviation; documented in the
  AUSTRALIS_THEME docstring as a v0.6.2 conscious break with spec.

## Tests + smoke

241/241 GREEN; ruff clean. Live screenshot exports:
- Main app: chrome colors are #1a1a1a / #2a2a2a / #3a3a3a / #6b6b6b
  / #bdbdbd — all neutral grays. Aurora accents preserved as
  textual highlights.
- Agent picker: same — neutral chrome, Aurora accents intact for
  highlighted item border + agent-id-line.

Patch bump (v0.6.1 → v0.6.2): purely cosmetic palette adjustment;
no public-API change.
 2026-05-24 18:15:54 -07:00
vh eb93e6d5f0 style(tui): kill remaining blue + thinking-current into pane (v0.6.1) 
Three operator-flagged issues:

## 1. "Background is still blue" — Header sub-widgets + scrollbar

Two surviving blue sources after v0.6.0:

- **Header sub-widgets** (HeaderIcon, HeaderTitle, HeaderClock) each
  carry their own `$primary` tint that the parent
  `Header { background }` rule alone doesn't override. Sub-selectors
  added: `Header, HeaderIcon, HeaderTitle, HeaderClock { background:
  $surface; color: $au-bright-blue; }`.
- **Scrollbar gutter** uses Textual's `$primary-tint` (#32436a) by
  default. Per-widget scrollbar overrides: `ListView` (picker) and
  `RichLog` (every pane) get explicit Sea darks for gutter + thumb.

Live verification: both AgentPickerApp and RatatoskrApp now render
ZERO instances of `#6388d8` (Aurora blue) or `#32436a` (its dark
derivative) in the export-screenshot SVG.

## 2. "Picker is bright cyan with unreadable text" — ListView focus

Textual's default `ListView:focus > ListItem.--highlight { background:
$primary }` was overriding my v0.6.0 `#agent-list > ListItem.--highlight
{ background: $au-dark-30 }` because `:focus` carries higher
specificity. The highlighted item was rendering with Aurora-blue
background + bright-blue text = unreadable.

Fix: both selectors targeted explicitly with sufficient specificity:
`ListView > ListItem.--highlight, ListView:focus > ListItem.--highlight
{ background: $au-dark-30 }`. Description text bumped to Sea bright-70
for better contrast against the dark-30 highlight.

## 3. "Streaming everywhere, should just stream in line"

User flagged the disconnect: live thinking rendered above the
TabbedContent in the right-column header, then on closure the content
"moved" to thinking-log inside the Thinking pane. Read as jarring
discontinuity.

Fix: `thinking-current` Static moved INTO the Thinking TabPane (docked
bottom), below `thinking-log`. Both surfaces co-located now — live
streaming + closed runs share the same pane. Operator switches to
Ctrl+3 (Thinking) to see chronological closed runs ABOVE + live
streaming line BELOW. Same pattern as the transcript: closed history
+ inline streaming tail.

Trade-off: live thinking is now visible only when on the Thinking
tab. Pre-v0.6.1 it was always visible above the tabs. The user
explicitly prefers the co-located shape; this is the right call.

## Contract amendment

docs/contracts/issues/13.contract.md INV-024 amended: thinking-current
now docks bottom of the Thinking TabPane (was right-column header).
v0.6.0 layout-spec snapshot updated to reflect the new shape. Drift-
check clean.

## Tests + smoke

241/241 GREEN; ruff clean. Live smoke against personal Worldtree
confirmed:
- thinking-current AND thinking-log both inside thinking-tab.walk_children().
- Post-Done state: 23 closed-run lines in thinking-log, thinking-current
  cleared to empty.
- Picker exports zero blue rects; main App exports zero blue rects.

Patch bump (v0.6.0 → v0.6.1): purely cosmetic + layout adjustment
within the existing pane structure; no public-API change.
 2026-05-24 15:46:26 -07:00
vh cfee89ac1c refactor(tui): streaming + turn headers + Thinking pane + picker fix (v0.6.0) 
Operator-driven big-batch polish + restructure:

## 1. Streaming text — no more per-token RichLog spam

Pre-v0.6.0, every Text SSE delta wrote its own RichLog line, so
"Let me read the..." became 4+ separate lines (a Worldtree-style
sentence-by-sentence reveal that read as broken). v0.6.0 adds a
`#current-text` Static docked above the prompt; TuiPresenterState
buffers Text deltas in `text_buffer` and updates the Static in
place. On terminal event the Static clears and the transcript
gets:
  - raw=False: post-Done Markdown body + Rule separator
  - raw=True:  accumulated plain text

The Static collapses to height=0 when empty so the prompt sits at
the column bottom unchanged.

## 2. Turn-ID headers across every pane

`_stream_turn_worker` writes a `Rule(title="turn N")` to all four
log panes (transcript, tools, debug, thinking) on the first event
of each new turn. Operators can now visually correlate "what
happened in Tools during turn 42" by section markers in matching
positions across panes.

## 3. New Thinking TabPane (Ctrl+3)

Closed thinking runs now route to `#thinking-log` (a dedicated
TabPane) instead of `#debug-log`. Each closed run writes three
entries:
  - Rule(title="turn N · thinking #K start")
  - Markdown(thinking_content)
  - Rule(title="turn N · thinking #K end")

Model reasoning often has lists/code/structure — rendering as
Markdown (instead of the previous "· thinking: ..." prefix line)
makes it scannable. The `thinking_run_index` counter scopes per
turn so multi-thinking-run turns get distinct markers.

`thinking-current` Static (live per-delta preview) stays in the
right column above TabbedContent (unchanged from v0.5.0) — live
visibility persists across tab switches.

## 4. Agent picker — multi-line items, full description visible

Pre-v0.6.0 the picker rendered each agent as a single Label with
"{id} · {name} — {description}", which truncated descriptions
visually. v0.6.0 uses two Static children per ListItem:
  - bold Aurora bright-blue line: "{agent_id} · {name}"
  - wrapped Sea dark-60 line(s): full description

ListItems are auto-height so long descriptions wrap as needed.
Highlighted (--highlight) row uses Sea dark-30 background instead
of Aurora blue (which the operator flagged as ugly).

## 5. Kill residual blue chrome

The user's "background is still blue" report traced to the prompt
Input's focused border, which I'd set to $primary (Aurora blue).
Switched to $au-bright-cyan (#42dcd1) — focus highlight is now
cyan, consistent with the operator's-voice accent throughout the
TUI. Also added explicit overrides for ContentTabs strip
background + active-tab underline color → Australis cyan.

## 6. Surfaced emotion-appraisal request to worldtree-dev

User asked for emotion-appraisal telemetry, but no SSE event for
this exists in the spec — persona/Vili affect lives in persona.log
(file-tail, blocked on remote-Worldtree topology) and per-character
state (poll endpoint, not per-turn). Posted an althing thread
proposing two shapes (worker_phase payload extension OR new
affect_update event type) and routing the decision to their team.
A 4th `Emotion` TabPane plugs in trivially when a wire event lands.
Low-priority / quality-of-life framing — not blocking ship.

## Contract amendment

docs/contracts/issues/13.contract.md amended in-place: INV-019
extended to 3 TabPanes; new INV-021 (Text → current_text Static),
INV-022 (thinking closed runs → thinking_log with Markdown +
start/end Rules), INV-023 (turn-ID headers across all panes),
INV-024 (thinking-current Static stays in right column with
"thinking… " prefix per v0.5.1 polish). INV-020 (render-exception
fallback routing) updated for Thinking → thinking_log. Drift-check
clean.

## Tests

241 GREEN (down from 244 in test count — 5 routing tests rewritten
for the new shape, replacing the v0.5.0 thinking-in-debug-log
assertions with the v0.6.0 thinking-log-as-Markdown shape; net
test coverage equivalent). ruff clean.

Live smoke against personal Worldtree's mimir confirmed:
  - transcript: 27 lines (turn header + user echo + done +
    markdown body, NO per-token spam)
  - thinking_log: 19 lines (turn header + 2x thinking start/end
    Rule sections with Markdown bodies)
  - current_text cleared post-Done

Minor bump (v0.5.1 → v0.6.0) per SemVer etiquette: visible routing
+ new pane = operator-observable surface change.
 2026-05-24 15:29:55 -07:00
vh 7106af5c09 style(tui): UI polish pass (v0.5.1) 
Cosmetic refinements on top of v0.5.0's content-only main pane. No
behavior change; ships as a patch bump.

## Color signal — terminal labels tinted per outcome

The transcript's [done]/[error]/[cancelled] labels were plain
foreground (Australis #a9bcc3 white), which made them slow to scan
against the surrounding assistant text. Now tinted per outcome:

- [done]      → Aurora green   (#16B866 / $success)
- [error]     → Dawn red       (#ff491a / $error)
- [cancelled] → Dawn yellow    (#e1c631 / $warning)

The post-Done Rule() separator is also tinted to Australis dark-60
(#86929d) so the streamed-text → markdown-body boundary reads as
chrome, not a content artifact.

## Empty-state placeholders

Tools and Debug panes were stark-empty before any turn fired — easy
to misread as "the pane is broken." Now show placeholder lines on
mount in Sea dark-50 italic:

  Tools tab: (no tool events yet — start a turn that uses tools)
  Debug tab: (waiting for telemetry — start a turn)

The placeholders scroll off naturally as real events fill the panes.

## Live thinking widget self-explains

The thinking-current Static at the top of the right column used to
just display raw thinking content with no context — an operator
glancing at the screen mid-stream might not realize they were
looking at LLM chain-of-thought. Now prefixed with "thinking… " so
the widget self-identifies.

## Spacing + chrome

- Transcript / tools-log / debug-log: 1-cell horizontal padding so
  content doesn't hug the column border.
- thinking-current: italic text-style on top of the dark-60 color,
  so the live-preview band is visually distinct from solid-colored
  log content.
- Active tab in TabbedContent: Aurora bright-cyan label + bold
  text-style, so the eye lands on the currently selected pane.
- Input placeholder text: tinted to Sea dark-50 so it reads as
  placeholder, not content.

## Test impact

3 new tests added (test_done_label_styled_success,
test_empty_state_placeholders_present, plus the polish hits
test_thinking_widget_truncation / test_thinking_coalesce updated for
the "thinking… " prefix). 4 existing tests that checked
`isinstance(w, str) and w.startswith("[done]")` updated to use the
_text_of helper (terminal labels are now RichText, not str).
_spy_writes helper widened to accept positional args after Textual's
internal deferred-render path started passing them positionally
post-Resize.

241/241 GREEN; ruff clean. Live smoke against personal Worldtree
confirmed: Done line renders in Aurora green #16B866 verbatim;
both placeholder lines appear in dark-50; thinking widget shows
"thinking… <content>" during a turn.

Patch bump (v0.5.0 → v0.5.1) per SemVer etiquette: purely cosmetic;
no signature change; no caller-visible behavioral shift.
 2026-05-24 15:06:10 -07:00
vh ffd22fb587 refactor(tui): content-only main pane + Debug tab + dark chrome (v0.5.0) 
Two operator-driven changes off v0.4.1:

1. **Main pane is content-only.** Pre-v0.5.0 the transcript mixed
   assistant text with telemetry (Thinking closed runs, WorkerPhase,
   TextBoundary) — only tool events were factored out per #13. The
   transcript now receives ONLY: user-prompt echo, assistant Text
   deltas, [done]/[error]/[cancelled] terminal labels, and the
   post-Done Markdown render. All telemetry routes to a new Debug
   tab in the right column.

2. **Chrome no longer blue.** Textual's default Header / Footer /
   active-tab styling tints with `$primary` (Aurora blue under
   Australis), which read as garish on dark terminals. Header,
   Footer, and the TabbedContent tab strip get explicit
   `background: $surface` (Sea bright-black #373b46) so the chrome
   sits cool and unobtrusive against the Ice black background.

## Layout reshape

```
LEFT COLUMN (content only):           RIGHT COLUMN (telemetry):
  transcript (RichLog, 1fr)             thinking-current (Static, dock top)
  prompt (Input, dock bottom)           TabbedContent:
                                          Tools  (tool_start, tool_result)
                                          Debug  (thinking, worker_phase,
                                                  text_boundary)
```

The thinking-current live-preview Static moves from left → right
column so the left column is genuinely content-only. Live thinking
visibility now persists across tab switches (it docks above the
TabbedContent, not inside any tab).

## Presenter routing (TuiPresenterState.render)

Signature widens with `debug_log: RichLog`. Routing matrix:

  Text                       → log (transcript)
  Done / Error / Cancelled   → log (transcript) [terminal labels]
  ToolStart / ToolResult     → tools_log (Tools tab)
  Thinking (closed run)      → debug_log (Debug tab)
  WorkerPhase                → debug_log (Debug tab)
  TextBoundary               → debug_log (Debug tab)
  Thinking (per-delta)       → thinking_widget (live preview)

INV-009 render-exception fallback preserves routing per event class
(new INV-020) — ToolStart/Result falls back to tools_log;
Thinking/WorkerPhase/TextBoundary to debug_log; everything else to log.

## Keybindings

- Ctrl+1 → Tools tab (existing, unchanged)
- Ctrl+2 → Debug tab (NEW)

`pane-name` footer widget updates dynamically as the operator
switches tabs ("Tools" ↔ "Debug"). This was previously deferred to
"the multi-tab issue" per the Volva contract-review amendment;
multi-tab now exists, so the dynamic update lands here.

## Contract amendments

docs/contracts/issues/13.contract.md amended in-place:
- INV-015 amended: transcript is content-only; telemetry routes to
  debug_log. Old routing (telemetry in transcript) retired under the
  no-backwards-compat rule.
- INV-017 amended: thinking-current docks to right column (was left).
- INV-019 new: two TabPanes (Tools + Debug), Ctrl+1/Ctrl+2 bindings,
  dynamic pane-name update.
- INV-020 new: render-exception fallback preserves per-event-class
  routing.
- Layout-spec snapshot ASCII diagram updated.

Drift-check clean.

## Tests

239/239 GREEN (+3 new: debug_tab_exists, ctrl_2_activates_debug_tab,
pane_name_updates_on_tab_switch). 6 existing tests adjusted for the
new routing (test_thinking_closes_one_debuglog_entry,
test_multiple_thinking_runs_each_get_debuglog_entry,
test_render_exception_fallback,
test_cancelled_mid_thinking_closes,
test_worker_phase_demoted_to_debug_log,
test_left_column_content_only). ruff clean.

Live smoke against personal Worldtree: mimir KB-search turn
populated tools_log with 11 lines of tool events (search_library +
read_note); debug_log with 20 lines of worker_phase + thinking
content; transcript stayed content-only with `❯ user-prompt`
(Aurora bright-cyan) + assistant text deltas. Routing matrix
holds end-to-end. (Diagnostic note: RichLog.lines is the rendered-
output buffer; inactive TabPane content shows lines=0 until the
tab activates and renders. Internal write store is correct — this
is a Textual rendering quirk, not a routing bug.)

Minor bump (v0.4.1 → v0.5.0) per SemVer etiquette: visible routing
surface change for operators; transcript and Debug tab contents
look different from yesterday's v0.4.1.
 2026-05-24 14:20:35 -07:00
vh 2756f5f1dd style(tui): apply Australis theme to TUI chrome + widgets (v0.4.1) 
Retheme the Textual TUI under the Australis Dark colorscheme
(github.com/lkraven/australis) — Aurora blue/cyan/green primary,
Ice neutrals (#222531 bg, #a9bcc3 fg, #cce7ec highlight), Sea
darks for chrome separators, Dawn accents reserved for terminal-
event labels (red/yellow). 16-color cool-tone palette with medium
contrast.

Mechanism: Textual `Theme` API. AUSTRALIS_THEME defined at module
scope mapped to semantic tokens (primary/secondary/accent/success/
warning/error/foreground/background/surface/panel) plus a Sea
variables block (`au-dark-30..60`, `au-bright-70/80/white`, plus
Aurora bright variants). Both `RatatoskrApp` and `AgentPickerApp`
register the theme in `__init__` and set `self.theme = "australis"`.

Per-widget styling via DEFAULT_CSS theme variables (no hex
sprinkled in CSS):

- `#identity` → `$au-bright-blue` (Aurora bright-blue).
- `#pane-name` → `$au-bright-cyan` (current-pane indicator).
- `#hint` → `$au-dark-60` (subtle Ctrl-C state line).
- `#prompt` border → `$panel` unfocused / `$primary` focused
  (focus highlight in Aurora blue).
- `#left-column` gets a `border-right: solid $panel` separator.
- `#thinking-current` color → `$au-dark-60` (matches demoted style).
- `#transcript` + `#tools-log` background → `$background`.
- Agent picker's highlighted ListItem → `$primary` bg +
  `$au-bright-white` fg.

Rich Text styling (where Textual's theme system doesn't apply):

- `_dim()` helper for demoted telemetry now uses explicit
  `#86929d` (Sea dark-60) instead of the terminal-dim filter
  `"dim"`. Renders consistently across emulators and stays
  anchored to the brand palette.
- User-prompt echo (`❯ <content>` in transcript) wrapped in
  `RichText` styled with `#42dcd1` (Aurora bright-cyan) — calls
  out the operator's voice in the primary palette.

CLI mode (`--send`) is unaffected by design — raw stdout has no
theme concept. The retheme is TUI-only.

236/236 tests GREEN; ruff clean. Live smoke against personal
Worldtree: `app.theme == "australis"`, all widget colors resolve
to expected Australis hex values (identity → `#a4c4ff`,
pane-name → `#42dcd1`, hint → `#86929d`).

One existing test adjusted: `test_worker_phase_demoted` previously
asserted `style == "dim"`; now asserts non-empty style (the demoted
style is now an explicit Australis hex, not the terminal "dim"
sentinel). Behavior-equivalent — the demotion intent is preserved.

Patch bump (v0.4.0 → v0.4.1) per SemVer etiquette: cosmetic
refinement of just-shipped surface, no public-API change.
 2026-05-24 13:49:36 -07:00
vh 24e4371ec7 feat(tui): issue #13 — §5 layout reshape + Tools pane (v0.4.0) 
Reshape the TUI from vertical-stack single-pane to Horizontal
two-column with TabbedContent on the right; v1 has a single Tools
tab that consumes ToolStart/ToolResult SSE events previously
rendered inline in the transcript. Foundation for the rest of
design-brief §5; subsequent panes (Persona/AdminEvents/BifrostState/
ServerLog) plug in as sibling TabPanes when their substrate
blockers resolve.

Three coupled pieces, all in-place amendments to issues #4 + #12:

- **Layout**: compose() yields Horizontal#main-row containing
  Vertical#left-column (transcript + thinking-current + prompt) and
  Vertical#right-column (TabbedContent#side-panes with
  TabPane#tools-tab → RichLog#tools-log). Width split 2fr:1fr. CSS
  dock rules narrow to per-container scope so thinking-current
  toggling doesn't reflow the right column.
- **Tools pane**: TuiPresenterState.render() signature widens with
  tools_log: RichLog. ToolStart/ToolResult route there per INV-014;
  every other event keeps its issue-#12 routing. Plain-label
  fallback under render-exception preserves routing (INV-009).
- **Ctrl+1 binding + pane-name widget**: BINDINGS gains
  Binding("ctrl+1", "focus_tools") which programmatically sets
  TabbedContent.active; Textual's default preserves Input focus per
  INV-016 (test asserts; regression path documented).
  Static#pane-name in the footer renders "Tools" v1 (static — no
  tab-switch handler wiring lands in #13 per amendment-2 from
  Volva paraphrase review).

CLI mode (--send) is unaffected by design per INV-018 — non-
interactive, no tabs concept; CLI keeps inline tool-event rendering.

Contract: docs/contracts/issues/13.contract.md (drift-check clean,
two amendments applied from Volva contract-paraphrase pass).

Tests: +9 net (TestLayoutShape × 7 + TestTuiPresenterState routing
× 3, minus 1 deprecated test_tool_start_demoted superseded by
test_tool_start_routes_to_tools_log). 236 total GREEN; ruff clean.

Live smoke against personal Worldtree's mimir: tool-using turn
(KB search) populated tools_log with tool_start + tool_result for
search_library + read_note; transcript stayed chat-only with
worker_phase + thinking. Routing-not-duplication confirmed
end-to-end.
 2026-05-23 21:41:16 -07:00
vh d30be12deb feat(sessions,cli,tui): issue #8 — startup agent picker (v0.3.0) 
Adds GET /agents fetch + ListView picker for bare `--new` (TUI mode
without --agent). Three in-place amendments:

- ratatoskr.sessions: new `list_agents()` + `AgentInfo` frozen
  dataclass with omit-when-null/empty defaults mirroring SessionInfo's
  INV-001/INV-002 origin-conditional pattern. Non-200 responses raise
  the existing SessionApiFailed (no new exception).
- ratatoskr.cli: `_parse_args` softens `--agent` from absolute to
  mode-conditional — required for `--send --new`, optional for bare
  `--new`, forbidden with `--session` (unchanged INV-004).
- ratatoskr.tui: new `AgentPickerApp(App[str | None])` — separate
  Textual App (not Screen-within-RatatoskrApp) so list_agents errors
  land on real stderr before any alt-screen opens (preserves issue
  #6's INV-001). `_resolve_then_run` gains a pre-create branch:
  fetch agents → empty list → exit 13; non-200 → exit 20; network
  error → exit 21; picker dismissed → exit 0; otherwise thread chosen
  agent_id into create_session.

Contract: docs/contracts/issues/8.contract.md (drift-check clean).

Tests: +18 (227 total, was 209). Live smoke against personal Worldtree
(:8081) returned 12 agents; programmatic picker drive auto-picked lofn
and created a real session with `end_user_id="ratatoskr-tui"`.
 2026-05-23 17:58:22 -07:00
vh c85f6bd701 fix(tui): anchor layout via dock so Input never moves (v0.2.1) 
Reported during v0.2.0 mimir smoke: the Input pane bounces up/down
mid-turn and streamed tokens land at shifting screen positions. Cause
is the v0.2.0 compose order — `Static(id="thinking-current")` was
yielded between hint and Footer in the auto-stacked flow, so each
display=True/False toggle per thinking-run shifted Input + identity +
hint vertically. RichLog growth from streaming text also drifted Input
downward in the auto-layout.

Fix: dock the chrome to the screen edges via DEFAULT_CSS:
- thinking-current docks top under Header (grows/shrinks above RichLog,
  doesn't affect Input position).
- transcript (RichLog) gets `height: 1fr` — absorbs all layout reflows
  internally via its scroll viewport.
- prompt (Input), identity, hint all dock bottom — locked above Footer.

Compose order moves thinking-current to position 2 (right after Header)
so its dock-top placement is visually adjacent to where Textual lays it
out. Old position (between hint and Footer) would still work with the
dock CSS, but the proximity reads more clearly.

Screen-relative positions are now stable: Input is anchored to the
bottom-dock stack; RichLog's content scrolls inside its bounded
viewport regardless of how much thinking-current expands. Tokens land
at the same screen position each delta.

No public API change; pure layout fix. 209/209 tests GREEN; ruff clean.
v0.2.0 → v0.2.1 (patch).

Cannot directly verify in TTY from a non-interactive session; operator
verification needed in real terminal.
 2026-05-23 17:13:27 -07:00
vh 3b9c610587 feat(cli,tui): issue #12 — presenter contract semantics amendment (v0.2.0) 
Replaces the stateless _render_event / _render_event_to_log helpers with
stateful per-turn presenters (CliPresenterState / TuiPresenterState).
Coalesces thinking-event deltas into a single growing display per run;
demotes telemetry events with editorial hierarchy; formats duration +
usage for human reading. Headline behavior change: a 50-token thinking
phase now renders as ONE coalesced growing line in CLI (or one closed
RichLog entry + per-delta live Static widget in TUI), not 50 lines of
[thinking] spam.

Editorial promotion line (issue #12 INV-002):
- Load-bearing (no demotion prefix): Text, Done, Error, Cancelled
- Demoted telemetry (`. ` ASCII prefix in CLI; dim `· ` in TUI):
  WorkerPhase, Thinking, TextBoundary, ToolStart, ToolResult

Stateful coalescing:
- Thinking deltas accumulate into thinking_buffer; first non-thinking
  event closes the run with a single \n boundary in CLI / one closed
  dim RichLog entry in TUI.
- TUI adds a dedicated Static(id="thinking-current") widget that shows
  the last ~200 chars of the active run, mirroring per-delta updates.
  Two-views-of-thinking decoupling per INV-004: chronological RichLog +
  always-visible widget.
- CLI INV-005: when stdout text was streamed mid-line,
  text_written_since_newline triggers a stdout flush + \n before the
  next stderr terminal label — guarantees [done] / [error] / [cancelled]
  land on their own line in a TTY without breaking pipe-to-file
  scripted consumers.

Formatting helpers (issue #12 INV-006 / INV-007):
- _format_duration_ms — autoscale `347ms` / `5.5s` / `1.2m`
- _format_usage — natural-language `6756 in -> 126 out (6882 total, 0
  cached)` with arrow="->" CLI / "→" TUI

Cross-frontier design pass (eitri-smithy-dev, althing
01KSBE52YZR5E3SPTKA672JE43) returned 16-of-16 confirmed decisions + 4
material divergences applied:
- ASCII `. ` prefix in CLI (`·` is U+00B7, not ASCII)
- RichLog one-closed-entry-per-run + Static per-delta updates (not
  inline-mirror as initially proposed)
- presenter-state object instead of pure-function rendering
- Framed as "contract semantics amendment", not "polish"

Volva paraphrase round (5 prose-precision fixes applied to
12.contract.md): INV-001 "growing display" semantics; single hide
mechanism for the Static widget (Textual reactive `display: bool`);
[render_error] security clause (type-only, no exception message);
text_written_since_newline `\n`-terminated text corner case;
[create_session] integration path (bypasses state.render — not an SSE
Event variant).

Volva code-review round (5 findings applied):
- F1 drift: render-exception fallback now writes BOTH a plain-label
  fallback line for the original event AND the `[render_error] <type>`
  line (was missing the fallback half).
- F2 drift: dim Rich style applied to all demoted-telemetry RichLog
  writes via `rich.text.Text(..., style="dim")` (was plain str).
- F3 drift: belt-and-braces widget clear+hide on EVERY terminal event
  (Done/Error/Cancelled), even when thinking_open was False.
- F4 precision: _format_usage gains PRE-001 assertion on the four
  expected usage keys.
- F5 precision: _run_turn signature amended in issue #3 contract to
  document the new `state: CliPresenterState | None = None` test-
  injection kwarg.

[create_session] lifecycle line demoted to `. create_session:` (written
directly by _amain; bypasses state.render since it's not a wire-level
SSE Event variant). Pre-amendment _render_event / _render_event_to_log
and their test classes removed under the no-backwards-compat rule.

Issues #3 and #4 contracts amended in-place: #3 (CliPresenterState
CLASS + FN block + helper FN blocks + _run_turn signature + _amain
create_session demotion); #4 (TuiPresenterState CLASS + FN block +
compose Static widget + _stream_turn_worker state construction).

209 tests GREEN; ruff clean. Bumps v0.1.0 → v0.2.0 (minor — output
shape change breaks pre-amendment grep patterns like `[thinking] '`;
no public API surface change beyond the rendering contract).

Persistent-memory commit-along: captures the issue #12 decision,
forward direction (require end_user_id for every access — declined
worldtree-dev's requires_end_user_id offer because we'll send it
universally), and the Heimdall scope-model foot-gun note (the
"per-Tier-1-agent scope add" diagnosis was a phantom ask resolved by
worldtree-dev's correction; agent.call:* baseline covers all Tier 1).
 2026-05-23 16:13:55 -07:00
vh 804c2df6eb feat(sessions,cli,tui): issues #5 + #6 + worldtree-dev consumer-API follow-up 
Issue #6 (TUI startup error visibility): restructure run_tui lifecycle so
pre-App.run() failures land on real stderr instead of getting eaten by
the alt-screen teardown. New _resolve_then_run async helper opens the
AsyncClient via async-with, does pre-flight session resolution, routes
AgentNotFound / SessionApiFailed / network errors to sys.stderr (verbatim
same labels + exit codes as cli._amain), then constructs RatatoskrApp
with pre-resolved state and awaits app.run_async(). RatatoskrApp.__init__
signature widens to (args, *, session_id, agent_id, client) — all three
required. on_mount narrows to identity-widget population; on_unmount
becomes a no-op (client lifetime owned by run_tui's async-with).

Issue #5 (--end-user-id for per-end-user agents): sessions.create_session
gains keyword-only end_user_id kwarg with PRE-003 non-empty assertion;
ParsedArgs.end_user_id field added (default None); --end-user-id flag
with non-empty validation; _amain + _resolve_then_run thread it to their
create_session calls. RATATOSKR_END_USER_ID env-var fallback
(flag > env > None) per the post-2026-05-23 amendment; env.sh (gitignored)
ships "ratatoskr-tui" as project-stable partition default.

Worldtree-dev consumer-API follow-up (althing 01KSBARG2B8M): User-Agent
header added (ratatoskr/<version> (vh@phasefinal.com), version pulled via
importlib.metadata) to both AsyncClient constructions so server logs can
distinguish ratatoskr traffic from other consumers.

Volva code-review (2 rounds on #6) found 8 test-precision gaps + 1 PRE
assertion drift, all Category 1 fixed: missing PRE-001 at
_resolve_then_run entry; Rule separator assertions on markdown render;
RichLog-write spy on empty submit; input-cleared + no-new-worker on
cancelling busy; worker.cancel observation on three force-exit paths;
on_unmount-no-close focused test (the prior client-lifetime test patched
run_async so on_unmount was never exercised); happy --new resolve test
verifying POST count + identity propagation.

Issues #2/#3/#4/#5 contracts amended in-place to reflect:
- create_session widened (PRE-003, body construction step, body shape POST)
- ParsedArgs description + _parse_args STEPS + _amain create_session call
  + new TESTS for end_user_id + env-var fallback
- _resolve_then_run STEPS + new TEST entries; on_mount narrowed;
  INV-007 amended for new client ownership
- Post-#6 adjustment note on issue #5 (_resolve_then_run replaces
  on_mount as the threading site since #6 moved session resolution out
  of the alt-screen)

188 tests GREEN; ruff clean. Bumps to v0.1.0 — first minor release, the
load-bearing reason is RatatoskrApp.__init__'s breaking signature change
(additive end_user_id alone wouldn't have triggered a minor pre-v1.x).

Files Gitea issues #9 (spec-pin refresh v0.19.0 → v0.22.1), #10 (track
Worldtree #196 subject:{type,id} migration), #11 (AdminEvents pane auth
prerequisite admin.events.read). Infra-ops pinged via althing for
agents.call:lofn scope add (broker pattern; they forwarded to
worldtree-dev because personal Worldtree exposes no public
scope-mutation endpoint).
 2026-05-23 14:34:53 -07:00
vh 999b0b4765 contract(issue#1): pin sse_client to gitea issue + seed default labels 
Convert the sse_client contract into an issue-scoped contract bound to
the freshly-filed gitea issue #1. Frontmatter migrates from module-shape
(module:/purpose:) to issue-shape (target_module:/scope:/prd:) per
CONTRACT-FORMAT §2.1.I. The prd: block pins to issue #1's body SHA-256
(abcbc49467e86f1d at 2026-05-21T03:57:37+00:00); drift check verifies
the pin matches the live issue body.

scripts/contract_drift_check.py needs pyyaml; added to [dev] in
pyproject.toml. Without it the drift check (and the contract parser)
fail with ModuleNotFoundError — that's a scaffold hole I'd hit again
on a fresh checkout.

Also seed 17 default labels on gitea via tea so issue tracking has a
working vocabulary out of the gate. Five buckets: Sleipnir gating
(ready-for-agent, blocked-needs-contract, blocked-needs-dependency),
triage (needs-triage, needs-architect-decision, needs-info), type
(bug, enhancement, task, documentation), resolution (duplicate,
wontfix, invalid), Ratatoskr-specific area (sse-client, tui, cli,
observability). Labels are gitea-side state — not in this commit.

Known: contract_parser.py --validate ERRORs on the issue-scoped
frontmatter because the parser is v2.0-shape. CONTRACT-FORMAT §2.1.L
H10 explicitly marks parser kind-aware validation as a Brokkr-side
follow-up. Parser is a canonical-synced file so we do NOT patch it
locally (would drift from corviduo-project-template).
 2026-05-20 20:59:46 -07:00
vh 9703eb2b6b init: seed Ratatoskr from corviduo-project-template + ship v0 scaffold 
Worldtree Conversation API debug TUI. Multi-pane observability dashboard:
chat transcript + persona/Vili affect log + tool events + admin events +
Bifrost state + tool inventory + (opt-in) raw server log.

Design locked at docs/design-brief.md (originated as
brokkr-smithy/docs/ratatoskr-design-brief.md). Operator-locked decisions:

- Textual application-shell framework (multi-pane dashboard, not REPL).
- Separate repo + separate dev team (no Worldtree-source imports).
- httpx-sse for SSE consumption (reference Python SSE-resume impl).
- Triple version-skew mitigation: spec-pin in pyproject.toml + recorded
  SSE snapshot tests + conformance smoke. Initial pin: Worldtree v0.19.0
  at 55101e909abcd2219833266b6f905c5bc956e0f0.
- Persona pane: label-don't-refuse PII posture.
- Server-log pane: opt-in via --server-log <path>.
- Two-stage Ctrl-C (cancel then exit).
- Markdown rendering default-on; --raw opt-out.

In the box:

- docs/design-brief.md — the locked design with full rationale.
- docs/SPEC-PIN.md — Worldtree spec pin + bump procedure.
- docs/conversation-api-spec.md + docs/conversation_api.contract.md —
  vendored Worldtree spec snapshots at the pinned SHA.
- pyproject.toml — Python 3.12, hatchling, uv-managed, deps locked.
- src/ratatoskr/ — stub package (cli.py raises NotImplementedError).
- tests/test_no_worldtree_imports.py — boundary smoke test PASSING.
- tests/snapshots/README.md — recording convention for SSE snapshot tests.

Not in the box yet:

- Gitea remote (operator/infra-ops to register at vh/ratatoskr).
- Implementation — the dev team owns this; design brief is the spec.

Origin: althing thread 01KS3R34XD3N6HMK91VXESHGW7 (worldtree-dev →
brokkr-smithy-dev, 2026-05-20). Volva consulted via thread
01KS3VF6W33N3V5FNMGQ91YNVD.
 2026-05-20 20:38:22 -07:00