wendkeep 0.9.1 → 0.11.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to **wendkeep** are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.11.0] — 2026-07-06
+
+Vault-wide cost.
+
+### Added
+- **`wendkeep cost`** — aggregate AI-coding spend across every session note in the vault:
+  total (main + subagents), by model, by day. `--since <YYYY-MM-DD>` to window; `--json` for
+  scripting. Builds on the per-session cost the capture hooks already record — on a real
+  project vault it surfaced **~$4.7k across 140 sessions** in one command.
+
+## [0.10.0] — 2026-07-06
+
+Subagent & workflow telemetry — closing the biggest observability gap.
+
+### Added
+- **Subagent + workflow capture:** the Stop hook now scans the session's sibling subagent
+  transcripts (`<session>/subagents/**`) and workflow runs, and folds them into the session
+  note — a new `## Subagents & Workflows` section (aggregate + a collapsible per-subagent
+  table) plus frontmatter fields (`subagents_count`, `subagents_tokens_total`,
+  `subagents_custo_usd`, `tokens_total_incl_subagents`). Reuses the token-usage parser
+  (deduped per request). Previously a session that spawned a Workflow recorded ONLY the main
+  transcript — on a real audit session that hid **12 subagents / 4.6M tokens / $7.59** (2× the
+  main). The main `tokens_total` stays the main agent's (comparable to Claude Code's own
+  display); subagents are a separate axis.
+- Provider-gated by structure (Claude Code's `subagents/` layout); fail-open — never blocks Stop.
+
 ## [0.9.1] — 2026-07-06
 
 Interactive install UX: language first.
@@ -223,6 +249,8 @@ Initial release — the capture engine, extracted from a system in daily product
 - `wendkeep init` (cross-platform installer) + optional `@bitbonsai/mcpvault` MCP server.
 
 <!-- Only v0.4.0+ is tagged in git (history starts here); older versions link to npm. -->
+[0.11.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.11.0
+[0.10.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.10.0
 [0.9.1]: https://github.com/rogersialves/wendkeep/releases/tag/v0.9.1
 [0.9.0]: https://github.com/rogersialves/wendkeep/releases/tag/v0.9.0
 [0.8.1]: https://github.com/rogersialves/wendkeep/releases/tag/v0.8.1

package/README.md

@@ -73,7 +73,8 @@ No re‑copying, no snapshot to re‑sync — the package is the single source o
 | `wendkeep change <sub>` | Change lifecycle: `new [--simple]` / `list` / `show` / `status` / `done <id>` / `undone <id>` / `diff` / `archive [--force]`. |
 | `wendkeep verify [--deep]` | Run the change's task sensors; `--deep` assembles the independent-verification package. |
 | `wendkeep spec <sub>` | Living specs: `list` / `show <capability>`. |
-| `wendkeep sensors list` | Show the sensors from `wendkeep.sensors.json` (JSON Schema included in the package). |
+| `wendkeep sensors <sub>` | `list` / `add <id> "<command>"` — view/edit `wendkeep.sensors.json` (JSON Schema shipped). |
+| `wendkeep cost [--since d]` | Aggregate AI-coding spend across the vault's sessions — total, by model, by day (`--json`). |
 | `wendkeep lesson add "t" "l"` | Record a project-local lesson (injected at the next SessionStart). |
 | `wendkeep sync-defs` | Copy `.brain/agents\|skills` into the project (`.codex/agents`, `.claude/skills`). |
 | `wendkeep validate-memory [path]` | Validate `.brain/CORE.md` (cap 25, 3 sections, no secrets/PII). |

package/bin/wendkeep.mjs

@@ -47,6 +47,7 @@ Usage:
                            done <id> | undone <id> | diff | archive [--force].
   wendkeep spec <sub>          Living specs: list | show <capability>.
   wendkeep sensors <sub>       list | add <id> "<command>" [--severity --type --report].
+  wendkeep cost [--since d]    Aggregate AI-coding spend across the vault's sessions (--json).
   wendkeep verify [--change s] Run a change's task sensors + record evidence (the gate).
   wendkeep lesson add "t" "l"   Record a project-local lesson (injected at SessionStart).
   wendkeep validate-memory [path]  Validate .brain/CORE.md against the compaction
@@ -130,6 +131,11 @@ async function main() {
       runSensors(rest);
       break;
     }
+    case 'cost': {
+      const { runCost } = await import('../src/cost.mjs');
+      runCost(rest);
+      break;
+    }
     case '--version':
     case '-v':
       process.stdout.write(`${version()}\n`);

package/hooks/session-stop.mjs

@@ -8,6 +8,7 @@ import { addUsage, costBreakdown, emptyTokenUsage, normalizeClaudeUsage, normali
 import { buildBrainDigest, buildBrainIndex } from './brain-core.mjs';
 import { activeChangeLink } from './change-core.mjs';
 import { getLocale } from './locale.mjs';
+import { upsertSubagentUsage } from './subagent-usage.mjs';
 import {
   ensureDir,
   findActiveSessionByTranscript,
@@ -1044,6 +1045,14 @@ function main() {
     process.stderr.write(`[codex-obsidian] Token usage falhou: ${error.message}\n`);
   }
 
+  // Subagent/workflow telemetry (0.10.0): fold sibling subagent transcripts into the note.
+  // Provider-gated by structure + fail-open — never derruba o Stop.
+  try {
+    upsertSubagentUsage(sessionPath, transcriptPath);
+  } catch (error) {
+    process.stderr.write(`[codex-obsidian] Subagent usage falhou: ${error.message}\n`);
+  }
+
   if (!shouldFinalizeSession()) {
     writeControl(vaultBase, {
       ...control,

package/hooks/subagent-usage.mjs

@@ -0,0 +1,176 @@
+// hooks/subagent-usage.mjs — capture subagent + workflow telemetry (0.10.0). The Stop hook
+// only reads the MAIN transcript; a session that spawns subagents/workflows (e.g. a Workflow
+// run) burns tokens in sibling transcripts the note never recorded. This scans them.
+// Reuses token-usage.mjs's parser. Provider-gated by structure (Claude Code layout).
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { parseTokenUsageFromTranscript, summarizeTokenUsage } from './token-usage.mjs';
+
+const fmt = (n) => Math.trunc(Number(n) || 0).toString().replace(/\B(?=(\d{3})+(?!\d))/g, '.');
+const usd = (n) => `$${(Number(n) || 0).toFixed(4)}`;
+
+// <slug>/<id>.jsonl (main transcript) -> <slug>/<id>/ (sibling dir with subagents/workflows).
+export function sessionDirFromTranscript(transcriptPath) {
+  return String(transcriptPath || '').replace(/\.jsonl?$/i, '');
+}
+
+function walkAgentJsonl(dir) {
+  const out = [];
+  let names;
+  try { names = readdirSync(dir); } catch { return out; }
+  for (const n of names) {
+    const p = join(dir, n);
+    let st;
+    try { st = statSync(p); } catch { continue; }
+    if (st.isDirectory()) out.push(...walkAgentJsonl(p));
+    else if (n.startsWith('agent-') && n.endsWith('.jsonl')) out.push(p);
+  }
+  return out;
+}
+
+// workflows/scripts/<name>-wf_<rid>.js  ->  { wf_<rid>: <name> }
+function workflowNameMap(sessionDir) {
+  const map = {};
+  let names;
+  try { names = readdirSync(join(sessionDir, 'workflows', 'scripts')); } catch { return map; }
+  for (const n of names) {
+    const m = n.match(/^(.*)-(wf_[a-z0-9-]+)\.js$/i);
+    if (m) map[m[2]] = m[1];
+  }
+  return map;
+}
+
+function runIdOfPath(file) {
+  const m = file.replace(/\\/g, '/').match(/\/(wf_[a-z0-9-]+)\//i);
+  return m ? m[1] : null;
+}
+
+function tokensTotal(t = {}) {
+  return (t.input || 0) + (t.cached || 0) + (t.cacheWrite || 0) + (t.output || 0);
+}
+
+const round4 = (n) => Math.round((Number(n) || 0) * 10000) / 10000;
+
+// Aggregate every subagent transcript under <sessionDir>/subagents. null when the dir is
+// absent (Codex / a session with no subagents) or nothing parseable.
+export function collectSubagentUsage(sessionDir) {
+  const subDir = join(sessionDir, 'subagents');
+  if (!existsSync(subDir)) return null;
+  const files = walkAgentJsonl(subDir);
+  if (!files.length) return null;
+
+  const nameMap = workflowNameMap(sessionDir);
+  const subagents = [];
+  const wf = {};
+  const usageAgg = { input: 0, cached: 0, cacheWrite: 0, output: 0 };
+  let count = 0;
+  let calls = 0;
+  let cost = 0;
+
+  for (const f of files) {
+    const summary = summarizeTokenUsage(parseTokenUsageFromTranscript(f));
+    if (!summary.calls) continue;
+    const runId = runIdOfPath(f);
+    const workflow = runId ? nameMap[runId] || runId : null;
+    let agentType = '';
+    try { agentType = JSON.parse(readFileSync(f.replace(/\.jsonl$/i, '.meta.json'), 'utf8')).agentType || ''; } catch { /* no meta */ }
+    const tokens = tokensTotal(summary.totals);
+
+    subagents.push({
+      id: basename(f).replace(/^agent-/, '').replace(/\.jsonl$/i, '').slice(0, 12),
+      agentType,
+      workflow,
+      model: summary.models[0] || '?',
+      tools: summary.tools.length,
+      calls: summary.calls,
+      tokens,
+      cost: round4(summary.costs.model),
+    });
+
+    count += 1;
+    calls += summary.calls;
+    cost += summary.costs.model;
+    for (const k of Object.keys(usageAgg)) usageAgg[k] += summary.totals[k] || 0;
+    if (runId) {
+      wf[runId] = wf[runId] || { agents: 0, cost: 0 };
+      wf[runId].agents += 1;
+      wf[runId].cost += summary.costs.model;
+    }
+  }
+  if (!count) return null;
+
+  const workflows = Object.entries(wf).map(([runId, v]) => ({
+    runId, name: nameMap[runId] || runId, agents: v.agents, cost: round4(v.cost),
+  }));
+
+  return {
+    subagents,
+    workflows,
+    aggregate: { count, calls, tokens: tokensTotal(usageAgg), cost: round4(cost), usage: usageAgg },
+  };
+}
+
+export function renderSubagentSection(c) {
+  const a = c.aggregate;
+  const wf = c.workflows.length
+    ? c.workflows.map((w) => `${w.name} (${w.runId} · ${w.agents} agentes · ${usd(w.cost)})`).join('; ')
+    : '(nenhum)';
+  const rows = c.subagents
+    .map((s) => `| ${s.id} | ${s.agentType || '-'} | ${s.workflow || '-'} | ${s.model} | ${s.tools} | ${fmt(s.tokens)} | ${usd(s.cost)} |`)
+    .join('\n');
+  return `## Subagents & Workflows
+
+> Custo de subagents/workflows desta sessão — NÃO incluído no total principal acima.
+
+- **Subagents:** ${a.count} · ${a.calls} chamadas · ${fmt(a.tokens)} tokens · ${usd(a.cost)}
+- **Workflows:** ${wf}
+
+<details><summary>Por subagent (${a.count})</summary>
+
+| Agent | Tipo | Workflow | Modelo | Tools | Tokens | Custo |
+|---|---|---|---|---:|---:|---:|
+${rows}
+
+</details>`;
+}
+
+function setFrontmatterField(content, key, value) {
+  const m = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!m) return content;
+  const re = new RegExp(`^${key}:.*$`, 'm');
+  const line = `${key}: ${value}`;
+  const fm = re.test(m[1]) ? m[1].replace(re, line) : `${m[1]}\n${line}`;
+  return content.replace(m[0], `---\n${fm}\n---`);
+}
+
+function frontmatterNumber(content, key) {
+  const m = content.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
+  return m ? Number(String(m[1]).trim().replace(/^["']|["']$/g, '')) || 0 : 0;
+}
+
+function upsertSection(content, heading, body) {
+  const esc = heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`${esc}\\n[\\s\\S]*?(?=\\n## |$)`);
+  if (re.test(content)) return content.replace(re, `${body}\n`);
+  for (const anchor of ['\n## Encerramento', '\n## Issues Linear', '\n## Pendências']) {
+    const i = content.indexOf(anchor);
+    if (i >= 0) return `${content.slice(0, i)}\n\n${body}\n${content.slice(i)}`;
+  }
+  return `${content.trimEnd()}\n\n${body}\n`;
+}
+
+// Stop-hook entry: scan the session's subagents/workflows, fold into the note. Fail-open.
+export function upsertSubagentUsage(sessionPath, transcriptPath) {
+  if (!sessionPath || !existsSync(sessionPath)) return false;
+  const collected = collectSubagentUsage(sessionDirFromTranscript(transcriptPath));
+  if (!collected) return false;
+  const a = collected.aggregate;
+  let content = readFileSync(sessionPath, 'utf8');
+  content = setFrontmatterField(content, 'subagents_count', a.count);
+  content = setFrontmatterField(content, 'subagents_tokens_total', a.tokens);
+  content = setFrontmatterField(content, 'subagents_custo_usd', a.cost);
+  content = setFrontmatterField(content, 'tokens_total_incl_subagents', frontmatterNumber(content, 'tokens_total') + a.tokens);
+  content = upsertSection(content, '## Subagents & Workflows', renderSubagentSection(collected));
+  writeFileSync(sessionPath, content, 'utf8');
+  return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wendkeep",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "A persistent-memory harness for AI coding agents on your Obsidian vault: turn-by-turn session capture plus a native, zero-dependency spec→change→verify→archive loop (sensor-gated, independent verdict, mutation discrimination). Local-first, agent-agnostic (Claude Code, Codex, Cursor…).",
   "type": "module",
   "bin": {

package/src/cost.mjs

@@ -0,0 +1,107 @@
+// `wendkeep cost` — aggregate AI-coding spend across every session note in the vault.
+// Each session note carries cost in its frontmatter (main + subagents since 0.10.0); this
+// rolls the whole vault up: total, by day, by model. Pure aggregation + a thin CLI.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { getLocale } from '../hooks/locale.mjs';
+
+const round4 = (n) => Math.round((Number(n) || 0) * 10000) / 10000;
+const usd = (n) => `$${(Number(n) || 0).toFixed(4)}`;
+
+function fmValue(content, key) {
+  const m = content.match(new RegExp(`^${key}:\\s*(.+)$`, 'm'));
+  return m ? m[1].trim().replace(/^["']|["']$/g, '') : '';
+}
+
+// Parse the cost-relevant frontmatter of one note; null if it is not a session note.
+export function parseSessionCost(content) {
+  if (!/^type:\s*session\s*$/m.test(content)) return null;
+  return {
+    date: (fmValue(content, 'date') || '').slice(0, 10),
+    model: fmValue(content, 'custo_modelo_label') || fmValue(content, 'modelo') || '?',
+    mainCost: Number(fmValue(content, 'custo_modelo_usd')) || 0,
+    subCost: Number(fmValue(content, 'subagents_custo_usd')) || 0,
+    tokens: Number(fmValue(content, 'tokens_total')) || 0,
+    subTokens: Number(fmValue(content, 'subagents_tokens_total')) || 0,
+  };
+}
+
+export function aggregateCosts(entries) {
+  const byDay = {};
+  const byModel = {};
+  let main = 0;
+  let sub = 0;
+  let tokens = 0;
+  let subTokens = 0;
+  for (const e of entries) {
+    main += e.mainCost; sub += e.subCost; tokens += e.tokens; subTokens += e.subTokens;
+    const d = e.date || '?';
+    (byDay[d] = byDay[d] || { cost: 0, count: 0 }).cost += e.mainCost + e.subCost;
+    byDay[d].count += 1;
+    (byModel[e.model] = byModel[e.model] || { cost: 0, count: 0 }).cost += e.mainCost + e.subCost;
+    byModel[e.model].count += 1;
+  }
+  return {
+    count: entries.length,
+    main: round4(main), sub: round4(sub), total: round4(main + sub),
+    tokens, subTokens,
+    byDay: Object.entries(byDay).sort().map(([date, v]) => ({ date, cost: round4(v.cost), count: v.count })),
+    byModel: Object.entries(byModel).sort((a, b) => b[1].cost - a[1].cost).map(([model, v]) => ({ model, cost: round4(v.cost), count: v.count })),
+  };
+}
+
+function walkNotes(dir) {
+  const out = [];
+  let names;
+  try { names = readdirSync(dir); } catch { return out; }
+  for (const n of names) {
+    const p = join(dir, n);
+    let st;
+    try { st = statSync(p); } catch { continue; }
+    if (st.isDirectory()) out.push(...walkNotes(p));
+    else if (n.endsWith('.md')) out.push(p);
+  }
+  return out;
+}
+
+export function collectVaultCost(vaultBase, { since } = {}) {
+  const sessionsDir = join(vaultBase, getLocale(vaultBase).folders.sessions);
+  const entries = [];
+  for (const f of walkNotes(sessionsDir)) {
+    let e;
+    try { e = parseSessionCost(readFileSync(f, 'utf8')); } catch { continue; }
+    if (!e) continue;
+    if (since && e.date && e.date < since) continue;
+    entries.push(e);
+  }
+  return aggregateCosts(entries);
+}
+
+function opt(argv, name) {
+  const i = argv.indexOf(name);
+  if (i >= 0) return argv[i + 1];
+  const eq = argv.find((a) => a.startsWith(`${name}=`));
+  return eq ? eq.slice(name.length + 1) : undefined;
+}
+
+export function runCost(argv) {
+  const vaultRaw = opt(argv, '--vault') || process.env.OBSIDIAN_VAULT_PATH;
+  if (!vaultRaw) { process.stderr.write('wendkeep cost: no vault (--vault or OBSIDIAN_VAULT_PATH).\n'); process.exit(2); }
+  const vaultBase = isAbsolute(vaultRaw) ? vaultRaw : resolve(process.cwd(), vaultRaw);
+  if (!existsSync(vaultBase)) { process.stderr.write(`wendkeep cost: vault not found: ${vaultBase}\n`); process.exit(2); }
+  const agg = collectVaultCost(vaultBase, { since: opt(argv, '--since') });
+
+  if (argv.includes('--json')) { process.stdout.write(`${JSON.stringify(agg, null, 2)}\n`); process.exit(0); }
+
+  process.stdout.write(`Custo total (vault): ${usd(agg.total)} — ${agg.count} sessão(ões)\n`);
+  process.stdout.write(`  main: ${usd(agg.main)} · subagents: ${usd(agg.sub)}\n`);
+  if (agg.byModel.length) {
+    process.stdout.write('\nPor modelo:\n');
+    for (const m of agg.byModel) process.stdout.write(`  ${m.model.padEnd(20)} ${usd(m.cost)}  (${m.count})\n`);
+  }
+  if (agg.byDay.length) {
+    process.stdout.write('\nPor dia:\n');
+    for (const d of agg.byDay) process.stdout.write(`  ${d.date}  ${usd(d.cost)}  (${d.count})\n`);
+  }
+  process.exit(0);
+}

package/src/taxonomy.mjs

@@ -31,6 +31,7 @@ export const HOOK_FILES = [
   'session-stop.mjs',
   'linked-notes.mjs',
   'token-usage.mjs',
+  'subagent-usage.mjs',
   'pricing.json',
   'brain-core.mjs',
   'change-core.mjs',