ruflo-ruos

1import type { EngineInterface, Register } from 'claude-code'
2
3import { HOSTS_PATH, segmentText } from './segment'
4
5/** How often the segment re-reads hosts.json (a local file read, no network). */
6export const REFRESH_MS = 15_000
7
8type State = { last: string | null | undefined }
9
10/**
11 * Re-read the plugin's hosts.json and set the `ruos` segment when it changed.
12 * `$.ruflo` exists only where the ruflo mod is seated, and `claude plugin
13 * validate` rejects feature-detecting a noun, so the call sits in try/catch:
14 * without ruflo-mods it rejects and nothing is drawn.
15 */
16async function refresh($: EngineInterface, state: State): Promise<void> {
17  let text: string | null = null
18  try {
19    const root = await $.session.root()
20    text = segmentText(await $.fs.read(`${root}/${HOSTS_PATH}`))
21  } catch {
22    text = null // no snapshot yet: nothing to show
23  }
24  if (text === state.last) return
25  try {
26    await $.ruflo.segment({ id: 'ruos', text })
27    state.last = text
28  } catch {
29    // ruflo mod not seated, or it refused the segment: draw nothing
30  }
31}
32
33/**
34 * ruflo-ruos as a mod (ADR-405): contributes the `ruos` segment to ruflo's
35 * status line. Reads only the plugin's own hosts.json; never calls ruOS (no
36 * network, no `$.ruos` dependency) and never issues a destructive tool.
37 */
38export const register: Register = on => {
39  const state: State = { last: undefined }
40
41  on('session.start', async ($, e, next) => {
42    const result = await next(e)
43    await refresh($, state)
44    try {
45      $.clock.every(REFRESH_MS, () => refresh($, state))
46    } catch {
47      // a withheld clock only means no periodic refresh
48    }
49    return result
50  })
51
52  on('prompt.submit', async ($, e, next) => {
53    await refresh($, state)
54    return next(e)
55  })
56}
57

1/**
2 * The `ruos` status segment text (ADR-405), derived from the plugin's own
3 * `.claude-flow/ruos/hosts.json` snapshot. Pure: no `$`, so it is tested
4 * directly. Text is untrusted on both sides; ruflo-mods also sanitises.
5 */
6
7export const HOSTS_PATH = '.claude-flow/ruos/hosts.json'
8/** ruflo-mods renders at most 48 characters per segment. */
9export const SEGMENT_MAX = 48
10
11type Host = { name?: unknown; agents?: unknown }
12
13/** Control and bidi-override characters never reach the status line. */
14const clean = (s: string) => s.replace(/[\u0000-\u001f\u007f-\u009f‪-‮⁦-⁩]/g, '').trim()
15
16/**
17 * `ruOS 2 agents · Work Desktop` (+N more hosts), or null when no ruflo
18 * agent is placed on a ruOS desktop (null clears the segment).
19 */
20export function segmentText(hostsJson: string | undefined): string | null {
21  if (!hostsJson) return null
22  let hosts: Host[]
23  try {
24    const parsed = JSON.parse(hostsJson) as { hosts?: unknown }
25    hosts = Array.isArray(parsed.hosts) ? (parsed.hosts as Host[]).slice(0, 200) : []
26  } catch {
27    return null
28  }
29  const busy = hosts
30    .map(h => ({ name: typeof h.name === 'string' ? clean(h.name) : '', agents: Array.isArray(h.agents) ? h.agents.length : 0 }))
31    .filter(h => h.agents > 0)
32  if (busy.length === 0) return null
33  const total = busy.reduce((n, h) => n + h.agents, 0)
34  const head = `ruOS ${total} agent${total === 1 ? '' : 's'} · ${busy[0]?.name || 'desktop'}`
35  const text = busy.length > 1 ? `${head} +${busy.length - 1}` : head
36  return text.length > SEGMENT_MAX ? `${text.slice(0, SEGMENT_MAX - 1)}…` : text
37}
38

1/**
2 * Vendored `$.ruflo` contract (ruflo-mods, ADR-404), the subset ruflo-ruos
3 * uses. Source of truth: plugins/ruflo-mods/types/index.d.ts — kept in step
4 * by tests/vendored-types.test.mjs. Where the ruflo mod is not seated there
5 * is no `$.ruflo` and a call rejects; ruflo-ruos catches and draws nothing.
6 */
7export type RufloSegment = { id: string; text: string | null }
8
9declare module 'claude-code' {
10  interface EngineInterface {
11    ruflo: {
12      /** Sets (or with `text: null` removes) one status bar segment. */
13      segment: (input: RufloSegment) => Promise<void>
14    }
15  }
16}
17