π 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-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.jsonindex 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.mdindex 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 tighUntil 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.mdnew file mode 100644index 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 envelopediff --git a/plugins/ruflo-cost-tracker/scripts/smoke.sh b/plugins/ruflo-cost-tracker/scripts/smoke.shnew file mode 100755index 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 1diff --git a/plugins/ruflo-cost-tracker/skills/cost-optimize/SKILL.md b/plugins/ruflo-cost-tracker/skills/cost-optimize/SKILL.mdindex 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-optimizedescription: Analyze token usage patterns and recommend cost optimizations with estimated savingsargument-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 risk3. **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 batched5. **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```bashnpx @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.mdindex 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-reportdescription: Generate a cost report showing token usage and USD costs by agent and modelargument-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 applicable3. **Aggregate by model** -- sum costs per model, compute percentage share4. **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```bashnpx @claude-flow/cli@latest memory search --query "cost report for today" --namespace cost-tracking+npx @claude-flow/cli@latest memory list --namespace cost-tracking```