diff --git a/README.md b/README.md index 01a31d4..6b65061 100644 --- a/README.md +++ b/README.md @@ -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 ` | In-chat skill discovery/install (`list`, `search `, `install `) | -| `/backend ` | Show or control global runtime backend mode | +| `/runtime ` | 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: diff --git a/docs/api/PROTOCOL.md b/docs/api/PROTOCOL.md index 04828bd..7b8a1fd 100644 --- a/docs/api/PROTOCOL.md +++ b/docs/api/PROTOCOL.md @@ -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`. diff --git a/docs/architecture/AGENT_DIAGRAM.md b/docs/architecture/AGENT_DIAGRAM.md index 3ea9321..09fc27c 100644 --- a/docs/architecture/AGENT_DIAGRAM.md +++ b/docs/architecture/AGENT_DIAGRAM.md @@ -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 diff --git a/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md b/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md index c685ae1..bfb1fd2 100644 --- a/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md +++ b/docs/architecture/GATEWAY_SESSIONS_AND_QUEUE.md @@ -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 diff --git a/docs/plans/state.json b/docs/plans/state.json index c72bcd2..f6c82b5 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -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",