🌊 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-ruos): mod part — ruos status segment via $.ruflo.segment
ruvc957086f3bf0
diff --git a/plugins/ruflo-ruos/README.md b/plugins/ruflo-ruos/README.mdindex d16720fe2f..f819d763f6 100644--- a/plugins/ruflo-ruos/README.md+++ b/plugins/ruflo-ruos/README.md@@ -55,6 +55,10 @@ $CLI record start|output|end --run <runId> ...$CLI deploy-info --desktop <id> --repo projects/app```+## Status line (mod)++When the ruflo mod (`ruflo-mods`) is loaded, this plugin's mod adds a `ruos` segment to ruflo's status line, e.g. `ruOS 2 agents · Work Desktop`, and clears it when no agent is running. It reads only `.claude-flow/ruos/hosts.json`, makes no network calls, and draws nothing without ruflo-mods. Verify it with `claude plugin test plugins/ruflo-ruos`.+## Swarm stateRemote agents are recorded with ruflo's own tools: `agent_spawn` with `config.host = {kind: "ruos", desktopId, desktopName, transport, runId}`, then `agent_update`, then `claims_claim`/`claims_release` on `ruos-run-<runId>`. The plugin itself writes only to `.claude-flow/ruos/`:diff --git a/plugins/ruflo-ruos/hooks/hooks.json b/plugins/ruflo-ruos/hooks/hooks.jsonnew file mode 100644index 0000000000..ce6da4adc4--- /dev/null+++ b/plugins/ruflo-ruos/hooks/hooks.json@@ -0,0 +1,4 @@+{+ "description": "ruflo-ruos as a mod (ADR-405, optional): shows which ruflo agents run on your ruOS desktops as the `ruos` segment of ruflo's status line ($.ruflo.segment). Reads only .claude-flow/ruos/hosts.json; no network, no ruOS calls; draws nothing when the ruflo mod is not loaded.",+ "modules": ["./register.ts"]+}diff --git a/plugins/ruflo-ruos/hooks/register.ts b/plugins/ruflo-ruos/hooks/register.tsnew file mode 100644index 0000000000..e644dd87bb--- /dev/null+++ b/plugins/ruflo-ruos/hooks/register.ts@@ -0,0 +1,56 @@+import type { EngineInterface, Register } from 'claude-code'++import { HOSTS_PATH, segmentText } from './segment'++/** How often the segment re-reads hosts.json (a local file read, no network). */+export const REFRESH_MS = 15_000++type State = { last: string | null | undefined }++/**+ * Re-read the plugin's hosts.json and set the `ruos` segment when it changed.+ * `$.ruflo` exists only where the ruflo mod is seated, and `claude plugin+ * validate` rejects feature-detecting a noun, so the call sits in try/catch:+ * without ruflo-mods it rejects and nothing is drawn.+ */+async function refresh($: EngineInterface, state: State): Promise<void> {+ let text: string | null = null+ try {+ const root = await $.session.root()+ text = segmentText(await $.fs.read(`${root}/${HOSTS_PATH}`))+ } catch {+ text = null // no snapshot yet: nothing to show+ }+ if (text === state.last) return+ try {+ await $.ruflo.segment({ id: 'ruos', text })+ state.last = text+ } catch {+ // ruflo mod not seated, or it refused the segment: draw nothing+ }+}++/**+ * ruflo-ruos as a mod (ADR-405): contributes the `ruos` segment to ruflo's+ * status line. Reads only the plugin's own hosts.json; never calls ruOS (no+ * network, no `$.ruos` dependency) and never issues a destructive tool.+ */+export const register: Register = on => {+ const state: State = { last: undefined }++ on('session.start', async ($, e, next) => {+ const result = await next(e)+ await refresh($, state)+ try {+ $.clock.every(REFRESH_MS, () => refresh($, state))+ } catch {+ // a withheld clock only means no periodic refresh+ }+ return result+ })++ on('prompt.submit', async ($, e, next) => {+ await refresh($, state)+ return next(e)+ })+}diff --git a/plugins/ruflo-ruos/hooks/segment.ts b/plugins/ruflo-ruos/hooks/segment.tsnew file mode 100644index 0000000000..3f38c1aa14--- /dev/null+++ b/plugins/ruflo-ruos/hooks/segment.ts@@ -0,0 +1,37 @@+/**+ * The `ruos` status segment text (ADR-405), derived from the plugin's own+ * `.claude-flow/ruos/hosts.json` snapshot. Pure: no `$`, so it is tested+ * directly. Text is untrusted on both sides; ruflo-mods also sanitises.+ */++export const HOSTS_PATH = '.claude-flow/ruos/hosts.json'+/** ruflo-mods renders at most 48 characters per segment. */+export const SEGMENT_MAX = 48++type Host = { name?: unknown; agents?: unknown }++/** Control and bidi-override characters never reach the status line. */+const clean = (s: string) => s.replace(/[\u0000-\u001f\u007f-\u009f--]/g, '').trim()++/**+ * `ruOS 2 agents · Work Desktop` (+N more hosts), or null when no ruflo+ * agent is placed on a ruOS desktop (null clears the segment).+ */+export function segmentText(hostsJson: string | undefined): string | null {+ if (!hostsJson) return null+ let hosts: Host[]+ try {+ const parsed = JSON.parse(hostsJson) as { hosts?: unknown }+ hosts = Array.isArray(parsed.hosts) ? (parsed.hosts as Host[]).slice(0, 200) : []+ } catch {+ return null+ }+ const busy = hosts+ .map(h => ({ name: typeof h.name === 'string' ? clean(h.name) : '', agents: Array.isArray(h.agents) ? h.agents.length : 0 }))+ .filter(h => h.agents > 0)+ if (busy.length === 0) return null+ const total = busy.reduce((n, h) => n + h.agents, 0)+ const head = `ruOS ${total} agent${total === 1 ? '' : 's'} · ${busy[0]?.name || 'desktop'}`+ const text = busy.length > 1 ? `${head} +${busy.length - 1}` : head+ return text.length > SEGMENT_MAX ? `${text.slice(0, SEGMENT_MAX - 1)}…` : text+}diff --git a/plugins/ruflo-ruos/scripts/smoke.sh b/plugins/ruflo-ruos/scripts/smoke.shindex 8a1ccce152..16446a6e99 100755--- a/plugins/ruflo-ruos/scripts/smoke.sh+++ b/plugins/ruflo-ruos/scripts/smoke.sh@@ -25,7 +25,7 @@ grep -q '^name: ruos-host-operator$' "$ROOT/agents/ruos-host-operator.md" 2>/dev[[ -z "$miss" ]] && ok || bad "$miss"step "3. every source file under 500 lines"-long=$(find "$ROOT/scripts" "$ROOT/tests" -name '*.mjs' -exec awk 'END{if(NR>500)print FILENAME":"NR}' {} \;)+long=$(find "$ROOT/scripts" "$ROOT/tests" "$ROOT/hooks" \( -name '*.mjs' -o -name '*.ts' \) -exec awk 'END{if(NR>500)print FILENAME":"NR}' {} \;)[[ -z "$long" ]] && ok || bad "$long"step "4. no source path opens the :17870 executor"@@ -55,7 +55,14 @@ elseprintf "SKIP (no tsc)\n"fi-step "9. ADR-405 present"+step "9. mod part: claude plugin validate + test (skipped if claude absent)"+if command -v claude >/dev/null 2>&1 && claude plugin --help 2>/dev/null | grep -q 'test \['; then+ if out=$(claude plugin validate "$ROOT" 2>&1) && out=$(claude plugin test "$ROOT" 2>&1); then ok; else bad "$(printf '%s' "$out" | tail -5)"; fi+else+ printf "SKIP (no claude CLI with plugin test)\n"+fi++step "10. ADR-405 present"[[ -f "$ROOT/../../v3/docs/adr/ADR-405-ruos-desktops-as-swarm-hosts.md" ]] && ok || bad "missing ADR"echodiff --git a/plugins/ruflo-ruos/tests/mod.test.ts b/plugins/ruflo-ruos/tests/mod.test.tsnew file mode 100644index 0000000000..9aa32ae48a--- /dev/null+++ b/plugins/ruflo-ruos/tests/mod.test.ts@@ -0,0 +1,72 @@+import type { On } from 'claude-code'+import type { Plugin } from 'claude-code/testing'+import { describe, expect, test, tier } from 'claude-code/testing'++import { segmentText, SEGMENT_MAX } from '../hooks/segment'++tier('user')++const ROOT = '/work'+const HOSTS = `${ROOT}/.claude-flow/ruos/hosts.json`+const START = { surface: 'terminal', isInteractive: true, cwd: ROOT } as const+const prompt = (text: string) => ({ text, wait: false, origin: { kind: 'composer' } }) as const++/** A stand-in for ruflo-mods' `$.ruflo` noun that records each segment call. */+function fakeRuflo(calls: { id: string; text: string | null }[]): Plugin {+ return {+ name: 'fake-ruflo',+ tier: 'user',+ register: on => {+ on('engine.create', async ($, e, next) => {+ const beneath = await next(e)+ const added = { ruflo: { segment: async (input: { id: string; text: string | null }) => void calls.push(input) } }+ return { ...added, ...beneath }+ })+ },+ }+}++/** Project root and a file map beneath the mod, answered from memory. */+function world(on: On, files: Map<string, string>) {+ on('session.start', ($, e) => ({ cwd: e.cwd }))+ on('session.root', () => ({ value: ROOT }))+ on('fs.read', ($, e) => {+ const text = files.get(e.path)+ return text === undefined ? { deny: `ENOENT: '${e.path}'` } : { value: text }+ })+ on('prompt.submit', ($, e) => ({ text: e.text }))+}++const hosts = (...h: { name: string; agents: string[] }[]) =>+ JSON.stringify({ updatedAt: '2026-10-01T21:47:00.000Z', hosts: h.map((x, i) => ({ desktopId: `${i}`.repeat(32), ...x })) })++describe('ruflo-ruos segment', () => {+ test('segmentText: counts agents, names the first busy host, clears when idle', () => {+ expect(segmentText(undefined)).toBeNull()+ expect(segmentText('not json')).toBeNull()+ expect(segmentText(hosts({ name: 'Work Desktop', agents: [] }))).toBeNull()+ expect(segmentText(hosts({ name: 'Work Desktop', agents: ['a1'] }))).toBe('ruOS 1 agent · Work Desktop')+ expect(segmentText(hosts({ name: 'Idle', agents: [] }, { name: 'Work Desktop', agents: ['a', 'b'] }, { name: 'Lab', agents: ['c'] }))).toBe(+ 'ruOS 3 agents · Work Desktop +1',+ )+ expect(segmentText(hosts({ name: 'Bad\u001b[31mName', agents: ['a'] }))).toBe('ruOS 1 agent · Bad[31mName')+ expect(segmentText(hosts({ name: 'x'.repeat(100), agents: ['a'] }))?.length).toBe(SEGMENT_MAX)+ })++ test('sets the ruos segment from hosts.json and clears it when agents finish', async ($, on) => {+ const calls: { id: string; text: string | null }[] = []+ const files = new Map([[HOSTS, hosts({ name: 'Work Desktop', agents: ['ruos-r-1'] })]])+ world(on, files)+ fakeRuflo(calls).register(on, {})+ await $.session.start(START)+ files.set(HOSTS, hosts({ name: 'Work Desktop', agents: [] }))+ await $.prompt.submit(prompt('next'))+ expect(calls.filter(c => c.id === 'ruos').map(c => c.text)).toEqual(['ruOS 1 agent · Work Desktop', null])+ })++ test('without the ruflo mod the call rejects and nothing breaks', async ($, on) => {+ world(on, new Map([[HOSTS, hosts({ name: 'Work Desktop', agents: ['a'] })]]))+ await $.session.start(START)+ expect((await $.prompt.submit(prompt('hello'))).text).toBe('hello')+ })+})diff --git a/plugins/ruflo-ruos/tests/requirements.test.mjs b/plugins/ruflo-ruos/tests/requirements.test.mjsindex eda9434015..22d571c656 100644--- a/plugins/ruflo-ruos/tests/requirements.test.mjs+++ b/plugins/ruflo-ruos/tests/requirements.test.mjs@@ -154,7 +154,7 @@ test('no code path issues desktop_delete or secret_delete', async () => {const root = join(here, '..');/** @param {string} d @returns {string[]} */const walk = (d) => readdirSync(d).filter((n) => !n.startsWith('.') || n === '.claude-plugin').flatMap((n) => { const p = join(d, n); return statSync(p).isDirectory() ? walk(p) : [p]; });- for (const file of walk(root).filter((p) => !p.includes(`${join(root, 'tests')}`) && /\.(mjs|md|sh|json)$/.test(p))) {+ for (const file of walk(root).filter((p) => !p.includes(`${join(root, 'tests')}`) && /\.(mjs|ts|md|sh|json)$/.test(p))) {const text = readFileSync(file, 'utf8');for (const name of FORBIDDEN_TOOLS) {const hits = text.split('\n').filter((l) => l.includes(name) && !l.includes('FORBIDDEN_TOOLS = ') && !/never|human/i.test(l));diff --git a/plugins/ruflo-ruos/tests/vendored-types.test.mjs b/plugins/ruflo-ruos/tests/vendored-types.test.mjsnew file mode 100644index 0000000000..dbae39ee09--- /dev/null+++ b/plugins/ruflo-ruos/tests/vendored-types.test.mjs@@ -0,0 +1,42 @@+// @ts-check+/**+ * Parity: plugins/ruflo-ruos/types/index.d.ts vendors the `$.ruflo.segment`+ * contract from plugins/ruflo-mods/types/index.d.ts (ADR-404). If the source+ * changes shape, this fails instead of the mod silently drawing nothing.+ * Skips while ruflo-mods is not in the tree (its PR merges first).+ */+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { existsSync, readFileSync } from 'node:fs';+import { join, dirname } from 'node:path';+import { fileURLToPath } from 'node:url';++const here = dirname(fileURLToPath(import.meta.url));+const VENDORED = join(here, '../types/index.d.ts');+const SOURCE = join(here, '../../ruflo-mods/types/index.d.ts');++/** @param {string} text */+const norm = (text) => text.replace(/\s+/g, ' ').trim();++/**+ * @param {string} text+ * @param {RegExp} re+ */+const pick = (text, re) => norm(re.exec(text)?.[0] ?? '');++test('vendored $.ruflo.segment matches ruflo-mods', { skip: !existsSync(SOURCE) && 'ruflo-mods not in tree' }, () => {+ const vendored = readFileSync(VENDORED, 'utf8');+ const source = readFileSync(SOURCE, 'utf8');+ const typeRe = /export type RufloSegment = [^\n]+/;+ const methodRe = /segment: \(input: RufloSegment\) => Promise<void>/;+ assert.ok(pick(source, typeRe), 'source still exports RufloSegment');+ assert.equal(pick(vendored, typeRe), pick(source, typeRe));+ assert.equal(pick(vendored, methodRe), pick(source, methodRe));+ assert.match(source, /interface EngineInterface \{[\s\S]*ruflo: Ruflo/);+});++test('vendored types declare only what ruflo-ruos uses', () => {+ const vendored = readFileSync(VENDORED, 'utf8');+ assert.match(vendored, /segment: \(input: RufloSegment\) => Promise<void>/);+ assert.ok(!/lastRoute|snapshot/.test(vendored.replace(/\/\*\*[\s\S]*?\*\//g, '')), 'no unused surface');+});diff --git a/plugins/ruflo-ruos/tsconfig.json b/plugins/ruflo-ruos/tsconfig.jsonnew file mode 100644index 0000000000..8f220441c5--- /dev/null+++ b/plugins/ruflo-ruos/tsconfig.json@@ -0,0 +1,4 @@+{+ "//": "Claude Code (>= 2.1.287) writes its declarations and this base config into .claude-plugin/types/ when it loads the plugin (gitignored). Run `claude plugin validate .` once, then `tsc -p .`",+ "extends": "./.claude-plugin/types/tsconfig.json"+}diff --git a/plugins/ruflo-ruos/types/index.d.ts b/plugins/ruflo-ruos/types/index.d.tsnew file mode 100644index 0000000000..dd656207a8--- /dev/null+++ b/plugins/ruflo-ruos/types/index.d.ts@@ -0,0 +1,16 @@+/**+ * Vendored `$.ruflo` contract (ruflo-mods, ADR-404), the subset ruflo-ruos+ * uses. Source of truth: plugins/ruflo-mods/types/index.d.ts — kept in step+ * by tests/vendored-types.test.mjs. Where the ruflo mod is not seated there+ * is no `$.ruflo` and a call rejects; ruflo-ruos catches and draws nothing.+ */+export type RufloSegment = { id: string; text: string | null }++declare module 'claude-code' {+ interface EngineInterface {+ ruflo: {+ /** Sets (or with `text: null` removes) one status bar segment. */+ segment: (input: RufloSegment) => Promise<void>+ }+ }+}diff --git a/scripts/ci-test-baseline.txt b/scripts/ci-test-baseline.txtindex c5fba99e65..ce08c3be1d 100644--- a/scripts/ci-test-baseline.txt+++ b/scripts/ci-test-baseline.txt@@ -140,3 +140,6 @@ plugins/ruflo-ruos/tests/ledger-cli.test.mjsplugins/ruflo-ruos/tests/requirements.test.mjsplugins/ruflo-ruos/tests/transports.test.mjsplugins/ruflo-ruos/tests/validate-autostop.test.mjs+plugins/ruflo-ruos/tests/vendored-types.test.mjs+# ruflo-ruos mod test: imports 'claude-code/testing' (run by `claude plugin test plugins/ruflo-ruos`)+plugins/ruflo-ruos/tests/mod.test.tsdiff --git a/v3/docs/adr/ADR-405-ruos-desktops-as-swarm-hosts.md b/v3/docs/adr/ADR-405-ruos-desktops-as-swarm-hosts.mdindex 01df3984c0..d124c4b4df 100644--- a/v3/docs/adr/ADR-405-ruos-desktops-as-swarm-hosts.md+++ b/v3/docs/adr/ADR-405-ruos-desktops-as-swarm-hosts.md@@ -131,12 +131,13 @@ If the CLI cannot be resolved, or policy denies a call, the ledger degrades to t- The plugin has no npm dependencies.- The ruflo CLI is resolved at runtime and is optional.- The `$.ruos` and `$.ruflo` Claude Code mod nouns are never required. `$.ruos.desktops()` makes no network calls and may be stale, so freshness always comes from `desktop_status`.-- **Mod part (deferred until mods-planner lands `segment`).** The planned contract follows `claude plugin validate`, which allows only flat `$.noun.method(input)` calls and rejects feature detection:- - status segment: `$.ruflo.segment({ id: 'ruos', text })`, with `text: null` to clear;- - read-only `$.ruos` calls: `desktops()`, `lite()`, `lastAudit({n})`, `viewOpen({machine})`, `viewClose()`, `viewIsOpen()`, from `@cognitum/[email protected]`;- - every call wrapped in try/catch with a fallback;- - types vendored from ruos-desktop `packages/ruos/mod/ruos/types/index.d.ts`, with a parity test.- `/ruflo-ruos:view` delegates to `/ruos view`.+- **Mod part** (`hooks/register.ts`, `hooks/segment.ts`). This shipped after ruflo-mods landed `segment` in #3608 (ADR-404).+ - On `session.start`, on each `prompt.submit` and every 15 s, it reads only the plugin's own `hosts.json` and sets `$.ruflo.segment({ id: 'ruos', text })`, e.g. "ruOS 2 agents · Work Desktop", with `text: null` once no agent runs.+ - `claude plugin validate` allows only flat `$.noun.method(input)` calls and rejects feature detection, so the call sits in try/catch. Without the ruflo mod it rejects and nothing is drawn.+ - It makes no network calls, takes no `$.ruos` dependency and issues no destructive tool.+ - The `$.ruflo` type is vendored in `types/index.d.ts`, with a parity test against `plugins/ruflo-mods/types/index.d.ts`.+ - It is verified by `claude plugin validate` and by `claude plugin test`: 3 tests, using a stand-in `$.ruflo` noun, plus a run without it.+ - `$.ruos` (flat and read-only in `@cognitum/[email protected]`: `desktops()`, `lite()`, `lastAudit({n})`, `viewOpen({machine})`, `viewClose()`, `viewIsOpen()`) is not consumed yet. `/ruflo-ruos:view` delegates to `/ruos view` instead.## Failure modes