Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(tui): every console view opens in ruflo tui, with a menu, a go prompt, Back and opt-in mouse (ADR-489 phase 5)

re7c29326d408
diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md
index dd3c319737..bad3e8dd98 100644
--- a/docs/USERGUIDE.md
+++ b/docs/USERGUIDE.md
@@ -596,6 +596,8 @@ npx ruflo tui --fps 12 # frames per second for moving pictures, 0-3
npx ruflo tui --no-anim # draw the pictures still (same as --fps 0)
npx ruflo tui --no-pictures # the words of each picture only
npx ruflo tui --boot # play the look's start-up screen first
+npx ruflo tui --mouse # click a page in the bar, scroll with the wheel (every action also has a key)
+npx ruflo tui --view federation # open on any console page, not only the first six
npx ruflo tui --plain | head -40 # print one plain frame and exit 0 (scripts, CI; the plain look, no colour)
```
@@ -610,6 +612,9 @@ Without a terminal and without `--plain`, `tui` prints a one-line hint and exits
| `j` `k` or the arrow keys | Scroll |
| `r` | Read the files again |
| `t` | Next look: Classic BBS, Orbital, plain |
+| `0` | The main menu: the console's board, with each entry's key (press it to open that page) |
+| `:` or `/` | Go to any page by name, id or key: `settings`, `go federation`, `terminal` |
+| `Esc` or Backspace | Back to the page you were on |
| `q` or `Ctrl-C` | Quit |
**What each page shows.** It reads Ruflo's own files and the CLI's output in the current project, and says `n/a` for anything it cannot measure.
@@ -637,7 +642,7 @@ y sends it · n cancels · it expires in 59 s
- **OpenRouter** needs `OPENROUTER_API_KEY` in your environment. The key is named by its variable and never shown. Requests go only to `https://openrouter.ai` and to the HTTPS hosts you name with `--convo-targets` (or `RUFLO_TUI_CONVO_TARGETS`, syntax `endpoint:<name>=<https-base-url>|<KEY_ENV>|<model>;...`), with no redirects. `--model` picks the model (default `openrouter/auto`), and `--max-spend-usd` stops sending once the provider-reported spend reaches the cap (default `0.5`).
- `--no-ai` turns the AI page off.
-**Limits.** Read-only except the AI page. Tested on Linux in tmux with Node 22; Windows, macOS and Node 20 are untested. The animation was measured on Linux: at 8 frames per second it used about 2–3% of one core and 14–80 KB/s of terminal output depending on the look and window size (Orbital on a 200 by 50 window is the heaviest), and 30 frames per second about 9% and 230 KB/s. The pages beyond these six, the main menu with its grouped navigation, and clicking are the next stage of ADR-489. Design and decisions: [ADR-489](../v3/docs/adr/ADR-489-ruflo-tui-standalone-console.md).
+**Limits.** Read-only except the AI page. Tested on Linux in tmux with Node 22; Windows, macOS and Node 20 are untested. The animation was measured on Linux: at 8 frames per second it used about 2–3% of one core and 14–80 KB/s of terminal output depending on the look and window size (Orbital on a 200 by 50 window is the heaviest), and 30 frames per second about 9% and 230 KB/s. **Every console page opens here** (33 of them, from the main menu `0` or the go prompt `:`), each with the console's own body. What changes is recorded per page in ADR-489: most are read-only here because their action buttons wait for the confirm gate (the next stage); the Room needs a Claude Code session and says so on one screen; the console's terminal is this shell's AI page. On the menu the console's keys work (`b` Hive-Mind, `9` Memory Lab, …; `q` still quits and `p` is the go prompt), so a letter there is not the page-bar letter. Design and decisions: [ADR-489](../v3/docs/adr/ADR-489-ruflo-tui-standalone-console.md).
**In Claude Code**, the same console has an optional Orbital look and a Theme Studio: run `/ruflo themes`. See the [console README](../plugins/ruflo-console/README.md#orbital-theme).
diff --git a/plugins/ruflo-console/tests/tui-nav.spec.ts b/plugins/ruflo-console/tests/tui-nav.spec.ts
index 98fded2d3e..391a0af735 100644
--- a/plugins/ruflo-console/tests/tui-nav.spec.ts
+++ b/plugins/ruflo-console/tests/tui-nav.spec.ts
@@ -70,7 +70,7 @@ describe('keys', () => {
expect([keyOf('o'), keyOf('c'), keyOf('s'), keyOf('e'), keyOf('m'), keyOf('a')]).toEqual([{ page: 'overview' }, { page: 'cost' }, { page: 'swarm' }, { page: 'events' }, { page: 'missions' }, { page: 'ai' }])
expect([keyOf('\t'), keyOf(`${ESC}[C`), keyOf('l')]).toEqual(['next', 'next', 'next'])
expect([keyOf(`${ESC}[Z`), keyOf(`${ESC}[D`), keyOf('h')]).toEqual(['prev', 'prev', 'prev'])
- expect([keyOf('0'), keyOf('7'), keyOf('9'), keyOf('x'), keyOf(`${ESC}]0;t\u0007`)]).toEqual([null, null, null, null, null])
+ expect([keyOf('7'), keyOf('8'), keyOf('9'), keyOf('x'), keyOf(`${ESC}]0;t\u0007`)]).toEqual([null, null, null, null, null])
})
it('has no key for Room: its content is a message box and Claude sessions this host does not have', () => {
diff --git a/plugins/ruflo-console/tests/tui-parity.spec.ts b/plugins/ruflo-console/tests/tui-parity.spec.ts
new file mode 100644
index 0000000000..c7aaf98ca6
--- /dev/null
+++ b/plugins/ruflo-console/tests/tui-parity.spec.ts
@@ -0,0 +1,220 @@
+/**
+ * Every console view has a recorded decision for the standalone terminal (ADR-489 phase 5), the shell opens each one, and the go prompt, the
+ * main-menu keys, Back and the mouse reach them. Run with
+ * npx vitest run plugins/ruflo-console/tests/tui-parity.spec.ts
+ */
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+
+import { VIEWS } from '../hooks/state'
+import { navHit, navLine, runTui, type TuiIO } from '../tui/run'
+import { PAGE_IDS, PARITY } from '../tui/parity'
+import { openSession } from '../tui/session'
+import { RUFLO_FILES } from './fixtures/ruflo-run'
+
+const ESC = '\u001b'
+const ADR = join(__dirname, '../../../v3/docs/adr/ADR-489-ruflo-tui-standalone-console.md')
+let root: string
+let project: string
+
+beforeAll(() => {
+ root = mkdtempSync(join(tmpdir(), 'tui-parity-'))
+ project = join(root, 'project')
+ for (const [path, body] of Object.entries(RUFLO_FILES)) {
+ mkdirSync(dirname(join(project, path)), { recursive: true })
+ writeFileSync(join(project, path), body)
+ }
+})
+afterAll(() => rmSync(root, { recursive: true, force: true }))
+
+const settle = (ms = 150) => new Promise(resolve => setTimeout(resolve, ms))
+const strip = (text: string) => text.replace(/\u001b\[[0-9;?<]*[A-Za-z]/g, '')
+
+describe('a decision for every console view', () => {
+ it('has a row in PARITY for each view in VIEWS, and for nothing else', () => {
+ const ids = [...VIEWS.map(view => view.id), 'agent'].sort()
+
+ expect(Object.keys(PARITY).sort()).toEqual(ids)
+ expect(PAGE_IDS).toEqual([...VIEWS.map(view => view.id), 'ai'])
+ for (const [id, entry] of Object.entries(PARITY)) {
+ expect(['same', 'partial', 'equivalent', 'claude-only'], id).toContain(entry.status)
+ expect(entry.why.length, id).toBeGreaterThan(8)
+ }
+ })
+
+ it('is written out in ADR-489, row for row, so the guide and the code cannot disagree', () => {
+ const adr = readFileSync(ADR, 'utf8')
+
+ for (const view of [...VIEWS, { id: 'agent', label: 'Agent drill-down' }]) {
+ const entry = PARITY[view.id as keyof typeof PARITY]
+
+ expect(adr, view.id).toContain(`| \`${view.id}\` | ${view.label} | ${entry.status} | ${entry.why} |`)
+ }
+ })
+
+ it('opens every view without throwing, in words only, with nothing but colour in the bytes', async () => {
+ const session = openSession({ cwd: project, home: join(root, 'home'), look: 'plain', fps: 0 })
+
+ await session.refresh()
+ for (const view of VIEWS) {
+ session.show(view.id)
+
+ const lines = session.frame(100, 'none', 40)
+
+ expect(lines.length, view.id).toBeGreaterThan(0)
+ expect(lines.join('\n'), view.id).not.toMatch(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/)
+ }
+ session.stop()
+ })
+
+ it('sends the console terminal to the AI page and says plainly that the Room needs Claude Code', async () => {
+ const session = openSession({ cwd: project, home: join(root, 'home'), look: 'plain', fps: 0, aiPage: {} })
+
+ session.show('terminal')
+ expect(session.page).toBe('ai')
+ session.show('room')
+ expect(session.page).toBe('room')
+
+ const note = session.frame(100, 'none', 30).join('\n')
+
+ expect(note).toContain('Room: Claude Code only')
+ expect(note).toContain(PARITY.room.why)
+ session.stop()
+ })
+
+ it('draws the main menu entries as words next to their keys (they were blank)', async () => {
+ const session = openSession({ cwd: project, home: join(root, 'home'), look: 'plain', fps: 0 })
+
+ await session.refresh()
+ session.show('menu')
+
+ const text = session.frame(100, 'none', 60).join('\n')
+
+ for (const word of ['Missions', 'Overview', 'Hive-Mind', 'Memory Lab', 'Settings']) expect(text, word).toContain(word)
+ session.stop()
+ })
+})
+
+function terminal(columns = 110, rows = 36) {
+ const out: string[] = []
+ const listeners: Array<(chunk: string) => void> = []
+ const io: TuiIO = {
+ stdin: { isTTY: true, setRawMode: () => undefined, on: (_e, fn) => void listeners.push(fn as never), off: () => void listeners.splice(0), resume: () => undefined, pause: () => undefined },
+ stdout: { isTTY: true, columns, rows, write: (text: string) => void out.push(text), on: () => undefined, off: () => undefined },
+ stderr: { write: () => undefined },
+ env: { TERM: 'xterm-256color' },
+ }
+
+ return { io, out, press: (key: string) => listeners.forEach(fn => fn(key)), screen: () => strip(out.join('').split(`${ESC}[H`).pop() ?? '') }
+}
+
+const options = { look: 'plain' as const, fps: 0 }
+
+describe('getting to every view from the keys', () => {
+ it('0 opens the menu, a menu key opens that view, and Esc comes back to where you were', async () => {
+ const t = terminal()
+ const running = runTui({ cwd: project, home: join(root, 'home'), ...options }, t.io)
+
+ await settle()
+ t.press('0')
+ await settle()
+ expect(t.screen()).toContain('Main Menu')
+ expect(navLine('menu', 110, 'none')).toContain('[Main Menu]')
+ t.press('b') // Hive-Mind on the board (b is Page Up everywhere else)
+ await settle()
+ expect(t.screen()).toMatch(/Hive-Mind/)
+ t.press(ESC)
+ await settle()
+ expect(t.screen()).toContain('Main Menu')
+ t.press(ESC)
+ await settle()
+ expect(t.screen()).toMatch(/Overview/)
+ t.press('q')
+ await running
+ })
+
+ it('has a go prompt that takes a name, an id or a prefix, and says so when there is no such page', async () => {
+ const t = terminal()
+ const running = runTui({ cwd: project, home: join(root, 'home'), ...options }, t.io)
+
+ await settle()
+ t.press(':')
+ for (const ch of 'go federation') t.press(ch)
+ expect(t.screen()).toContain('go> go federation')
+ t.press('\r')
+ await settle()
+ expect(t.screen()).toContain('Federation')
+ t.press('/')
+ for (const ch of 'nonsense') t.press(ch)
+ t.press('\r')
+ await settle()
+ expect(t.screen()).toContain('no page called "nonsense"')
+ t.press(':')
+ for (const ch of 'term') t.press(ch)
+ t.press('\r')
+ await settle()
+ expect(t.screen()).toMatch(/AI/)
+ t.press('q')
+ await running
+ })
+
+ it('lets a pasted escape sequence into the prompt as nothing (the prompt keeps text, not bytes)', async () => {
+ const t = terminal()
+ const running = runTui({ cwd: project, home: join(root, 'home'), ...options }, t.io)
+
+ await settle()
+ t.press(':')
+ t.press(`${ESC}]0;evil\u0007`)
+ expect(t.screen()).toContain('go> ▌')
+ t.press(ESC)
+ t.press('q')
+ await running
+ })
+
+ it('--view takes any page', async () => {
+ const t = terminal()
+ const running = runTui({ cwd: project, home: join(root, 'home'), view: 'federation', ...options }, t.io)
+
+ await settle()
+ expect(t.screen()).toContain('Federation')
+ t.press('q')
+ await running
+ })
+})
+
+describe('the mouse', () => {
+ it('is off unless asked for: no reporting is switched on, and report bytes are not read as keys', async () => {
+ const t = terminal()
+ const running = runTui({ cwd: project, home: join(root, 'home'), ...options }, t.io)
+
+ await settle()
+ expect(t.out.join('')).not.toContain('?1000h')
+ t.press(`${ESC}[<0;14;1M`)
+ await settle()
+ expect(t.screen()).toMatch(/Overview/)
+ t.press('q')
+ await running
+ })
+
+ it('with --mouse: a click on a page chip opens it, the wheel scrolls, and reporting is switched off on q', async () => {
+ const t = terminal(110, 12)
+ const running = runTui({ cwd: project, home: join(root, 'home'), mouse: true, ...options }, t.io)
+
+ await settle()
+ expect(t.out.join('')).toContain(`${ESC}[?1000h${ESC}[?1006h`)
+ expect(navHit(1, 110)).toBe('overview')
+ expect(navHit(14, 110)).toBe('cost')
+ t.press(`${ESC}[<0;14;1M`)
+ await settle()
+ expect(t.screen()).toMatch(/Cost/)
+ t.press(`${ESC}[<65;5;5M`)
+ await settle()
+ expect(t.screen()).toMatch(/\d+-\d+\/\d+/)
+ t.press(`${ESC}[<0;14;1m`) // a release is not a click
+ t.press('q')
+ await running
+ expect(t.out.join('').endsWith(`${ESC}[?1006l${ESC}[?1000l${ESC}[?1004l${ESC}[?25h${ESC}[?1049l`)).toBe(true)
+ })
+})
diff --git a/plugins/ruflo-console/tui/ansi.ts b/plugins/ruflo-console/tui/ansi.ts
index f2c0c6181e..e7ca886ffd 100644
--- a/plugins/ruflo-console/tui/ansi.ts
+++ b/plugins/ruflo-console/tui/ansi.ts
@@ -298,6 +298,9 @@ export function render(node: unknown, width: number, depth: Depth): string[] {
if (label.includes('✦')) return []
+ // A main-menu entry is a label next to its key chip, and the key is what opens it here (the shell reads it): the words stay, as text.
+ if (typeof props.key === 'string' && props.key.startsWith('menu-go-')) return [cut(` ${label} `, width)]
+
if (typeof props.key === 'string' && props.key.startsWith('sec-')) return [cut(`${sgr({ bold: true }, depth)}${label.replace(/^[▾▸]\s*/, '')}${depth === 'none' ? '' : RESET}`, width)]
return /^[●○]/.test(label) ? [cut(`${sgr({ dimColor: true }, depth)}${label} ${depth === 'none' ? '' : RESET}`, width)] : []
@@ -305,6 +308,9 @@ export function render(node: unknown, width: number, depth: Depth): string[] {
if (type !== 'Box') return []
+ // A box that asks for a width (the main menu's two groups side by side) is no wider than that, as on the console.
+ if (typeof props.width === 'number' && Number.isFinite(props.width) && props.width >= 3) width = Math.min(width, Math.floor(props.width))
+
const frame = props.borderStyle === 'round' || props.borderStyle === 'single' ? BORDER[props.borderStyle] : null
const padX = typeof props.paddingX === 'number' && props.paddingX > 0 ? Math.min(4, Math.floor(props.paddingX)) : 0
const inner = Math.max(1, width - (frame === null ? 0 : 2) - padX * 2)
diff --git a/plugins/ruflo-console/tui/main.ts b/plugins/ruflo-console/tui/main.ts
index df4c29f922..cda815cb96 100644
--- a/plugins/ruflo-console/tui/main.ts
+++ b/plugins/ruflo-console/tui/main.ts
@@ -1,4 +1,4 @@
/** The bundle entry (ADR-489): what `ruflo tui` loads. Built to dist/tui.mjs by scripts/build-tui.mjs. */
-export { runTui, isTuiView, keyOf, depthOf } from './run'
+export { runTui, isTuiView, isPage, keyOf, depthOf } from './run'
export type { TuiIO, TuiOptions } from './run'
export { TUI_VIEWS } from './session'
diff --git a/plugins/ruflo-console/tui/parity.ts b/plugins/ruflo-console/tui/parity.ts
new file mode 100644
index 0000000000..f5ffcb488f
--- /dev/null
+++ b/plugins/ruflo-console/tui/parity.ts
@@ -0,0 +1,54 @@
+/**
+ * Every console view and what `ruflo tui` does with it (ADR-489 phase 5). A view is a decision, not an accident: `parity.spec.ts` fails when a view
+ * is added to the console's `VIEWS` without an entry here, and when ADR-489's table does not name each view.
+ *
+ * - `same` the console's own page body, read-only, as in Claude Code.
+ * - `partial` the console's own page body, but part of it needs Claude Code (or the confirm gate of phase 6): `why` says which.
+ * - `equivalent` the job is done by another standalone page (`opens`).
+ * - `claude-only` the page is about a Claude Code session this terminal does not have: it opens a one-screen note, never an empty fake.
+ */
+import { VIEWS, type ViewId } from '../hooks/state'
+
+export type Parity = { status: 'same' | 'partial' | 'equivalent' | 'claude-only'; why: string; opens?: 'ai' }
+
+const READ_ONLY = 'read-only here: its action buttons are not drawn until the confirm gate of phase 6'
+
+export const PARITY: Record<ViewId | 'agent', Parity> = {
+ menu: { status: 'same', why: 'entries open by their key, as on the console board' },
+ missions: { status: 'partial', why: 'the mission record only: entering a goal, planning and research start a Claude turn' },
+ overview: { status: 'same', why: 'the Claude-only controls are not drawn' },
+ swarm: { status: 'same', why: 'topology, agents and votes as ruflo wrote them' },
+ hive: { status: 'partial', why: READ_ONLY },
+ claims: { status: 'partial', why: READ_ONLY },
+ workflows: { status: 'partial', why: 'the ruflo swarm side; Claude Code workflow runs are not visible outside a session' },
+ federation: { status: 'partial', why: READ_ONLY },
+ plugins: { status: 'partial', why: 'what is installed and loaded; "loaded as a mod" is a Claude Code fact and reads n/a' },
+ learning: { status: 'same', why: 'router picks, outcomes and the pipeline as on disk' },
+ metaharness: { status: 'partial', why: READ_ONLY },
+ memory: { status: 'partial', why: READ_ONLY },
+ cost: { status: 'partial', why: 'provider ledger and router counts; Claude Code spend, context and the budget ladder read n/a' },
+ timeline: { status: 'partial', why: 'agent lanes from status reports; Claude Code tool-call lanes need a session' },
+ approvals: { status: 'partial', why: 'shows what waits; answering is a write and waits for the confirm gate of phase 6' },
+ events: { status: 'same', why: 'the event stream as it is on disk; Ask Claude is not drawn' },
+ room: { status: 'claude-only', why: 'it is what people said to Claude in a session, plus a message box; this terminal has neither' },
+ xruv: { status: 'partial', why: READ_ONLY },
+ terminal: { status: 'equivalent', why: 'the standalone AI page (Codex or OpenRouter, each question after a card)', opens: 'ai' },
+ skills: { status: 'partial', why: READ_ONLY },
+ secure: { status: 'partial', why: READ_ONLY },
+ perf: { status: 'partial', why: READ_ONLY },
+ automate: { status: 'partial', why: READ_ONLY },
+ neural: { status: 'partial', why: READ_ONLY },
+ vector: { status: 'partial', why: READ_ONLY },
+ evolve: { status: 'partial', why: READ_ONLY },
+ devtools: { status: 'partial', why: READ_ONLY },
+ sandbox: { status: 'partial', why: READ_ONLY },
+ market: { status: 'partial', why: READ_ONLY },
+ adrs: { status: 'partial', why: READ_ONLY },
+ whatsnew: { status: 'same', why: 'changelogs of the installed plugins' },
+ themes: { status: 'partial', why: 'the look is chosen with t or --look; the colour picker and generated themes are not here yet' },
+ settings: { status: 'partial', why: 'shown read-only; changing a setting waits for the confirm gate of phase 6' },
+ agent: { status: 'partial', why: 'the drill-down from a Swarm selection; selecting needs the host keys, so it says so' },
+}
+
+/** The views the standalone shell can open by name: every console view and the AI page. */
+export const PAGE_IDS: readonly (ViewId | 'ai')[] = [...VIEWS.map(view => view.id), 'ai']
diff --git a/plugins/ruflo-console/tui/run.ts b/plugins/ruflo-console/tui/run.ts
index 1475d27d00..6ceda27b9f 100644
--- a/plugins/ruflo-console/tui/run.ts
+++ b/plugins/ruflo-console/tui/run.ts
@@ -5,7 +5,9 @@
*/
import type { Depth } from './ansi'
import { cells, clean, widthOf } from './ansi'
-import { openSession, TUI_VIEWS, type Look, type Session, type SessionOptions, type TuiView } from './session'
+import { VIEWS, viewOf } from '../hooks/state'
+import { PAGE_IDS } from './parity'
+import { openSession, TUI_VIEWS, type Look, type Page, type Session, type SessionOptions, type TuiView } from './session'
export type TuiInput = {
isTTY?: boolean
@@ -24,9 +26,11 @@ export type TuiOutput = {
off?: (event: 'resize', fn: () => void) => unknown
}
export type TuiIO = { stdin: TuiInput; stdout: TuiOutput; stderr: { write: (text: string) => unknown }; env: Record<string, string | undefined>; signal?: AbortSignal }
-export type TuiOptions = { cwd: string; view?: TuiView; plain?: boolean; cliEntry?: string; configDir?: string; home?: string; pluginRoot?: string; refreshMs?: number; /** The look (bbs | orbital | plain: default bbs) and the frames per second of moving pictures (default 8, at most 30; 0 draws them still). */ look?: Look; fps?: number; /** False: no animation (a still frame, like fps 0). */ anim?: boolean; /** False: no pictures, only their words. */ pictures?: boolean; /** True: play the start-up screen first (as the console's boot setting). */ boot?: boolean; /** The AI page's settings; absent: the page is off. */ aiPage?: SessionOptions['aiPage'] }
+export type TuiOptions = { cwd: string; view?: Page; /** True: read SGR mouse reports (a click on the page bar, the wheel to scroll). Off by default; every mouse action has a key. */ mouse?: boolean; plain?: boolean; cliEntry?: string; configDir?: string; home?: string; pluginRoot?: string; refreshMs?: number; /** The look (bbs | orbital | plain: default bbs) and the frames per second of moving pictures (default 8, at most 30; 0 draws them still). */ look?: Look; fps?: number; /** False: no animation (a still frame, like fps 0). */ anim?: boolean; /** False: no pictures, only their words. */ pictures?: boolean; /** True: play the start-up screen first (as the console's boot setting). */ boot?: boolean; /** The AI page's settings; absent: the page is off. */ aiPage?: SessionOptions['aiPage'] }
export const isTuiView = (value: unknown): value is TuiView => typeof value === 'string' && (TUI_VIEWS as readonly string[]).includes(value)
+/** Any page the shell can open, which is every console view and the AI page (`--view`, the go prompt). */
+export const isPage = (value: unknown): value is Page => typeof value === 'string' && (PAGE_IDS as readonly string[]).includes(value)
/** Colour depth from the environment: NO_COLOR and a dumb terminal get none, COLORTERM truecolor/24bit gets 24-bit, the rest 256. */
export function depthOf(env: Record<string, string | undefined>): Depth {
@@ -48,20 +52,46 @@ const LABELS: Record<TuiView, string> = { overview: 'Overview', cost: 'Cost', sw
const LETTER: Partial<Record<string, TuiView>> = { o: 'overview', c: 'cost', s: 'swarm', e: 'events', m: 'missions', a: 'ai' }
/** The page bar: every page with its number (the current one in reverse), or `‹ 3/6 Swarm ›` when the terminal is too narrow for all of them. Page names are ours, never from a file. */
-export function navLine(view: TuiView, columns: number, depth: Depth): string {
+export function navLine(view: Page, columns: number, depth: Depth): string {
const wide = TUI_VIEWS.map((page, i) => {
const text = ` ${i + 1} ${LABELS[page]} `
return page === view && depth !== 'none' ? `${ESC}[7m${text}${ESC}[0m` : page === view ? `[${text.trim()}]` : text
}).join(' ')
+ const other = (TUI_VIEWS as readonly string[]).includes(view) ? null : (VIEWS.find(entry => entry.id === view)?.label ?? view)
- return widthOf(wide) <= columns ? wide : `‹ ${TUI_VIEWS.indexOf(view) + 1}/${TUI_VIEWS.length} ${LABELS[view]} ›`
+ // A page that is not one of the six shows after them, as the one chip that is on.
+ if (other !== null) {
+ const chip = depth !== 'none' ? `${ESC}[7m ${other} ${ESC}[0m` : `[${other}]`
+ const all = `${wide} ${chip}`
+
+ return widthOf(all) <= columns ? all : `‹ ${clean(other)} › (Esc back)`.slice(0, columns)
+ }
+
+ return widthOf(wide) <= columns ? wide : `‹ ${TUI_VIEWS.indexOf(view as TuiView) + 1}/${TUI_VIEWS.length} ${LABELS[view as TuiView]} ›`
+}
+
+/** Which of the six page chips a click at column `x` (1-based) lands on, or null: the same positions `navLine` draws when it fits. */
+export function navHit(x: number, columns: number): TuiView | null {
+ const chips = TUI_VIEWS.map((page, k) => ` ${k + 1} ${LABELS[page]} `)
+
+ if (chips.join(' ').length > columns) return null
+
+ let at = 1
+
+ for (const [k, chip] of chips.entries()) {
+ if (x >= at && x < at + chip.length) return TUI_VIEWS[k] as TuiView
+ at += chip.length + 1
+ }
+
+ return null
}
/** The key line under the page: every key when there is room, fewer keys as the terminal narrows, always inside `columns` (the scroll position, when there is one, is counted in). `own` replaces the page keys (the AI page has its own). */
export function keyLine(columns: number, place = '', own?: readonly string[]): string {
const pages = `1-${TUI_VIEWS.length}`
- const tiers = own ?? [`${pages} or o c s e m a page · tab next · r refresh · t look · j/k scroll · q quit · read-only`, `${pages} page · tab next · r refresh · j/k scroll · q quit`, `${pages} page · j/k scroll · q quit`, `${pages} page · q quit`]
+ const menu = '0 menu · : go to any page · Esc back'
+ const tiers = own ?? [`${pages} or o c s e m a page · ${menu} · tab next · r refresh · t look · j/k scroll · q quit · read-only`, `${pages} or o c s e m a page · 0 menu · : go · tab next · r refresh · j/k scroll · q quit · read-only`, `${pages} page · 0 menu · : go · Esc back · tab next · r refresh · j/k scroll · q quit`, `${pages} page · tab next · r refresh · j/k scroll · q quit`, `${pages} page · j/k scroll · q quit`, `${pages} page · q quit`]
const fits = tiers.find(line => cells(line + place) <= columns) ?? tiers[tiers.length - 1] as string
return `${fits}${place}`.slice(0, columns)
@@ -76,7 +106,7 @@ export function aiKeyTiers(mode: 'type' | 'nav', hasCard: boolean): string[] {
}
/** One keypress as an action, from the bytes a terminal sends. Anything else is ignored. */
-export type Key = 'quit' | 'look' | { page: TuiView } | 'next' | 'prev' | 'refresh' | 'down' | 'up' | 'pagedown' | 'pageup' | 'top' | 'bottom' | null
+export type Key = 'quit' | 'look' | 'menu' | 'prompt' | 'back' | { page: TuiView } | 'next' | 'prev' | 'refresh' | 'down' | 'up' | 'pagedown' | 'pageup' | 'top' | 'bottom' | null
export function keyOf(chunk: string): Key {
switch (chunk) {
@@ -92,6 +122,15 @@ export function keyOf(chunk: string): Key {
case 'h':
case `${ESC}[D`:
return 'prev'
+ case '0':
+ return 'menu'
+ case ':':
+ case '/':
+ return 'prompt'
+ case `${ESC}`:
+ case '\u007f':
+ case '\b':
+ return 'back'
case 'r':
return 'refresh'
case 't':
@@ -150,7 +189,7 @@ function writeTick(io: TuiIO, screen: string[], memory: Memory, columns: number,
if (out !== '') io.stdout.write(out)
}
-function paint(session: Session, io: TuiIO, depth: Depth, scroll: number, memory: Memory, clear = false, tick = false): number {
+function paint(session: Session, io: TuiIO, depth: Depth, scroll: number, memory: Memory, clear = false, tick = false, line = ''): number {
const ai = session.page === 'ai' ? session.ai : null
const raw = io.stdout.columns ?? 100
const rows = Math.max(5, io.stdout.rows ?? 30)
@@ -177,7 +216,7 @@ function paint(session: Session, io: TuiIO, depth: Depth, scroll: number, memory
// The AI page fits its own conversation to the room and follows the tail; the others scroll.
const top = session.page === 'ai' ? 0 : Math.max(0, Math.min(scroll, Math.max(0, lines.length - room)))
const place = lines.length > room ? ` · ${top + 1}-${Math.min(lines.length, top + room)}/${lines.length}` : ''
- const footer = `${depth === 'none' ? '' : `${ESC}[2m`}${clean(keyLine(columns, place, session.page === 'ai' && session.ai !== null ? aiKeyTiers(session.ai.mode, session.ai.card !== null) : undefined))}${depth === 'none' ? '' : `${ESC}[0m`}`
+ const footer = `${depth === 'none' ? '' : `${ESC}[2m`}${line !== '' ? clean(line).slice(0, columns) : clean(keyLine(columns, place, session.page === 'ai' && session.ai !== null ? aiKeyTiers(session.ai.mode, session.ai.card !== null) : undefined))}${depth === 'none' ? '' : `${ESC}[0m`}`
const body = [...lines.slice(top, top + room), ...Array.from({ length: Math.max(0, room - (lines.length - top)) }, () => '')]
@@ -193,7 +232,7 @@ function paint(session: Session, io: TuiIO, depth: Depth, scroll: number, memory
}
/** `--plain`: one frame as plain text on stdout (the same views, read-only, no escapes) and exit 0. Nothing on stderr, so a script's output is only the frame. */
-async function once(session: Session, io: TuiIO, view: TuiView): Promise<number> {
+async function once(session: Session, io: TuiIO, view: Page): Promise<number> {
session.show(view)
await session.refresh()
const columns = Math.max(MIN_COLUMNS, Math.min(200, io.stdout.columns ?? 100))
@@ -216,7 +255,7 @@ export async function runTui(options: TuiOptions, io: TuiIO): Promise<number> {
}
const session = openSession({ cwd: options.cwd, ...((options.look ?? (options.plain === true ? 'plain' : undefined)) !== undefined && { look: options.look ?? 'plain' }), fps: options.anim === false ? 0 : fpsOf(options.fps), ...(options.pictures === false && { pictures: false }), ...(options.boot === true && { boot: true }), ...(options.cliEntry !== undefined && { cliEntry: options.cliEntry }), ...(options.configDir !== undefined && { configDir: options.configDir }), ...(options.home !== undefined && { home: options.home }), ...(options.pluginRoot !== undefined && { pluginRoot: options.pluginRoot }), ...(options.aiPage !== undefined && { aiPage: options.aiPage }) })
- let view: TuiView = options.view ?? 'overview'
+ let view: Page = options.view ?? 'overview'
try {
if (options.plain === true || !interactive || io.stdin.setRawMode === undefined) return await once(session, io, view)
@@ -228,28 +267,107 @@ export async function runTui(options: TuiOptions, io: TuiIO): Promise<number> {
let finish: () => void = () => undefined
const done = new Promise<void>(resolve => void (finish = resolve))
const memory: Memory = { lines: [], columns: 0, rows: 0 }
- const draw = (tick = false) => void (scroll = paint(session, io, depth, scroll, memory, false, tick))
+ // The go prompt (":" or "/"): a page by its name, id or key, read from the keys, shown in the key line. `notice` is one line of news until the next key.
+ let prompt: string | null = null
+ let notice = ''
+ const history: Page[] = []
+ const line = () => (prompt !== null ? `go> ${prompt}▌ (a page name · Enter opens · Esc cancels)` : notice)
+ const draw = (tick = false) => void (scroll = paint(session, io, depth, scroll, memory, false, tick, line()))
const reread = async () => {
await session.refresh()
if (!isDone) draw()
}
session.onChange(() => void (isDone || draw()))
+ const open = (next: Page) => {
+ if (next !== view) history.push(view), history.length > 30 && history.shift()
+
+ view = next
+ scroll = 0
+ session.show(view)
+ view = session.page
+ if (session.page === 'ai') session.ai?.enter()
+ else if (!(TUI_VIEWS as readonly string[]).includes(view)) void reread()
+ }
+ const goTo = (word: string) => {
+ const name = word.trim().replace(/^(go|open)\s+/i, '')
+ const found = name.toLowerCase() === 'ai' ? 'ai' : viewOf(name)
+
+ if (found === null || found === 'agent') notice = `no page called "${clean(name).slice(0, 30)}": try 0 for the menu`
+ else open(found)
+ }
+ const onMouse = (chunk: string): boolean => {
+ const hit = /^\u001b\[<(\d+);(\d+);(\d+)([Mm])$/.exec(chunk)
+
+ if (hit === null) return false
+
+ const [button, x, y] = [Number(hit[1]), Number(hit[2]), Number(hit[3])]
+
+ if (hit[4] !== 'M') return true
+ if (button === 64) scroll = Math.max(0, scroll - 3)
+ else if (button === 65) scroll += 3
+ else if (button === 0 && y === 1) {
+ const page = navHit(x, Math.min(200, io.stdout.columns ?? 100))
+
+ if (page !== null) open(page)
+ }
+
+ draw()
+
+ return true
+ }
+
const onKey = (chunk: Buffer | string) => {
// The AI page takes the keys while you type (digits and letters are text there): Esc hands them back to the shell, and Ctrl-C always quits.
- if (view === 'ai' && session.ai !== null && session.ai.press(chunk.toString()).consumed) return draw()
+ if (session.page === 'ai' && session.ai !== null && session.ai.press(chunk.toString()).consumed) return draw()
// Focus reports (the terminal tells us when it is behind another window): a hidden terminal draws nothing, and a refocused one draws at once.
if (chunk.toString() === `${ESC}[O`) return void (isFocused = false)
if (chunk.toString() === `${ESC}[I`) return void ((isFocused = true), draw())
- const key = keyOf(chunk.toString())
+ if (options.mouse === true && onMouse(chunk.toString())) return
+
+ const text = chunk.toString()
+
+ notice = ''
+
+ if (prompt !== null) {
+ if (text === '\r' || text === '\n') {
+ const word = prompt
+
+ prompt = null
+ goTo(word)
+ } else if (text === ESC || text === '\u0003') prompt = null
+ else if (text === '\u007f' || text === '\b') prompt = prompt.slice(0, -1)
+ else if (text.length === 1 && text >= ' ' && text !== '\u007f' && prompt.length < 40) prompt += text
+ else if (text.length > 1 && !text.includes(ESC) && prompt.length + text.length <= 40) prompt += clean(text).replace(/[\r\n]/g, '')
+
+ return draw()
+ }
+
+ // The main menu's keys are the console's own: an entry opens by its key chip (q still quits, and p is the palette, here the go prompt).
+ if (view === 'menu' && text.length === 1 && text !== 'q') {
+ const entry = VIEWS.find(candidate => candidate.key !== '' && candidate.key === text)
+
+ if (entry !== undefined) return void (open(entry.id), draw())
+ if (text === 'p') return void ((prompt = ''), draw())
+ }
+
+ const key = keyOf(text)
const page = Math.max(1, (io.stdout.rows ?? 30) - 2)
if (key === 'quit') return finish()
- if (typeof key === 'object' && key !== null) (view = key.page), (scroll = 0), session.show(view), view === 'ai' && session.ai?.enter()
- else if (key === 'next') (view = TUI_VIEWS[(TUI_VIEWS.indexOf(view) + 1) % TUI_VIEWS.length] as TuiView), (scroll = 0), session.show(view)
- else if (key === 'prev') (view = TUI_VIEWS[(TUI_VIEWS.indexOf(view) + TUI_VIEWS.length - 1) % TUI_VIEWS.length] as TuiView), (scroll = 0), session.show(view)
+ if (typeof key === 'object' && key !== null) open(key.page)
+ else if (key === 'menu') open('menu')
+ else if (key === 'prompt') prompt = ''
+ else if (key === 'back') {
+ const previous = history.pop()
+
+ if (previous === undefined) notice = 'nothing to go back to'
+ else (view = previous), (scroll = 0), session.show(view), (view = session.page)
+ }
+ else if (key === 'next') open(TUI_VIEWS[(TUI_VIEWS.indexOf(view as TuiView) + 1) % TUI_VIEWS.length] as TuiView)
+ else if (key === 'prev') open(TUI_VIEWS[(TUI_VIEWS.indexOf(view as TuiView) + TUI_VIEWS.length - 1) % TUI_VIEWS.length] as TuiView)
else if (key === 'down') scroll += 1
else if (key === 'up') scroll = Math.max(0, scroll - 1)
else if (key === 'pagedown') scroll += page
@@ -264,7 +382,7 @@ export async function runTui(options: TuiOptions, io: TuiIO): Promise<number> {
}
session.show(view)
- io.stdout.write(`${ESC}[?1049h${ESC}[?25l${ESC}[?1004h`)
+ io.stdout.write(`${ESC}[?1049h${ESC}[?25l${ESC}[?1004h${options.mouse === true ? `${ESC}[?1000h${ESC}[?1006h` : ''}`)
io.stdin.setRawMode(true)
io.stdin.resume()
io.stdin.on('data', onKey)
@@ -301,7 +419,7 @@ export async function runTui(options: TuiOptions, io: TuiIO): Promise<number> {
io.stdout.off?.('resize', resize)
io.stdin.setRawMode(false)
io.stdin.pause()
- io.stdout.write(`${ESC}[?1004l${ESC}[?25h${ESC}[?1049l`)
+ io.stdout.write(`${options.mouse === true ? `${ESC}[?1006l${ESC}[?1000l` : ''}${ESC}[?1004l${ESC}[?25h${ESC}[?1049l`)
}
return 0
diff --git a/plugins/ruflo-console/tui/session.ts b/plugins/ruflo-console/tui/session.ts
index 8662ce9665..72a356651d 100644
--- a/plugins/ruflo-console/tui/session.ts
+++ b/plugins/ruflo-console/tui/session.ts
@@ -8,6 +8,8 @@ import type { Host } from '../hooks/host'
import { newState, type State } from '../hooks/state'
import { picturesOf } from '../hooks/views/frames'
import { BODIES, NARROW } from '../hooks/views/pane'
+import { VIEWS, type ViewId } from '../hooks/state'
+import { PARITY } from './parity'
import { standalonePane } from '../hooks/views/standalone-pane'
import { render, terminalKit, type Depth } from './ansi'
import { aiConfigOf, openAi, type Ai, type AiOptions as AiPageOptions } from './ai'
@@ -23,6 +25,8 @@ export const TUI_VIEWS = ['overview', 'cost', 'swarm', 'events', 'missions', 'ai
export type TuiView = (typeof TUI_VIEWS)[number]
/** The pages that are the console's own views. `ai` is the terminal's own page (ADR-489 phase 3): ask Codex or OpenRouter. */
export type ConsoleView = Exclude<TuiView, 'ai'>
+/** Any page the shell can show: every console view (ADR-489 phase 5, `parity.ts` says what each does here) and the AI page. */
+export type Page = ViewId | 'ai'
/** What the AI page may do. Absent: the page says it is off and the host refuses every spawn, send and key read (phase 2). */
export type Look = 'bbs' | 'orbital' | 'plain'
@@ -57,10 +61,10 @@ export type Session = {
/** True when this frame has anything that moves (a picture drawn at fps above 0): the shell redraws on its clock only then. */
moving: () => boolean
/** The page now showing. */
- page: TuiView
+ page: Page
/** Reads the disk again and runs the page's read-only probes, then returns. Never throws. */
refresh: () => Promise<void>
- show: (view: TuiView) => void
+ show: (view: Page) => void
/** The page as terminal lines, `columns` wide. `rows` is how many the terminal has for it (the AI page fits its conversation to them). */
frame: (columns: number, depth: Depth, rows?: number) => string[]
/** Something changed that the screen should show (streamed output): the shell redraws. */
@@ -101,7 +105,7 @@ export function openSession(options: SessionOptions, host?: Host): Session {
const controller = createController(state, node)
const ai = page === undefined ? null : openAi(state, node, page)
const aiStatus: AiStatus = { codex: ai === null ? 'off' : 'checking…', openrouter: ai === null ? 'off' : 'checking…' }
- let current: TuiView = 'overview'
+ let current: Page = 'overview'
let cardFits = false
let isMoving = false
@@ -148,11 +152,12 @@ export function openSession(options: SessionOptions, host?: Host): Session {
}
},
show: view => {
- current = view
+ // A page whose job another page does (the console's AI terminal is this shell's AI page) opens that page.
+ current = view === 'ai' ? 'ai' : (PARITY[view]?.opens ?? view)
- if (view !== 'ai') {
- state.view = view
- state.back = view
+ if (current !== 'ai') {
+ state.view = current
+ state.back = current
}
},
frame: (columns, depth, rows = 30) => {
@@ -168,6 +173,13 @@ export function openSession(options: SessionOptions, host?: Host): Session {
return drawn.lines
}
+ // A page about a Claude Code session says so in one screen, not as a page of empty cards.
+ if (PARITY[current as ViewId]?.status === 'claude-only') {
+ const entry = VIEWS.find(view => view.id === current)
+
+ return [`${entry?.label ?? current}: Claude Code only`, '', PARITY[current as ViewId].why, '', 'Open it in the ruflo console inside Claude Code. Press 0 for the main menu, Esc to go back.']
+ }
+
// Pictures need colour and room: without either the views say in words what the picture shows (the same fallback the console has below NARROW columns).
const draws = options.pictures !== false && depth !== 'none' && columns >= NARROW
const now = Date.now()
diff --git a/v3/@claude-flow/cli/__tests__/tui-command.test.ts b/v3/@claude-flow/cli/__tests__/tui-command.test.ts
index f8bf3fc949..34225277e2 100644
--- a/v3/@claude-flow/cli/__tests__/tui-command.test.ts
+++ b/v3/@claude-flow/cli/__tests__/tui-command.test.ts
@@ -64,8 +64,8 @@ describe('tui command', () => {
expect(result).toMatchObject({ success: false, exitCode: 1 });
});
- it.skipIf(locateTuiBundle() === null)('opens each of the six pages with --plain, and refuses Room and anything else with exit 2 (real bundle)', async () => {
- for (const view of ['overview', 'cost', 'swarm', 'events', 'missions', 'ai']) {
+ it.skipIf(locateTuiBundle() === null)('opens each of the six pages and any other console view with --plain, and refuses an unknown name with exit 2 (real bundle)', async () => {
+ for (const view of ['overview', 'cost', 'swarm', 'events', 'missions', 'ai', 'menu', 'federation', 'settings', 'room']) {
const lines: string[] = [];
const real = process.stdout.write.bind(process.stdout);
process.stdout.write = ((chunk: string | Uint8Array) => (lines.push(String(chunk)), true)) as typeof process.stdout.write;
@@ -80,7 +80,7 @@ describe('tui command', () => {
expect(lines.join(''), view).not.toContain(process.env.OPENROUTER_API_KEY ?? '\u0000never');
}
- for (const view of ['room', 'nope']) {
+ for (const view of ['nope', 'federation; rm -rf /']) {
expect(await tuiCommand.action!({ args: [], flags: { view, plain: true }, cwd: tmp() } as never), view).toMatchObject({ success: false, exitCode: 2 });
}
});
@@ -152,7 +152,7 @@ describe('tui command', () => {
describe('the look and motion flags', () => {
it('pass a valid look, an fps from 0 to 30 (a number or digits), --no-anim, --no-pictures and --boot, and nothing else', () => {
expect(lookFlags({})).toEqual({});
- expect(lookFlags({ look: 'orbital', fps: 12, anim: false, pictures: false, boot: true })).toEqual({ look: 'orbital', fps: 12, anim: false, pictures: false, boot: true });
+ expect(lookFlags({ look: 'orbital', fps: 12, anim: false, pictures: false, boot: true, mouse: true })).toEqual({ look: 'orbital', fps: 12, anim: false, pictures: false, boot: true, mouse: true });
expect(lookFlags({ look: 'bbs', fps: '30' })).toEqual({ look: 'bbs', fps: 30 });
expect(lookFlags({ fps: 0 })).toEqual({ fps: 0 });
});
@@ -166,6 +166,6 @@ describe('the look and motion flags', () => {
});
it('are listed in the command\'s options', () => {
- expect((tuiCommand.options ?? []).map(option => option.name)).toEqual(expect.arrayContaining(['look', 'fps', 'anim', 'pictures', 'boot']));
+ expect((tuiCommand.options ?? []).map(option => option.name)).toEqual(expect.arrayContaining(['look', 'fps', 'anim', 'pictures', 'boot', 'mouse']));
});
});
diff --git a/v3/@claude-flow/cli/src/commands/tui.ts b/v3/@claude-flow/cli/src/commands/tui.ts
index db87c06fa0..82e4934a04 100644
--- a/v3/@claude-flow/cli/src/commands/tui.ts
+++ b/v3/@claude-flow/cli/src/commands/tui.ts
@@ -25,7 +25,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
const VIEWS = ['overview', 'cost', 'swarm', 'events', 'missions', 'ai'] as const;
-type TuiModule = { runTui: (options: Record<string, unknown>, io: Record<string, unknown>) => Promise<number>; isTuiView: (value: unknown) => boolean };
+type TuiModule = { runTui: (options: Record<string, unknown>, io: Record<string, unknown>) => Promise<number>; isTuiView: (value: unknown) => boolean; isPage?: (value: unknown) => boolean };
/** `<own install>/plugins/ruflo-console/dist/tui.mjs`, the first that exists. */
export function locateTuiBundle(startDir: string = __dirname): string | null {
@@ -43,7 +43,7 @@ function cliEntry(): string | undefined {
}
/** The look and motion flags: `--look bbs|orbital|plain` (default bbs, as in the console), `--fps N` (0-30, default 8; 0 draws pictures still), `--no-anim`, `--no-pictures`. A bad value is ignored, never passed on. */
-export function lookFlags(flags: Record<string, unknown> | undefined): { look?: string; fps?: number; anim?: boolean; pictures?: boolean; boot?: boolean } {
+export function lookFlags(flags: Record<string, unknown> | undefined): { look?: string; fps?: number; anim?: boolean; pictures?: boolean; boot?: boolean; mouse?: boolean } {
const look = flags?.look;
const fps = flags?.fps;
const number = typeof fps === 'number' ? fps : typeof fps === 'string' && /^\d{1,2}$/.test(fps) ? Number(fps) : undefined;
@@ -54,6 +54,7 @@ export function lookFlags(flags: Record<string, unknown> | undefined): { look?:
...(flags?.anim === false ? { anim: false } : {}),
...(flags?.pictures === false ? { pictures: false } : {}),
...(flags?.boot === true ? { boot: true } : {}),
+ ...(flags?.mouse === true ? { mouse: true } : {}),
};
}
@@ -71,7 +72,7 @@ export const tuiCommand: Command = {
name: 'tui',
description: 'The ruflo console in your terminal: Overview, Cost, Swarm, Events, Missions (read-only) and an AI page that asks Codex or OpenRouter, each question after a card.',
options: [
- { name: 'view', description: `Page to open: ${VIEWS.join(' | ')}`, type: 'string' as const, default: 'overview' },
+ { name: 'view', description: `Page to open: ${VIEWS.join(' | ')}, or any console view (menu, federation, settings, ...): 0 opens the menu and : goes to a page by name`, type: 'string' as const, default: 'overview' },
{ name: 'ai', description: 'The AI page (ask Codex read-only or OpenRouter, each question after a confirm card). --no-ai turns it off', type: 'boolean' as const, default: true },
{ name: 'model', description: 'OpenRouter model for this session (default openrouter/auto)', type: 'string' as const },
{ name: 'max-spend-usd', description: 'Stop sending to OpenRouter once the provider-reported spend reaches this (default 0.5)', type: 'number' as const },
@@ -80,6 +81,7 @@ export const tuiCommand: Command = {
{ name: 'fps', description: 'Frames per second for moving pictures, 0-30 (default 8; 0 draws every picture still)', type: 'number' as const },
{ name: 'anim', description: 'Animate the pictures. --no-anim draws them still', type: 'boolean' as const, default: true },
{ name: 'pictures', description: 'Draw the pictures of the console (title art, swarm graph, gauges). --no-pictures shows their words only', type: 'boolean' as const, default: true },
+ { name: 'mouse', description: 'Read mouse reports: click a page in the bar, scroll with the wheel (every action also has a key)', type: 'boolean' as const, default: false },
{ name: 'boot', description: 'Play the look\'s start-up screen first (as the console\'s boot setting)', type: 'boolean' as const, default: false },
{ name: 'plain', description: 'Print one frame as plain text and exit 0 (scripts and CI). Without it, a non-terminal gets a hint and exit 2', type: 'boolean' as const, default: false },
],
@@ -93,7 +95,10 @@ export const tuiCommand: Command = {
const ctx = context as { args?: string[]; flags?: Record<string, unknown>; cwd?: string };
const wanted = (ctx.flags?.view as string | undefined) ?? ctx.args?.find(arg => !arg.startsWith('-')) ?? 'overview';
- if (!(VIEWS as readonly string[]).includes(wanted)) {
+ // The six pages are known here; any other console view (menu, federation, settings, …) is checked against the bundle's own list once it is loaded.
+ const isKnown = (VIEWS as readonly string[]).includes(wanted);
+
+ if (!isKnown && !/^[a-z]{2,16}$/.test(wanted)) {
output.writeln(output.error(`tui: unknown view "${String(wanted).slice(0, 40)}". Use one of: ${VIEWS.join(', ')}`));
return { success: false, exitCode: 2, data: { error: 'unknown-view' } };
}
@@ -113,6 +118,11 @@ export const tuiCommand: Command = {
return { success: false, exitCode: 1, data: { error: 'bundle-load-failed' } };
}
+ if (!isKnown && mod.isPage?.(wanted) !== true) {
+ output.writeln(output.error(`tui: unknown view "${String(wanted).slice(0, 40)}". Use one of: ${VIEWS.join(', ')}, or any console view such as menu, federation, settings`));
+ return { success: false, exitCode: 2, data: { error: 'unknown-view' } };
+ }
+
const stop = new AbortController();
const onSignal = () => stop.abort();
process.once('SIGTERM', onSignal);
diff --git a/v3/docs/adr/ADR-489-ruflo-tui-standalone-console.md b/v3/docs/adr/ADR-489-ruflo-tui-standalone-console.md
index f699f87fa5..71601add37 100644
--- a/v3/docs/adr/ADR-489-ruflo-tui-standalone-console.md
+++ b/v3/docs/adr/ADR-489-ruflo-tui-standalone-console.md
@@ -1,6 +1,6 @@
# ADR 489: `ruflo tui`: the console in a terminal of its own, over the same views
-Status: Accepted. The owner accepted decisions A to E on 2026-10-11 (section 8). Phase 1 (read-only Overview and Cost, `--plain`, publish wiring) is implemented in PR #4059; phase 2 (Swarm, Events and Missions, page bar and keys, resize, host capability flag) is implemented in PR #4075; phase 3 (the AI page: Codex and OpenRouter, each question after a card) is implemented in PR 2 of the continuation; phase 4 (pictures, looks and motion) is implemented in console 0.44.0; phase 5 (every console view through this host) and phase 6 (actions) are the roadmap and must follow those decisions.
+Status: Accepted. The owner accepted decisions A to E on 2026-10-11 (section 8). Phase 1 (read-only Overview and Cost, `--plain`, publish wiring) is implemented in PR #4059; phase 2 (Swarm, Events and Missions, page bar and keys, resize, host capability flag) is implemented in PR #4075; phase 3 (the AI page: Codex and OpenRouter, each question after a card) is implemented in PR 2 of the continuation; phase 4 (pictures, looks and motion) is implemented in console 0.44.0; phase 5 (every console view through this host, the menu, the go prompt, Back and the mouse) is implemented in the next change; phase 6 (actions) is the roadmap and must follow those decisions.
Date: 2026-10-11
@@ -159,7 +159,7 @@ not a replacement and not a second implementation.
- **Spend.** `--max-spend-usd` (default 0.5) stops the next OpenRouter question once the provider-reported total reaches it. Codex reports no dollars: its turns are counted and its cost reads n/a. The multi-provider ledger (ADR-437) reads Codex's own rollouts and OpenRouter's key usage; this page adds no writer to it.
- **Not in this PR:** the per-session **workspace-write opt-in**. The host accepts `workspace-write` when built with `allowWrite` and the guard pins it (tests), but the page offers no toggle and the console's Codex argv is read-only, so no write path exists yet; it needs a card that names the files Codex may change, which is phase 4.
4. **Pictures, looks and motion (done, console 0.44.0).** The kit gains `Raster` (`tui/ansi.ts`): the Grid's cells drawn as coloured glyphs, 24-bit when `COLORTERM` says so and the nearest of the 256 otherwise. A cell is data: a control, escape, invisible, surrogate or wide code point becomes a space, `cells` that are not exactly `columns*rows` u32 triplets (or exceed 200*90) draw nothing, and the secret-line filter still applies. The standalone pane now leads each page with the same `art()` the console uses (title or masthead, the swarm graph and the other pictures), in the console's three looks (Classic BBS default, Orbital, plain; `--look`, `t`), with `--boot` for the start-up screen. Pictures move at `--fps` (default 8, max 30, `--no-anim` or 0 for still): key presses and resizes write a whole frame as before, animation ticks write only the rows that changed with absolute positioning; ticks are skipped while a frame is being written, and stop while the terminal reports focus lost (`ESC[?1004h`). No colour (`NO_COLOR`, `TERM=dumb`), `--no-pictures`, or under 44 columns: the words of each picture, as before. No new network and no new write path. Measured on Linux/tmux: bundle +1.2 KB gzip; about 2-3% of one core and 14-80 KB/s at 8 fps, about 9% and 230 KB/s at 30 fps (Orbital, 200x50 is the worst case). Unverified: Windows, macOS, terminals other than tmux/xterm-256color.
-5. **Every console view through this host (roadmap).** Each view in the console's `VIEWS` list gets a recorded decision in the parity table below (identical, "Claude Code only" with a one-line reason, or needs a host capability), a main menu with grouped navigation, `go <view>` by name and optional mouse reporting with key fallback.
+5. **Every console view through this host (done).** The six pages stay the page bar. Every other console view opens with the console's own body: `0` is the main menu (its keys open entries, `p` is the go prompt), `:` or `/` is the go prompt (name, id, key or prefix, via the console's own `viewOf`), `Esc` or Backspace is Back (a 30-deep history), `--view` takes any page. Each view has a decision in `tui/parity.ts` (`same`, `partial`, `equivalent`, `claude-only`) and a row in the table below; `tests/tui-parity.spec.ts` fails when a view in the console's `VIEWS` has no decision or no row. The terminal renderer now honours a Box's `width` (the board's two groups sit side by side, as on the console) and draws the board's entry labels (they were blank). **Mouse** is opt-in (`--mouse`, SGR reports): a click on a page chip opens it and the wheel scrolls; reports are switched on only with the flag and off on exit, and report bytes are ignored without it. Buttons inside a page are not clickable here, because they act and acting waits for phase 6.
6. **Actions.** Pressable buttons and fields (an optional lazily loaded input dependency, or hand-rolled), the confirm card, the palette; each write goes through `Runner` as in the mod.
### Parity with the console (decisions recorded per item; the table is completed in phase 5)
@@ -169,7 +169,46 @@ not a replacement and not a second implementation.
| Title art, masthead, pictures, looks, boot, animation | Same drawings (phase 4) | `art()` and `picturesOf()` are shared; only the Raster surface differs |
| Overview, Cost, Swarm, Events, Missions, AI | Shipped | phases 1 to 3 |
| Ask Claude buttons, Claude control card, prompt-box band, toasts, session-tool server, live session transcript (Room) | Claude Code only | they act on, or read from, a running Claude Code session that this host does not have |
-| Remaining views, main menu, command palette, mouse, settings pages | Roadmap (phase 5/6) | not yet decided per view |
+
+**Per view (checked by `tests/tui-parity.spec.ts`, which fails when a console view has no row here):**
+
+| View | Name | In `ruflo tui` | Why |
+|---|---|---|---|
+| `menu` | Main Menu | same | entries open by their key, as on the console board |
+| `missions` | Missions | partial | the mission record only: entering a goal, planning and research start a Claude turn |
+| `overview` | Overview | same | the Claude-only controls are not drawn |
+| `swarm` | Swarm | same | topology, agents and votes as ruflo wrote them |
+| `hive` | Hive-Mind | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |
+| `claims` | Claims | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |
+| `workflows` | Workflows | partial | the ruflo swarm side; Claude Code workflow runs are not visible outside a session |
+| `federation` | Federation | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |
+| `plugins` | Plugins | partial | what is installed and loaded; "loaded as a mod" is a Claude Code fact and reads n/a |
+| `learning` | Learning | same | router picks, outcomes and the pipeline as on disk |
+| `metaharness` | MetaHarness | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |
+| `memory` | Memory | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |
+| `cost` | Cost | partial | provider ledger and router counts; Claude Code spend, context and the budget ladder read n/a |
+| `timeline` | Timeline | partial | agent lanes from status reports; Claude Code tool-call lanes need a session |
+| `approvals` | Approvals | partial | shows what waits; answering is a write and waits for the confirm gate of phase 6 |
+| `events` | Events | same | the event stream as it is on disk; Ask Claude is not drawn |
+| `room` | Room | claude-only | it is what people said to Claude in a session, plus a message box; this terminal has neither |
+| `xruv` | x.ruv.io | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |
+| `terminal` | Terminal | equivalent | the standalone AI page (Codex or OpenRouter, each question after a card) |
+| `skills` | Skills | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |
+| `secure` | Security & Doctor | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |
+| `perf` | Performance | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |
+| `automate` | Automation | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |
+| `neural` | Learning Lab | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |
+| `vector` | Vector Lab | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |
+| `evolve` | Self-Evolution | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |
+| `devtools` | Dev Tools | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |
+| `sandbox` | Sandbox | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |
+| `market` | Plugin Catalog | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |
+| `adrs` | ADRs | partial | read-only here: its action buttons are not drawn until the confirm gate of phase 6 |
+| `whatsnew` | What’s new | same | changelogs of the installed plugins |
+| `themes` | Theme Studio | partial | the look is chosen with t or --look; the colour picker and generated themes are not here yet |
+| `settings` | Settings | partial | shown read-only; changing a setting waits for the confirm gate of phase 6 |
+| `agent` | Agent drill-down | partial | the drill-down from a Swarm selection; selecting needs the host keys, so it says so |
+
## 5. Risks