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.