[P0] Build first-class AgentProlog TUI over canonical headless protocol #9

New issue

Open

opened 2026-09-02 17:24:18 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-02 17:24:18 +00:00

Owner

Worker

agentprolog-rage-integration

Goal

Build the primary keyboard-first AgentProlog TUI as a frontend/plugin over the same canonical headless AgentProlog/Prolog-RLM protocol used by DeepSeek Harness.

The TUI must be excellent for real coding work without becoming a second runtime or reconstructing truth from pretty logs.

Depends on current AgentProlog product epic #1 and consumes lost-rob0t/prolog-rlm#335 / AgentProlog #9 for canonical reasoning-mode state.

Architecture

TUI
  -> typed AgentProlog headless/bridge protocol
  -> canonical AgentProlog session/runtime
  -> public Prolog-RLM APIs

The TUI owns presentation, input and interaction only.

It MUST NOT independently own or emulate:

model/provider execution;
planning/symbolic semantics;
tool execution;
capability or authority state;
conversation/history truth;
effect identity;
verifier/acceptance state;
subagent scheduling.

If information required by the UI is missing, add the smallest typed public inspection/event seam instead of scraping logs or guessing.

Required first-class views

Design the TUI around a persistent conversation/run view with compact panes or switchable screens for:

conversation and streaming assistant output;
active reasoning mode: direct, symbolic, symbolic-recursive, or auto -> selected;
run/operation status and cancellation;
Spec/plan/verification summaries when present;
tool/action activity and approval state;
changed files/diff summary;
test/check results;
recursive/subagent activity and budget state;
structured errors/failures;
trace/evidence/usage/cost inspection;
session/new/resume where supported by canonical runtime APIs.

Keep the default screen uncluttered. Detailed trace/evidence views should be reachable without permanently consuming the main conversation area.

Keyboard/command UX

At minimum support:

send/edit prompt;
/direct;
/symbolic;
/symbolic-recursive;
/auto;
cancel active run;
open/close inspection panes;
navigate tool/subagent/verification events;
new session / resume session when backed by canonical APIs;
copy/select useful output/diff/evidence.

Favor Vim-friendly/key-driven operation while retaining discoverable help/key hints.

Streaming and state

Render provider/assistant streaming from canonical events when available.
Never infer completion solely from stream termination when verifier/runtime state says otherwise.
Mode/status/authority/approval displays must come from canonical inspection state.
Reconnect/resume must reconstruct UI from typed canonical state/events, not frontend-local assumptions.
Slow views such as traces or large diffs must remain bounded/lazy.

Approvals and effects

When canonical runtime exposes a pending approval/diff operation, show the exact structured request and supported actions. The TUI may submit an approval decision but must not invent a fifth authority mode or bypass confinement/effect identity.

Implementation direction

Inspect current repository/Nix/tooling before selecting the TUI framework. Prefer a maintained terminal UI stack that packages cleanly under the project's Nix baseline and supports async event-driven rendering. Do not introduce a frontend framework that forces duplication of the AgentProlog runtime.

Keep frontend protocol adapters isolated so the headless contract remains independently testable.

Tests

deterministic protocol fixture drives conversation/status/mode rendering;
mode changes through UI reflect canonical state from AgentProlog #9;
reconnect reconstructs current session without duplicated messages/events;
cancellation renders terminal canonical state;
pending approval renders exact operation and submits one canonical decision;
large trace/diff views remain bounded/lazy;
malformed/unknown protocol events fail visibly without corrupting session state;
unsupported runtime features are shown as unavailable rather than fabricated;
headless integration remains usable with the TUI absent.

Acceptance

a real AgentProlog session can be started and operated entirely from the TUI;
assistant output, operations, mode, verification and failures come from canonical state;
all four reasoning commands are usable;
active run can be cancelled;
approvals, diffs and tests are practically inspectable;
reconnect/resume behavior is deterministic where supported;
TUI packaging is included in Nix/dev-shell/app surfaces without breaking headless or DSH;
focused frontend tests and exact-head integration/Nix checks are green;
no second provider/planner/history/authority/effect/verifier runtime is introduced.

## Worker `agentprolog-rage-integration` ## Goal Build the primary keyboard-first AgentProlog TUI as a frontend/plugin over the same canonical headless AgentProlog/Prolog-RLM protocol used by DeepSeek Harness. The TUI must be excellent for real coding work without becoming a second runtime or reconstructing truth from pretty logs. Depends on current AgentProlog product epic #1 and consumes `lost-rob0t/prolog-rlm#335` / AgentProlog #9 for canonical reasoning-mode state. ## Architecture ```text TUI -> typed AgentProlog headless/bridge protocol -> canonical AgentProlog session/runtime -> public Prolog-RLM APIs ``` The TUI owns presentation, input and interaction only. It MUST NOT independently own or emulate: - model/provider execution; - planning/symbolic semantics; - tool execution; - capability or authority state; - conversation/history truth; - effect identity; - verifier/acceptance state; - subagent scheduling. If information required by the UI is missing, add the smallest typed public inspection/event seam instead of scraping logs or guessing. ## Required first-class views Design the TUI around a persistent conversation/run view with compact panes or switchable screens for: - conversation and streaming assistant output; - active reasoning mode: `direct`, `symbolic`, `symbolic-recursive`, or `auto -> selected`; - run/operation status and cancellation; - Spec/plan/verification summaries when present; - tool/action activity and approval state; - changed files/diff summary; - test/check results; - recursive/subagent activity and budget state; - structured errors/failures; - trace/evidence/usage/cost inspection; - session/new/resume where supported by canonical runtime APIs. Keep the default screen uncluttered. Detailed trace/evidence views should be reachable without permanently consuming the main conversation area. ## Keyboard/command UX At minimum support: - send/edit prompt; - `/direct`; - `/symbolic`; - `/symbolic-recursive`; - `/auto`; - cancel active run; - open/close inspection panes; - navigate tool/subagent/verification events; - new session / resume session when backed by canonical APIs; - copy/select useful output/diff/evidence. Favor Vim-friendly/key-driven operation while retaining discoverable help/key hints. ## Streaming and state - Render provider/assistant streaming from canonical events when available. - Never infer completion solely from stream termination when verifier/runtime state says otherwise. - Mode/status/authority/approval displays must come from canonical inspection state. - Reconnect/resume must reconstruct UI from typed canonical state/events, not frontend-local assumptions. - Slow views such as traces or large diffs must remain bounded/lazy. ## Approvals and effects When canonical runtime exposes a pending approval/diff operation, show the exact structured request and supported actions. The TUI may submit an approval decision but must not invent a fifth authority mode or bypass confinement/effect identity. ## Implementation direction Inspect current repository/Nix/tooling before selecting the TUI framework. Prefer a maintained terminal UI stack that packages cleanly under the project's Nix baseline and supports async event-driven rendering. Do not introduce a frontend framework that forces duplication of the AgentProlog runtime. Keep frontend protocol adapters isolated so the headless contract remains independently testable. ## Tests - deterministic protocol fixture drives conversation/status/mode rendering; - mode changes through UI reflect canonical state from AgentProlog #9; - reconnect reconstructs current session without duplicated messages/events; - cancellation renders terminal canonical state; - pending approval renders exact operation and submits one canonical decision; - large trace/diff views remain bounded/lazy; - malformed/unknown protocol events fail visibly without corrupting session state; - unsupported runtime features are shown as unavailable rather than fabricated; - headless integration remains usable with the TUI absent. ## Acceptance - a real AgentProlog session can be started and operated entirely from the TUI; - assistant output, operations, mode, verification and failures come from canonical state; - all four reasoning commands are usable; - active run can be cancelled; - approvals, diffs and tests are practically inspectable; - reconnect/resume behavior is deterministic where supported; - TUI packaging is included in Nix/dev-shell/app surfaces without breaking headless or DSH; - focused frontend tests and exact-head integration/Nix checks are green; - no second provider/planner/history/authority/effect/verifier runtime is introduced.

nsaspy referenced this issue

2026-09-02 17:24:22 +00:00

[P0] Implement plugin-only DeepSeek Harness AgentFactory #11

nsaspy referenced this issue

2026-09-11 04:54:15 +00:00

[P0][agentProlog-worker] Rebuild Prolog-RLM plugin UX + canonical context meter + bottom-row mode controls #18