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

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.json
index 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.md
index 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, tool
diff --git a/plugins/ruflo-mods/hooks/cost/index.ts b/plugins/ruflo-mods/hooks/cost/index.ts
index 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.costBudgetUsd
if (limit === undefined) return
state.budget = { level: 'OK', limit }
+ let announced: BudgetLevel = 'OK' // the highest rung told; a fall and a second rise stay quiet
on('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 result
const level = alertLevel(usd / limit)
- const raised = isRaised(state.budget.level, level)
+ const raised = isRaised(announced, level)
+ if (raised) announced = level
state.budget = { level, usd, limit }
if (raised) {
try {
diff --git a/plugins/ruflo-mods/hooks/guidance/index.ts b/plugins/ruflo-mods/hooks/guidance/index.ts
index 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, selectGuidance
export type GuidanceHooks = {
start: () => void
- prompt: (text: string, fs: FileHost) => Promise<string | undefined>
+ prompt: (text: string, fs: FileHost, record: boolean) => Promise<string | undefined>
active: () => ActiveTask | undefined
check: (task: ActiveTask | undefined, decision: unknown) => void
tool: (task: ActiveTask | undefined, event: unknown, result: { deny?: unknown; isError?: boolean }) => void
@@ -29,9 +29,10 @@ export function createGuidance(state: ModState, options: ModOptions): GuidanceHo
start() {
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): GuidanceHo
s.status = read.kind === 'ok' ? 'ready' : read.kind === 'absent' ? 'missing' : 'unreadable'
if (read.kind !== 'ok') return undefined
const 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): GuidanceHo
try {
const id = (event as { tool_use_id?: unknown }).tool_use_id
if (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.ts
index 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: number
dropped: number
+ idsDropped: number
status: 'off' | 'ready' | 'missing' | 'unreadable'
flush: Promise<void>
}
@@ -42,7 +44,7 @@ export const OBSERVATIONS_DIR = '.claude-flow/mods/guidance/observations'
export const MAX_OBSERVATIONS = 128
export 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['completion
const active = s.active
s.active = undefined
if (!active) return
+ s.idsDropped += active.idsDropped
if (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.ts
index 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, guid
on('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')) : undefined
const 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.ts
index 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.sh
index 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.ts
index 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.ts
index 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/)
+ })
})