π 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
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.jsonindex 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.mdindex 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```bashbash 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 benchdiff --git a/plugins/ruflo-cost-tracker/scripts/smoke.sh b/plugins/ruflo-cost-tracker/scripts/smoke.shindex 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'"elsemiss=""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; dof="$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.mjsnew file mode 100755index 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.mdnew file mode 100644index 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