agentgrep(feat[tui]): Chat layout and deductive search

[tony]

Summary

• Add a chat TUI layout — a Claude-Code/pi-style conversation transcript where each query is a you ▸ … turn and matches stream in beneath it as result bubbles, capped per block with a count note so the narrowing reads straight down the screen (1240 → 88 → 12).
• Add a deductive workflow — the first prompt fixes a haystack with one engine search; each later prompt narrows within it in-memory; ctrl+up widens back out and ctrl+l clears. It composes with any layout, not just chat.
• Fix the dead Workflow.BINDINGS seam — bindings declared on a workflow were never installed on the hosting screen, so workflow-owned keys could never fire. Bindings now install on attach (removed by identity on swap), and an on_action hook routes parameterized key actions back into the Textual-free strategy object.
• Extend the WorkflowHost surface with set_input_text (re-seed the prompt after a widen) and update_breadcrumb (repaint the refinement path); the chat layout renders both, while HUD and grep-log re-seed the input and no-op the breadcrumb so deductive narrows their views too.
• Document the layer in ADR 0014 and list the new pair in the TUI guide.

What it looks like

┌ agentgrep · chat · deductive ─────────────────────────────┐
│ you   ▸ rust error handling                               │
│ grep  ▸ 1,240 prompts  (haystack)                         │
│ you   ▸ anyhow                                            │
│ grep  ▸ 88 prompts                                        │
│ you   ▸ thiserror                                         │
│ grep  ▸ 12 prompts                                        │
│   · 2026-06-12 codex  migrate anyhow→thiserror in cli     │
├───────────────────────────────────────────────────────── │
│ all ▸ rust error handling ▸ anyhow ▸ thiserror            │
│ ▸ _                                          ⏎ narrow ^P ⌄ │
└───────────────────────────────────────────────────────── ┘

$ agentgrep ui --layout chat --workflow deductive

Changes by area

Layouts

• src/agentgrep/ui/layouts/chat.py: ChatLayout (full WorkflowHost over the shared grep-log non-blocking transport — gated emitter, @offload worker, @pump_only apply, chunked mounts) plus a self-contained DetailScreen modal that builds heavy bodies off the pump and bails if dismissed mid-build.
• src/agentgrep/ui/layouts/_base.py: install/remove the active workflow's BINDINGS on every attach, and action_workflow to delegate key actions into the workflow.
• src/agentgrep/ui/layouts/{hud,greplog}.py: set_input_text + no-op update_breadcrumb so deductive composes there without crashing.

Workflows

• src/agentgrep/ui/workflows/deductive.py: DeductiveWorkflow with an immutable refinement-frame stack; narrows via filter_loaded, widens by popping.
• src/agentgrep/ui/workflows/_protocol.py: Workflow.on_action and the two new WorkflowHost hooks; search.py/browse.py get no-op on_action.

Widgets

• src/agentgrep/ui/widgets/turns.py: frozen-slots Turn value objects, a MessageTurn bubble, and a non-slotted TurnRenderer dispatching by type via singledispatchmethod (bounded — first line + compact path).
• src/agentgrep/ui/widgets/transcript.py: ConversationLog, an append-only VerticalScroll(layout: stream) that mounts turns and never recomposes.
• src/agentgrep/ui/widgets/breadcrumb.py: RefinementBreadcrumb for the narrowing path.

Registry & docs

• src/agentgrep/ui/registry.py: register the chat layout and deductive workflow.
• ADR 0014 + the TUI guide entry.

Design decisions

• In-memory narrowing, not a per-turn re-query: the engine seam (SearchInvoker.run) only accepts a SearchQuery, not a set of record IDs, so narrowing filters the already-loaded haystack with a composed AND (a single refinement passes through verbatim; two or more are paren-grouped clauses). This is the correct "fixed haystack" semantics and the cheaper non-blocking choice. It routes through filter_loaded only, so a future disk re-grep escape hatch is a drop-in — compose every frame including the base and call run_search — with no data-model change. Accepted gap: in-memory narrowing can't see records beyond the haystack's initial limit (the re-grep hatch is the planned mitigation).
• Narrowing supersedes an in-flight haystack search: a refinement bumps the search generation, so a still-streaming haystack's late batches are dropped (NB-10) rather than mounting unfiltered into the narrowed block; the refinement runs over whatever loaded so far.
• Widen appends a wider block rather than unmounting: preserves the append-only "build each finished turn once, never re-render" discipline that keeps a long transcript non-blocking.
• Renderer split from the value object: a frozen=True, slots=True turn has no __dict__, so derived state lives on the non-slotted TurnRenderer. Renders are bounded (sliced before line-splitting); the detail modal builds heavy bodies off the pump.
• New ADR rather than a registry instance: this grows the WorkflowHost protocol surface and adds the on_action routing seam (a contract future workflows depend on), so it's recorded as ADR 0014 extending the reusable-widget and pluggable-layout ADRs and leaving the non-blocking invariants unchanged.

Verification

The new layout and workflow are registered:

$ rg -n "_load_chat|_load_deductive" src/agentgrep/ui/registry.py

The transcript is append-only — it must never recompose:

$ rg -n "recompose" src/agentgrep/ui/widgets/transcript.py

JSON parsing stays confined to the bounded detail-body builder:

$ rg -n "json\.(loads|dumps)" src/agentgrep/ui/layouts/chat.py

Workflow bindings are installed and routed:

$ rg -n "make_bindings|action_workflow|on_action" src/agentgrep/ui/layouts/_base.py

Test plan

• uv run ruff check . and uv run ruff format . — clean
• uv run ty check — clean (full tree, including tests)
• uv run pytest — full suite green
• test_ui_deductive.py — narrowing matrix against a recording host, the composed-filter form (single verbatim vs AND-grouped), and an end-to-end narrow over real records through the engine seam, plus ctrl+up routing on the chat layout
• test_ui_chat.py — streaming mounts result turns, filter appends a narrowed block, the per-block cap bounds mounted turns, detail opens on a focused result
• test_ui_pluggable.py — binding install/route/remove end-to-end and the F2/F3 cycle through the third layout/workflow
• test_ui_widgets.py — TurnRenderer dispatch + bounded result render
• test_tui_non_blocking.py — the static guard scans the new chat/turns/transcript pump entrypoints
• just build-docs — ADR 0014 renders and cross-references resolve
• Recommended before merge: exercise --layout chat --workflow deductive once under AGENTGREP_TUI_WATCHDOG=1 against a large real store

[tony]

Code review

Found 1 issue:

1. DeductiveWorkflow imports Textual at module scope (from textual.binding import Binding, used for priority=True keys), which contradicts the "Textual-free" invariant this PR states in four places: the module docstring ("Textual-free, so the strategy is unit-testable against a fake host"), ADR 0014 DN-2/DN-4 ("a workflow still imports no Textual"), and the action_workflow docstring in _base.py ("so the strategy object never imports Textual"). The other workflows import no Textual, and Workflow.BINDINGS is typed cabc.Sequence[object] to avoid the dependency. Either keep the workflow tuple-only and have _install_workflow_bindings apply priority=True, or relax the documented invariant.

agentgrep/src/agentgrep/ui/workflows/deductive.py

Lines 24 to 29 in b28e4c0

	import typing as t
	from textual.binding import Binding
	if t.TYPE_CHECKING:
	from agentgrep.ui.workflows._protocol import WorkflowHost

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}