🌊 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
fix(ruflo-mods): 0.3.4 budget rung once per session, no guidance observations without route ownership, report dropped tool ids
ruv576672ea44a6
diff --git a/plugins/ruflo-mods/.claude-plugin/plugin.json b/plugins/ruflo-mods/.claude-plugin/plugin.jsonindex fa5ac5c4f7..a7a8be0d99 100644--- a/plugins/ruflo-mods/.claude-plugin/plugin.json+++ b/plugins/ruflo-mods/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "ruflo-mods","description": "ruflo as a Claude Code mod (function hooks, ADR-404): in-process prompt routing, edit learning signals, tighten-only tool checks from ruflo policy, the cost-tracker budget ladder, a mod trust gate for newly installed mods, and the $.ruflo noun other mods compose their status with. Opt-in and removable: the classic hook-handler hooks stay the default and take every event back whenever the mod is not loaded.",- "version": "0.3.3",+ "version": "0.3.4","author": {"name": "ruvnet","url": "https://github.com/ruvnet"diff --git a/plugins/ruflo-mods/README.md b/plugins/ruflo-mods/README.mdindex 488964db52..0859db11d9 100644--- a/plugins/ruflo-mods/README.md+++ b/plugins/ruflo-mods/README.md@@ -65,7 +65,7 @@ In a session, `/ruflo mods` (through ruflo-console's `/ruflo`) reports what the- **Tool checks:** `tool.check` only tightens. It applies the dangerous-command list and ruflo policy rules that name `claude-code.*` actions (written by the CLI to `.claude-flow/policy/claude-code.json`). It never loosens a verdict.- **Trust gate:** `plugin.register` names what a later-installed mod can do (host commands, network, environment, tool verdicts) and, under `modTrust: refuse-risky`, refuses it unless allow-listed.- **`$.ruflo`:** other mods add a status segment with `$.ruflo.segment({ id, text })` instead of drawing a second bar; `lastRoute()` and `snapshot()` read what the mod measured. Contract: `types/index.d.ts`.-- **Budget:** `session.measure` applies the cost-tracker budget ladder to live session cost (`costBudgetUsd`); `costHardStop` halts new subagents at 100%.+- **Budget:** `session.measure` applies the cost-tracker budget ladder to live session cost (`costBudgetUsd`); Each rung is announced once per session, even if cost falls and rises again. `costHardStop` halts new subagents at 100%.The classic `hook-handler.cjs` hooks stay installed and remain the fallback. The mod takes an event only where the classic helper hands it over (`RUFLO_MODS_OWNS`), so nothing fires twice. When the mod is not loaded, every classic hook runs as before.@@ -134,7 +134,7 @@ Enable the two independent options through Claude Code user settings:}```-`guidanceLearning` records observations, despite its compatibility-oriented name.+`guidanceLearning` records observations, despite its compatibility-oriented name. A project that does not own `route` records none (it still gets `guidanceContext`). Tool ids past 256 per task are not counted; `/ruflo-mods` reports how many.Each registration lifetime owns a separate queue under`.claude-flow/mods/guidance/observations/`. Records contain generated task IDs,bundle digest, source revision, displayed rule IDs, permission counters, tooldiff --git a/plugins/ruflo-mods/hooks/cost/index.ts b/plugins/ruflo-mods/hooks/cost/index.tsindex 2d4ef61309..57afebb872 100644--- a/plugins/ruflo-mods/hooks/cost/index.ts+++ b/plugins/ruflo-mods/hooks/cost/index.ts@@ -2,7 +2,7 @@ import type { On } from 'claude-code'import type { ModOptions } from '../options'import { redraw, type ModState } from '../state'-import { alertLevel, isRaised } from './budget'+import { alertLevel, isRaised, type BudgetLevel } from './budget'/*** ruflo-cost-tracker's budget ladder on the session's live cost:@@ -15,6 +15,7 @@ export function registerCost(on: On, state: ModState, options: ModOptions) {const limit = options.costBudgetUsdif (limit === undefined) returnstate.budget = { level: 'OK', limit }+ let announced: BudgetLevel = 'OK' // the highest rung told; a fall and a second rise stay quieton('session.measure', async ($, e, next) => {const result = await next(e)@@ -22,7 +23,8 @@ export function registerCost(on: On, state: ModState, options: ModOptions) {if (typeof usd !== 'number' || !Number.isFinite(usd) || usd < 0) return resultconst level = alertLevel(usd / limit)- const raised = isRaised(state.budget.level, level)+ const raised = isRaised(announced, level)+ if (raised) announced = levelstate.budget = { level, usd, limit }if (raised) {try {diff --git a/plugins/ruflo-mods/hooks/guidance/index.ts b/plugins/ruflo-mods/hooks/guidance/index.tsindex 602a82c2b4..9afa33cdbf 100644--- a/plugins/ruflo-mods/hooks/guidance/index.ts+++ b/plugins/ruflo-mods/hooks/guidance/index.ts@@ -6,7 +6,7 @@ import { MAX_PROJECTION_BYTES, parseProjection, PROJECTION_PATH, selectGuidanceexport type GuidanceHooks = {start: () => void- prompt: (text: string, fs: FileHost) => Promise<string | undefined>+ prompt: (text: string, fs: FileHost, record: boolean) => Promise<string | undefined>active: () => ActiveTask | undefinedcheck: (task: ActiveTask | undefined, decision: unknown) => voidtool: (task: ActiveTask | undefined, event: unknown, result: { deny?: unknown; isError?: boolean }) => void@@ -29,9 +29,10 @@ export function createGuidance(state: ModState, options: ModOptions): GuidanceHostart() {if (!s.runId) { s.runId = newRunId(); s.status = 'missing' }},- async prompt(text, fs) {+ async prompt(text, fs, record) {if (!s.runId) return undefined- if (options.guidanceLearning) finishTask(s, 'interrupted')+ const learn = options.guidanceLearning && record // a project that does not own routing records nothing+ if (learn) finishTask(s, 'interrupted')const read = await projection({stat: async path => {const stat = await fs.stat(path)@@ -43,8 +44,8 @@ export function createGuidance(state: ModState, options: ModOptions): GuidanceHos.status = read.kind === 'ok' ? 'ready' : read.kind === 'absent' ? 'missing' : 'unreadable'if (read.kind !== 'ok') return undefinedconst selected = selectGuidance(text, read.value)- if (options.guidanceLearning) {- s.active = { taskId: ++s.taskSeq, projection: read.value, ruleIds: options.guidanceContext ? selected.ids : [], checks: { allow: 0, ask: 0, deny: 0 }, tools: { ok: 0, error: 0, denied: 0 }, toolIds: new Set() }+ if (learn) {+ s.active = { taskId: ++s.taskSeq, projection: read.value, ruleIds: options.guidanceContext ? selected.ids : [], checks: { allow: 0, ask: 0, deny: 0 }, tools: { ok: 0, error: 0, denied: 0 }, toolIds: new Set(), idsDropped: 0 }}return options.guidanceContext ? selected.context : undefined},@@ -57,7 +58,8 @@ export function createGuidance(state: ModState, options: ModOptions): GuidanceHotry {const id = (event as { tool_use_id?: unknown }).tool_use_idif (typeof id === 'string') {- if (task.toolIds.has(id) || task.toolIds.size >= 256) return+ if (task.toolIds.has(id)) return+ if (task.toolIds.size >= 256) { task.idsDropped++; return }task.toolIds.add(id)}if (result.deny !== undefined) task.tools.denied++diff --git a/plugins/ruflo-mods/hooks/guidance/observations.ts b/plugins/ruflo-mods/hooks/guidance/observations.tsindex 2fca76fb2e..d86643d40f 100644--- a/plugins/ruflo-mods/hooks/guidance/observations.ts+++ b/plugins/ruflo-mods/hooks/guidance/observations.ts@@ -24,6 +24,7 @@ export type ActiveTask = {checks: Observation['checks']tools: Observation['tools']toolIds: Set<string>+ idsDropped: number}export type GuidanceState = {@@ -34,6 +35,7 @@ export type GuidanceState = {pending: Observation[]saved: numberdropped: number+ idsDropped: numberstatus: 'off' | 'ready' | 'missing' | 'unreadable'flush: Promise<void>}@@ -42,7 +44,7 @@ export const OBSERVATIONS_DIR = '.claude-flow/mods/guidance/observations'export const MAX_OBSERVATIONS = 128export const MAX_QUEUE_CHARS = 256 * 1024-export const guidanceState = (): GuidanceState => ({ runId: '', taskSeq: 0, seenTurns: new Set(), pending: [], saved: 0, dropped: 0, status: 'off', flush: Promise.resolve() })+export const guidanceState = (): GuidanceState => ({ runId: '', taskSeq: 0, seenTurns: new Set(), pending: [], saved: 0, dropped: 0, idsDropped: 0, status: 'off', flush: Promise.resolve() })/** A storage namespace, never an authenticated host session identity. */export const newRunId = () => `mod-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 12)}-${Math.random().toString(36).slice(2, 12)}`@@ -65,6 +67,7 @@ export function finishTask(s: GuidanceState, completion: Observation['completionconst active = s.actives.active = undefinedif (!active) return+ s.idsDropped += active.idsDroppedif (s.pending.length + s.saved >= MAX_OBSERVATIONS) { s.dropped++; return }s.pending.push({version: 1, kind: 'guidance-observation', id: `${s.runId}:${active.taskId}`, runId: s.runId, taskId: active.taskId,diff --git a/plugins/ruflo-mods/hooks/route/index.ts b/plugins/ruflo-mods/hooks/route/index.tsindex 6552ac4ecc..e5a8fecb34 100644--- a/plugins/ruflo-mods/hooks/route/index.ts+++ b/plugins/ruflo-mods/hooks/route/index.ts@@ -23,7 +23,7 @@ export function registerRoute(on: On, state: ModState, options: ModOptions, guidon('prompt.submit', async ($, e, next) => {const text = typeof e.text === 'string' ? e.text : ''if (state.agentTrim.enabled) state.agentTrim.prompt = text.slice(0, 4000).toLowerCase() // agent.offer keeps a type the prompt names- const advisory = guidance ? await guidance.prompt(text, { stat: path => $.fs.stat(path), read: path => $.fs.read(path) }) : undefined+ const advisory = guidance ? await guidance.prompt(text, { stat: path => $.fs.stat(path), read: path => $.fs.read(path) }, state.owned.has('route')) : undefinedconst context = [...(e.context ?? []), ...(advisory ? [advisory] : [])]if (!state.owned.has('route')) return next(advisory ? { ...e, context } : e)const result = routeTask(text)diff --git a/plugins/ruflo-mods/hooks/state.ts b/plugins/ruflo-mods/hooks/state.tsindex 1f1caf76d4..7c818e1bd3 100644--- a/plugins/ruflo-mods/hooks/state.ts+++ b/plugins/ruflo-mods/hooks/state.ts@@ -146,5 +146,7 @@ export function report(s: ModState): string {` delivery: ${s.delivery.enabled ? `${s.delivery.consumed} dropped, ${s.delivery.blocked} refused` : 'off (set the deliveryScreen option)'}`,` segments: ${segments.join(', ') || 'none'}`,` guidance: ${s.guidance.status}; ${s.guidance.saved} unverified observation(s), ${s.guidance.pending.length} pending, ${s.guidance.dropped} dropped`,- ].join('\n')+ ]+ .concat(s.guidance.idsDropped + (s.guidance.active?.idsDropped ?? 0) > 0 ? [` ${s.guidance.idsDropped + (s.guidance.active?.idsDropped ?? 0)} tool id(s) past the 256 cap not counted`] : [])+ .join('\n')}diff --git a/plugins/ruflo-mods/scripts/smoke.sh b/plugins/ruflo-mods/scripts/smoke.shindex 65060394af..278fe669da 100755--- a/plugins/ruflo-mods/scripts/smoke.sh+++ b/plugins/ruflo-mods/scripts/smoke.sh@@ -1,5 +1,5 @@#!/usr/bin/env bash-# Structural + security smoke for ruflo-mods v0.3.3 (ADR-404, ADR-447).+# Structural + security smoke for ruflo-mods v0.3.4 (ADR-404, ADR-447).# Static only: CI has no Claude Code, so the hooks module's behaviour is held# by v3/@claude-flow/cli/__tests__/mods/*.test.ts and, where function hooks are# on, by `claude plugin test plugins/ruflo-mods`.@@ -12,9 +12,9 @@ ok() { printf "PASS\n"; PASS=$((PASS+1)); }bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }HOOKS="$ROOT/hooks"-step "1. plugin.json declares ruflo-mods 0.3.3"+step "1. plugin.json declares ruflo-mods 0.3.4"grep -q '"name": "ruflo-mods"' "$ROOT/.claude-plugin/plugin.json" \- && grep -q '"version": "0.3.3"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"+ && grep -q '"version": "0.3.4"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"step "2. hooks.json names exactly one module and no classic hook commands"grep -q '"modules": \["./register.ts"\]' "$HOOKS/hooks.json" && ! grep -q '"command"' "$HOOKS/hooks.json" \diff --git a/plugins/ruflo-mods/tests/cost.test.ts b/plugins/ruflo-mods/tests/cost.test.tsindex 36094fb276..c479b5d621 100644--- a/plugins/ruflo-mods/tests/cost.test.ts+++ b/plugins/ruflo-mods/tests/cost.test.ts@@ -26,4 +26,14 @@ describe('cost', () => {expect((await spawn()).deny).toMatch(/halted \(costHardStop\)/)expect(JSON.parse((await $.command.run(run('consumer-snapshot'))).text ?? 'null').budget).toEqual({ level: 'HARD_STOP', usd: 2.4, limit: 2 })})++ test('a rung announced once stays quiet when cost falls and rises again', { options: { costBudgetUsd: 2 } }, async ($, on) => {+ world(on)+ const toasts: string[] = []+ on('ui.toast', ($, e) => (toasts.push(e.text), { value: undefined }))+ on('session.measure', ($, e) => ({ changed: e.changed }))+ await $.session.start(START)+ for (const usd of [1.1, 0.2, 1.2, 1.6, 1.0, 1.7, 1.9]) await $.session.measure(measure(usd))+ expect(toasts.map(t => t.split(':')[0])).toEqual(['ruflo budget INFO', 'ruflo budget WARNING', 'ruflo budget CRITICAL'])+ })})diff --git a/plugins/ruflo-mods/tests/guidance.test.ts b/plugins/ruflo-mods/tests/guidance.test.tsindex 4c1836503b..644228dde4 100644--- a/plugins/ruflo-mods/tests/guidance.test.ts+++ b/plugins/ruflo-mods/tests/guidance.test.ts@@ -1,5 +1,5 @@import { describe, expect, test, tier } from 'claude-code/testing'-import { prompt, ROOT, START, world } from './fixtures/world'+import { HELPER, prompt, ROOT, START, world } from './fixtures/world'tier('user')@@ -76,4 +76,35 @@ describe('guidance (ADR-447)', () => {expect(context).not.toContain('advisory guidance DATA')expect(queued(w.files).length).toBe(0)})++ test('a project that does not own routing records no observations but still gets guidance context', { options }, async ($, on) => {+ const classic = { hooks: { UserPromptSubmit: [{ hooks: [{ command: 'node "$CLAUDE_PROJECT_DIR/.claude/helpers/hook-handler.cjs" route' }] }] } }+ const w = world(on, classic, { [PATH]: projection(), [HELPER]: '// an older helper' })+ let context = ''+ on('prompt.submit', ($, e) => { context = e.context?.join('\n') ?? ''; return { text: e.text } })+ on('tool.call', () => ({ result: 'ok' }))+ on('turn.complete', ($, e) => ({ text: e.answer }))+ await $.session.start(START)+ await $.prompt.submit(prompt('Write parser tests'))+ await $.tool.call({ tool: 'Read', file_path: 'a' })+ await $.turn.complete(complete('t1'))+ expect(context).toContain('TEST-001')+ expect(queued(w.files).length).toBe(0)+ })++ test('tool ids past the per-task cap are counted and the report says how many', { options }, async ($, on) => {+ world(on, {}, { [PATH]: projection() })+ on('prompt.submit', ($, e) => ({ text: e.text }))+ on('tool.call', () => ({ result: 'ok' }))+ on('turn.complete', ($, e) => ({ text: e.answer }))+ on('command.run', () => ({ text: 'core' }))+ await $.session.start(START)+ await $.prompt.submit(prompt('Write parser tests'))+ for (let i = 0; i < 260; i++) await $.tool.call({ tool: 'Read', file_path: 'a', tool_use_id: `id${i}` } as never)+ const text = (await $.command.run({ command: 'ruflo-mods', args: '', origin: { kind: 'composer' as const }, presentation: { isFullscreen: false, columns: 100 } })).text+ expect(text).toMatch(/4 tool id\(s\) past the 256 cap not counted/)+ await $.turn.complete(complete('t1'))+ const after = (await $.command.run({ command: 'ruflo-mods', args: '', origin: { kind: 'composer' as const }, presentation: { isFullscreen: false, columns: 100 } })).text+ expect(after).toMatch(/4 tool id\(s\) past the 256 cap not counted/)+ })})