🌊 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat(ruflo-console): Claude controls the console: finished() wait, dashboard first, live e2e, demo GIF (ADR-444)
ruvf44a4ab593f4
diff --git a/README.md b/README.mdindex 77eeb695e5..ff059b92c1 100644--- a/README.md+++ b/README.md@@ -54,6 +54,12 @@ User --> Ruflo (CLI/MCP) --> Router --> Swarm --> Agents --> Memory --> LLM Prov<sub>The <code>/ruflo</code> console running in Claude Code, shown in a compact, near-square frame (the cockpit docked beside Claude, cropped to the cockpit) so it reads on a phone as well as a desktop: the whole boot (the neon sign in its border, the ruvector constellation lit by what is really installed, every area checked, an easter egg), the main menu entering and its cards folding, the grouped nav, a quick tour of twenty-odd pages (the Swarm topology, the Federation map, the Sandbox page for tmux, RVF and RVM, Cost, Memory, Dev Tools and more), the command palette (a tag on every entry for what it does), <b>ruHelp</b> (built-in help: ask a question, get steps with buttons; a guide for every capability), settings and refresh. A <a href="docs/assets/ruflo-console-walkthrough-wide.gif">wide-display walkthrough</a> shows the same console with room for every label. <code>npx ruflo init</code>, restart Claude Code, then <code>/ruflo</code>.</sub>+**Let Claude drive the console.** The console can also be driven *by* Claude: with control turned on (Settings → Claude control), Claude gets four tools (`console_state`, `console_open`, `console_set`, `console_run`) and sets up a mission, opens the Learning Lab or Security page, or runs a palette entry, while the cockpit shows it happening. How far it may go is your setting (`read`, `write`, `manage`, `full`: an action above the level is refused and nothing runs) and whether it waits for your Yes (`ask`) or confirms itself (`auto`). Overview shows a live log of every action and a **Take back control** button that stops all of it at once. It is off by default. See [ADR-444](v3/docs/adr/ADR-444-claude-controls-the-console.md).++<p align="center"><img src="docs/assets/ruflo-console-claude-control.gif" alt="Claude Code with the ruflo console beside it: Claude sets a mission goal, creates the mission and opens the Learning, Security and Overview pages through the console tools; the Claude control dashboard logs each action; swarm-stop is refused because it needs the full level; the person clicks Take back control and the next request is refused"></p>++<sub>A real recording (Claude Haiku, a few cents): control set to <code>write</code> with auto-confirm. Setting a goal and creating the mission is within that level; stopping a swarm needs <code>full</code>, so it is refused; after <b>Take back control</b> every call is refused.</sub>+**Install the mods from the ruflo marketplace** (Claude Code 2.1.287 or later; mods run with your account's permissions and are not sandboxed, so read the code first):```textdiff --git a/docs/assets/ruflo-console-claude-control.gif b/docs/assets/ruflo-console-claude-control.gifnew file mode 100644index 0000000000..142e400001Binary files /dev/null and b/docs/assets/ruflo-console-claude-control.gif differdiff --git a/plugins/ruflo-console/hooks/model-tools.ts b/plugins/ruflo-console/hooks/model-tools.tsindex ed3ea40618..f01bd4a77e 100644--- a/plugins/ruflo-console/hooks/model-tools.ts+++ b/plugins/ruflo-console/hooks/model-tools.ts@@ -76,6 +76,21 @@ export function parseControlEnv(value: unknown): { level: ControlLevel; confirm:export type ModelToolDeps = { state: State; control: Controller }+/** How long Claude's call waits for an action that runs on its own. */+export const FINISH_MS = 90_000++/** True if `work` finished within `ms` (on the host's clock: a mod has no setTimeout), false if the limit came first. */+function within(work: Promise<void>, ms: number, host: Pick<Controller['host'], 'after'>): Promise<boolean> {+ return new Promise(resolve => {+ const timer = host.after(ms, () => resolve(false))++ void work.then(() => {+ timer.cancel()+ resolve(true)+ })+ })+}+const say = (state: State, tool: string, summary: string, outcome: ControlEntry['outcome'], detail = ''): void => {state.control.log.push({ atMs: Date.now(), tool, summary: plain(summary, 80), outcome, detail: plain(detail, 160) })if (state.control.log.length > LOG_MAX) state.control.log.splice(0, state.control.log.length - LOG_MAX)@@ -173,12 +188,21 @@ async function settlePending(deps: ModelToolDeps, tool: string, id: string, askeawait control.runner.confirm()await control.runner.settled()+ // An action that brings its own run (creating a mission is several CLI calls) is not waited on by confirm: wait here, with a limit.+ const isFinished = await within(control.runner.finished(), FINISH_MS, control.host)+const fresh = state.outcome !== null && state.outcome.atMs > askedAt ? state.outcome : nullconst mission = mcOf(state).last !== lastBefore ? mcOf(state).last : nullconst done = fresh ?? missionsay(state, tool, id, done === null || done.ok ? 'ok' : 'error', done?.detail ?? '')+ if (!isFinished) {+ say(state, tool, id, 'waiting', 'still running')++ return { status: 'waiting', text: `Started: "${plain(pending.label, 100)}". It is still running after ${FINISH_MS / 1000} s; call console_state later to see the result.` }+ }+return { status: 'done', text: `${done === null ? 'Ran' : done.ok ? 'Done' : 'Failed'}: ${plain(pending.label, 100)}.${done === null ? '' : ` ${plain(done.detail, 200)}`}` }}diff --git a/plugins/ruflo-console/hooks/register.ts b/plugins/ruflo-console/hooks/register.tsindex d8eb57aab1..3edb669975 100644--- a/plugins/ruflo-console/hooks/register.ts+++ b/plugins/ruflo-console/hooks/register.ts@@ -337,7 +337,8 @@ export const register: Register = (on, raw: PluginOptions) => {/** The band's mark pulses during a turn: a redraw at its start, and the loop stopped at its end, whatever redraws. */on('turn.start', ($, e, next) => {- if (e.agentId === undefined) state.control.turnCalls = 0+ // A new turn: the per-turn cap on Claude's console actions starts over.+ state.control.turnCalls = 0try {$.ui.invalidate('ui.render')diff --git a/plugins/ruflo-console/hooks/runner.ts b/plugins/ruflo-console/hooks/runner.tsindex e1784327ed..4ae1129527 100644--- a/plugins/ruflo-console/hooks/runner.ts+++ b/plugins/ruflo-console/hooks/runner.ts@@ -30,11 +30,14 @@ export type Runner = {runById: (id: string, text: string) => boolean/** Resolves when the read started last has finished: `/ruflo run` waits on it to answer with what it printed. */settled: () => Promise<void>+ /** Resolves when the last action that brought its own `run` (and is not awaited by `confirm`) has finished: the model tools wait on it, with a limit. */+ finished: () => Promise<void>}export function createRunner(state: State, host: Host, deps: RunnerDeps): Runner {let pendingSpec: ActionSpec | null = nulllet inflight: Promise<void> = Promise.resolve()+ let background: Promise<void> = Promise.resolve()const say = (label: string, ok: boolean, detail: string, lines?: string[]) => {state.outcome = { label, ok, verified: 'n/a', detail, atMs: Date.now(), ...(lines !== undefined && { lines }) }@@ -46,6 +49,8 @@ export function createRunner(state: State, host: Host, deps: RunnerDeps): Runnerif (spec.run !== undefined) {const running = spec.run()+ background = running.then(() => undefined, () => undefined)+// A read that runs its own command (a skills search) is waited on, so `/ruflo run` answers with what it found.if (spec.isReadOnly === true) await running@@ -197,5 +202,5 @@ export function createRunner(state: State, host: Host, deps: RunnerDeps): Runnerreturn true}- return { ask, confirm, cancel, runEntry, runById, settled: () => inflight }+ return { ask, confirm, cancel, runEntry, runById, settled: () => inflight, finished: () => background }}diff --git a/plugins/ruflo-console/hooks/views/control.ts b/plugins/ruflo-console/hooks/views/control.tsindex 843df85ec8..98545f5718 100644--- a/plugins/ruflo-console/hooks/views/control.ts+++ b/plugins/ruflo-console/hooks/views/control.ts@@ -7,6 +7,9 @@ import { ago, button, kv, row, rule, text, THEME, type Ctx } from './common'const MARK = { ok: '✓', waiting: '…', denied: '✕', error: '!' } as constconst COLOR = { ok: THEME.ok, waiting: THEME.warn, denied: THEME.bad, error: THEME.bad } as const+/** True while control is on or Claude has acted this session: then the dashboard leads the page, so it is never below the fold. */+export const isControlActive = (ctx: Ctx): boolean => levelOf(settingsOf(ctx.state).ai.modelControl) !== 'off' || ctx.state.control.log.length > 0+/*** The "Claude control" dashboard (ADR-444): whether Claude may drive the console and how far, what it has done this session, and the* button that takes control back. Shown on Overview; the log is the audit trail, newest last.diff --git a/plugins/ruflo-console/hooks/views/overview.ts b/plugins/ruflo-console/hooks/views/overview.tsindex 9b45e8db58..d8994c6e11 100644--- a/plugins/ruflo-console/hooks/views/overview.ts+++ b/plugins/ruflo-console/hooks/views/overview.ts@@ -3,7 +3,7 @@ import type { RenderElement } from 'claude-code'import { alertsOf } from '../data/alerts'import type { MemoryStats } from '../data/cli'import type { StartId } from '../starts'-import { controlRows } from './control'+import { controlRows, isControlActive } from './control'import { optimizerRows } from './optimizer'import { ago, col, count, kv, live, picture, rule, sourceLine, starts, text, THEME, type Ctx } from './common'@@ -19,7 +19,7 @@ export function overviewView(ctx: Ctx): RenderElement {const loaded = state.mods.filter(mod => mod.isLoaded).lengthconst refused = state.mods.length - loadedconst swarm = snap?.swarm ?? null- const rows: RenderElement[] = [...optimizerRows(ctx), ...controlRows(ctx), rule(ctx, 'Subsystems', snap?.isRufloProject === false ? 'not a ruflo project' : '')]+ const rows: RenderElement[] = [...(isControlActive(ctx) ? [...controlRows(ctx), ...optimizerRows(ctx)] : [...optimizerRows(ctx), ...controlRows(ctx)]), rule(ctx, 'Subsystems', snap?.isRufloProject === false ? 'not a ruflo project' : '')]rows.push(kv(ctx, 'ruflo CLI', version !== null ? `v${version} (${state.options.cli})` : sourceLine(state.probes.get('version'), nowMs, 'n/a').text))rows.push(diff --git a/plugins/ruflo-console/scripts/e2e-control.sh b/plugins/ruflo-console/scripts/e2e-control.shindex 7e5627e5fb..a9d2e93097 100755--- a/plugins/ruflo-console/scripts/e2e-control.sh+++ b/plugins/ruflo-console/scripts/e2e-control.sh@@ -43,7 +43,7 @@ TOOLS="mcp__ruflo-console__console_state,mcp__ruflo-console__console_open,mcp__rrun() {local name="$1" control="$2" prompt="$3"(cd "$PROJECT" && env ${control:+RUFLO_CONSOLE_CONTROL="$control"} CLAUDE_CONFIG_DIR="$CFG" timeout 240 "$CLAUDE" -p --model haiku --max-budget-usd 0.50 \- --plugin-dir "$PLUGIN" --allowedTools "$TOOLS" --output-format stream-json --verbose --debug-file "$OUT/$name.log" "$prompt" </dev/null >"$OUT/$name.jsonl" 2>"$OUT/$name.err")+ --plugin-dir "$PLUGIN" --allowedTools "$TOOLS" --disallowedTools Bash,Write,Edit,NotebookEdit --output-format stream-json --verbose --debug-file "$OUT/$name.log" "$prompt" </dev/null >"$OUT/$name.jsonl" 2>"$OUT/$name.err")}# transcript NAME: one line per console tool call and per result, for the assertions below.@@ -64,6 +64,14 @@ console.log(`COST ${r ? r.total_cost_usd : '?'}`)NODE}+# attempt NAME CONTROL PROMPT: a run, then its transcript; if the model made no console call at all (a small model sometimes talks about the tools+# instead of calling them) it is run once more. A refusal or a wrong result is never retried: only an absent attempt.+attempt() {+ run "$1" "$2" "$3"+ transcript "$1" >"$OUT/$1.txt"+ if ! grep -q '^CALL' "$OUT/$1.txt"; then run "$1" "$2" "$3"; transcript "$1" >"$OUT/$1.txt"; fi+}+ASK="Use only the ruflo console tools (console_state, console_open, console_set, console_run). Do the steps in order and report the exact results."# A: off@@ -72,23 +80,20 @@ transcript A >"$OUT/A.txt"check A1 "control off: no console tool is callable" "A.txt" bash -c "! grep -q '^CALL' '$OUT/A.txt'"# B: read-run B "read" "$ASK 1) console_state. 2) console_open view=overview. 3) console_set field=goal value='x'."-transcript B >"$OUT/B.txt"+attempt B "read" "$ASK 1) console_state. 2) console_open view=overview. 3) console_set field=goal value='x'."check B1 "read: console_state answers with the page" "B.txt" grep -q 'RESULT console_state {"view"' "$OUT/B.txt"check B2 "read: console_open opens a page" "B.txt" grep -q 'RESULT console_open Opened' "$OUT/B.txt"check B3 "read: console_set is refused and names the level it needs" "B.txt" grep -q 'RESULT console_set Refused: console_set needs the "write" level' "$OUT/B.txt"# C: write, auto-run C "write:auto" "$ASK 1) console_open view=missions. 2) console_set field=goal value='add a dark mode toggle'. 3) console_run id=mission-create. 4) console_state."-transcript C >"$OUT/C.txt"+attempt C "write:auto" "$ASK 1) console_open view=missions. 2) console_set field=goal value='add a dark mode toggle'. 3) console_run id=mission-create. 4) console_state."check C1 "write: the goal is set" "C.txt" grep -q 'RESULT console_set Set goal' "$OUT/C.txt"check C2 "write: the console planned it (state shows the goal)" "C.txt" grep -q 'RESULT console_state .*dark mode toggle' "$OUT/C.txt"check C3 "write+auto: Claude's own call ran mission-create (Done or Failed, never Waiting)" "C.txt" grep -qE 'RESULT console_run (Done|Failed): create the mission' "$OUT/C.txt"check C4 "write+auto: no billed guidance turn was queued behind the goal" "C.txt" bash -c "! grep -q 'guidance on this mission' '$OUT/C.txt'"# D: write, ask-run D "write:ask" "$ASK 1) console_open view=missions. 2) console_set field=goal value='add a dark mode toggle'. 3) console_run id=mission-create. 4) console_state."-transcript D >"$OUT/D.txt"+attempt D "write:ask" "$ASK 1) console_open view=missions. 2) console_set field=goal value='add a dark mode toggle'. 3) console_run id=mission-create. 4) console_state."check D1 "ask: mission-create waits for the person" "D.txt" grep -q 'RESULT console_run Waiting for the person to confirm' "$OUT/D.txt"check D2 "ask: Claude never confirmed it (no Done/Failed for mission-create)" "D.txt" bash -c "! grep -qE 'RESULT console_run (Done|Failed)' '$OUT/D.txt'"check D3 "ask: the state names what is waiting" "D.txt" grep -q '"waiting":{' "$OUT/D.txt"diff --git a/plugins/ruflo-console/tests/model-tools.spec.ts b/plugins/ruflo-console/tests/model-tools.spec.tsindex 993c93b46f..5ee3cbebf5 100644--- a/plugins/ruflo-console/tests/model-tools.spec.ts+++ b/plugins/ruflo-console/tests/model-tools.spec.ts@@ -17,13 +17,13 @@ type Level = 'off' | 'read' | 'write' | 'manage' | 'full'/** A controller whose runner behaves like the real one: read-only entries finish at once, the rest wait in `state.pending`. */function setup(level: Level, confirm: 'ask' | 'auto' = 'ask', entries: Record<string, { label: string; readOnly?: boolean; note?: string }> = {}, followUp?: { label: string; note?: string }) {const state = newState({})- const calls = { setView: [] as string[], open: 0, goal: [] as string[], profile: [] as string[], draft: [] as string[][], confirm: 0, cancel: 0, runs: [] as string[] }+ const calls = { timers: [] as (() => void)[], finishAfter: undefined as Promise<void> | undefined, setView: [] as string[], open: 0, goal: [] as string[], profile: [] as string[], draft: [] as string[][], confirm: 0, cancel: 0, runs: [] as string[] }Object.assign(settingsOf(state).ai, { modelControl: level, modelConfirm: confirm })const catalog = { 'mission-open': { label: 'open Mission Control', readOnly: true }, 'mission-create': { label: 'create the mission and its tasks' }, 'mission-cancel': { label: 'cancel the mission and its open tasks' }, 'plugin-install': { label: 'install a plugin', note: 'network: clones it from GitHub' }, 'hand-task': { label: 'hand task t1 to Claude', note: 'Starts a Claude Code turn (billed as any turn is)' }, ...entries }const control = {- host: { invalidate: () => undefined },+ host: { invalidate: () => undefined, after: (_ms: number, fn: () => void) => ({ cancel: () => calls.timers.splice(calls.timers.indexOf(fn), 1), fire: fn, ...(calls.timers.push(fn) && {}) }) },setView: (view: string) => void calls.setView.push(view),open: async () => void (calls.open += 1),actions: { mission: { goal: (text: string) => {@@ -43,6 +43,7 @@ function setup(level: Level, confirm: 'ask' | 'auto' = 'ask', entries: Record<streturn true},settled: async () => undefined,+ finished: async () => (calls.finishAfter === undefined ? undefined : calls.finishAfter),confirm: async () => {calls.confirm += 1state.outcome = { label: state.pending?.label ?? '', ok: true, verified: 'n/a', detail: 'ran', atMs: Date.now() + 1 }@@ -275,6 +276,33 @@ describe('running an entry: ask, auto, and the level', () => {expect(await callTool('console_run', { id: 'mission-create' }, deps)).toMatch(/^Failed: create the mission.* the ruflo CLI did not answer/)})+ it('waits for an action that runs on its own to finish before saying Done, and says Started if it does not in time', async () => {+ let release: () => void = () => undefined+ const slow = setup('write', 'auto')++ slow.calls.finishAfter = new Promise<void>(resolve => (release = resolve))++ const answer = slow.deps.control.runner.confirm !== undefined ? callTool('console_run', { id: 'mission-create' }, slow.deps) : Promise.resolve('')+ let settled: string | null = null++ void answer.then(text => (settled = text))+ await Promise.resolve()+ await new Promise(resolve => setTimeout(resolve, 5))+ expect(settled).toBeNull()+ release()+ expect(await answer).toMatch(/^Ran: create the mission|^Done: create the mission/)++ const stuck = setup('write', 'auto')++ stuck.calls.finishAfter = new Promise<void>(() => undefined)++ const waiting = callTool('console_run', { id: 'mission-create' }, stuck.deps)++ await new Promise(resolve => setTimeout(resolve, 5))+ for (const fire of [...stuck.calls.timers]) fire()+ expect(await waiting).toMatch(/^Started: .*still running after 90 s/)+ })+it('refuses and cancels an action above the level, even in auto mode: nothing runs', async () => {const { deps, calls } = setup('write', 'auto')@@ -337,6 +365,19 @@ describe('the dashboard', () => {expect(show(state)).toContain('Give control back')})+ it('leads the Overview while control is on, and sits after the optimizer when it is off', async () => {+ const { deps, state } = setup('write', 'ask')++ await callTool('console_state', {}, deps)++ const on = show(state).toLowerCase()+ const off = show(newState({})).toLowerCase()++ expect(on.indexOf('claude control')).toBeGreaterThanOrEqual(0)+ expect(on.indexOf('claude control')).toBeLessThan(on.indexOf('optimizer'))+ expect(off.indexOf('claude control')).toBeGreaterThan(off.indexOf('optimizer'))+ })+it('has no tool whose job is to answer Yes: confirming is only ever the chosen auto mode, inside console_run', () => {expect(TOOL_SPECS.map(spec => spec.name).filter(name => /confirm|yes|approve|allow/.test(name))).toEqual([])})diff --git a/v3/docs/adr/ADR-444-claude-controls-the-console.md b/v3/docs/adr/ADR-444-claude-controls-the-console.mdindex cf38ab2b67..c848ab274a 100644--- a/v3/docs/adr/ADR-444-claude-controls-the-console.md+++ b/v3/docs/adr/ADR-444-claude-controls-the-console.md@@ -12,9 +12,9 @@ Builds on: ADR-406 (missions), ADR-443 (missions and Claude), the console's paleThe console sends commands and guidance to Claude Code. The reverse is as useful: tell Claude "set up a mission", "open the Learning Lab", "run the security scan" and have it drive the console, with the cockpit showing what it does, the way computer use shows a screen being operated. Everything the console can do for a person already goes through one surface (pages, fields, palette entries, a confirm step), so Claude can use the same surface.-## 2. What was checked+## 2. What was checked (and found)-A throwaway mod registered a tool with `$.tool.register` and answered it from a `tool.call` hook. In this Claude Code build (2.1.x) the tool is listed to the model as `mcp__<plugin>__<name>` even in `claude -p`, and the call ran. The result must be a **string** (an object is refused by the tool's schema check). Not yet checked: behaviour with several tools in one turn and how permission dialogs look for them; the end-to-end check (`scripts/e2e-control.sh`) covers the first.+A throwaway mod registered a tool with `$.tool.register` and answered it from a `tool.call` hook. In this Claude Code build (2.1.x) the tool is listed to the model as `mcp__<plugin>__<name>` even in `claude -p`, and the call ran. The result must be a **string** (an object is refused by the tool's schema check). `scripts/e2e-control.sh` (live, gated by `RUFLO_E2E_LIVE=1`, a few cents with haiku) then ran four real sessions: control off (no tool exists for the model), read (state and open work, a field is refused naming the level), write with auto-confirm (the goal is set and planned, Claude's own call creates the mission) and write with ask (the same action waits for the person and Claude does not confirm it). The live runs found three real problems that unit tests had not: the classifier read "spends nothing" as spending, so creating a mission was refused at `write`; a goal's follow-up (a billed guidance turn) is queued asynchronously after the call returns, so it must not run when Claude is the one driving (the console now skips the offer for 60 s after any tool call); and Mission Control reports its own actions on `last`, not on the generic outcome, so a result was reported without its detail. The last live run then showed that Claude was told "Ran" before the mission existed: the runner deliberately does not wait for an action that brings its own `run` (so a long harness run does not hold a person's buttons), so `confirm()` returns early. The runner now exposes `finished()`, the model tools wait on it for up to 90 s (after that the answer is "Started… still running; call console_state later"), and a person's clicks behave as before. An audit of all 270 palette entries then found `stop the swarm`, `memory cleanup` and `memory migrate` classed as plain writes; they are `delete` now (105 entries read, 101 write, 27 network, 2 spend, 4+ delete).## 3. Decision@@ -35,7 +35,7 @@ Four tools, `mcp__ruflo-console__` plus:| `manage` | also run entries that touch the network (install, update, push) || `full` | also run entries that spend money or delete or stop things (deploys, cancellations, resets) |-and a second setting, **confirm**: `ask` (default) leaves every non-read action pending in the console's own confirm row for the person to answer; `auto` lets Claude's call confirm itself, within the level. An entry's class is read from its spec (read-only flag, label, command and note); an entry that cannot be classified counts as the most dangerous class, so it needs `full`.+and a second setting, **confirm**: `ask` (default) leaves every non-read action pending in the console's own confirm row for the person to answer; `auto` lets Claude's call confirm itself, within the level. An entry's class is read from its spec: the console's own read-only flag, else its label, command and notes. Words for deleting, stopping, resetting, cleaning up or migrating make it `delete`; words for a billed turn or "costs money" make it `spend`; words for the network (install, push, fetch, update, publish) make it `network`; anything else that is not read-only is a local `write`. The notes also say what an action does *not* do ("spends nothing", "not a charge", "runs no agent"), and those do not count.**The cockpit is the dashboard.** An "Claude control" section on Overview shows the level and confirm mode, whether control is on or paused, the call count, and a log of the last actions with their outcome (ok, waiting for you, refused, failed). A **Take back control** button pauses every tool at once (the next call is refused with that reason) and **Give control back** resumes. The log is the audit trail for a session.