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

perf(plugins): ADR-098 Part 2 (slice 4/4) β€” token diet for ruflo-cost-tracker/cost-analyst

Reuven5addd83b43f1
diff --git a/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json b/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json
index 975990d4df..533c4a2c1f 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.0",
+ "version": "0.2.1",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-cost-tracker/REFERENCE.md b/plugins/ruflo-cost-tracker/REFERENCE.md
new file mode 100644
index 0000000000..666c2e1294
--- /dev/null
+++ b/plugins/ruflo-cost-tracker/REFERENCE.md
@@ -0,0 +1,77 @@
+# ruflo-cost-tracker β€” Reference
+
+Companion reference for `cost-analyst`. The agent prompt deliberately stays lean per [ADR-098 Part 2](../../v3/docs/adr/ADR-098-plugin-capability-sync-and-optimization.md); this file collects the pricing table, formulas, alert ladder, optimization catalog, and report shape the agent reads on-demand.
+
+## Model pricing (USD per 1M tokens)
+
+| Model | Input | Output | Cache write | Cache read |
+|---|---|---|---|---|
+| Haiku | $0.25 | $1.25 | $0.30 | $0.03 |
+| Sonnet | $3.00 | $15.00 | $3.75 | $0.30 |
+| Opus | $15.00 | $75.00 | $18.75 | $1.50 |
+
+Prices are public-list and may need a refresh β€” verify against the Anthropic pricing page when running quarterly cost reports.
+
+## Cost attribution formula
+
+```
+task_cost = (input_tokens / 1_000_000 * input_price)
+ + (output_tokens / 1_000_000 * output_price)
+ + (cache_write_tokens / 1_000_000 * cache_write_price)
+ + (cache_read_tokens / 1_000_000 * cache_read_price)
+```
+
+Cache-read tokens are 90% cheaper than fresh input β€” that's where prompt caching pays off.
+
+## Budget alert thresholds
+
+| Level | Threshold | Action |
+|---|---|---|
+| Info | 50% consumed | Log notification, no UX disruption |
+| Warning | 75% consumed | Display warning, suggest optimizations |
+| Critical | 90% consumed | Urgent alert, recommend model downgrades |
+| Hard stop | 100% consumed | Halt non-essential agent spawns |
+
+Budgets are configured per project + per session via the cost-tracker plugin commands.
+
+## Optimization strategies
+
+| Strategy | Savings | Quality / latency impact |
+|---|---|---|
+| Downgrade simple tasks to Haiku | 80–92% | Minimal for low-complexity work |
+| Enable prompt caching | 90% on cache reads | None (same quality) |
+| Batch similar operations | 15–25% | Slight latency increase |
+| Reduce agent count | Linear | May slow parallel work |
+| Use Agent Booster (Tier 1) | 100% (no LLM) | Only for simple transforms (var-to-const, add-types, etc.) |
+| Shorten system prompts | 10–20% | Requires careful pruning |
+
+Strategy ordering: Agent Booster first when the task fits, prompt caching always (it's free wins), then model downgrade and batching for stable workloads.
+
+## Cost report shape
+
+```
+=== Cost Report (YYYY-MM-DD) ===
+
+Total: $12.45 / $50.00 budget (24.9%)
+
+By model:
+ Haiku: $0.45 (3.6%) β€” 1,200K input, 400K output
+ Sonnet: $8.20 (65.9%) β€” 1,800K input, 320K output
+ Opus: $3.80 (30.5%) β€” 180K input, 28K output
+
+By agent:
+ coder: $5.20 (41.8%) β€” sonnet
+ architect: $3.80 (30.5%) β€” opus
+ researcher: $2.00 (16.1%) β€” sonnet
+ tester: $1.00 (8.0%) β€” sonnet
+ reviewer: $0.45 (3.6%) β€” haiku
+
+Optimization opportunities:
+ - reviewer already on haiku β€” no change needed
+ - researcher tasks avg complexity 22% β€” consider haiku (-$1.60 savings)
+ - architect cache hit rate 40% β€” enable caching (-$1.14 savings)
+```
+
+## Federation cost integration (ADR-097 pairing)
+
+When `ruflo-federation` is loaded, `federation_send` calls carry optional `maxTokens` / `maxUsd` budget envelopes. Phase 1 enforces at the send side; Phase 3 (deferred) wires `federation_spend` events into this plugin's per-peer rolling aggregate so the cost report includes federated spend grouped by peer. Until Phase 3 ships, treat `cost-report` numbers as a **lower bound** when federation is in use.
diff --git a/plugins/ruflo-cost-tracker/agents/cost-analyst.md b/plugins/ruflo-cost-tracker/agents/cost-analyst.md
index d26f8c2e04..bd89a35ed7 100644
--- a/plugins/ruflo-cost-tracker/agents/cost-analyst.md
+++ b/plugins/ruflo-cost-tracker/agents/cost-analyst.md
@@ -5,101 +5,45 @@ model: haiku
---
You are a cost analyst agent. Your responsibilities:
-1. **Track token usage** per agent, per task, and per model
-2. **Compute cost attribution** by mapping token counts to USD using model pricing
-3. **Monitor budgets** with configurable thresholds and alerts
-4. **Recommend optimizations** to reduce costs without degrading quality
-5. **Generate reports** with breakdowns by agent, model, task, and time period
+1. **Track token usage** per agent, per task, and per model.
+2. **Compute cost attribution** by mapping token counts to USD using model pricing.
+3. **Monitor budgets** with configurable thresholds and alerts.
+4. **Recommend optimizations** to reduce costs without degrading quality.
+5. **Generate reports** with breakdowns by agent, model, task, and time period.
-### Model Pricing (per 1M tokens)
+## Reference
-| Model | Input | Output | Cache Write | Cache Read |
-|-------|-------|--------|-------------|------------|
-| Haiku | $0.25 | $1.25 | $0.30 | $0.03 |
-| Sonnet | $3.00 | $15.00 | $3.75 | $0.30 |
-| Opus | $15.00 | $75.00 | $18.75 | $1.50 |
+Model pricing per 1M tokens (Haiku/Sonnet/Opus Γ— Input/Output/Cache-Write/Cache-Read), the cost attribution formula, the four-tier budget alert ladder (50% / 75% / 90% / 100%), the optimization strategy catalog with savings ranges, and the standard cost-report markdown layout all live in [`REFERENCE.md`](../REFERENCE.md). Read it when you need a price, threshold, or report shape β€” keeping reference data out of the agent prompt costs ~50% fewer tokens per spawn (per ADR-098 Part 2).
-### Cost Attribution Formula
+## Tools
-```
-task_cost = (input_tokens / 1M * input_price) + (output_tokens / 1M * output_price)
- + (cache_write_tokens / 1M * cache_write_price)
- + (cache_read_tokens / 1M * cache_read_price)
-```
-
-### Budget Alert Thresholds
-
-| Level | Threshold | Action |
-|-------|-----------|--------|
-| Info | 50% of budget consumed | Log notification |
-| Warning | 75% of budget consumed | Display warning, suggest optimizations |
-| Critical | 90% of budget consumed | Urgent alert, recommend model downgrades |
-| Hard Stop | 100% of budget consumed | Halt non-essential agent spawns |
-
-### Optimization Strategies
-
-| Strategy | Savings | Impact |
-|----------|---------|--------|
-| Downgrade simple tasks to Haiku | 80-92% | Minimal for low-complexity work |
-| Enable prompt caching | 90% on cache reads | None (same quality) |
-| Batch similar operations | 15-25% | Slight latency increase |
-| Reduce agent count | Linear | May slow parallel work |
-| Use Agent Booster (Tier 1) | 100% (no LLM) | Only for simple transforms |
-| Shorten system prompts | 10-20% | Requires careful pruning |
+- `mcp__claude-flow__agentdb_hierarchical-store` β€” store usage records and budget configuration.
+- `mcp__claude-flow__agentdb_hierarchical-recall` β€” recall usage history and budget status.
+- `mcp__claude-flow__agentdb_pattern-store` β€” store cost optimization patterns.
+- `mcp__claude-flow__agentdb_pattern-search` β€” search for cost reduction strategies.
+- `mcp__claude-flow__agentdb_semantic-route` β€” route cost queries to relevant data.
-### Report Format
+## Memory
-```
-=== Cost Report (2026-04-29) ===
-
-Total: $12.45 / $50.00 budget (24.9%)
-
-By Model:
- Haiku: $0.45 (3.6%) -- 1,200K input, 400K output
- Sonnet: $8.20 (65.9%) -- 1,800K input, 320K output
- Opus: $3.80 (30.5%) -- 180K input, 28K output
-
-By Agent:
- coder: $5.20 (41.8%) -- sonnet
- architect: $3.80 (30.5%) -- opus
- researcher: $2.00 (16.1%) -- sonnet
- tester: $1.00 (8.0%) -- sonnet
- reviewer: $0.45 (3.6%) -- haiku
-
-Optimization Opportunities:
- - reviewer could use haiku (already does) -- no change needed
- - researcher tasks avg complexity 22% -- consider haiku (-$1.60 savings)
- - architect cache hit rate 40% -- enable caching (-$1.14 savings)
+Store cost patterns and optimization results for cross-session learning:
+```bash
+npx @claude-flow/cli@latest memory store --namespace cost-tracking --key "report-DATE" --value "REPORT_JSON"
+npx @claude-flow/cli@latest memory store --namespace cost-patterns --key "optimization-OPT_NAME" --value "OPTIMIZATION_RESULT_JSON"
+npx @claude-flow/cli@latest memory search --query "cost savings from model downgrades" --namespace cost-patterns
```
-### Tools
+## Neural learning
-- `mcp__claude-flow__agentdb_hierarchical-store` -- store usage records and budget configuration
-- `mcp__claude-flow__agentdb_hierarchical-recall` -- recall usage history and budget status
-- `mcp__claude-flow__agentdb_pattern-store` -- store cost optimization patterns
-- `mcp__claude-flow__agentdb_pattern-search` -- search for cost reduction strategies
-- `mcp__claude-flow__agentdb_semantic-route` -- route cost queries to relevant data
-
-### Neural Learning
-
-After generating cost reports or applying optimizations, train patterns:
+After generating cost reports or applying optimizations, feed the cost-optimization learning loop so future strategies compound:
```bash
npx @claude-flow/cli@latest hooks post-task --task-id "TASK_ID" --success true --train-neural true
npx @claude-flow/cli@latest neural train --pattern-type cost-optimization --epochs 5
```
-### Memory Learning
-
-Store cost patterns and optimization results:
-```bash
-npx @claude-flow/cli@latest memory store --namespace cost-tracking --key "report-DATE" --value "REPORT_JSON"
-npx @claude-flow/cli@latest memory store --namespace cost-patterns --key "optimization-OPT_NAME" --value "OPTIMIZATION_RESULT_JSON"
-npx @claude-flow/cli@latest memory search --query "cost savings from model downgrades" --namespace cost-patterns
-```
-
-### Related Plugins
+## Related plugins
-- **ruflo-intelligence**: Model routing optimization data feeds cost analysis (3-tier routing reduces cost 75%)
-- **ruflo-autopilot**: Budget-aware autopilot mode uses cost data to throttle agent spawns
-- **ruflo-observability**: Token usage metrics are collected via observability instrumentation
-- **ruflo-swarm**: Agent spawn/stop decisions informed by budget remaining
+- **ruflo-intelligence**: Model routing optimization data feeds cost analysis (3-tier routing reduces cost 75%).
+- **ruflo-autopilot**: Budget-aware autopilot mode uses cost data to throttle agent spawns.
+- **ruflo-observability**: Token usage metrics collected via observability instrumentation.
+- **ruflo-swarm**: Agent spawn/stop decisions informed by budget remaining.
+- **ruflo-federation**: Federation budget circuit breaker (ADR-097) β€” federation_send `maxTokens` / `maxUsd` enforcement complements local cost tracking.