🌊 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(console): interactive control plane and multi-model bridge (ADR-465)
ruvd7a642aa4634
diff --git a/plugins/ruflo-console/tests/wf-control-views.spec.ts b/plugins/ruflo-console/tests/wf-control-views.spec.tsindex deeabf0ee2..d073b5199b 100644--- a/plugins/ruflo-console/tests/wf-control-views.spec.ts+++ b/plugins/ruflo-console/tests/wf-control-views.spec.ts@@ -17,7 +17,7 @@ import { resetControl, stopSlotSpec, wireWfControl } from '../hooks/views/wf-conimport { workflowsPage } from '../hooks/views/wf-page'import { slotsFor, type SlotEnv } from '../hooks/views/wf-slots'import { workflowsActions } from '../hooks/wf-actions'-import { liveOf, resetConvo, saveTranscript, stopWatch, watchSpec } from '../hooks/wf-convo-live'+import { liveOf, resetConvo, saveTranscript, sendSpec, stopWatch, watchSpec } from '../hooks/wf-convo-live'import { targetsFor } from '../hooks/wf-convo-live'type El = { kind: string; props: Record<string, unknown> }@@ -367,6 +367,13 @@ describe('the Conversation board', () => {expect(saved[1]).toMatchObject({ spec: null, why: expect.stringMatching(/nothing to save/) })})+ it('asking no one, or asking with no host, is refused with the reason and no spec', () => {+ const { state } = open()++ expect(sendSpec(state, [], 'hello')).toMatchObject({ spec: null, why: expect.stringMatching(/pick a target/) })+ expect(sendSpec(newState({}), targetsFor(state, [wfRun()]), 'hello')).toMatchObject({ spec: null, why: expect.stringMatching(/not wired/) })+ })+it('with no host wired, or no tool at all, the board says so instead of drawing dead buttons', () => {const { ctx } = world()diff --git a/plugins/ruflo-console/tests/wf-convo.spec.ts b/plugins/ruflo-console/tests/wf-convo.spec.tsindex d114bcb589..8bb9c38d0f 100644--- a/plugins/ruflo-console/tests/wf-convo.spec.ts+++ b/plugins/ruflo-console/tests/wf-convo.spec.ts@@ -9,7 +9,8 @@ import { addMessage, applyFetch, compareOf, fanOutOf, fromBbs, fromChannel, lastimport { chatBody, parseChat, payloadOf, sendTo, taskNote, type SendDeps } from '../hooks/data/wf-send'import { endpointsOf, isBaseUrl, MAX_FANOUT, OPENROUTER, parseConfig, parseMentions, peersOf, targetsOf, type Target } from '../hooks/data/wf-targets'-const KEY = 'sk-or-v1-0123456789abcdefSECRET'+/** Deliberately not shaped like any vendor key: only the explicit scrub of the named variable's value can mask it. */+const KEY = 'k9x2-plain-42'const hive = { topology: 'hierarchical-mesh', strategy: 'raft', queen: 'q', queenTerm: 1, workers: ['a1'], pending: [], history: [], broadcasts: [], memoryKeys: [] } as unknown as HiveInfotype Rec = { run: { argv: readonly string[]; timeoutMs: number; stdin?: string }[]; http: { url: string; init: { method: string; headers: Record<string, string>; body: string } }[]; tool: Record<string, unknown>[]; prompts: string[] }diff --git a/v3/docs/adr/ADR-458-swarm-workflow-management-ui.md b/v3/docs/adr/ADR-458-swarm-workflow-management-ui.mdindex e920a32a5e..89202f2b82 100644--- a/v3/docs/adr/ADR-458-swarm-workflow-management-ui.md+++ b/v3/docs/adr/ADR-458-swarm-workflow-management-ui.md@@ -53,7 +53,7 @@ n/a. The cap and the number of unread transcripts are printed in the page.Actions: ruflo agents get `Stop agent` and `Spawn another <type>`, which are `stopAgent` and `spawnAgent` from `ops.ts` (fixedargv) handed to the existing confirm card through `hooks.ask`. A workflow agent gets `Open transcript`, which names its path-(`hooks.show`). The console cannot stop a Claude Code workflow and the page says so.+(`hooks.show`). The console cannot stop a Claude Code workflow and the page says so. (Amended by ADR-465: the control tab calls the engine's own TaskStop and SendMessage behind the confirm card and the engine's permission check, where that tab is switched on; the page says which.)No file in the console's existing registries is edited by this change; the wiring is in section 5.diff --git a/v3/docs/adr/ADR-460-workflow-links-nesting-and-guidance.md b/v3/docs/adr/ADR-460-workflow-links-nesting-and-guidance.mdindex 2dbccdd55a..ceac5e1ac9 100644--- a/v3/docs/adr/ADR-460-workflow-links-nesting-and-guidance.md+++ b/v3/docs/adr/ADR-460-workflow-links-nesting-and-guidance.md@@ -17,7 +17,7 @@ views, and the only way to say something to a swarm is to leave the page. Two faruflo's verbs write records: `hive-mind broadcast` appends to the hive's shared memory (the last 100), `task_update`and `claims_handoff` edit store files, a consensus proposal binds no one. None of them interrupts a running agent; an agentsees a record only when it reads that store. Second, a Claude Code workflow agent has no ruflo record at all, and the-console has no verb that stops or messages a running workflow.+console has no verb of its own that stops or messages a running workflow. (Amended by ADR-465: it can call the engine's TaskStop and SendMessage through the host, labelled by how far each path is proven.)## 2. Decisiondiff --git a/v3/docs/adr/ADR-465-interactive-control-plane-and-multi-model-bridge.md b/v3/docs/adr/ADR-465-interactive-control-plane-and-multi-model-bridge.mdnew file mode 100644index 0000000000..7a2763d5af--- /dev/null+++ b/v3/docs/adr/ADR-465-interactive-control-plane-and-multi-model-bridge.md@@ -0,0 +1,117 @@+# ADR 465: Interactive control plane and multi-model bridge++Status: Accepted++Date: 2026-10-05++Builds on: ADR-458 (the Workflows page), ADR-460 (guidance), ADR-464 (slot seams), ADR-444 (Claude controls the console), ADR-453 (confirm-gated verbs)++Amends: ADR-458 and ADR-460, which said the console cannot stop or message a running workflow.++## 1. Context++ADR-458 and ADR-460 told the person the console "cannot stop or message a running workflow" and offered only a prompt-box prefill. That was+true of the console's own verbs and untrue of the host: Claude Code lets a mod call the engine's own tools. A spike (headless `claude -p`,+2.1.289, a throwaway plugin; recorded in the task that produced this ADR) measured what is real:++| Path | Result | What it does NOT show |+|---|---|---|+| `$.tool.call({tool:'TaskStop', task_id})` on a running background agent | `Successfully stopped task: ... (sleeper)`, `agent.list` then `killed`; a bad id resolves `isError` ("No task found") | Never tried on a workflow run's id, nor on an agent inside a workflow run |+| `$.tool.call({tool:'SendMessage', to})`, by name and by id | `success:true`, "Message queued for delivery ... at its next tool round" | Delivery and effect: the agent was stopped right after. Not tried on a workflow-engine agent |+| `$.tool.check` | `{decision}` for Bash and TaskStop under default, dontAsk, acceptEdits; a denied call resolves `{deny}` | Behaviour in an interactive session with a dialog |+| `$.tool.call` of `mcp__*` tools | listed (1178 tools) only | Never called |+| `ListAgents` from a mod | works, lists peer sessions | Never sent to a peer: cross-session delivery is unverified |++The person also wants the console to be interactive between them, Claude agents and other AIs.++## 2. Decision++### 2.1 Control actions, through the engine and nothing else++`data/wf-control.ts` (pure) builds three actions for a Claude Code workflow run: **Stop** (agent: `TaskStop {task_id: agent id}`; whole run:+`TaskStop {task_id: run id}`), **Message** (`SendMessage {to: agent id, message}`) and **Redirect** (the run stop, then the resume text+prepared in the prompt box, only when the stop worked). Each is an `ActionSpec` whose `shows` is the exact call, so the confirm card shows+it, and whose `run` calls the host's `toolCall` (`$.tool.call`, from a clock tick as `submitPrompt` is, never inside the hook that asked).++- The engine's permission check and dialog decide the call. Before it, `toolCheck` (`$.tool.check`) is asked and a `deny` ends the action.+- **No laundering.** A `deny` (from the check or from the call) is shown as a refusal and nothing else is tried in its place: no Bash+ `kill`, no other tool, no peer. Only the person may press "prepare as text instead", which fills the prompt box (the main session's own+ permissions then apply when they press Enter).+- Each action carries a proof label that says how far its path is known: Stop an agent `verified` (the spike's exact case); Stop a run+ `unverified`; Message `queued-only`; Redirect `unverified` (two halves, said as two). The tab prints the label and the words. An answer+ of `isError`, `success:false` or "not reachable" is an error in the outcome row, never a success.+- Where a build does not bind `toolCall`, the specs are absent and the tab says so and offers the text prefill: the honest degradation.+- A ruflo swarm run's agents are not Claude tasks; the tab points at the page's own stop and the guide tab.++`Host` gains three optional members (`toolCall`, `toolCheck`, `httpSend`) and `register.ts` binds them: the one shared-file change the+control plane needs, because nothing may reach `$` but through the Host.++### 2.2 Targets and the Conversation++`data/wf-targets.ts` is the registry. A target declares its **transport**, **what leaves the machine** (machine, tailnet, internet, in+words), its **cost class** and **how a reply arrives**, and these are drawn before anything is sent:++| Target | Transport | Leaves | Reply |+|---|---|---|---|+| `@claude` | `host.submitPrompt` (a visible turn) | nothing extra | the next transcript turn, not captured here |+| `@<agent>` | `SendMessage` through the engine | nothing | none routed back; queued only |+| `@hive`, `@hive-propose`, `@task` | `ruflo mcp exec` (`hive-mind_broadcast`, `hive-mind_consensus`, `task_update`) | nothing | none; a worker sees it when it reads the store |+| `@<room>` | `federation_bbs_publish`, read back with `federation_bbs_watch` | this machine, peers where the room syncs | polled |+| `@x-<channel>` | `x_federation_channel_publish`, `x_federation_channel_read` | the relay (a `pub:` channel is public) | polled |+| `@peer-<host>` | the federation helper `dispatch`, which is `claude -p` over ssh on the peer | the tailnet | the peer's stdout |+| `@codex` | `codex exec -s read-only --skip-git-repo-check --ephemeral -C <cwd> -`, prompt on stdin | OpenAI, via the codex CLI | its final message |+| `@openrouter`, `@<endpoint>` | `POST <base>/chat/completions` through `host.httpSend` | the provider | the same response |++Configuration is one option, `convoTargets`: `endpoint:<name>=<base-url>|<KEY_ENV>|<model>; bbs:<room>; x:<channel>`. A key is named by its+environment variable and read with `printenv` at send time; it rides one header and is masked out of the card, the thread, the transcript+and the provider's own reply. A key pasted where a name belongs is refused. A base URL must be https (http only to localhost, a bare host+or a tailnet address), with no credentials, query or fragment. OpenRouter (`OPENROUTER_API_KEY`, `openrouter/auto`) is offered by default;+the meta-llm gateway is just an endpoint the person names.++`data/wf-send.ts` builds the payload the card shows and runs the same strings (`payloadOf` and `sendTo` share one builder), so the card cannot+show something other than what is sent. `data/wf-convo.ts` holds the threads (24 targets, 100 messages, 4000 characters each, all masked on+the way in), `@mention` routing (`@all` is the agents, the hive and the rooms, never anything that leaves the machine), fan-out to at most 6+targets on ONE card listing every payload, answers side by side, relay of one target's answer to another (through the target's own card),+per-thread tokens and cost, polling (20 s, at most 30 reads, started and stopped by the person, the read named on the card), and the+transcript (new file under `.claude-flow/console/exports/`, never overwrites, no link on the way, masked again, cut at 60000 characters with+the cut said). Cost is shown only where the provider billed one (`usage.cost`); otherwise "n/a", never a guessed figure or $0.++### 2.3 Autopilot and permissions++The relayed request asks that the swarm mission loop run for days or weeks without "acting for permission". That loop is **not built here**, and this ADR does not pre-empt it. What it does fix is the boundary: every control and conversation action is an `ActionSpec` with a `run`, and the runner never remembers such a spec (`remember.ts rememberKey` returns null for any spec with `run`, `argv` or `stdin`), so each one always stops at the confirm card. A loop therefore cannot send, stop or message through these actions without the person's own press; a separate, explicit authorisation record (what may be sent, to whom, how often, at what cost) is the right place to widen that, and is a different feature set. The engine's permission decision is never bypassed, and a learning or adaptive system may propose a send but never widen its own tools, network, secrets, spend, concurrency or release authority.++### 2.4 Wiring (the merge owner's switch)++New modules plug in through ADR-464's seams: `views/wf-control.ts` registers the `control` tab and the `ctl-stop` action (no hotkey);+`views/wf-convo.ts` registers the `conversation` board (order 60, folded shut). They are switched on by one import each in+`views/wf-register.ts` and one call each in `wf-wire.ts` (`wireWfControl(state, host)`, `wireWfConvo(state, host, <convoTargets>)`). The pages say+where Stop is done according to whether the `control` tab is registered, so the wording is true in either state.++## 3. Consequences++- The person can stop, message and redirect a running workflow from the page, each behind a card that shows the exact call, and talk to other+ models from one place with the cost and exposure of each declared.+- Stop on a workflow run and Message to a workflow agent may be answered "not found/not reachable" by the engine; the page shows that as an error+ and says what is proven. No claim of delivery is made anywhere: "queued" is the strongest word.+- A message to a peer or to Codex runs a model elsewhere with that machine's permissions: the card says so, and the federation helper still+ enforces trust and blocks destructive prompts.+- The conversation is in memory (and the saved transcripts); a console restart drops the threads.+- `Host` has three more optional members; a host that lacks them degrades to the prefill and to "this host cannot send an HTTP request".++## 4. Test and benchmark plan++Tests are pure with fake bridges and transports (`tests/wf-control.spec.ts`, `wf-convo.spec.ts`, `wf-control-views.spec.ts`): the spike's real+answers classified; the exact call on the card equals the call made; a permission `deny` stops before the call and by the call; the redirect+does not prefill after a failed stop; every transport's argv, stdin, headers and timeout; a key read from the named variable, sent, and masked+out of an echoed reply; refusal of keys-as-names, credential URLs and plain http; thread, message and transcript caps; n/a cost; side-by-side+compare; relay; polling cursor and stop at the cap; the slots registering beside the others with no hotkey clash; and the old "cannot stop"+sentences gone from the pages. Ten mutations of the code under test were each killed by a test. Micro-benchmark (this host, per call):+`targetsOf` with 33 targets 0.006 ms, `parseMentions` 0.002 ms, `payloadOf` 0.004 ms, `compareOf` over 24 threads 0.005 ms, a transcript at+its cap about 1 ms: nothing on the render path is measurable. Unverified, and to be measured in an interactive session by the merge owner:+TaskStop on a workflow run's id, SendMessage to a workflow agent, a dialog opening during `$.tool.call`.++## 5. Rollback++Remove the import line from `views/wf-register.ts` and the two `wire` calls: the tab, the button and the board disappear and the pages say+"Stop and message ... need the control tab, which is not switched on in this build" (no dead button). The `Host` members are optional and+unused then. Nothing is stored outside the person's own transcripts and the optional `convoTargets` option.