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

22.8 KB
Raw Blame
import type { EngineInterface, PluginOptions, Register } from 'claude-code'
import { tolerantPress } from './press-guard'
import { ANSWER_KEYS } from './views/attention'
import { createController, type Controller } from './controller'
import { startSessions } from './sessions'
import { record } from './data/events'
import { plain } from './data/parse'
import { homeOf, isAbsolutePath, joinPath } from './data/paths'
import { dispatch } from './dispatch'
import { markPicture } from './gfx/pictures'
import type { Host } from './host'
import { ownerLine, ownerOf } from './tool-owner'
import { newState, PANE_ID, restore, restoreSessions, storeKeyOf, termStoreKeyOf } from './state'
import { BAR_KEY, barView } from './views/bar'
import { addNotice, dismissNotices } from './notices'
import { setBootChecks } from './boot-checks'
import { startWriteFlavor } from './data/write-flavor'
import { buildOf, isOurCheckout, setBuild } from './build'
import { announceModelTools, parseControlEnv, serveModelTools } from './model-tools'
import { loadAiPrefs, setControlCap } from './settings'
import { loadAtStart } from './startup-loads'
import { recordToast } from './toasts'
import { contextSection, onPromptSubmit, onTurnComplete } from './mission-claude'
import { selfCheckResults } from './self-check'
import { kitForSurface, type Kit } from './views/common'
import { createToaster, type Digest, type ToastLevel, type ToastPrefs } from './toast-policy'
import { picturesOf } from './views/frames'
import { withClearing } from './views/clearing'
import { NARROW, paneView } from './views/pane'

const RUFLO_TOOL = /^mcp__(claude-flow|ruflo|plugin_ruflo[\w-]*)__/

/**
 * Binds a Host from `$`, every member spelled `$.noun.method(...)` here and nowhere else, so the engine reads what
 * the module calls off this one place. Calls that answer nothing are wrapped: a refused draw is not a crashed hook.
 */
/** True while the console itself scrolls the pane to its top, so the terminal's own wheel handling does not take that for the person's wheel. */
let isResettingScroll = false

function hostOf($: EngineInterface, cwd: string, toasts: { prefs: () => ToastPrefs; record: (digest: Digest) => void }): Host {
  const rooted = (path: string) => (isAbsolutePath(path) ? path : joinPath(cwd, path))
  const quietly = (fn: () => unknown) => {
    try {
      const result = fn()

      if (result instanceof Promise) result.catch(() => undefined)
    } catch {
      // Refused: there is nothing to do about a draw nobody may make.
    }
  }

  // ADR-477: every toast of the console goes through the shared policy (levels, one clean line, de-duplication, a rate limit, the person's
  // Toasts setting); drawn or not, each is recorded for the Events page. A refused draw is a refused toast, never a crash.
  const toaster = createToaster({
    source: 'console',
    now: () => Date.now(),
    show: (line, options) => $.ui.toast(line, options),
    after: (ms, fn) => $.clock.after(ms, fn),
    prefs: toasts.prefs,
    persist: toasts.record,
  })

  return {
    fs: {
      read: async path => $.fs.read(rooted(path)),
      stat: async path => $.fs.stat(rooted(path)),
      list: async path => $.fs.list(rooted(path)),
      // The Windows write flavor (write-via.ts): the host's own file API, since no dd, sh, install, mkdir or cp is on the engine's PATH there.
      write: async (path, text) => $.fs.write(rooted(path), text),
      exists: async path => $.fs.exists(rooted(path)),
    },
        every: (ms, fn) => $.clock.every(ms, fn),
    after: (ms, fn) => $.clock.after(ms, fn),
    storeGet: async key => $.store.get(key),
    storeSet: async (key, value) => $.store.set(key, value as never),
    fetchText: async url => {
      const response = await $.http.fetch(url)

      return { ok: response.ok, status: response.status, text: response.text }
    },
    askChoice: async (question, options) => $.ui.ask(question, options),
    toast: (text, timeoutMs, level: ToastLevel = 'info') => quietly(() => void toaster.toast({ level, text, ...(timeoutMs !== undefined && { timeoutMs }) })),
    invalidate: () => quietly(() => $.ui.invalidate('ui.render')),
    // Once now and once after the new page has drawn: a page taller than the one before keeps the old offset until it is moved.
    scrollTop: () => {
      const go = () =>
        quietly(() => {
          isResettingScroll = true

          return Promise.resolve($.ui.scroll({ to: 'start', in: PANE_ID })).finally(() => {
            isResettingScroll = false
          })
        })

      go()
      $.clock.after(80, go)
    },
    focus: async (paneId, key) => $.ui.focus({ requestId: paneId, key }),
    blit: args => quietly(() => $.ui.blit(args)),
    openPane: async pane => $.ui.open(pane),
    closePane: async id => $.ui.close({ id }),
    panes: async () => $.ui.panes(),
    registerCommand: async spec => $.command.register(spec),
    run: async (argv, timeoutMs, stdin) => $.process.run(argv, { cwd, timeoutMs, ...(stdin !== undefined && { stdin }) }),
    spawn: (argv, input) => $.process.spawn({ argv, cwd, ...(input !== undefined && { input }) }),
    usage: async () => {
      const usage = await $.session.usage()

      return { ...(usage.cost?.usd !== undefined && { costUsd: usage.cost.usd }), ...(usage.context?.percent !== undefined && { contextPercent: usage.context.percent }) }
    },
    rufloTools: async () => {
      const names = (await $.tool.list()).flatMap(tool => RUFLO_TOOL.exec(tool.name)?.slice(1, 2) ?? [])

      return { tools: names.length, servers: [...new Set(names)].sort() }
    },
    settings: async () => $.settings.read(),
    home: async () => {
      const [home, userProfile, homeDrive, homePath] = await Promise.all([
        $.env.get('HOME'),
        $.env.get('USERPROFILE'),
        $.env.get('HOMEDRIVE'),
        $.env.get('HOMEPATH'),
      ])
      const envVars: { [key: string]: string | undefined } = { HOME: home, USERPROFILE: userProfile, HOMEDRIVE: homeDrive, HOMEPATH: homePath }

      return homeOf(k => envVars[k])
    },
    configDir: async () => $.env.get('CLAUDE_CONFIG_DIR'),
    // The engine lists the variables a module reads, so $.env.get takes a literal name (`claude plugin validate` refuses a computed one, and the mod then does not load):
    // the one model key the console's own OpenRouter target names is readable here; any other name is not.
    env: async name => (name === 'OPENROUTER_API_KEY' ? $.env.get('OPENROUTER_API_KEY') : undefined),
    pluginRoot: $.plugin.root,
    // `$.ruflo` exists only where ruflo-mods is seated; validate refuses feature-detecting a noun, so these are
    // async: a missing noun throws inside the promise and every caller's catch sees a rejection.
    rufloSnapshot: async () => $.ruflo.snapshot(),
    rufloRoute: async () => $.ruflo.lastRoute(),
    rufloSegment: async text => $.ruflo.segment({ id: 'console', text }),
    // Both wait on the turn, so neither may be called from inside a command.run hook (`/ruflo yes` is one): they run from a clock
    // tick, a later event of their own.
    submitPrompt: text =>
      new Promise<void>((resolve, reject) => {
        $.clock.after(1, () => void $.prompt.submit({ text }).then(() => resolve(), reject))
      }),
    fillPrompt: async text => (await $.prompt.fill({ text, mode: 'replace' })).isFilled,
    runSlash: (command, args) =>
      new Promise((resolve, reject) => {
        $.clock.after(1, () => void $.command.run({ command, args }).then(resolve, reject))
      }),
    listCommands: async () => (await $.command.list()).map(command => command.name),
    // ADR-465. A tool call waits on the turn like submitPrompt, so it starts from a clock tick, never inside the hook that asked.
    toolCall: input =>
      new Promise((resolve, reject) => {
        $.clock.after(1, () => void $.tool.call(input as never).then(reply => resolve(reply as never), reject))
      }),
    toolCheck: async (tool, input) => $.tool.check({ tool, input }),
    httpSend: async (url, init) => {
      const response = await $.http.fetch(url, init)

      return { ok: response.ok, status: response.status, text: response.text }
    },
  }
}

/**
 * ruflo-console: ruflo's cockpit inside Claude Code, and the home of `/ruflo`. A pane of views over ruflo's state on
 * disk and the ruflo CLI's local answers, a band above the prompt, a command palette, and management views (agent
 * drill-down, timeline, approvals, events). Every change goes through the ruflo CLI with fixed argv after a confirm.
 */
export const register: Register = (on, raw: PluginOptions) => {
  // The boot log reports this check, so an [ OK ] on screen means the area's commands resolved. It spawns nothing and takes a
  // moment; a failure of the check itself leaves the log drawing as it did, never stops the console.
  try {
    setBootChecks(selfCheckResults())
  } catch {
    setBootChecks(undefined)
  }

  const state = newState(raw)
  let host: Host | null = null
  let control: Controller | null = null

  // Claude's console tools (ADR-444): answered only for their own names, and only when the person's setting lets them exist.
  serveModelTools(on, () => (control === null ? null : { state, control }))

  on('session.start', async ($, e, next) => {
    control?.stop()
    host = hostOf($, e.cwd, { prefs: () => state.toastPrefs, record: digest => recordToast(state, digest) })
    // Which write the host takes (GNU dd/install on Linux, the constant sh scripts on macOS/BSD, the host's file API on Windows). Started
    // before the controller (whose timers write) exists; every write awaits it (writeFlavorReady), so none is built with a guessed flavor.
    const detecting = host
    void startWriteFlavor((argv, timeoutMs) => detecting.run(argv, timeoutMs), undefined, e.cwd)
    state.cwd = e.cwd
    state.nostrKeyVerifiedAtMs = null
    state.isInteractive = e.isInteractive !== false
    control = createController(state, host)

    // Which build is this? Only a checkout of this plugin in its repository is read (an installed copy inside some other repo is not
    // that repo's commit); read-only, $0, and any failure leaves the header at its version alone.
    const here = host
    const root = here.pluginRoot

    const built = here
      .run(['git', '-C', root, 'rev-parse', '--show-prefix'], 3_000)
      .then(prefix => (prefix.exitCode === 0 && isOurCheckout(prefix.stdout) ? here.run(['git', '-C', root, '--no-optional-locks', '-c', 'core.fsmonitor=false', '-c', 'core.hooksPath=/dev/null', 'describe', '--always', '--dirty', '--abbrev=7'], 3_000) : null))
      .then(described => {
        setBuild(described !== null && described.exitCode === 0 ? buildOf(described.stdout) : '')
        here.invalidate()
      })
      .catch(() => undefined)

    loadAtStart(state, here, built)

    const bound = host

    state.home = (await bound.home().catch(() => undefined)) ?? null
    state.configDir = (await bound.configDir().catch(() => undefined)) ?? (state.home === null ? null : `${state.home}/.claude`)
    // A recording or a wide screen can ask for a wider dock: RUFLO_CONSOLE_COLUMNS, whole columns, 40 to 400.
    const asked = Number(await (async () => $.env.get('RUFLO_CONSOLE_COLUMNS'))().catch(() => ''))

    // RUFLO_CONSOLE_PANEL=command|off overrides the panel option for this session (a recording that shows /ruflo opening it).
    const panel = await (async () => $.env.get('RUFLO_CONSOLE_PANEL'))().catch(() => undefined)

    if (panel === 'command' || panel === 'off') state.options.panel = panel
    state.dockColumns = Number.isInteger(asked) && asked >= 40 && asked <= 400 ? asked : 0
    // The x.ruv.io board's admin rows: only whether the token is set is kept, never its value.
    state.xruv.hasAdminToken = await (async () => $.env.get('RUFLO_X_ADMIN_TOKEN'))().then(
      value => typeof value === 'string' && value !== '',
      () => null,
    )
    await Promise.all([
      bound
        .registerCommand({ name: 'ruflo', description: 'ruflo: the cockpit (views, palette, agents, approvals) and every ruflo mod command — /ruflo help', argumentHint: '[view|palette|agent <id>|mods|swarm <sub>|help]' })
        .catch(() => undefined),
      // Kept for good (ADR-406: no command is removed or renamed): `/ruflo-console` is the same command as `/ruflo`.
      bound.registerCommand({ name: 'ruflo-console', description: 'Same as /ruflo: the ruflo console', argumentHint: '[view|palette|help]' }).catch(() => undefined),
      bound.storeGet(storeKeyOf(e.cwd)).then(value => restore(state, value), () => undefined),
      bound.storeGet(termStoreKeyOf(e.cwd)).then(value => restoreSessions(state, value), () => undefined),
      bound.rufloTools().then(counted => void (state.rufloTools = counted), () => undefined),
    ])
    control.start()
    startSessions(state, bound)
    await control.refresh()
    control.autoOpen()

    // Declare the console tools to the model when control is on: the saved setting, or this session's RUFLO_CONSOLE_CONTROL=<level>:<ask|auto>, which can only lower it.
    await loadAiPrefs(state, bound).catch(() => undefined)

    const forced = parseControlEnv(await (async () => $.env.get('RUFLO_CONSOLE_CONTROL'))().catch(() => undefined))

    // The override may only lower what the person saved (ADR-450 T12): a project's settings env must not raise Claude's control.
    // It is kept as session state and applied on every load and save of the preferences, so opening Settings cannot lift it (#3814).
    setControlCap(state, forced === null ? null : { level: forced.level, confirm: forced.confirm })
    await announceModelTools(tool => $.tool.register(tool), state).catch(() => 0)

    return next(e)
  })

  on('session.end', async ($, e, next) => {
    control?.stop()

    return next(e)
  })

  /**
   * `/ruflo`: the console's own subcommands are answered here; `mods` and `swarm <sub>` go to the plugins beneath that
   * hook the same command (ruflo-mods, ruflo-swarm), and are answered with a hint when neither does.
   */
  on('command.run', { command: 'ruflo' }, async ($, e, next) => {
    if (control === null) return next(e)

    return dispatch(control, state, e.args, async () => (await next(e)) as { text?: string } | undefined)
  })

  /** `/ruflo-console` is the same command: ruflo-mods and ruflo-swarm hook it as they hook `/ruflo`. */
  on('command.run', { command: 'ruflo-console' }, async ($, e, next) => {
    if (control === null) return next(e)

    return dispatch(control, state, e.args, async () => (await next(e)) as { text?: string } | undefined)
  })

  // Which element was pressed or submitted, before its own closure runs: the runner reads it as the origin of the ask that follows, so
  // the page puts the confirm and the answer right under it (views/attention.ts). Answering a confirm never moves the origin.
  on('ui.press', { component: 'Pane' }, ($, e, next) => {
    if (!ANSWER_KEYS.has(e.element)) state.lastPressed = e.element

    // A click that reaches the engine after its drawing was replaced (a resize) finds no handler: answered quietly (press-guard.ts).
    return tolerantPress(() => next(e), { element: e.element })
  })

  on('ui.input', { component: 'Pane' }, ($, e, next) => {
    if (e.kind === 'submit') state.lastPressed = e.element

    return next(e)
  })

  on('ui.render', { component: 'Pane', requestId: PANE_ID }, ($, e, next) => {
    if (control === null) {
      return next(e)
    }

    const started = Date.now()
    const table = kitForSurface($.ui.resolve(e) as unknown as Kit, e.surface)
    const columns = Math.max(20, Math.floor(Number(e.props.bodyColumns) || 0) - 1)
    const isNarrow = columns < NARROW
    const kit: Kit = isNarrow ? { Box: table.Box, Text: table.Text, Button: table.Button, ...(table.Input !== undefined && { Input: table.Input }) } : table

    if (!state.pane.isOpen) state.pane.bootAtMs = Date.now()
    state.pane.isOpen = true
    state.pane.isFocused = e.props.isFocused === true
    state.pane.columns = columns
    state.pane.placement = e.props.placement
    // Height-dependent art must use this render's allocation before its Raster size is recorded.
    state.pane.rows = Math.max(0, Math.floor(Number(e.props.scroll?.bodyRows) || 0))
    // A reload while the pane stayed up: timers are gone, so resume them from here.
    if (!state.timers.has('watch')) control.resume()

    const pictures = isNarrow ? new Map() : picturesOf(state, columns, Date.now(), Date.now(), kit.Raster === undefined)

    state.mounted = kit.Raster === undefined ? new Map() : new Map([...pictures].map(([key, grid]) => [key, { columns: grid.columns, rows: grid.rows }]))
    state.pictured = pictures.size
    control.animate()

    const tree = paneView({ kit: withClearing(kit, state, control.actions.clearField, { columns, repaint: () => host?.invalidate() }), state, nowMs: Date.now(), columns, pictures, act: control.actions })

    state.stats.renders.push(Date.now() - started)
    if (state.stats.renders.length > 200) state.stats.renders.shift()

    return tree
  })

  // The AI terminal's conversation is its own window: the wheel and the page keys over the pane move it, so the header,
  // tabs and the field below stay where they are (the engine would scroll the whole pane).
  on('ui.scroll', { component: 'Pane', requestId: PANE_ID }, ($, e, next) => {
    if (control === null || state.view !== 'terminal' || e.by === 0 || isResettingScroll) return next(e)

    const lines = Math.abs(e.by) >= e.bodyRows ? Math.max(1, Math.round(e.bodyRows / 2)) : Math.abs(e.by) * 3

    control.actions.term.scroll(e.by < 0 ? lines : -lines)

    // The pane itself stays put: ask the engine for the offset it already has.
    return next({ ...e, offset: e.offset - e.by })
  })

  on('ui.render', { component: 'AbovePrompt' }, ($, e, next) => {
    const mode = state.bandMode ?? state.options.bar
    const show = mode === 'on' || (mode === 'auto' && state.snapshot?.isRufloProject === true)

    if (control === null || e.props.hasSurvey || !show) {
      return next(e)
    }

    const table = kitForSurface($.ui.resolve(e) as unknown as Kit, e.surface)
    const bound = control

    state.barDrawnAtMs = Date.now()

    const mark = table.Raster !== undefined ? table.Raster(markPicture(e.props.isWorking, Date.now()).toRaster(BAR_KEY)) : null

    state.turnActive = e.props.isWorking === true
    bound.markFrame(e.requestId, e.props.isWorking && mark !== null)

    // A click on a part opens the console on its view, with the keys, so the person can act there at once.
    return barView(table, state, Math.floor(Number(e.props.bodyColumns) || 80), mark, () => void bound.open(false), view => {
      bound.setView(view)
      void bound.open(true)
    }, () => {
      dismissNotices(state)
      try {
        $.ui.invalidate('ui.render')
      } catch {
        // A refused redraw leaves the notice showing until the next one.
      }
    })
  })

  // A tool row that ran while one mission task was running says which: one dim line under the engine's own row.
  on('ui.render', { component: 'ToolUse' }, async ($, e, next) => {
    const owner = ownerOf(state, e.props.tool_use_id, e.props.isRunning === true)

    if (owner === null) return next(e)

    const table = $.ui.resolve(e) as unknown as Kit
    const own = await next(e)

    return table.Box({ key: `owner-${e.props.tool_use_id}`, flexDirection: 'column', children: [own, table.Text({ dimColor: true, children: `  ${ownerLine(owner)}` })] })
  })

  /** 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) => {
    // A new turn: the per-turn cap on Claude's console actions starts over.
    state.control.turnCalls = 0
    if (e.agentId === undefined) state.turnStartedMs = Date.now()

    try {
      $.ui.invalidate('ui.render')
    } catch {
      // A refused redraw leaves the mark at rest.
    }

    return next(e)
  })

  on('turn.complete', ($, e, next) => {
    if (e.agentId === undefined && state.turnStartedMs !== null) {
      // A long turn that ends while nobody watches is worth saying: the band announces it (a short one is not news).
      const took = Date.now() - state.turnStartedMs

      if (took >= 30_000) addNotice(state, { level: 'ok', text: `✓ Claude finished a turn · ${took < 60_000 ? `${Math.round(took / 1000)}s` : `${Math.floor(took / 60_000)}m ${Math.round((took % 60_000) / 1000)}s`}`, key: 'turn-done' })
    }
    if (e.agentId === undefined) state.turnStartedMs = null
    if (e.agentId === undefined) control?.markFrame('', false)
    if (e.agentId === undefined && host !== null) {
      try {
        onTurnComplete(state, host, e.reason)
      } catch {
        // A note that could not be recorded never changes the turn.
      }
    }

    return next(e)
  })

  // The mission Claude is working on rides in the system prompt (ADR-443); the text changes only when the task does.
  on('prompt.compose', async ($, e, next) => {
    const result = await next(e)
    const section = contextSection(state)

    return section === null ? result : { sections: [...result.sections, section] }
  })

  // A prompt carrying a mission's loop marker is that loop's tick.
  on('prompt.submit', ($, e, next) => {
    if (host !== null) {
      try {
        onPromptSubmit(state, host, e.text)
      } catch {
        // Counting a tick never blocks the prompt.
      }
    }

    return next(e)
  })

  on('ui.close', async ($, e, next) => {
    const result = await next(e)

    if (e.id === PANE_ID && result.deny === undefined) {
      state.pane.isOpen = false
      state.pane.isShown = false
      if (e.origin.kind === 'person') control?.closedByPerson()
      control?.animate()
    }

    return result
  })

  /** Observes only: every call goes on unchanged; the count feeds the activity sparkline. */
  on('tool.call', ($, e, next) => {
    control?.noteToolCall(e.agentId, e.tool)

    return next(e)
  })

  /** Observes only: a deny any verdict reached is listed in the approvals queue; the verdict passes on unchanged. */
  on('tool.check', async ($, e, next) => {
    const verdict = await next(e)

    if (verdict.decision === 'deny') {
      state.denied.push({ tool: plain(String(e.tool), 40), reason: plain(verdict.reason ?? 'no reason given', 160), atMs: Date.now() })
      if (state.denied.length > 20) state.denied.shift()
      record(state.events, [{ atMs: Date.now(), kind: 'mods', text: `${plain(String(e.tool), 40)} denied: ${plain(verdict.reason ?? '', 80)}` }])
    }

    return verdict
  })

  /** Observes only, never refuses: which mods the engine admitted or refused after the console, for the plugins view. */
  on('plugin.register', async ($, e, next) => {
    const result = await next(e)

    state.mods.push({ name: plain(e.name, 40), provenance: plain(e.provenance, 80), isLoaded: result.refuse === undefined, ...(result.refuse !== undefined && { reason: plain(result.refuse, 120) }), atMs: Date.now() })
    if (state.mods.length > 50) state.mods.shift()
    record(state.events, [{ atMs: Date.now(), kind: 'mods', text: `${plain(e.name, 40)} ${result.refuse === undefined ? 'loaded' : 'REFUSED'} (${plain(e.provenance, 60)})` }])

    return result
  })
}