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): P1 β€” auto-capture token usage from session jsonl (v0.5.0)

Reuven78f06f62373c
diff --git a/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json b/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json
index c23e0299d1..f4498f9a23 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.4.0",
+ "version": "0.5.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -22,6 +22,7 @@
"tier1-routing",
"model-routing",
"benchmarking",
- "verified"
+ "verified",
+ "telemetry"
]
}
diff --git a/plugins/ruflo-cost-tracker/README.md b/plugins/ruflo-cost-tracker/README.md
index d0bd8f066d..668142ca4b 100644
--- a/plugins/ruflo-cost-tracker/README.md
+++ b/plugins/ruflo-cost-tracker/README.md
@@ -24,14 +24,16 @@ claude --plugin-dir plugins/ruflo-cost-tracker
|-------|-------|-------------|
| `cost-report` | `/cost-report [--period today]` | Generate a cost report with token usage and USD costs by tier, model, and agent |
| `cost-optimize` | `/cost-optimize` | Analyze usage patterns, recommend cost optimizations, and emit `hooks_model-outcome` events |
+| `cost-track` | `/cost-track` | **Auto-capture** per-session token usage from the Claude Code jsonl into `cost-tracking` namespace (producer side) |
| `cost-booster-route` | `/cost-booster-route <task>` | Route tasks via `hooks_route` and report Agent Booster (Tier 1) bypass utilization |
| `cost-booster-edit` | `/cost-booster-edit <intent> <file>` | **Apply** a Tier 1 transform via `agent-booster.apply()` (sub-millisecond, $0, deterministic) |
| `cost-benchmark` | `/cost-benchmark [--llm] [--anthropic]` | Run the corpus benchmark and persist measured-vs-claimed table to `docs/benchmarks/runs/` |
| `cost-compact-context` | `/cost-compact-context <query>` | Wrap `getTokenOptimizer().getCompactContext()` for retrieval-compacted analysis (graceful fallback when agentic-flow not installed) |
-## Commands (7 subcommands)
+## Commands (8 subcommands)
```bash
+cost track # Auto-capture this session's token usage (producer)
cost report [--period today|week|month] # Cost report (with By-tier block, reads measured booster data)
cost breakdown [--by agent|model|task] # Detailed breakdown by dimension
cost budget set <amount> # Set budget limit in USD
@@ -124,7 +126,7 @@ Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadow
```bash
bash plugins/ruflo-cost-tracker/scripts/smoke.sh
-# Expected: "27 passed, 0 failed"
+# Expected: "30 passed, 0 failed"
```
## Architecture Decisions
diff --git a/plugins/ruflo-cost-tracker/commands/ruflo-cost.md b/plugins/ruflo-cost-tracker/commands/ruflo-cost.md
index 710dca9292..9762347181 100644
--- a/plugins/ruflo-cost-tracker/commands/ruflo-cost.md
+++ b/plugins/ruflo-cost-tracker/commands/ruflo-cost.md
@@ -33,6 +33,11 @@ Cost tracking commands:
6. Calculate estimated savings for each recommendation
7. Display: recommendation, current cost, projected cost, savings, impact assessment
+**`cost track`** -- Auto-capture token usage for the active Claude Code session and persist to the `cost-tracking` namespace. Run after significant work or at session end so `cost report` has real data.
+1. Invoke `node plugins/ruflo-cost-tracker/scripts/track.mjs` (no flags = current cwd's most-recent session)
+2. Print: total cost, per-model and per-tier breakdown, persisted memory key
+3. Sets the `cost-tracking` namespace record at key `session-<sessionId>` (consumed by `cost-report` step 1)
+
**`cost benchmark [--llm] [--anthropic]`** -- Run the corpus benchmark to verify booster claims with measured numbers.
1. Without flags: booster-only (free, ~85 ms wall-time, no API keys needed)
2. `--llm`: also run Gemini 2.0 Flash baseline (uses GCP `GOOGLE_AI_API_KEY` secret)
diff --git a/plugins/ruflo-cost-tracker/scripts/smoke.sh b/plugins/ruflo-cost-tracker/scripts/smoke.sh
index fcd1be16b8..6b5fea8703 100755
--- a/plugins/ruflo-cost-tracker/scripts/smoke.sh
+++ b/plugins/ruflo-cost-tracker/scripts/smoke.sh
@@ -8,21 +8,21 @@ 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.4.0 with new keywords"
+step "1. plugin.json declares 0.5.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.4.0" ]]; then
- bad "expected 0.4.0, got '$v'"
+if [[ "$v" != "0.5.0" ]]; then
+ bad "expected 0.5.0, got '$v'"
else
miss=""
- for k in namespace-routing mcp agentic-flow agent-booster tier1-routing model-routing benchmarking verified; do
+ for k in namespace-routing mcp agentic-flow agent-booster tier1-routing model-routing benchmarking verified telemetry; do
grep -q "\"$k\"" "$ROOT/.claude-plugin/plugin.json" || miss="$miss $k"
done
[[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
fi
-step "2. all six skills present with valid frontmatter"
+step "2. all seven skills present with valid frontmatter"
miss=""
-for s in cost-report cost-optimize cost-booster-route cost-booster-edit cost-compact-context cost-benchmark; do
+for s in cost-report cost-optimize cost-booster-route cost-booster-edit cost-compact-context cost-benchmark cost-track; do
f="$ROOT/skills/$s/SKILL.md"
[[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }
for k in 'name:' 'description:' 'allowed-tools:'; do
@@ -219,5 +219,29 @@ F="$ROOT/skills/cost-report/SKILL.md"
grep -qE 'runs/latest\.json|measured booster|measured.*Tier' "$F" \
&& ok || bad "cost-report does not consume bench output"
+step "28. cost-track skill exists, references session jsonl + memory_store"
+F="$ROOT/skills/cost-track/SKILL.md"
+miss=""
+[[ -f "$F" ]] || miss="$miss missing-file"
+grep -qE '\.claude/projects|session.*jsonl|jsonl' "$F" || miss="$miss session-ref"
+grep -qE 'memory_store|memory store' "$F" || miss="$miss memory-store"
+grep -q 'cost-tracking' "$F" || miss="$miss namespace"
+grep -q '^allowed-tools:[[:space:]]*\*' "$F" && miss="$miss wildcard"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "29. track.mjs harness present + parses + uses spawnSync (no shell-escape risks)"
+F="$ROOT/scripts/track.mjs"
+miss=""
+[[ -x "$F" ]] || miss="$miss not-executable"
+node --check "$F" 2>/dev/null || miss="$miss syntax-error"
+grep -q "spawnSync" "$F" || miss="$miss no-spawnSync"
+grep -q "PRICING" "$F" || miss="$miss no-pricing-table"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+step "30. ruflo-cost.md documents 'cost track' subcommand"
+F="$ROOT/commands/ruflo-cost.md"
+grep -qE "cost track" "$F" && grep -qE "session.*jsonl|track\.mjs" "$F" \
+ && ok || bad "missing cost-track subcommand or session-source ref"
+
printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
[[ $FAIL -eq 0 ]] || exit 1
diff --git a/plugins/ruflo-cost-tracker/scripts/track.mjs b/plugins/ruflo-cost-tracker/scripts/track.mjs
new file mode 100755
index 0000000000..995e786721
--- /dev/null
+++ b/plugins/ruflo-cost-tracker/scripts/track.mjs
@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// cost-track β€” auto-capture token usage from a Claude Code session jsonl
+// and persist a structured record to the `cost-tracking` AgentDB namespace.
+//
+// Resolution: by default reads the most-recently-modified session jsonl in
+// ~/.claude/projects/<encoded-cwd>/. Override with TRACK_CWD or TRACK_SESSION.
+//
+// Optional env:
+// TRACK_CWD=<path> override which project's sessions to scan
+// TRACK_SESSION=<file> pin to a specific session jsonl
+// TRACK_OUT=<path> also write the JSON summary to this path
+// TRACK_DRY_RUN=1 skip the memory_store call
+// TRACK_QUIET=1 suppress markdown summary
+// TRACK_NAMESPACE=<name> override (default: cost-tracking)
+
+import { readFileSync, writeFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+
+const PROJECTS_DIR = join(homedir(), '.claude', 'projects');
+
+// USD per 1M tokens β€” kept in sync with REFERENCE.md "Model pricing" table.
+const PRICING = {
+ haiku: { input: 0.25, output: 1.25, cache_write: 0.30, cache_read: 0.03 },
+ sonnet: { input: 3.00, output: 15.00, cache_write: 3.75, cache_read: 0.30 },
+ opus: { input: 15.00, output: 75.00, cache_write: 18.75, cache_read: 1.50 },
+};
+
+function modelTier(model) {
+ if (!model) return 'unknown';
+ const m = String(model).toLowerCase();
+ if (m.includes('haiku')) return 'haiku';
+ if (m.includes('sonnet')) return 'sonnet';
+ if (m.includes('opus')) return 'opus';
+ return 'unknown';
+}
+
+function costForUsage(tier, usage) {
+ const p = PRICING[tier];
+ if (!p || !usage) return 0;
+ return (usage.input_tokens || 0) / 1e6 * p.input
+ + (usage.output_tokens || 0) / 1e6 * p.output
+ + (usage.cache_creation_input_tokens || 0) / 1e6 * p.cache_write
+ + (usage.cache_read_input_tokens || 0) / 1e6 * p.cache_read;
+}
+
+function encodeProjectPath(cwd) {
+ // Claude Code encodes absolute path by replacing `/` with `-`.
+ return cwd.replace(/\//g, '-');
+}
+
+function findProjectDir(cwd) {
+ const candidate = join(PROJECTS_DIR, encodeProjectPath(cwd));
+ return existsSync(candidate) ? candidate : null;
+}
+
+function findActiveSession(projectDir) {
+ const entries = readdirSync(projectDir)
+ .filter((f) => f.endsWith('.jsonl'))
+ .map((f) => ({ f, mtime: statSync(join(projectDir, f)).mtimeMs }))
+ .sort((a, b) => b.mtime - a.mtime);
+ return entries[0] ? join(projectDir, entries[0].f) : null;
+}
+
+function summarizeSession(jsonlPath) {
+ const text = readFileSync(jsonlPath, 'utf-8');
+ const lines = text.split('\n').filter(Boolean);
+ const byModel = {};
+ const byTier = { haiku: 0, sonnet: 0, opus: 0, unknown: 0 };
+ let messageCount = 0, totalCost = 0;
+ let firstTs = null, lastTs = null;
+ let sessionId = null, cwd = null;
+
+ for (const line of lines) {
+ let m;
+ try { m = JSON.parse(line); } catch { continue; }
+ if (!sessionId && m.sessionId) sessionId = m.sessionId;
+ if (!cwd && m.cwd) cwd = m.cwd;
+ if (m.timestamp) {
+ if (!firstTs || m.timestamp < firstTs) firstTs = m.timestamp;
+ if (!lastTs || m.timestamp > lastTs) lastTs = m.timestamp;
+ }
+ if (m.type !== 'assistant' || !m.message?.usage) continue;
+ messageCount++;
+ const model = m.message.model || 'unknown';
+ const tier = modelTier(model);
+ const u = m.message.usage;
+ const cost = costForUsage(tier, u);
+ const slot = byModel[model] || {
+ tier,
+ input_tokens: 0, output_tokens: 0,
+ cache_creation_input_tokens: 0, cache_read_input_tokens: 0,
+ messages: 0, cost_usd: 0,
+ };
+ slot.input_tokens += u.input_tokens || 0;
+ slot.output_tokens += u.output_tokens || 0;
+ slot.cache_creation_input_tokens += u.cache_creation_input_tokens || 0;
+ slot.cache_read_input_tokens += u.cache_read_input_tokens || 0;
+ slot.messages++;
+ slot.cost_usd += cost;
+ byModel[model] = slot;
+ byTier[tier] += cost;
+ totalCost += cost;
+ }
+
+ return {
+ sessionId, cwd, startedAt: firstTs, endedAt: lastTs,
+ messageCount, byModel, byTier, total_cost_usd: totalCost,
+ capturedAt: new Date().toISOString(),
+ };
+}
+
+function persistToMemory(summary) {
+ const ns = process.env.TRACK_NAMESPACE || 'cost-tracking';
+ const key = `session-${summary.sessionId || 'unknown'}`;
+ // spawnSync with explicit args avoids shell-escape pitfalls for the JSON value.
+ const r = spawnSync('npx', [
+ '@claude-flow/cli@latest', 'memory', 'store',
+ '--namespace', ns,
+ '--key', key,
+ '--value', JSON.stringify(summary),
+ ], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
+ if (r.status !== 0) {
+ return { ok: false, reason: r.stderr?.slice(0, 300) || `exit ${r.status}` };
+ }
+ return { ok: true, namespace: ns, key };
+}
+
+function main() {
+ const targetCwd = process.env.TRACK_CWD || process.cwd();
+ const projectDir = findProjectDir(targetCwd);
+ if (!projectDir) {
+ console.error(`cost-track: no Claude Code project dir for cwd=${targetCwd}`);
+ console.error(`looked under ${PROJECTS_DIR}/${encodeProjectPath(targetCwd)}`);
+ process.exit(2);
+ }
+ const sessionPath = process.env.TRACK_SESSION || findActiveSession(projectDir);
+ if (!sessionPath || !existsSync(sessionPath)) {
+ console.error(`cost-track: no session jsonl in ${projectDir}`);
+ process.exit(2);
+ }
+
+ const summary = summarizeSession(sessionPath);
+
+ if (process.env.TRACK_OUT) {
+ writeFileSync(process.env.TRACK_OUT, JSON.stringify(summary, null, 2));
+ }
+
+ let storeResult = { ok: false, reason: 'dry-run' };
+ if (process.env.TRACK_DRY_RUN !== '1') {
+ storeResult = persistToMemory(summary);
+ }
+
+ if (process.env.TRACK_QUIET === '1') return;
+
+ console.log(`# cost-track β€” session ${(summary.sessionId || '').slice(0, 8) || 'unknown'}`);
+ console.log('');
+ console.log(`| Metric | Value |`);
+ console.log(`|---|---:|`);
+ console.log(`| Session ID | \`${summary.sessionId}\` |`);
+ console.log(`| Project | \`${summary.cwd}\` |`);
+ console.log(`| First message | ${summary.startedAt} |`);
+ console.log(`| Last message | ${summary.endedAt} |`);
+ console.log(`| Assistant messages | ${summary.messageCount} |`);
+ console.log(`| **Total cost** | **$${summary.total_cost_usd.toFixed(6)}** |`);
+ console.log(`| Persisted | ${storeResult.ok ? `\`${storeResult.namespace}:${storeResult.key}\`` : `**FAILED** (${storeResult.reason})`} |`);
+ console.log('');
+ console.log('## Per-model breakdown');
+ console.log('');
+ console.log('| Model | Tier | Messages | Input | Output | Cache write | Cache read | Cost |');
+ console.log('|---|---|---:|---:|---:|---:|---:|---:|');
+ for (const [m, s] of Object.entries(summary.byModel).sort((a, b) => b[1].cost_usd - a[1].cost_usd)) {
+ console.log(`| \`${m}\` | ${s.tier} | ${s.messages} | ${s.input_tokens} | ${s.output_tokens} | ${s.cache_creation_input_tokens} | ${s.cache_read_input_tokens} | $${s.cost_usd.toFixed(6)} |`);
+ }
+ console.log('');
+ console.log('## Per-tier breakdown');
+ console.log('');
+ console.log('| Tier | Cost |');
+ console.log('|---|---:|');
+ for (const [t, c] of Object.entries(summary.byTier).sort((a, b) => b[1] - a[1])) {
+ if (c > 0) console.log(`| ${t} | $${c.toFixed(6)} |`);
+ }
+}
+
+main();
diff --git a/plugins/ruflo-cost-tracker/skills/cost-track/SKILL.md b/plugins/ruflo-cost-tracker/skills/cost-track/SKILL.md
new file mode 100644
index 0000000000..f655c1bfe3
--- /dev/null
+++ b/plugins/ruflo-cost-tracker/skills/cost-track/SKILL.md
@@ -0,0 +1,79 @@
+---
+name: cost-track
+description: Auto-capture per-session token usage from the Claude Code session jsonl and persist to the cost-tracking namespace
+argument-hint: ""
+allowed-tools: Bash mcp__claude-flow__memory_store
+---
+
+# Cost Track
+
+Reads the active Claude Code session jsonl (`~/.claude/projects/<encoded-cwd>/<session>.jsonl`), tallies assistant-message `usage` per model, computes USD cost using REFERENCE.md pricing, and writes a structured record to the `cost-tracking` AgentDB namespace. This is the **producer** that gives `cost-report` and `cost-optimize` real data to consume.
+
+## When to use
+
+- After a meaningful chunk of work, to capture spend for the report.
+- At session-end to persist the final tally.
+- Periodically during long sessions (cron-friendly β€” see `/loop 30m`).
+
+## Steps
+
+1. **Run the tracker** from the project root:
+
+ ```bash
+ node plugins/ruflo-cost-tracker/scripts/track.mjs
+ ```
+
+ The script auto-discovers the session jsonl from the current working directory. To pin a specific session: `TRACK_SESSION=/path/to/session.jsonl`. To dry-run (no memory write): `TRACK_DRY_RUN=1`.
+
+2. **Inspect the markdown summary** β€” total cost, per-model and per-tier breakdowns, and the persisted memory key.
+
+3. **Verify persistence** β€” `mcp__claude-flow__memory_search --query "session-" --namespace cost-tracking` should list the new record. `cost-report` step 1 reads from this namespace.
+
+## Record shape (in `cost-tracking` namespace)
+
+Key: `session-<sessionId>`. Value (JSON):
+
+```json
+{
+ "sessionId": "1dba3b8c-...",
+ "cwd": "/Users/cohen/Projects/ruflo",
+ "startedAt": "2026-05-04T...",
+ "endedAt": "2026-05-05T...",
+ "messageCount": 234,
+ "byModel": {
+ "claude-opus-4-7": {
+ "tier": "opus",
+ "input_tokens": 12345,
+ "output_tokens": 6789,
+ "cache_creation_input_tokens": 800000,
+ "cache_read_input_tokens": 2000000,
+ "messages": 50,
+ "cost_usd": 1.23
+ }
+ },
+ "byTier": { "haiku": 0.0, "sonnet": 0.45, "opus": 1.23, "unknown": 0 },
+ "total_cost_usd": 1.68,
+ "capturedAt": "2026-05-05T..."
+}
+```
+
+## Pricing source of truth
+
+The script's `PRICING` constant mirrors REFERENCE.md "Model pricing (USD per 1M tokens)". Update both together when prices change. Cache-write tokens are billed at `cache_write` rate; cache-read tokens at `cache_read` (per Anthropic billing docs).
+
+## Env overrides
+
+| Env | Default | Purpose |
+|---|---|---|
+| `TRACK_CWD` | `process.cwd()` | Override which project's sessions to scan |
+| `TRACK_SESSION` | most-recent jsonl | Pin a specific session file |
+| `TRACK_OUT` | unset | Also write the JSON summary to this path |
+| `TRACK_DRY_RUN=1` | unset | Skip the `memory store` call |
+| `TRACK_QUIET=1` | unset | Suppress markdown output |
+| `TRACK_NAMESPACE` | `cost-tracking` | Override target namespace |
+
+## Cross-references
+
+- `cost-report` (consumer) β€” reads records produced by this skill
+- REFERENCE.md "Cost attribution formula" β€” the math the script implements
+- `cost-budget-check` (consumer; landing in P2) β€” reads totals to evaluate alerts