π 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): 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.jsonindex 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.mdindex 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 dimensioncost budget set <amount> # Set budget limit in USD@@ -124,7 +126,7 @@ Reserved namespaces (`pattern`, `claude-memories`, `default`) MUST NOT be shadow```bashbash plugins/ruflo-cost-tracker/scripts/smoke.sh-# Expected: "27 passed, 0 failed"+# Expected: "30 passed, 0 failed"```## Architecture Decisionsdiff --git a/plugins/ruflo-cost-tracker/commands/ruflo-cost.md b/plugins/ruflo-cost-tracker/commands/ruflo-cost.mdindex 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 recommendation7. 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.shindex 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'"elsemiss=""- 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; dogrep -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; dof="$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 1diff --git a/plugins/ruflo-cost-tracker/scripts/track.mjs b/plugins/ruflo-cost-tracker/scripts/track.mjsnew file mode 100755index 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.mdnew file mode 100644index 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