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): actions by name behind the console's confirm card (ADR-489 phase 6)

r9a9411c26cd7
diff --git a/docs/USERGUIDE.md b/docs/USERGUIDE.md
index bad3e8dd98..12e5e0aeec 100644
--- a/docs/USERGUIDE.md
+++ b/docs/USERGUIDE.md
@@ -615,6 +615,7 @@ Without a terminal and without `--plain`, `tui` prints a one-line hint and exits
| `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 |
+| `y` / `n` | Only while a confirm card is on screen: `y` runs the command it shows, `n` or `Esc` drops it |
| `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.
@@ -642,7 +643,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. **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).
+**Limits.** It reads files and changes nothing, except what you ask for by name and confirm with a single `y` on the console card, and the AI page after its own card. 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. **Actions.** The go prompt (`:`) also takes an action by name, such as `swarm-stop` or `evolve plan`: a read runs at once; a change shows the console's confirm card (who asked, the exact command, what it will do) pinned under the bar, and only a single `y` runs it, and only when the whole card fits on screen. A paste, Enter or a card cut off by a small window runs nothing. Settings cannot be changed here yet. 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-actions.spec.ts b/plugins/ruflo-console/tests/tui-actions.spec.ts
new file mode 100644
index 0000000000..783a38b8be
--- /dev/null
+++ b/plugins/ruflo-console/tests/tui-actions.spec.ts
@@ -0,0 +1,192 @@
+/**
+ * Actions in the standalone terminal go through the console's own confirm gate (ADR-489 phase 6): the go prompt takes an action by name, a read
+ * runs at once, a change raises the console's card (who asked, the exact command, the effect) and runs only on a lone y while the whole card is
+ * on screen. A paste, a half-drawn card, another key or a different card never run it. Run with
+ * npx vitest run plugins/ruflo-console/tests/tui-actions.spec.ts
+ */
+import { existsSync, 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 { runTui, type TuiIO } from '../tui/run'
+import { RUFLO_FILES } from './fixtures/ruflo-run'
+
+const ESC = '\u001b'
+let root: string
+let project: string
+let cli: string
+let log: string
+
+beforeAll(() => {
+ root = mkdtempSync(join(tmpdir(), 'tui-actions-'))
+ 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)
+ }
+ // A stand-in for the ruflo CLI: it records the argv it was given and prints a line.
+ log = join(root, 'argv.log')
+ cli = join(root, 'cli.js')
+ writeFileSync(cli, `require('node:fs').appendFileSync(${JSON.stringify(log)}, JSON.stringify(process.argv.slice(2)) + '\\n'); console.log('stub ran: ' + process.argv.slice(2).join(' '))\n`)
+})
+afterAll(() => rmSync(root, { recursive: true, force: true }))
+
+const settle = (ms = 250) => new Promise(resolve => setTimeout(resolve, ms))
+const strip = (text: string) => text.replace(/\u001b\[[0-9;?<]*[A-Za-z]/g, '')
+/** The commands the CLI stand-in was given, minus the console's own background reads (--version, memory stats, doctor …). */
+const ran = (): string[][] => (existsSync(log) ? readFileSync(log, 'utf8').trim().split('\n').filter(Boolean).map(line => JSON.parse(line) as string[]) : []).filter(argv => argv.some(word => word === 'stop' || (word === 'worker' && argv.includes('list'))))
+
+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, press: (key: string) => listeners.forEach(fn => fn(key)), screen: () => strip(out.join('').split(`${ESC}[H`).pop() ?? ''), type: (text: string) => [...text].forEach(ch => listeners.forEach(fn => fn(ch))) }
+}
+
+async function started(columns = 110, rows = 36) {
+ const t = terminal(columns, rows)
+ const running = runTui({ cwd: project, home: join(root, 'home'), look: 'plain', fps: 0, cliEntry: cli }, t.io)
+
+ await settle()
+
+ return { t, running }
+}
+
+const ask = async (t: ReturnType<typeof terminal>, word: string) => {
+ t.press(':')
+ t.type(word)
+ t.press('\r')
+ await settle()
+}
+
+describe('a change asked for by name', () => {
+ it('raises the console\'s card with the exact command, and runs nothing until a y', async () => {
+ const before = ran().length
+ const { t, running } = await started()
+
+ await ask(t, 'swarm-stop')
+
+ const screen = t.screen()
+
+ expect(screen).toContain('CONFIRM NEEDED')
+ expect(screen).toMatch(/runs: .*swarm stop/)
+ expect(screen).toContain('y runs')
+ expect(ran()).toHaveLength(before)
+ t.press('q')
+ await running
+ expect(ran()).toHaveLength(before)
+ })
+
+ it('runs exactly the command the card showed on a lone y, and shows the console own verdict on it', async () => {
+ const before = ran().length
+ const { t, running } = await started()
+
+ await ask(t, 'swarm-stop')
+ t.press('y')
+ await settle(600)
+
+ const after = ran().slice(before)
+
+ expect(after).toHaveLength(1)
+ expect(after[0]).toEqual(expect.arrayContaining(['swarm', 'stop']))
+ // The console's own verdict is shown: the stand-in CLI answered but changed nothing, and the page says so rather than claiming success.
+ expect(t.screen()).toContain('stop the swarm: ruflo answered ok')
+ expect(t.screen()).not.toContain('CONFIRM NEEDED')
+ t.press('q')
+ await running
+ })
+
+ it('n and Esc drop the card without running it', async () => {
+ const before = ran().length
+ const { t, running } = await started()
+
+ for (const key of ['n', ESC]) {
+ await ask(t, 'swarm-stop')
+ expect(t.screen()).toContain('CONFIRM NEEDED')
+ t.press(key)
+ await settle()
+ expect(t.screen()).not.toContain('CONFIRM NEEDED')
+ }
+ t.press('q')
+ await running
+ expect(ran()).toHaveLength(before)
+ })
+
+ it('is not answered by a paste, by Enter, or by a y inside other text', async () => {
+ const before = ran().length
+ const { t, running } = await started()
+
+ await ask(t, 'swarm-stop')
+ for (const text of ['yy', 'y\n', 'yes', '\r', ' y']) {
+ t.press(text)
+ await settle(80)
+ }
+ expect(ran()).toHaveLength(before)
+ expect(t.screen()).toContain('CONFIRM NEEDED')
+ t.press('n')
+ t.press('q')
+ await running
+ })
+
+ it('is not answered when the window is too small to show the whole card', async () => {
+ const before = ran().length
+ const { t, running } = await started(60, 9)
+
+ await ask(t, 'swarm-stop')
+ t.press('y')
+ await settle(500)
+ expect(ran()).toHaveLength(before)
+ expect(t.screen()).toContain('too small')
+ t.press('n')
+ t.press('q')
+ await running
+ })
+})
+
+describe('what is not an action', () => {
+ it('a name that is in no entry runs nothing (a typo never starts an action), and a page name opens the page', async () => {
+ const before = ran().length
+ const { t, running } = await started()
+
+ await ask(t, 'swrmstp')
+ expect(t.screen()).toContain('no page or action called "swrmstp"')
+ await ask(t, 'federation')
+ expect(t.screen()).toContain('Federation')
+ expect(ran()).toHaveLength(before)
+ t.press('q')
+ await running
+ })
+
+ it('a read runs at once with no card, through the ruflo CLI entry only', async () => {
+ const before = ran().length
+ const { t, running } = await started()
+
+ await ask(t, 'auto-workers-list')
+ await settle(500)
+ expect(t.screen()).not.toContain('CONFIRM NEEDED')
+ expect(ran().slice(before)[0]).toEqual(expect.arrayContaining(['worker', 'list']))
+ t.press('q')
+ await running
+ })
+
+ it('without a ruflo CLI entry nothing runs and the screen says so', async () => {
+ const t = terminal()
+ const running = runTui({ cwd: project, home: join(root, 'home'), look: 'plain', fps: 0 }, t.io)
+ const before = ran().length
+
+ await settle()
+ await ask(t, 'swarm-stop')
+ t.press('y')
+ await settle(500)
+ expect(ran()).toHaveLength(before)
+ t.press('q')
+ await running
+ })
+})
diff --git a/plugins/ruflo-console/tests/tui-nav.spec.ts b/plugins/ruflo-console/tests/tui-nav.spec.ts
index 391a0af735..392ce65ec9 100644
--- a/plugins/ruflo-console/tests/tui-nav.spec.ts
+++ b/plugins/ruflo-console/tests/tui-nav.spec.ts
@@ -87,8 +87,8 @@ describe('page bar and key line', () => {
expect(widthOf(navLine('missions', 60, '256'))).toBeLessThanOrEqual(60)
})
- it('has a short key line for a narrow terminal and says read-only on a wide one', () => {
- expect(keyLine(100)).toContain('read-only')
+ it('has a short key line for a narrow terminal and says ask first on a wide one', () => {
+ expect(keyLine(100)).toContain('ask first')
expect(keyLine(100)).toContain('q quit')
expect(keyLine(50)).toBe('1-6 page · j/k scroll · q quit')
expect(keyLine(25)).toBe('1-6 page · q quit')
diff --git a/plugins/ruflo-console/tests/tui-parity.spec.ts b/plugins/ruflo-console/tests/tui-parity.spec.ts
index c7aaf98ca6..2262bba951 100644
--- a/plugins/ruflo-console/tests/tui-parity.spec.ts
+++ b/plugins/ruflo-console/tests/tui-parity.spec.ts
@@ -150,7 +150,7 @@ describe('getting to every view from the keys', () => {
for (const ch of 'nonsense') t.press(ch)
t.press('\r')
await settle()
- expect(t.screen()).toContain('no page called "nonsense"')
+ expect(t.screen()).toContain('no page or action called "nonsense"')
t.press(':')
for (const ch of 'term') t.press(ch)
t.press('\r')
diff --git a/plugins/ruflo-console/tui/parity.ts b/plugins/ruflo-console/tui/parity.ts
index f5ffcb488f..82e38aefb1 100644
--- a/plugins/ruflo-console/tui/parity.ts
+++ b/plugins/ruflo-console/tui/parity.ts
@@ -11,7 +11,7 @@ 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'
+const READ_ONLY = 'its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card'
export const PARITY: Record<ViewId | 'agent', Parity> = {
menu: { status: 'same', why: 'entries open by their key, as on the console board' },
@@ -28,7 +28,7 @@ export const PARITY: Record<ViewId | 'agent', Parity> = {
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' },
+ approvals: { status: 'partial', why: 'shows what waits; answering a vote or a claim is asked for by name at the go prompt, after the card' },
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 },
@@ -46,7 +46,7 @@ export const PARITY: Record<ViewId | 'agent', Parity> = {
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' },
+ settings: { status: 'partial', why: 'shown as the standalone defaults; plugin options live in the Claude Code settings and the standalone has no store for them yet (the look is --look/t, the speed --fps)' },
agent: { status: 'partial', why: 'the drill-down from a Swarm selection; selecting needs the host keys, so it says so' },
}
diff --git a/plugins/ruflo-console/tui/pinned.ts b/plugins/ruflo-console/tui/pinned.ts
new file mode 100644
index 0000000000..163638ca3c
--- /dev/null
+++ b/plugins/ruflo-console/tui/pinned.ts
@@ -0,0 +1,57 @@
+/**
+ * The rows the shell pins under the page bar (ADR-489 phase 6): the confirm card of a change the person asked for, or what the last action
+ * printed. The card is the console's own `state.pending` (the same text `confirmRow` draws: who asked, the exact argv, the effect); only the
+ * wording of the keys differs, because this terminal has no buttons. It counts as shown (`state.shownCard`, the console's own gate for a bare
+ * typed yes) only when every row of it is on screen, so a window too small to show the argv can never answer it.
+ */
+import { askedBy } from '../hooks/data/room'
+import type { State } from '../hooks/state'
+import { THEME } from '../hooks/views/common'
+import { clean, render, terminalKit, type Depth } from './ansi'
+
+/** How long the result of an action stays pinned. */
+export const RESULT_MS = 20_000
+const MAX_RESULT_LINES = 8
+
+export function pinnedLines(state: State, columns: number, depth: Depth, room: number): string[] {
+ const kit = terminalKit()
+ const pending = state.pending
+
+ if (pending !== null) {
+ const hasMoney = pending.note !== undefined && /money|models/i.test(pending.note)
+ const tree = kit.Box({
+ flexDirection: 'column',
+ borderStyle: 'round',
+ borderColor: THEME.warn,
+ paddingX: 1,
+ children: [
+ kit.Text({ bold: true, color: THEME.warn, children: '▶ CONFIRM NEEDED: y runs it · n or Esc cancels' }),
+ kit.Text({ bold: true, color: THEME.warn, wrap: 'wrap', children: `Confirm: ${askedBy(pending)}${pending.label.replace(/\?+$/, '')}?` }),
+ // Wrapped, not clipped: a yes is a yes to the whole argv.
+ kit.Text({ dimColor: true, wrap: 'wrap', children: `runs: ${pending.shows ?? `ruflo ${pending.args.join(' ')}`}` }),
+ ...(pending.note !== undefined ? [kit.Text({ bold: hasMoney, color: hasMoney ? THEME.bad : THEME.warn, wrap: 'wrap', children: `Effect: ${pending.note}` })] : []),
+ ],
+ })
+ const lines = render(tree, columns, depth)
+
+ // Leave the page at least three rows: a card that crowds it out is not on screen in full.
+ if (lines.length <= Math.max(0, room - 3)) {
+ state.shownCard = pending.id ?? null
+
+ return lines
+ }
+
+ state.shownCard = null
+
+ return [clean('â–¶ CONFIRM NEEDED, but this window is too small to show the whole command: make it taller (or press n).')].map(line => line.slice(0, columns))
+ }
+
+ const outcome = state.outcome
+
+ if (outcome === null || Date.now() - outcome.atMs > RESULT_MS) return []
+
+ const head = `${outcome.ok ? '✔' : '✘'} ${clean(outcome.label).slice(0, 80)}: ${clean(outcome.detail).slice(0, 120)}`
+ const more = (outcome.lines ?? []).slice(0, MAX_RESULT_LINES).map(line => ` ${clean(line)}`)
+
+ return render(kit.Box({ flexDirection: 'column', children: [kit.Text({ bold: true, color: outcome.ok ? THEME.ok : THEME.bad, wrap: 'truncate-end', children: head }), ...more.map(line => kit.Text({ dimColor: true, wrap: 'truncate-end', children: line }))] }), columns, depth)
+}
diff --git a/plugins/ruflo-console/tui/run.ts b/plugins/ruflo-console/tui/run.ts
index 6ceda27b9f..01937bad07 100644
--- a/plugins/ruflo-console/tui/run.ts
+++ b/plugins/ruflo-console/tui/run.ts
@@ -91,7 +91,7 @@ export function navHit(x: number, columns: number): TuiView | null {
export function keyLine(columns: number, place = '', own?: readonly string[]): string {
const pages = `1-${TUI_VIEWS.length}`
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 tiers = own ?? [`${pages} or o c s e m a page · ${menu} · tab next · r refresh · t look · j/k scroll · q quit · ask first`, `${pages} or o c s e m a page · 0 menu · : go · tab next · r refresh · j/k scroll · q quit · ask first`, `${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)
@@ -214,13 +214,16 @@ 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}` : ''
+ // A confirm card (or the last action's result) is pinned under the bar, so scrolling never hides what a y would run.
+ const pinned = session.page === 'ai' ? [] : session.pinned(columns, depth, room)
+ const space = Math.max(1, room - pinned.length)
+ const top = session.page === 'ai' ? 0 : Math.max(0, Math.min(scroll, Math.max(0, lines.length - space)))
+ const place = lines.length > space ? ` · ${top + 1}-${Math.min(lines.length, top + space)}/${lines.length}` : ''
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)) }, () => '')]
+ const body = [...lines.slice(top, top + space), ...Array.from({ length: Math.max(0, space - (lines.length - top)) }, () => '')]
- const screen = [navLine(session.page, columns, depth), ...body, footer]
+ const screen = [navLine(session.page, columns, depth), ...pinned, ...body, footer]
if (tick && !clear) writeTick(io, screen, memory, columns, rows)
else writeFrame(io, screen, memory, columns, rows, clear)
@@ -271,7 +274,7 @@ export async function runTui(options: TuiOptions, io: TuiIO): Promise<number> {
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 line = () => (prompt !== null ? `go> ${prompt}▌ (a page, or an action to ask for · Enter · Esc cancels)` : notice !== '' ? notice : session.page !== 'ai' && session.pending() !== null ? 'y runs the command in the card · n or Esc cancels · the other keys still work' : '')
const draw = (tick = false) => void (scroll = paint(session, io, depth, scroll, memory, false, tick, line()))
const reread = async () => {
await session.refresh()
@@ -293,7 +296,9 @@ export async function runTui(options: TuiOptions, io: TuiIO): Promise<number> {
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`
+ // A name that is not a page is an action, asked the console's way: a read runs at once, a change shows a card and waits for a y.
+ if (name.startsWith('>')) notice = session.palette(name.slice(1))
+ else if (found === null || found === 'agent') notice = session.palette(name)
else open(found)
}
const onMouse = (chunk: string): boolean => {
@@ -345,6 +350,12 @@ export async function runTui(options: TuiOptions, io: TuiIO): Promise<number> {
return draw()
}
+ // A waiting card: only a lone y, while the whole card is on screen, runs it; n or Esc drops it (a paste is text, never an answer).
+ if (session.page !== 'ai' && session.pending() !== null) {
+ if (text === 'y' || text === 'Y') return void (session.answer(true), draw())
+ if (text === 'n' || text === 'N' || text === ESC) return void (session.answer(false), 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)
diff --git a/plugins/ruflo-console/tui/session.ts b/plugins/ruflo-console/tui/session.ts
index 72a356651d..1f46664c40 100644
--- a/plugins/ruflo-console/tui/session.ts
+++ b/plugins/ruflo-console/tui/session.ts
@@ -5,13 +5,14 @@
*/
import { createController, type Controller } from '../hooks/controller'
import type { Host } from '../hooks/host'
-import { newState, type State } from '../hooks/state'
+import { newState, VIEWS, type Pending, type State, type ViewId } from '../hooks/state'
import { picturesOf } from '../hooks/views/frames'
import { BODIES, NARROW } from '../hooks/views/pane'
-import { VIEWS, type ViewId } from '../hooks/state'
+import { filterPalette, isUnavailable, paletteEntries } from '../hooks/palette'
import { PARITY } from './parity'
import { standalonePane } from '../hooks/views/standalone-pane'
-import { render, terminalKit, type Depth } from './ansi'
+import { clean, render, terminalKit, type Depth } from './ansi'
+import { pinnedLines } from './pinned'
import { aiConfigOf, openAi, type Ai, type AiOptions as AiPageOptions } from './ai'
import { aiFrame } from './ai-page'
import { allowedHostsOf } from './ai-guard'
@@ -62,6 +63,16 @@ export type Session = {
moving: () => boolean
/** The page now showing. */
page: Page
+ /** The waiting confirm card, if any (the console's own `state.pending`). */
+ pending: () => Pending | null
+ /** Lines pinned under the page bar: the confirm card, or the last action's result for 20 s. `room` is the rows the terminal has for them and the page. The card counts as shown only when it is drawn whole. */
+ pinned: (columns: number, depth: Depth, room: number) => string[]
+ /** True when the whole card was on screen in the last frame: only then may a y answer it (#3983). */
+ cardShown: () => boolean
+ /** The best palette match for `word`, started the console's way: a read runs now, a change raises a card and waits. Returns one line saying what happened. */
+ palette: (word: string) => string
+ /** y or n on the waiting card. A yes names the card it answers, as on the console. */
+ answer: (yes: boolean) => void
/** Reads the disk again and runs the page's read-only probes, then returns. Never throws. */
refresh: () => Promise<void>
show: (view: Page) => void
@@ -134,6 +145,34 @@ export function openSession(options: SessionOptions, host?: Host): Session {
return next
},
moving: () => isMoving,
+ pending: () => state.pending,
+ cardShown: () => state.pending !== null && state.shownCard === (state.pending.id ?? null),
+ pinned: (columns, depth, room) => pinnedLines(state, columns, depth, room),
+ palette: word => {
+ const query = word.trim()
+ const lower = query.toLowerCase()
+ // Not the console's loose letters-in-order match: here a typed word must be IN the entry's name (or its id, or start a text command), so a typo never starts an action.
+ const all = paletteEntries(state, Date.now())
+ const best = all.find(entry => entry.id.toLowerCase() === lower) ?? filterPalette(all, query, 'all').find(entry => entry.label.toLowerCase().includes(lower) || (entry.run.kind === 'text' && lower.startsWith(`${entry.run.keyword.toLowerCase()} `)))
+
+ if (query === '' || best === undefined) return `no page or action called "${clean(query).slice(0, 30)}"`
+ if (best.run.kind !== 'spec' && best.run.kind !== 'text') return `"${clean(best.label).slice(0, 50)}" is a page or a Claude Code command: use its name as a page`
+ if (isUnavailable(best)) return `"${clean(best.label).slice(0, 50)}" is not available here`
+
+ state.shownCard = null
+ controller.actions.paletteQuery(query)
+ controller.actions.paletteRun(best.id)
+
+ return state.pending !== null ? `ask: ${clean(best.label).slice(0, 60)} (read the card, then y or n)` : `ran: ${clean(best.label).slice(0, 60)}`
+ },
+ answer: yes => {
+ const card = state.pending
+
+ if (card === null) return
+ if (!yes) return void controller.actions.cancel()
+ // A yes runs the card that was drawn whole and read, never one that was not.
+ if (state.shownCard === (card.id ?? null) && card.id !== undefined) controller.actions.confirm(card.id)
+ },
refresh: async () => {
try {
await ready
@@ -164,6 +203,8 @@ export function openSession(options: SessionOptions, host?: Host): Session {
state.pane.columns = columns
state.pane.rows = Math.max(0, rows)
isMoving = false
+ // The card was not on screen unless this frame (and the shell's pinned rows) draws it whole.
+ if (state.pending === null) state.shownCard = null
if (current === 'ai') {
const drawn = aiFrame(state, ai, aiStatus, columns, depth, rows)
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 71601add37..32e13d758a 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, 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.
+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 by name, behind the console's confirm card) is implemented in the same change; writing the plugin settings and clickable buttons are the remainder and must follow those decisions.
Date: 2026-10-11
@@ -160,7 +160,7 @@ not a replacement and not a second implementation.
- **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 (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.
+6. **Actions behind the card (done; settings writes and clickable buttons remain).** `:` or `/` takes an action as well as a page: a name that is not a page is looked up in the console's own palette (`paletteEntries`), and only a literal match counts (an entry's id, or its name containing the typed words, or a text command's keyword): the console's loose letters-in-order match is not used, so a typo never starts an action. A read (`$0`) runs at once through `Host.run`, which still accepts only the running ruflo CLI by argv; a change raises the console's own `state.pending` card, which the shell pins under the page bar (who asked, the exact `runs:` command, the effect) so scrolling cannot hide it. Only a lone `y` runs it, and only when every row of the card is on screen (`state.shownCard`, the console's own gate for a typed yes, is set by the shell only then): a paste, Enter, `yes`, a card too tall for the window, or a card replaced by another never run anything; `n` or Esc drops it; the console's 30 s expiry and its card-id matching apply unchanged. What the action printed, and the console's own verdict on it (`state.outcome`: ok, failed, or ran but the disk does not show the change), is pinned for 20 s. Claude-raised cards, the model-control level and remembered kinds need a Claude Code session and are not reachable here. The AI page keeps its own card and rules. Not done: writing plugin settings (the standalone has no store for them; the look and speed are `--look`/`t` and `--fps`), mouse clicks on a page's own buttons, and the per-session workspace-write toggle for Codex.
### Parity with the console (decisions recorded per item; the table is completed in phase 5)
@@ -178,35 +178,35 @@ not a replacement and not a second implementation.
| `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 |
+| `hive` | Hive-Mind | partial | its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card |
+| `claims` | Claims | partial | its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card |
| `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 |
+| `federation` | Federation | partial | its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card |
| `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 |
+| `metaharness` | MetaHarness | partial | its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card |
+| `memory` | Memory | partial | its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card |
| `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 |
+| `approvals` | Approvals | partial | shows what waits; answering a vote or a claim is asked for by name at the go prompt, after the card |
| `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 |
+| `xruv` | x.ruv.io | partial | its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card |
| `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 |
+| `skills` | Skills | partial | its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card |
+| `secure` | Security & Doctor | partial | its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card |
+| `perf` | Performance | partial | its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card |
+| `automate` | Automation | partial | its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card |
+| `neural` | Learning Lab | partial | its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card |
+| `vector` | Vector Lab | partial | its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card |
+| `evolve` | Self-Evolution | partial | its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card |
+| `devtools` | Dev Tools | partial | its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card |
+| `sandbox` | Sandbox | partial | its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card |
+| `market` | Plugin Catalog | partial | its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card |
+| `adrs` | ADRs | partial | its buttons are not drawn; its actions are asked for by name at the go prompt (:), each after the console card |
| `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 |
+| `settings` | Settings | partial | shown as the standalone defaults; plugin options live in the Claude Code settings and the standalone has no store for them yet (the look is --look/t, the speed --fps) |
| `agent` | Agent drill-down | partial | the drill-down from a Swarm selection; selecting needs the host keys, so it says so |