docs(runtime): document /runtime command path and status semantics
This commit is contained in:
William Valentin
@@ -363,12 +363,16 @@ backends:
|
||||
|
||||
`pi_embedded` is intended for canary migration cohorts. In spike mode (`no_tools_mode: true`), Flynn keeps tool-oriented turns on native and only routes plain-text turns to Pi.
|
||||
|
||||
When `pi_embedded` is selected, Flynn forwards the assembled runtime system prompt (for example `SOUL.md`/`IDENTITY.md`/`USER.md`/`TOOLS.md`, plus runtime/security sections) to Pi when `system_prompt_mode` is `flynn` or `hybrid`.
|
||||
|
||||
Runtime backend mode can be controlled live (persisted in `~/.local/share/flynn/preferences.json`):
|
||||
|
||||
- `/backend status` shows runtime mode and effective backend selection
|
||||
- `/backend activate pi` forces `pi_embedded` globally
|
||||
- `/backend deactivate pi` forces native for Pi-routed turns
|
||||
- `/backend use config` resets to `backends.default`
|
||||
- `/runtime status` shows runtime mode and effective backend selection
|
||||
- `/runtime activate pi` forces `pi_embedded` globally
|
||||
- `/runtime deactivate pi` forces native for Pi-routed turns
|
||||
- `/runtime use config` resets to `backends.default`
|
||||
|
||||
`/backend ...` remains a supported alias for compatibility.
|
||||
|
||||
This manual runtime mode control is the intended Pi activation/deactivation switch.
|
||||
|
||||
@@ -611,7 +615,7 @@ Notes:
|
||||
| `/approve [id]` | Approve latest (or specific) pending gate |
|
||||
| `/deny [id] [reason]` | Deny latest (or specific) pending gate |
|
||||
| `/skill <list|search|install>` | In-chat skill discovery/install (`list`, `search <term>`, `install <registry-id>`) |
|
||||
| `/backend <status\|activate pi\|deactivate pi\|use config>` | Show or control global runtime backend mode |
|
||||
| `/runtime <status\|activate pi\|deactivate pi\|use config>` | Show or control global runtime backend mode (`/backend ...` alias also supported) |
|
||||
|
||||
## Web UI Dashboard
|
||||
|
||||
@@ -669,6 +673,8 @@ pnpm tui:fs
|
||||
|
||||
TUI keyboard controls: `Esc` cancels active prompt/running response. `Ctrl+C` clears the current input; press `Ctrl+C` twice quickly to exit.
|
||||
|
||||
Note: runtime backend mode control is a daemon/channel command (`/runtime ...`, `/backend ...` alias), not the TUI-local `/backend [provider]` switch.
|
||||
|
||||
#### Runtime Model Switching
|
||||
|
||||
Switch providers and models on the fly without editing config or restarting:
|
||||
|
||||
@@ -37,7 +37,7 @@ The gateway serialises agent work **per session**, not per WebSocket connection:
|
||||
- Lane policy is configurable (`collect`, `followup`, `steer`, `steer_backlog`, `interrupt`) with per-channel and per-session overrides.
|
||||
- Session-local overrides can be managed at runtime via `agent.send` commands: `/queue`, `/queue set ...`, `/queue reset`.
|
||||
- Backend selection for a turn is server-side (`native` by default, optional external backends per config: `claude_code`, `opencode`, `codex`, `gemini`, `pi_embedded`) and does not change JSON-RPC method signatures.
|
||||
- Runtime backend mode overrides are available via `agent.send` command fast-path: `/backend status`, `/backend activate pi`, `/backend deactivate pi`, `/backend use config`.
|
||||
- Runtime backend mode overrides are available via `agent.send` command fast-path: `/runtime status`, `/runtime activate pi`, `/runtime deactivate pi`, `/runtime use config` (`/backend ...` remains a compatibility alias).
|
||||
- Backend routing and fallback outcomes are emitted to audit logs (`backend.route`, `backend.success`, `backend.fallback`) for rollout evaluation; this telemetry is outside JSON-RPC response payloads.
|
||||
|
||||
This is implemented via a per-lane queue (`LaneQueue`) in the gateway server, and used by `agent.send` and `agent.cancel`.
|
||||
|
||||
@@ -99,7 +99,7 @@ ChannelAdapter -> ChannelRegistry
|
||||
| createMessageRouter()
|
||||
| |
|
||||
| +----> Runtime backend mode overrides
|
||||
| (/backend status|activate pi|deactivate pi|use config)
|
||||
| (/runtime status|activate pi|deactivate pi|use config)
|
||||
| |
|
||||
| v
|
||||
| SessionManager
|
||||
|
||||
@@ -11,7 +11,7 @@ If you only want the protocol surface, see `docs/api/PROTOCOL.md`.
|
||||
- Agent work is queued per `sessionId` (FIFO), not per connection.
|
||||
- Sessions persist in SQLite via `SessionManager` even if clients disconnect.
|
||||
- Once dequeued, message routing may execute the native orchestrator path or an optional external backend path (`claude_code`, `opencode`, `codex`, `gemini`, `pi_embedded`) depending on agent/backend config.
|
||||
- Runtime backend mode can be overridden manually via `/backend` command fast-path (`status`, `activate pi`, `deactivate pi`, `use config`) and is persisted in preferences.
|
||||
- Runtime backend mode can be overridden manually via `/runtime` command fast-path (`status`, `activate pi`, `deactivate pi`, `use config`) and is persisted in preferences (`/backend` remains a compatibility alias).
|
||||
- Backend routing outcomes are auditable via `backend.route` / `backend.success` / `backend.fallback`, which enables offline canary evaluation without changing gateway protocol methods.
|
||||
|
||||
## Component Map
|
||||
|
||||
+29
-2
@@ -7,7 +7,7 @@
|
||||
"status": "completed",
|
||||
"date": "2026-02-24",
|
||||
"updated": "2026-02-24",
|
||||
"summary": "Added persisted global runtime backend mode control for Pi rollout/deactivation via `/backend` command fast-path (`status`, `activate pi`, `deactivate pi`, `use config`). This keeps Flynn's configured routing as default (`config_default`) while allowing manual Pi activation/deactivation without automatic global rollback.",
|
||||
"summary": "Added persisted global runtime backend mode control for Pi rollout/deactivation via `/backend` command fast-path (`status`, `activate pi`, `deactivate pi`, `use config`), with `/runtime` now available as a dedicated alias to avoid TUI `/backend` ambiguity. This keeps Flynn's configured routing as default (`config_default`) while allowing manual Pi activation/deactivation without automatic global rollback.",
|
||||
"files_modified": [
|
||||
"src/commands/types.ts",
|
||||
"src/commands/builtin/index.ts",
|
||||
@@ -26,6 +26,33 @@
|
||||
],
|
||||
"test_status": "pnpm test:run src/commands/builtin/index.test.ts src/preferences.test.ts src/daemon/routing.test.ts + pnpm typecheck passing"
|
||||
},
|
||||
"tui-runtime-command-reservation": {
|
||||
"status": "completed",
|
||||
"date": "2026-02-24",
|
||||
"updated": "2026-02-24",
|
||||
"summary": "Reserved `/runtime` in minimal/fullscreen TUI command parsing so it no longer falls through to the model/tool loop. TUI now responds with explicit guidance that runtime backend mode control is available in daemon/channel sessions, preventing accidental tool execution when users run `/runtime status` in TUI.",
|
||||
"files_modified": [
|
||||
"src/frontends/tui/commands.ts",
|
||||
"src/frontends/tui/minimal.ts",
|
||||
"src/frontends/tui/components/App.tsx",
|
||||
"src/frontends/tui/commands.test.ts",
|
||||
"src/frontends/tui/minimal.test.ts",
|
||||
"docs/plans/state.json"
|
||||
],
|
||||
"test_status": "pnpm test:run src/frontends/tui/commands.test.ts src/frontends/tui/minimal.test.ts + pnpm typecheck passing"
|
||||
},
|
||||
"runtime-backend-command-input-normalization": {
|
||||
"status": "completed",
|
||||
"date": "2026-02-24",
|
||||
"updated": "2026-02-24",
|
||||
"summary": "Hardened runtime backend mode command parsing to accept both subcommand input (`status`) and full-command input (`/runtime status`, `runtime status`, `/backend status`) so status/activation calls do not incorrectly fall back to usage text.",
|
||||
"files_modified": [
|
||||
"src/daemon/routing.ts",
|
||||
"src/daemon/routing.test.ts",
|
||||
"docs/plans/state.json"
|
||||
],
|
||||
"test_status": "pnpm test:run src/daemon/routing.test.ts + pnpm typecheck passing"
|
||||
},
|
||||
"pi-embedded-backend-canary-evaluation-phase": {
|
||||
"status": "completed",
|
||||
"date": "2026-02-24",
|
||||
@@ -6516,7 +6543,7 @@
|
||||
"next_up": "Track OpenClaw evolution regularly for inspiration and feature ideas",
|
||||
"pi_embedded_canary_spike": "completed — added optional pi_embedded backend adapter, canary-safe no-tools routing guard, backend success/fallback latency audit events, and docs/diagram updates while native remains default",
|
||||
"pi_embedded_evaluation_phase": "completed — final decision rollback (applied in runtime config): Window A failed latency/fallback gates (p50 +259ms, p95 +5695ms, fallback 25%, categories: pi_module_interface/empty_assistant_text); Window B remained sample-insufficient; controlled probes verified guard coverage (pi_no_tools_mode/capability_query/attachments_present each hit once)",
|
||||
"pi_embedded_manual_mode": "completed — added persisted runtime `/backend` controls for manual Pi activation/deactivation (`status`, `activate pi`, `deactivate pi`, `use config`) while keeping config-driven default routing"
|
||||
"pi_embedded_manual_mode": "completed — added persisted runtime backend controls for manual Pi activation/deactivation (`/runtime` preferred, `/backend` alias; `status`, `activate pi`, `deactivate pi`, `use config`) while keeping config-driven default routing"
|
||||
},
|
||||
"soul_md_and_cron_create": {
|
||||
"date": "2026-02-11",
|
||||
|
||||
Reference in New Issue
Block a user