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(ruflo-ruos): mod part — ruos status segment via $.ruflo.segment

ruvc957086f3bf0
diff --git a/plugins/ruflo-ruos/README.md b/plugins/ruflo-ruos/README.md
index 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 state
Remote 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.json
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.sh
index 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 @@ else
printf "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"
echo
diff --git a/plugins/ruflo-ruos/tests/mod.test.ts b/plugins/ruflo-ruos/tests/mod.test.ts
new file mode 100644
index 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[31m‮Name', 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.mjs
index 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.mjs
new file mode 100644
index 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.json
new file mode 100644
index 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.ts
new file mode 100644
index 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.txt
index 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.mjs
plugins/ruflo-ruos/tests/requirements.test.mjs
plugins/ruflo-ruos/tests/transports.test.mjs
plugins/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.ts
diff --git a/v3/docs/adr/ADR-405-ruos-desktops-as-swarm-hosts.md b/v3/docs/adr/ADR-405-ruos-desktops-as-swarm-hosts.md
index 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