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

feat(cost-tracker): P9 β€” programmatic cost-summary contract (v0.15.0)

Reuven129a6b405fd8
diff --git a/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json b/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json
index 01641160d4..383d2f6ae9 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 β€” uses memory_* (namespace-routed) for cost-tracking and cost-patterns; pairs with federation budget circuit breaker (ADR-097)",
- "version": "0.14.0",
+ "version": "0.15.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -30,6 +30,7 @@
"ci",
"prometheus",
"observability",
- "federation"
+ "federation",
+ "interop"
]
}
diff --git a/plugins/ruflo-cost-tracker/README.md b/plugins/ruflo-cost-tracker/README.md
index 574a5981ee..cdeb855b33 100644
--- a/plugins/ruflo-cost-tracker/README.md
+++ b/plugins/ruflo-cost-tracker/README.md
@@ -133,7 +133,7 @@ Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadow
```bash
bash plugins/ruflo-cost-tracker/scripts/smoke.sh
-# Expected: "40 passed, 0 failed"
+# Expected: "44 passed, 0 failed"
CI: see [`.github/workflows/cost-tracker-smoke.yml`](../../.github/workflows/cost-tracker-smoke.yml).
On every PR touching this plugin, GitHub Actions runs smoke + booster-only bench
diff --git a/plugins/ruflo-cost-tracker/scripts/smoke.sh b/plugins/ruflo-cost-tracker/scripts/smoke.sh
index 08dff5720b..ce94956767 100755
--- a/plugins/ruflo-cost-tracker/scripts/smoke.sh
+++ b/plugins/ruflo-cost-tracker/scripts/smoke.sh
@@ -8,10 +8,10 @@ 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.14.0 with new keywords"
+step "1. plugin.json declares 0.15.0 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.14.0" ]]; then
- bad "expected 0.14.0, got '$v'"
+if [[ "$v" != "0.15.0" ]]; then
+ bad "expected 0.15.0, got '$v'"
else
miss=""
for k in namespace-routing mcp agentic-flow agent-booster tier1-routing model-routing benchmarking verified telemetry budget; do
@@ -20,9 +20,9 @@ else
[[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
fi
-step "2. all twelve skills present with valid frontmatter"
+step "2. all thirteen skills present with valid frontmatter"
miss=""
-for s in cost-report cost-optimize cost-booster-route cost-booster-edit cost-compact-context cost-benchmark cost-track cost-budget-check cost-trend cost-conversation cost-export cost-federation; do
+for s in cost-report cost-optimize cost-booster-route cost-booster-edit cost-compact-context cost-benchmark cost-track cost-budget-check cost-trend cost-conversation cost-export cost-federation cost-summary; do
f="$ROOT/skills/$s/SKILL.md"
[[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }
for k in 'name:' 'description:' 'allowed-tools:'; do
@@ -321,6 +321,21 @@ step "39. ruflo-cost.md documents 'cost trend' subcommand"
grep -q "cost trend" "$ROOT/commands/ruflo-cost.md" \
&& ok || bad "missing"
+step "39c. cost-summary skill + summary.mjs (programmatic dump)"
+F1="$ROOT/scripts/summary.mjs"
+F2="$ROOT/skills/cost-summary/SKILL.md"
+miss=""
+[[ -x "$F1" ]] || miss="$miss summary-not-executable"
+node --check "$F1" 2>/dev/null || miss="$miss syntax-error"
+grep -q "total_cost_usd" "$F1" || miss="$miss no-headline-metric"
+grep -qE "byTier|byModel" "$F1" || miss="$miss no-aggregation"
+grep -q "alertLevel" "$F1" || miss="$miss no-alert-level"
+[[ -f "$F2" ]] || miss="$miss skill-missing"
+grep -q "summary\.mjs" "$F2" || miss="$miss skill-no-script-ref"
+grep -qE "stable|contract|JSON" "$F2" || miss="$miss no-contract-doc"
+grep -q '^allowed-tools:[[:space:]]*\*' "$F2" && miss="$miss wildcard"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
step "39b. cost-federation skill + federation.mjs (ADR-097 Phase 3 consumer)"
F1="$ROOT/scripts/federation.mjs"
F2="$ROOT/skills/cost-federation/SKILL.md"
diff --git a/plugins/ruflo-cost-tracker/scripts/summary.mjs b/plugins/ruflo-cost-tracker/scripts/summary.mjs
new file mode 100755
index 0000000000..d9705c12b4
--- /dev/null
+++ b/plugins/ruflo-cost-tracker/scripts/summary.mjs
@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// cost-summary β€” programmatic single-shot dump of all cost-tracking data.
+// Other plugins / scripts can shell out: `node summary.mjs --format json` and
+// parse the result. This is the plugin-local equivalent of the MCP tool
+// `cost_summary` that ADR-0002 considered but explicitly deferred (would
+// require modifying @claude-flow/cli source β€” out of scope for this plugin).
+//
+// Output (JSON shape β€” stable contract for consumers):
+// {
+// exportedAt: ISO,
+// total_cost_usd: number,
+// sessionCount: number,
+// conversationCount: number, // alias of sessionCount
+// byTier: { haiku, sonnet, opus, unknown }: USD,
+// byModel: { <model>: { tier, cost_usd, messages, ... } },
+// topSession: { sessionId, total_cost_usd, messageCount },
+// budget: null | { budget_usd, setAt, utilization, level },
+// federation: { eventCount, peerCount, totalUsd24h }
+// }
+//
+// Markdown form is also available (--format markdown, the default).
+
+import { spawnSync } from 'node:child_process';
+
+const NS = process.env.SUMMARY_NAMESPACE || 'cost-tracking';
+const FED_NS = process.env.SUMMARY_FED_NAMESPACE || 'federation-spend';
+
+function memoryListKeys(ns) {
+ const r = spawnSync('npx', [
+ '@claude-flow/cli@latest', 'memory', 'list',
+ '--namespace', ns, '--format', 'json',
+ ], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
+ if (r.status !== 0) return [];
+ const m = /\[[\s\S]*\]/.exec(r.stdout || '');
+ if (!m) return [];
+ try { return JSON.parse(m[0]).map((e) => e.key).filter(Boolean); } catch { return []; }
+}
+function memoryRetrieve(ns, key) {
+ const r = spawnSync('npx', [
+ '@claude-flow/cli@latest', 'memory', 'retrieve',
+ '--namespace', ns, '--key', key,
+ ], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
+ if (r.status !== 0) return null;
+ const m = /\{[\s\S]*\}/.exec(r.stdout || '');
+ if (!m) return null;
+ try { return JSON.parse(m[0]); } catch { return null; }
+}
+
+function alertLevel(util) {
+ if (util >= 1.00) return 'HARD_STOP';
+ if (util >= 0.90) return 'CRITICAL';
+ if (util >= 0.75) return 'WARNING';
+ if (util >= 0.50) return 'INFO';
+ return 'OK';
+}
+
+function gather() {
+ const ctKeys = memoryListKeys(NS);
+ const sessions = ctKeys.filter((k) => k.startsWith('session-'))
+ .map((k) => memoryRetrieve(NS, k)).filter(Boolean);
+
+ const totalUsd = sessions.reduce((s, r) => s + (r.total_cost_usd || 0), 0);
+ const byTier = { haiku: 0, sonnet: 0, opus: 0, unknown: 0 };
+ const byModel = {};
+ for (const r of sessions) {
+ if (r.byTier) for (const [t, v] of Object.entries(r.byTier)) byTier[t] = (byTier[t] || 0) + v;
+ if (r.byModel) {
+ for (const [m, slot] of Object.entries(r.byModel)) {
+ const agg = byModel[m] || { tier: slot.tier, cost_usd: 0, messages: 0,
+ input_tokens: 0, output_tokens: 0, cache_creation_input_tokens: 0, cache_read_input_tokens: 0 };
+ agg.cost_usd += slot.cost_usd || 0;
+ agg.messages += slot.messages || 0;
+ agg.input_tokens += slot.input_tokens || 0;
+ agg.output_tokens += slot.output_tokens || 0;
+ agg.cache_creation_input_tokens += slot.cache_creation_input_tokens || 0;
+ agg.cache_read_input_tokens += slot.cache_read_input_tokens || 0;
+ byModel[m] = agg;
+ }
+ }
+ }
+
+ const topSession = sessions.slice().sort((a, b) => (b.total_cost_usd || 0) - (a.total_cost_usd || 0))[0];
+
+ // Resolve current budget (latest budget-config-<ts>)
+ const budgetKey = ctKeys.filter((k) => /^budget-config(-\d+)?$/.test(k)).sort().reverse()[0];
+ const budgetCfg = budgetKey ? memoryRetrieve(NS, budgetKey) : null;
+ const budget = budgetCfg ? {
+ budget_usd: budgetCfg.budget_usd,
+ setAt: budgetCfg.setAt,
+ spent_usd: totalUsd,
+ utilization: budgetCfg.budget_usd > 0 ? totalUsd / budgetCfg.budget_usd : 0,
+ level: budgetCfg.budget_usd > 0 ? alertLevel(totalUsd / budgetCfg.budget_usd) : 'OK',
+ } : null;
+
+ // Federation aggregate
+ const fedKeys = memoryListKeys(FED_NS);
+ const fedEvents = fedKeys.filter((k) => k.startsWith('fed-spend-'))
+ .map((k) => memoryRetrieve(FED_NS, k)).filter(Boolean);
+ const peers = new Set(fedEvents.map((e) => e.peerId).filter(Boolean));
+ const now = Date.now();
+ const day = 24 * 3600 * 1000;
+ const totalUsd24h = fedEvents.reduce((s, e) => {
+ const ts = e.ts ? new Date(e.ts).getTime() : 0;
+ return s + (ts && now - ts < day ? (e.usdSpent || 0) : 0);
+ }, 0);
+
+ return {
+ exportedAt: new Date().toISOString(),
+ total_cost_usd: totalUsd,
+ sessionCount: sessions.length,
+ conversationCount: sessions.length,
+ byTier,
+ byModel,
+ topSession: topSession ? {
+ sessionId: topSession.sessionId,
+ total_cost_usd: topSession.total_cost_usd,
+ messageCount: topSession.messageCount,
+ } : null,
+ budget,
+ federation: {
+ eventCount: fedEvents.length,
+ peerCount: peers.size,
+ totalUsd24h,
+ },
+ };
+}
+
+function fmtUsd(n) { return `$${(n || 0).toFixed(4)}`; }
+
+function asMarkdown(s) {
+ const lines = [];
+ lines.push(`# cost-summary (${s.exportedAt})`);
+ lines.push('');
+ lines.push(`| Metric | Value |`);
+ lines.push(`|---|---:|`);
+ lines.push(`| Total measured spend | **${fmtUsd(s.total_cost_usd)}** |`);
+ lines.push(`| Conversations / sessions | ${s.sessionCount} |`);
+ if (s.budget) {
+ lines.push(`| Budget | ${fmtUsd(s.budget.budget_usd)} |`);
+ lines.push(`| Utilization | ${(s.budget.utilization * 100).toFixed(1)}% (${s.budget.level}) |`);
+ } else {
+ lines.push(`| Budget | unset |`);
+ }
+ lines.push(`| Federation events | ${s.federation.eventCount} (${s.federation.peerCount} peers, 24h ${fmtUsd(s.federation.totalUsd24h)}) |`);
+ lines.push('');
+ lines.push(`## By tier`);
+ lines.push('');
+ lines.push('| Tier | Cost |');
+ lines.push('|---|---:|');
+ for (const [t, c] of Object.entries(s.byTier)) {
+ if (c > 0) lines.push(`| ${t} | ${fmtUsd(c)} |`);
+ }
+ lines.push('');
+ if (s.topSession) {
+ lines.push(`## Top session`);
+ lines.push('');
+ lines.push(`- Session \`${(s.topSession.sessionId || '').slice(0, 8)}\`: ${fmtUsd(s.topSession.total_cost_usd)} across ${s.topSession.messageCount} messages`);
+ }
+ return lines.join('\n');
+}
+
+function parseFormat() {
+ const args = process.argv.slice(2);
+ for (let i = 0; i < args.length; i++) {
+ if (args[i] === '--format') return args[++i];
+ }
+ return process.env.SUMMARY_FORMAT || 'markdown';
+}
+
+const summary = gather();
+if (parseFormat() === 'json') {
+ console.log(JSON.stringify(summary, null, 2));
+} else {
+ console.log(asMarkdown(summary));
+}
diff --git a/plugins/ruflo-cost-tracker/skills/cost-summary/SKILL.md b/plugins/ruflo-cost-tracker/skills/cost-summary/SKILL.md
new file mode 100644
index 0000000000..77bef6ff89
--- /dev/null
+++ b/plugins/ruflo-cost-tracker/skills/cost-summary/SKILL.md
@@ -0,0 +1,74 @@
+---
+name: cost-summary
+description: Single-shot programmatic dump of all cost data β€” total spend, per-tier, top session, budget status, federation aggregate. JSON or markdown.
+argument-hint: "[--format json|markdown]"
+allowed-tools: Bash
+---
+
+# Cost Summary
+
+A stable single-call interface that other plugins / scripts / dashboards can shell out to and parse. ADR-0002 considered exposing `cost_report` / `cost_summary` as proper MCP tools but **deferred that** β€” adding MCP tools requires modifying `@claude-flow/cli` source, out of scope for plugin-local work. This script is the equivalent: same data, exposed via a stdout JSON contract.
+
+## When to use
+
+- Another plugin needs a snapshot of cost state β€” it shells out to `summary.mjs --format json` and parses.
+- A dashboard / Slackbot fetches a one-line cost rollup.
+- Quick "where am I right now?" view that pulls from every cost-tracker source (cost-tracking + federation-spend).
+
+## Output contract (JSON, stable)
+
+```json
+{
+ "exportedAt": "<ISO>",
+ "total_cost_usd": 1546.36,
+ "sessionCount": 1,
+ "conversationCount": 1,
+ "byTier": { "haiku": 0, "sonnet": 0, "opus": 1546.36, "unknown": 0 },
+ "byModel": {
+ "claude-opus-4-7": {
+ "tier": "opus",
+ "cost_usd": 1546.36,
+ "messages": 1597,
+ "input_tokens": 3090,
+ "output_tokens": 3295940,
+ "cache_creation_input_tokens": 10659599,
+ "cache_read_input_tokens": 732833690
+ }
+ },
+ "topSession": {
+ "sessionId": "1dba3b8c-...",
+ "total_cost_usd": 1546.36,
+ "messageCount": 1597
+ },
+ "budget": {
+ "budget_usd": 2500.00,
+ "setAt": "<ISO>",
+ "spent_usd": 1546.36,
+ "utilization": 0.6185,
+ "level": "INFO"
+ },
+ "federation": {
+ "eventCount": 0,
+ "peerCount": 0,
+ "totalUsd24h": 0
+ }
+}
+```
+
+## Steps
+
+```bash
+# Markdown (default)
+node plugins/ruflo-cost-tracker/scripts/summary.mjs
+
+# JSON for programmatic consumption
+node plugins/ruflo-cost-tracker/scripts/summary.mjs --format json
+```
+
+Optional env: `SUMMARY_NAMESPACE=cost-tracking`, `SUMMARY_FED_NAMESPACE=federation-spend`, `SUMMARY_FORMAT=json`.
+
+## Cross-references
+
+- `cost-report` β€” narrative report (per-agent / per-model lens; uses same data)
+- `cost-export` β€” pushes to Prometheus / webhook (this skill is pull-style; export is push-style)
+- ADR-0002 Β§"Decision" β€” explicitly defers proper MCP-tool registration to a future ADR