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-cost-tracker): v0.2.2 β€” fix namespace-routing bug + adopt plugin contract (ADR-0001)

Reuven9dc248700c24
diff --git a/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json b/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json
index 533c4a2c1f..e378de1dfc 100644
--- a/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json
+++ b/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-cost-tracker",
- "description": "Token usage tracking, model cost attribution per agent, budget alerts, and optimization recommendations",
- "version": "0.2.1",
+ "description": "Token usage tracking, model cost attribution per agent, budget alerts, and optimization recommendations β€” uses memory_* (namespace-routed) for cost-tracking and cost-patterns; pairs with federation budget circuit breaker (ADR-097)",
+ "version": "0.2.2",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -14,6 +14,8 @@
"tokens",
"budget",
"optimization",
- "usage"
+ "usage",
+ "namespace-routing",
+ "mcp"
]
}
diff --git a/plugins/ruflo-cost-tracker/README.md b/plugins/ruflo-cost-tracker/README.md
index 2207a2df48..f87669b2d8 100644
--- a/plugins/ruflo-cost-tracker/README.md
+++ b/plugins/ruflo-cost-tracker/README.md
@@ -81,8 +81,38 @@ Phase 1 of ADR-097 enforces at the **send** side. Two follow-up phases will tigh
Until Phase 3 ships, federated spend is **not** counted in the host's cost-tracker β€” only local agent spend. Treat `cost-report` numbers as a lower bound when federation is in use.
+## Compatibility
+
+- **CLI:** pinned to `@claude-flow/cli` v3.6 major+minor.
+- **Verification:** `bash plugins/ruflo-cost-tracker/scripts/smoke.sh` is the contract.
+
+## Namespace coordination
+
+This plugin owns two AgentDB namespaces:
+
+- `cost-tracking` β€” usage records (consumed by `cost-report`)
+- `cost-patterns` β€” optimization recommendations (consumed by `cost-optimize`)
+
+Both follow the kebab-case `<plugin-stem>-<intent>` convention from [ruflo-agentdb ADR-0001 Β§"Namespace convention"](../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md). Both are accessed via the `memory_*` tool family which routes by namespace.
+
+> **Routing note:** The `agentdb_hierarchical-*` and `agentdb_pattern-*` tools route by tier / ReasoningBank, not by namespace string. Earlier versions of `cost-report` and `cost-optimize` passed namespace arguments to those tools and got silently-ignored behavior. ADR-0001 fixes this by switching the load path to `memory_*` and documenting the dual write path for optimization patterns.
+
+Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed.
+
+## Verification
+
+```bash
+bash plugins/ruflo-cost-tracker/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Architecture Decisions
+
+- [`ADR-0001` β€” ruflo-cost-tracker plugin contract (namespace-routing fix, federation budget pairing, smoke as contract)](./docs/adrs/0001-cost-tracker-contract.md)
+
## Related Plugins
+- `ruflo-agentdb` β€” namespace convention owner; defines the routing rules ADR-0001 fixes a violation of
- `ruflo-observability` -- Token usage metrics collected via observability instrumentation
- `ruflo-neural-trader` -- PnL tracking and cost-adjusted return calculation
- `ruflo-federation` -- Budget circuit breaker on outbound federation_send (ADR-097)
diff --git a/plugins/ruflo-cost-tracker/docs/adrs/0001-cost-tracker-contract.md b/plugins/ruflo-cost-tracker/docs/adrs/0001-cost-tracker-contract.md
new file mode 100644
index 0000000000..bf6cf5fc47
--- /dev/null
+++ b/plugins/ruflo-cost-tracker/docs/adrs/0001-cost-tracker-contract.md
@@ -0,0 +1,98 @@
+---
+id: ADR-0001
+title: ruflo-cost-tracker plugin contract β€” pinning, namespace-routing fix, federation budget integration, smoke as contract
+status: Proposed
+date: 2026-05-04
+authors:
+ - reviewer (Claude Code)
+tags: [plugin, cost, tokens, budget, optimization, namespace, federation, smoke-test]
+---
+
+## Context
+
+`ruflo-cost-tracker` (v0.2.1) tracks token usage per agent/task/model, computes USD cost attribution, and recommends optimizations. It already documents:
+
+- Two AgentDB namespaces (`cost-tracking` for usage records, `cost-patterns` for optimization patterns)
+- Federation budget circuit breaker pairing per ADR-097 (host-side `federation_send` caps: `maxHops`, `maxTokens`, `maxUsd`, `hopCount`, `spent.{tokens,usd}`)
+- 5 cost subcommands (`report`, `breakdown`, `budget`, `optimize`, `history`)
+- 2 skills + 1 agent + REFERENCE.md (token-optimized per ADR-098 Part 2)
+
+### The drift this ADR fixes
+
+The two skills (`cost-report`, `cost-optimize`) call `agentdb_hierarchical-recall` with a `namespace: 'cost-tracking'` argument and `agentdb_pattern-store` with `namespace: 'cost-patterns'`. Per [ruflo-agentdb ADR-0001 Β§"Where namespace strings actually apply"](../../../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md), neither tool family routes by namespace:
+
+- `agentdb_hierarchical-*` routes by **tier** (`working|episodic|semantic`). Namespace argument is silently ignored.
+- `agentdb_pattern-*` routes through **ReasoningBank**. Namespace argument is silently ignored. Fallback writes to the reserved `pattern` namespace, not to `cost-patterns`.
+
+The CLI examples in the agent file have always been correct (`memory store --namespace cost-tracking`). The skills' MCP-tool mapping was wrong. This ADR fixes them.
+
+## Decision
+
+### 1. Skill fixes (real bug, not just docs)
+
+- `cost-report/SKILL.md` β€” replace `agentdb_hierarchical-recall` with `memory_search` / `memory_list` / `memory_retrieve` (namespace-routed). Update `allowed-tools` accordingly. Cross-link the namespace convention.
+- `cost-optimize/SKILL.md` β€” replace the load step with `memory_search`. Document **two write paths** for optimization patterns:
+ - `agentdb_pattern-store` (ReasoningBank-routed; no namespace arg; fallback lands in reserved `pattern` namespace)
+ - `memory_store --namespace cost-patterns` (namespace-routable; lands where the agent file's CLI examples promise)
+
+### 2. Add this ADR (Proposed)
+
+`docs/adrs/0001-cost-tracker-contract.md`. Cross-links the eight sibling ADRs.
+
+### 3. README augment
+
+Append:
+- **Compatibility** β€” pin to `@claude-flow/cli` v3.6.
+- **Namespace coordination** β€” owns `cost-tracking` (memory-routed) + `cost-patterns` (memory-routed). Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadowed.
+- **Architecture Decisions** + **Verification** sections.
+- The federation budget pairing block already in README stays as-is (already correctly references ADR-097).
+
+### 4. Plugin metadata
+
+Bump `0.2.1 β†’ 0.2.2`. Patch bump justified: skill fixes are functional changes (the skills weren't doing what they claimed), but the public command surface is unchanged. Keywords add `namespace-routing`, `mcp`.
+
+### 5. Smoke contract (`scripts/smoke.sh`)
+
+10 checks:
+
+1. plugin.json declares `0.2.2` with new keywords.
+2. Both skills (`cost-report`, `cost-optimize`) present with valid frontmatter.
+3. Skills use `memory_search` / `memory_store` for `cost-tracking` and `cost-patterns` namespaces (not `agentdb_hierarchical-*` / `agentdb_pattern-*` with a namespace arg).
+4. `cost-optimize` documents both pattern-store paths (ReasoningBank vs namespace-routable).
+5. README pins to `@claude-flow/cli` v3.6.
+6. README references ruflo-agentdb namespace convention.
+7. README's federation budget circuit breaker pairing block (ADR-097) is intact.
+8. ADR-0001 exists with status `Proposed`.
+9. REFERENCE.md exists and is non-empty (token-optimization pattern).
+10. No skill grants wildcard tool access.
+
+## Consequences
+
+**Positive:**
+- Skills now actually do what their docs promise. `cost-report` reads from `cost-tracking`; `cost-optimize` writes to `cost-patterns` (or to ReasoningBank explicitly).
+- Future plugins reading the cost-tracker skills as a template won't replicate the namespace-routing bug.
+
+**Negative:**
+- One downstream change visible to anyone scripting against the old (broken) MCP tool calls. Mitigation: the agent file's CLI examples already used the correct pattern.
+
+**Neutral:**
+- No new MCP tools. No new skills. No new subcommands. Functional fix + documentation + smoke.
+
+## Verification
+
+```bash
+bash plugins/ruflo-cost-tracker/scripts/smoke.sh
+# Expected: "10 passed, 0 failed"
+```
+
+## Related
+
+- `plugins/ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md` β€” namespace convention; defines the routing contract this ADR fixes a violation of
+- `plugins/ruflo-ruvector/docs/adrs/0001-pin-ruvector-0.2.25.md`
+- `plugins/ruflo-browser/docs/adrs/0001-browser-skills-architecture.md`
+- `plugins/ruflo-intelligence/docs/adrs/0001-intelligence-surface-completeness.md`
+- `plugins/ruflo-adr/docs/adrs/0001-adr-plugin-pattern.md`
+- `plugins/ruflo-aidefence/docs/adrs/0001-aidefence-contract.md`
+- `plugins/ruflo-autopilot/docs/adrs/0001-autopilot-contract.md`
+- `plugins/ruflo-core/docs/adrs/0001-core-contract.md`
+- `v3/docs/adr/ADR-097-federation-budget-circuit-breaker.md` β€” federation budget envelope
diff --git a/plugins/ruflo-cost-tracker/scripts/smoke.sh b/plugins/ruflo-cost-tracker/scripts/smoke.sh
new file mode 100755
index 0000000000..8070f6a55a
--- /dev/null
+++ b/plugins/ruflo-cost-tracker/scripts/smoke.sh
@@ -0,0 +1,85 @@
+#!/usr/bin/env bash
+# Structural smoke test for ruflo-cost-tracker v0.2.2 (ADR-0001).
+set -u
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PASS=0
+FAIL=0
+step() { printf "β†’ %s ... " "$1"; }
+ok() { printf "PASS\n"; PASS=$((PASS+1)); }
+bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
+
+step "1. plugin.json declares 0.2.2 with new keywords"
+v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
+if [[ "$v" != "0.2.2" ]]; then
+ bad "expected 0.2.2, got '$v'"
+else
+ miss=""
+ for k in namespace-routing mcp; do
+ grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
+ done
+ [[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
+fi
+
+step "2. both skills present with valid frontmatter"
+miss=""
+for s in cost-report cost-optimize; do
+ f="$ROOT/skills/$s/SKILL.md"
+ [[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }
+ for k in 'name:' 'description:' 'allowed-tools:'; do
+ grep -q "^$k" "$f" || miss="$miss $s-no-$k"
+ done
+done
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "3. skills use memory_* (namespace-routed), not agentdb_hierarchical-* with namespace"
+miss=""
+F="$ROOT/skills/cost-report/SKILL.md"
+grep -q "memory_search\|memory_list\|memory_retrieve" "$F" || miss="$miss cost-report-no-memory"
+grep -qE "agentdb_hierarchical-recall.+cost-tracking|cost-tracking.+agentdb_hierarchical-recall" "$F" && miss="$miss cost-report-still-uses-hierarchical"
+F="$ROOT/skills/cost-optimize/SKILL.md"
+grep -q "memory_search\|memory_list" "$F" || miss="$miss cost-optimize-no-memory"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "4. cost-optimize documents both pattern-store paths"
+F="$ROOT/skills/cost-optimize/SKILL.md"
+if grep -q "ReasoningBank" "$F" \
+ && grep -q "memory_store --namespace cost-patterns" "$F"; then
+ ok
+else
+ bad "missing dual-path documentation"
+fi
+
+step "5. README pins @claude-flow/cli to v3.6"
+grep -qE "@claude-flow/cli.*v3\.6|v3\.6.*claude-flow/cli" "$ROOT/README.md" \
+ && ok || bad "v3.6 pin missing"
+
+step "6. README defers to ruflo-agentdb namespace convention"
+grep -q "ruflo-agentdb" "$ROOT/README.md" \
+ && grep -q "Namespace convention" "$ROOT/README.md" \
+ && ok || bad "namespace coordination block incomplete"
+
+step "7. README federation budget circuit breaker (ADR-097) block intact"
+F="$ROOT/README.md"
+miss=""
+grep -q "ADR-097" "$F" || miss="$miss adr-ref"
+grep -qE "maxHops|maxTokens|maxUsd" "$F" || miss="$miss budget-fields"
+grep -q "BUDGET_EXCEEDED" "$F" || miss="$miss enforcement-string"
+[[ -z "$miss" ]] && ok || bad "federation block missing:$miss"
+
+step "8. ADR-0001 exists with status Proposed"
+ADR="$ROOT/docs/adrs/0001-cost-tracker-contract.md"
+[[ -f "$ADR" ]] && grep -qE "^status:[[:space:]]*Proposed" "$ADR" \
+ && ok || bad "ADR missing or status != Proposed"
+
+step "9. REFERENCE.md exists and is non-empty"
+[[ -s "$ROOT/REFERENCE.md" ]] && ok || bad "REFERENCE.md missing or empty"
+
+step "10. no wildcard tool grants in skills"
+bad_skills=""
+for f in "$ROOT"/skills/*/SKILL.md; do
+ grep -q '^allowed-tools:[[:space:]]*\*' "$f" && bad_skills="$bad_skills $(basename $(dirname "$f"))"
+done
+[[ -z "$bad_skills" ]] && ok || bad "wildcard:$bad_skills"
+
+printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
+[[ $FAIL -eq 0 ]] || exit 1
diff --git a/plugins/ruflo-cost-tracker/skills/cost-optimize/SKILL.md b/plugins/ruflo-cost-tracker/skills/cost-optimize/SKILL.md
index aef16cf17f..43fb481742 100644
--- a/plugins/ruflo-cost-tracker/skills/cost-optimize/SKILL.md
+++ b/plugins/ruflo-cost-tracker/skills/cost-optimize/SKILL.md
@@ -2,7 +2,7 @@
name: cost-optimize
description: Analyze token usage patterns and recommend cost optimizations with estimated savings
argument-hint: ""
-allowed-tools: mcp__claude-flow__agentdb_hierarchical-recall mcp__claude-flow__agentdb_pattern-search mcp__claude-flow__agentdb_pattern-store mcp__claude-flow__agentdb_semantic-route Bash
+allowed-tools: mcp__claude-flow__memory_search mcp__claude-flow__memory_list mcp__claude-flow__memory_store mcp__claude-flow__agentdb_pattern-search mcp__claude-flow__agentdb_pattern-store mcp__claude-flow__agentdb_semantic-route Bash
---
# Cost Optimize
@@ -15,19 +15,22 @@ When costs are higher than expected or you want to proactively reduce spending.
## Steps
-1. **Load usage data** -- call `mcp__claude-flow__agentdb_hierarchical-recall` to fetch recent token usage records from `cost-tracking` namespace (last 7 days)
+1. **Load usage data** -- call `mcp__claude-flow__memory_search` on the `cost-tracking` namespace (last 7 days). The `memory_*` tools route by namespace; use them β€” not `agentdb_hierarchical-*` (which routes by tier).
2. **Analyze model fit** -- for each agent, assess whether the model tier matches task complexity:
- - Agents doing simple tasks (formatting, linting) on Sonnet/Opus -> suggest Haiku or Agent Booster
- - Agents doing complex tasks (architecture, security) on Haiku -> flag quality risk
+ - Agents doing simple tasks (formatting, linting) on Sonnet/Opus β†’ suggest Haiku or Agent Booster
+ - Agents doing complex tasks (architecture, security) on Haiku β†’ flag quality risk
3. **Check cache rates** -- compute cache hit rate per agent; if below 60%, recommend enabling or improving prompt caching (90% cost reduction on cache reads)
4. **Detect redundancy** -- look for multiple agents performing overlapping tasks, or agents being spawned for work that could be batched
5. **Estimate savings** -- for each recommendation, calculate: current cost, projected cost after optimization, dollar savings, percentage reduction
-6. **Search patterns** -- call `mcp__claude-flow__agentdb_pattern-search` for previously successful optimizations
-7. **Store recommendations** -- call `mcp__claude-flow__agentdb_pattern-store` to record optimization recommendations in `cost-patterns` namespace
+6. **Search prior optimization patterns** -- call `mcp__claude-flow__agentdb_pattern-search` (ReasoningBank-routed; **don't** pass a `namespace` argument β€” pattern-* tools ignore it).
+7. **Store the optimization pattern** -- two paths:
+ - **Pattern store (typed, recommended)**: `mcp__claude-flow__agentdb_pattern-store` with `type: 'cost-optimization'`. Don't pass a `namespace` arg β€” ReasoningBank routes it; on bridge unavailability the fallback writes to the reserved `pattern` namespace with `controller: 'memory-store-fallback'` (see ruflo-agentdb ADR-0001).
+ - **Plain store (namespace-routable)**: `mcp__claude-flow__memory_store --namespace cost-patterns` β€” this DOES respect the `cost-patterns` namespace because `memory_*` is namespace-routed.
8. **Report** -- display: ranked recommendations with savings estimate, total potential savings, implementation priority (quick wins first)
## CLI alternative
```bash
npx @claude-flow/cli@latest memory search --query "cost optimization strategies" --namespace cost-patterns
+npx @claude-flow/cli@latest memory store --key "opt-2026-05-04" --value '{...}' --namespace cost-patterns
```
diff --git a/plugins/ruflo-cost-tracker/skills/cost-report/SKILL.md b/plugins/ruflo-cost-tracker/skills/cost-report/SKILL.md
index 87401fc195..023d92fea8 100644
--- a/plugins/ruflo-cost-tracker/skills/cost-report/SKILL.md
+++ b/plugins/ruflo-cost-tracker/skills/cost-report/SKILL.md
@@ -2,7 +2,7 @@
name: cost-report
description: Generate a cost report showing token usage and USD costs by agent and model
argument-hint: "[--period today]"
-allowed-tools: mcp__claude-flow__agentdb_hierarchical-recall mcp__claude-flow__agentdb_semantic-route mcp__claude-flow__agentdb_pattern-search Bash
+allowed-tools: mcp__claude-flow__memory_search mcp__claude-flow__memory_list mcp__claude-flow__memory_retrieve mcp__claude-flow__agentdb_pattern-search mcp__claude-flow__agentdb_semantic-route Bash
---
# Cost Report
@@ -15,7 +15,7 @@ When you need to understand current spending -- how much each agent costs, which
## Steps
-1. **Retrieve usage** -- call `mcp__claude-flow__agentdb_hierarchical-recall` to fetch token usage records from the `cost-tracking` namespace for the specified period (default: today)
+1. **Retrieve usage** -- call `mcp__claude-flow__memory_search` (or `_list` / `_retrieve`) on the `cost-tracking` namespace for the specified period (default: today). The `memory_*` tools route by namespace string; the `agentdb_hierarchical-*` tools do **not** (they route by tier `working|episodic|semantic`), so don't use them here. See [ruflo-agentdb ADR-0001 Β§"Namespace convention"](../../../ruflo-agentdb/docs/adrs/0001-agentdb-optimization.md) for the routing contract.
2. **Compute costs** -- for each record, calculate cost using model pricing:
- Haiku: $0.25/M input, $1.25/M output
- Sonnet: $3.00/M input, $15.00/M output
@@ -23,11 +23,12 @@ When you need to understand current spending -- how much each agent costs, which
- Include cache write/read costs where applicable
3. **Aggregate by model** -- sum costs per model, compute percentage share
4. **Aggregate by agent** -- sum costs per agent, include the model each agent used
-5. **Check budget** -- recall budget configuration and compute utilization percentage, check alert thresholds (50%/75%/90%/100%)
+5. **Check budget** -- recall budget configuration via `memory_retrieve` and compute utilization percentage, check alert thresholds (50%/75%/90%/100%)
6. **Report** -- display: total cost, budget remaining, model breakdown, agent breakdown, active alerts
## CLI alternative
```bash
npx @claude-flow/cli@latest memory search --query "cost report for today" --namespace cost-tracking
+npx @claude-flow/cli@latest memory list --namespace cost-tracking
```