flynn/docs/plans/2026-02-24-openclaw-gateway-first-tui-runtime-unification-plan.md

OpenClaw-Style Gateway-First TUI Runtime Unification Plan

Date: 2026-02-24
Branch: feature/openclaw-gateway-first-tui-runtime-unification

Summary

Unify Flynn command/runtime behavior so TUI, Telegram, and gateway/web chat all execute through the same daemon command/control path (OpenClaw-style control plane), while preserving local model backend switching via /backend for llamacpp and ollama.

Key policy:

• /runtime ... is global runtime mode control (config_default, force_native, force_pi_embedded) via daemon command services.
• /backend [provider] remains TUI-local backend selection for local tier only.
• TUI command execution should use gateway/daemon command services, not a separate local-only command path.

Goals and Success Criteria

1. TUI /runtime behavior matches Telegram/gateway behavior exactly.
2. TUI no longer has a divergent runtime-control command path.
3. TUI keeps local /backend switching for ollama and llamacpp.
4. flynn tui auto-starts/attaches daemon+gateway when needed.
5. Tests validate parity and no regressions.

Scope

In scope:

• Command-path unification for runtime controls.
• TUI bootstrap/attach behavior aligned with gateway runtime.
• Parser/help/tooltip updates for clear /runtime vs /backend semantics.
• Docs + Mermaid diagram updates.
• docs/plans/state.json update for this feature entry once implementation completes.

Out of scope:

• New backend modes beyond current three values.
• Protocol redesign unrelated to command routing.
• Broad TUI UX redesign outside command/runtime parity.

Public Interfaces and Behavioral Contract

1. flynn tui

• Primary behavior: connect to gateway-backed session.
• If unavailable: auto-start local daemon+gateway, retry connect, then proceed.
• Failure path: deterministic, actionable error message.

2. Slash commands in TUI

• /runtime status|activate pi|deactivate pi|use config: forwarded to daemon command service.
• /backend: local-tier backend command only.
• No /backend alias for global runtime mode in TUI.

3. Runtime mode persistence

• Existing preference persistence remains source of truth.
• No schema change unless required by implementation details.

Architecture Changes

1. Extract/reuse command service execution surface from daemon routing so it can be consumed uniformly by:

• Channel adapters.
• Gateway/web chat sessions.
• TUI sessions.

2. Wire TUI through gateway command path:

• Remove TUI-only runtime guard message path.
• Invoke same backend command service used by channel/gateway.

3. Keep local backend switching logic isolated:

• /backend remains local-tier (llamacpp/ollama) and does not mutate global runtime mode.

Implementation Phases

Phase 1: Branch + Baseline

1. Create branch feature/openclaw-gateway-first-tui-runtime-unification.
2. Capture baseline behavior with focused tests:

• src/frontends/tui/commands.test.ts
• src/frontends/tui/minimal.test.ts
• src/daemon/routing.test.ts
• relevant gateway agent handler tests.

3. Commit baseline harness updates (if any).

Phase 2: Command Service Unification

1. Refactor daemon runtime command handling into reusable service function(s).
2. Replace duplicated logic paths with shared invocation entry points.
3. Preserve command output text contract unless intentionally changed.
4. Add tests for parity across command surfaces.

Phase 3: Gateway-First TUI Runtime Path

1. Update src/cli/tui.ts startup flow to attach through gateway-backed runtime path.
2. Add daemon/gateway auto-start + reconnect sequence with bounded timeout.
3. Ensure minimal/fullscreen paths both use unified command execution.
4. Keep existing onTools, onResearch, onCouncil behavior compatible.

Phase 4: /runtime and /backend Semantics in TUI

1. Update parser/help/tooltip text in src/frontends/tui/commands.ts.
2. Implement /runtime forwarding in:

• src/frontends/tui/minimal.ts
• src/frontends/tui/components/App.tsx

3. Keep /backend local-only behavior; remove any global alias behavior in TUI.
4. Add tests for both commands and edge cases.

Phase 5: Docs and State

1. Update docs:

• README.md
• docs/architecture/AGENT_DIAGRAM.md
• docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md
• docs/api/PROTOCOL.md

2. Include Mermaid diagram updates or explicit “no diagram change required” note.
3. Update docs/plans/state.json with new feature entry and test status.

Phase 6: Validation and Merge

1. Run focused test suites + pnpm typecheck.
2. Fix regressions.
3. Rebase branch onto main.
4. Fast-forward merge and branch cleanup.

Test Plan

1. /runtime status in TUI returns same normalized mode/output as Telegram path.
2. /runtime activate pi sets persisted mode to force_pi_embedded.
3. /runtime deactivate pi sets persisted mode to force_native.
4. /runtime use config restores config_default.
5. /backend llamacpp and /backend ollama still work for local tier in TUI.
6. /backend status|activate pi|... in TUI does not control global runtime mode.
7. TUI auto-start path works when daemon/gateway are not already running.
8. TUI attach path works when daemon/gateway are already running.
9. Telegram/gateway /runtime behavior remains unchanged.

Subagent Model Assignment Plan

1. claude-haiku-4.5 (fast/mechanical)

• Parser/help/tooltip updates.
• Small test fixture updates.
• Docs wording and consistency checks.

2. claude-sonnet-4.6 (default implementation)

• TUI startup/runtime path refactor.
• Command service integration wiring.
• Main test additions and fixes.

3. claude-opus-4.6 (complex reasoning/architecture)

• Control-plane boundary validation.
• Failure-mode handling for auto-start/attach behavior.
• Final architecture/doc consistency review.

Risks and Mitigations

1. Risk: Regressing local /backend behavior while unifying runtime path.
   Mitigation: explicit tests for local-tier backend commands before/after refactor.

2. Risk: Startup race conditions during auto-start attach.
   Mitigation: bounded retry loop, deterministic backoff, explicit timeout errors.

3. Risk: Command-output drift across channels.
   Mitigation: golden-style assertions for runtime command outputs.

Defaults Locked

1. Architecture: gateway-first control plane (OpenClaw-style).
2. TUI behavior: /runtime global control via daemon service.
3. Compatibility: keep /backend local-only in TUI for llamacpp/ollama.
4. Delivery: staged atomic commits; final report after full implementation.