@klars/agentobs 0.2.1 → 0.3.0

package/dist/adapters/claude-code-hook.js

@@ -29,6 +29,7 @@ import { openDb } from '../core/db.js';
 import { ensureHome, paths } from '../core/paths.js';
 import { beginToolCall, completeToolCall, endSession, ensureSession, recordPolicyDecision, startSession, } from '../core/repo.js';
 import { contextFromToolInput, evaluate, loadPolicy } from '../core/policy-engine.js';
+import { blockingBudget, checkBudgets } from '../core/budget.js';
 import { attachTranscriptUsage } from './transcript.js';
 const AGENT_NAME = 'claude-code';
 /**
@@ -97,6 +98,46 @@ export function handleHook(payload) {
             const toolName = payload.tool_name ?? 'unknown';
             const id = toolCallId(payload);
             ensureSession(db, sessionId, AGENT_NAME, payload.cwd ?? null);
+            // Budgets first: an exceeded hard limit stops everything, however
+            // benign the individual command looks.
+            try {
+                const budgets = checkBudgets(db);
+                const overspent = blockingBudget(budgets);
+                if (overspent) {
+                    beginToolCall(db, {
+                        id,
+                        sessionId,
+                        toolName,
+                        input: payload.tool_input,
+                        status: 'blocked',
+                    });
+                    recordPolicyDecision(db, {
+                        toolCallId: id,
+                        sessionId,
+                        toolName,
+                        ruleMatched: `budget:${overspent.budget.period}`,
+                        decision: 'block',
+                        reason: `spend $${overspent.spent.toFixed(2)} exceeds the $${overspent.limit.toFixed(2)} ${overspent.budget.period} limit`,
+                    });
+                    return {
+                        stdout: JSON.stringify({
+                            hookSpecificOutput: {
+                                hookEventName: 'PreToolUse',
+                                permissionDecision: 'deny',
+                                permissionDecisionReason: `AgentObs budget reached: $${overspent.spent.toFixed(2)} spent against a ` +
+                                    `$${overspent.limit.toFixed(2)} ${overspent.budget.period} limit. ` +
+                                    `Raise it with "agentobs budget set --${overspent.budget.period} <amount>" ` +
+                                    `or remove it with "agentobs budget remove ${overspent.budget.period}".`,
+                            },
+                        }),
+                        exitCode: 0,
+                    };
+                }
+            }
+            catch (err) {
+                // A budget check must never wedge the agent - fail open, like policy.
+                debugLog(`budget check failed: ${String(err)}`);
+            }
             const { policy, errors } = loadPolicy();
             for (const err of errors)
                 debugLog(`policy: ${err}`);

package/dist/adapters/claude-transcript.js

@@ -135,14 +135,19 @@ export async function importTranscript(db, file) {
         const message = (row.message ?? {});
         const usage = message.usage;
         if (usage && typeof usage === 'object') {
-            // Only genuinely fresh input tokens go in tokensIn. Cache writes and
-            // reads are tracked separately because they bill at different rates,
-            // and because a cache read replays the whole context every turn - the
-            // headline token count must not include the same tokens hundreds of
-            // times.
-            result.tokensIn += usage.input_tokens ?? 0;
+            // Fresh input = uncached input + cache writes. A cache write is real
+            // new content being sent for the first time (just stored for reuse), so
+            // excluding it made "tokens in" absurd: 24K in against 4.6M out, when
+            // real agent usage is heavily input-weighted. It is still tracked
+            // separately for costing, since it bills at 1.25x.
+            //
+            // Cache *reads* stay out of this total: they replay the entire context
+            // on every turn, so counting them would report the same tokens hundreds
+            // of times (2.4 billion across three sessions).
+            const cacheWrite = usage.cache_creation_input_tokens ?? 0;
+            result.tokensIn += (usage.input_tokens ?? 0) + cacheWrite;
             result.tokensOut += usage.output_tokens ?? 0;
-            result.cacheWriteTokens += usage.cache_creation_input_tokens ?? 0;
+            result.cacheWriteTokens += cacheWrite;
             // cache_read is the whole conversation context replayed on every single
             // message, so it re-counts the same tokens on each turn - summing it
             // reported 413 million tokens for one session. It is tracked separately
@@ -186,6 +191,8 @@ export async function importTranscript(db, file) {
     }
     if (!sessionStarted)
         return result;
+    // tokensIn already contains the cache-write tokens, so they are costed once
+    // at the base rate here and only topped up by the extra 0.25x premium.
     const baseCost = computeCost(result.model, result.tokensIn, result.tokensOut);
     const readCost = computeCost(result.model, result.cacheReadTokens, 0);
     const writeCost = computeCost(result.model, result.cacheWriteTokens, 0);
@@ -194,7 +201,7 @@ export async function importTranscript(db, file) {
             ? null
             : baseCost +
                 (readCost ?? 0) * CACHE_READ_RATE +
-                (writeCost ?? 0) * CACHE_WRITE_RATE;
+                (writeCost ?? 0) * (CACHE_WRITE_RATE - 1);
     // Session totals come from the transcript's own usage blocks, which are
     // authoritative - the per-call rows have no tokens to sum.
     db.prepare(`UPDATE sessions

package/dist/cli.js

@@ -85,6 +85,7 @@ On Windows, cmd.exe builtins (dir, echo, type) need: agentobs run -- cmd /c dir`
         .option('--all', 'import every transcript found, however old', false)
         .option('--dry-run', 'list what would be imported, write nothing', false)
         .option('--session <id>', 'import one specific session id')
+        .option('--watch', 'keep importing as sessions run (live, no hooks)', false)
         .addHelpText('after', `
 Claude Code writes a JSONL transcript per session under
 ~/.claude/projects/. This reads them directly, so it works even when
@@ -112,6 +113,51 @@ the PreToolUse hook.`)
         const { exportData } = await import('./commands/export.js');
         await exportData(opts);
     });
+    program
+        .command('digest')
+        .description('A readable period summary: spend, top tools, projects, budgets')
+        .option('--since <range>', 'today, 7d, 30d, all', '7d')
+        .option('--json', 'emit JSON instead of prose', false)
+        .action(async (opts) => {
+        const { digest } = await import('./commands/digest.js');
+        await digest(opts);
+    });
+    program
+        .command('projects')
+        .description('Spend and activity grouped by working directory')
+        .option('--since <range>', 'today, 7d, 30d, all', '7d')
+        .option('--json', 'emit JSON', false)
+        .action(async (opts) => {
+        const { projects } = await import('./commands/projects.js');
+        await projects(opts);
+    });
+    const budget = program
+        .command('budget')
+        .description('Spend limits - warn or block when an agent passes a threshold')
+        .action(async () => {
+        const { budgetStatus } = await import('./commands/budget.js');
+        await budgetStatus();
+    });
+    budget
+        .command('set')
+        .description('Set a spend limit')
+        .option('--daily <usd>', 'daily limit in USD')
+        .option('--weekly <usd>', 'weekly limit in USD')
+        .option('--monthly <usd>', 'monthly limit in USD')
+        .option('--block', 'refuse tool calls past the limit (default: warn only)', false)
+        .option('--scope <path>', 'apply only to sessions under this directory')
+        .action(async (opts) => {
+        const { budgetSet } = await import('./commands/budget.js');
+        await budgetSet(opts);
+    });
+    budget
+        .command('remove')
+        .description('Remove a budget')
+        .argument('<id>', 'budget id, id prefix, or period name')
+        .action(async (id) => {
+        const { budgetRemove } = await import('./commands/budget.js');
+        await budgetRemove(id);
+    });
     const policy = program.command('policy').description('Guardrail policy management');
     policy
         .command('init')

package/dist/commands/budget.js

@@ -0,0 +1,86 @@
+/**
+ * `agentobs budget` - spend limits.
+ */
+import { openDb } from '../core/db.js';
+import { checkBudgets, listBudgets, removeBudget, setBudget, } from '../core/budget.js';
+const money = (v) => `$${v.toFixed(2)}`;
+/** A 20-cell bar. Text, so it works in any terminal without colour support. */
+function bar(ratio, width = 20) {
+    const filled = Math.min(width, Math.max(0, Math.round(ratio * width)));
+    return `[${'#'.repeat(filled)}${'.'.repeat(width - filled)}]`;
+}
+export async function budgetSet(opts) {
+    const periods = [
+        ['daily', opts.daily],
+        ['weekly', opts.weekly],
+        ['monthly', opts.monthly],
+    ];
+    const chosen = periods.filter(([, v]) => v !== undefined);
+    if (chosen.length === 0) {
+        console.error(`No limit given.
+
+  Usage:  agentobs budget set --daily 5
+          agentobs budget set --monthly 100 --block
+          agentobs budget set --daily 2 --scope /path/to/project
+
+  --block refuses further tool calls once the limit is crossed; without
+  it the limit only warns. Blocking needs the PreToolUse hook, since
+  that is the only point where a call can be stopped before it runs.`);
+        process.exitCode = 2;
+        return;
+    }
+    const db = openDb();
+    const action = opts.block ? 'block' : 'warn';
+    for (const [period, raw] of chosen) {
+        const limit = Number(raw);
+        if (!Number.isFinite(limit) || limit <= 0) {
+            console.error(`Invalid ${period} limit: ${raw}`);
+            process.exitCode = 2;
+            return;
+        }
+        const b = setBudget(db, { period, limitUsd: limit, action, scope: opts.scope ?? null });
+        console.log(`  ${period.padEnd(8)} ${money(b.limit_usd).padStart(9)}  ${b.action}` +
+            (b.scope ? `  scope: ${b.scope}` : ''));
+    }
+    console.log('\nRun "agentobs budget" to see current spend against these limits.');
+}
+export async function budgetStatus() {
+    const db = openDb();
+    const budgets = listBudgets(db);
+    if (budgets.length === 0) {
+        console.log(`No budgets set.
+
+  agentobs budget set --daily 5        warn when today passes $5
+  agentobs budget set --monthly 100 --block   stop at $100 this month
+
+Budgets are the spend equivalent of the policy guardrails: instead of
+finding out after the fact, you get told - or stopped - at the limit.`);
+        return;
+    }
+    // record:false - reporting status must not consume the one-shot alert that
+    // the hook path relies on to warn exactly once per period.
+    const statuses = checkBudgets(db, { record: false });
+    console.log('\n  Budget      Spent      Limit   Used  Action\n  ' + '-'.repeat(56));
+    for (const s of statuses) {
+        const pct = `${Math.round(s.ratio * 100)}%`.padStart(5);
+        const flag = s.exceeded ? (s.budget.action === 'block' ? ' OVER (blocking)' : ' OVER') : '';
+        console.log(`  ${s.budget.period.padEnd(9)} ${money(s.spent).padStart(9)} ${money(s.limit).padStart(10)} ` +
+            `${pct}  ${s.budget.action}${flag}`);
+        console.log(`  ${bar(s.ratio)}${s.budget.scope ? `  ${s.budget.scope}` : ''}`);
+    }
+    console.log('');
+}
+export async function budgetRemove(id) {
+    const db = openDb();
+    // Accept an id prefix: the full UUID is tedious to type, and `budget`
+    // prints only the period, so a user has to look the id up somehow.
+    const match = listBudgets(db).find((b) => b.id === id || b.id.startsWith(id) || b.period === id);
+    if (!match) {
+        console.error(`No budget matching "${id}". Run "agentobs budget" to list them.`);
+        process.exitCode = 1;
+        return;
+    }
+    removeBudget(db, match.id);
+    console.log(`Removed the ${match.period} budget (${money(match.limit_usd)}).`);
+}
+//# sourceMappingURL=budget.js.map

package/dist/commands/digest.js

@@ -0,0 +1,82 @@
+/**
+ * `agentobs digest` - a period summary worth reading.
+ *
+ * Stats answers "what are the totals"; a digest answers "what should I know".
+ * It leads with spend, names the most expensive day and project, and reports
+ * anything blocked - the handful of facts that would actually change what
+ * someone does next.
+ */
+import { openDb } from '../core/db.js';
+import { getProjects, getSummary, getTimeline, getToolsBreakdown, } from '../core/queries.js';
+import { checkBudgets } from '../core/budget.js';
+const money = (v) => (v === null ? '—' : `$${v.toFixed(2)}`);
+const pct = (n) => `${Math.round(n * 100)}%`;
+function toRange(value) {
+    return value === 'today' || value === '7d' || value === '30d' || value === 'all' ? value : '7d';
+}
+export async function digest(opts = {}) {
+    const db = openDb();
+    const range = toRange(opts.since);
+    const summary = getSummary(db, range);
+    const timeline = getTimeline(db, range);
+    const tools = getToolsBreakdown(db, range);
+    const projects = getProjects(db, range);
+    const budgets = checkBudgets(db, { record: false });
+    if (opts.json) {
+        console.log(JSON.stringify({ summary, timeline, tools, projects, budgets }, null, 2));
+        return;
+    }
+    if (summary.sessions === 0) {
+        console.log(`\n  Nothing recorded for ${range}.\n\n  Try "agentobs import" to pull in your Claude Code history.\n`);
+        return;
+    }
+    const label = { today: 'Today', '7d': 'This week', '30d': 'This month', all: 'All time' }[range];
+    const busiest = [...timeline].sort((a, b) => b.calls - a.calls)[0];
+    const priciest = [...timeline]
+        .filter((t) => t.cost_usd !== null)
+        .sort((a, b) => (b.cost_usd ?? 0) - (a.cost_usd ?? 0))[0];
+    const topTool = tools[0];
+    const topProject = projects[0];
+    const share = topTool && summary.tool_calls > 0 ? topTool.calls / summary.tool_calls : 0;
+    const lines = [
+        '',
+        `  ${label} · ${money(summary.total_cost_usd)} across ${summary.sessions} session${summary.sessions === 1 ? '' : 's'}`,
+        '',
+        `  ${summary.tool_calls.toLocaleString()} tool calls · ${(summary.tokens_in + summary.tokens_out).toLocaleString()} tokens · ${pct(summary.error_rate)} errors`,
+    ];
+    if (topTool) {
+        lines.push(`  Most used: ${topTool.tool_name} (${topTool.calls} calls, ${pct(share)} of all)`);
+    }
+    if (topProject && projects.length > 1) {
+        lines.push(`  Top project: ${topProject.project} (${money(topProject.cost_usd)})`);
+    }
+    if (priciest) {
+        lines.push(`  Priciest day: ${priciest.bucket} (${money(priciest.cost_usd)})`);
+    }
+    else if (busiest) {
+        lines.push(`  Busiest: ${busiest.bucket} (${busiest.calls} calls)`);
+    }
+    if (summary.blocked > 0) {
+        lines.push('', `  ${summary.blocked} call${summary.blocked === 1 ? '' : 's'} blocked by policy.`);
+    }
+    // Budgets are the actionable part: a digest that does not mention an
+    // exceeded limit has buried the one thing worth acting on.
+    const overspent = budgets.filter((b) => b.exceeded);
+    if (overspent.length > 0) {
+        lines.push('');
+        for (const b of overspent) {
+            lines.push(`  OVER BUDGET: ${money(b.spent)} against a ${money(b.limit)} ${b.budget.period} limit` +
+                (b.budget.action === 'block' ? ' (blocking)' : ''));
+        }
+    }
+    else if (budgets.length > 0) {
+        const tightest = [...budgets].sort((a, b) => b.ratio - a.ratio)[0];
+        lines.push('', `  Budget: ${pct(tightest.ratio)} of the ${tightest.budget.period} limit used.`);
+    }
+    if (summary.uncosted_calls > 0) {
+        lines.push('', `  Note: ${summary.uncosted_calls} call(s) have no price for their model, so the`, '  cost above under-reports. Add it to ~/.agentobs/pricing.json.');
+    }
+    lines.push('');
+    console.log(lines.join('\n'));
+}
+//# sourceMappingURL=digest.js.map

package/dist/commands/import.js

@@ -69,6 +69,10 @@ install keeps its config somewhere else.`);
     // the whole context is replayed on every turn, so it can reach billions of
     // tokens. That is genuine billing, but a single unexplained total looks
     // like a bug, so show where it comes from.
+    if (opts.watch) {
+        await followTranscripts(db, selected.map((t) => t.path));
+        return;
+    }
     console.log(`
   ${selected.length} session(s) · ${calls} tool calls
 
@@ -89,4 +93,56 @@ Run "agentobs stats --today" or "agentobs dashboard" to see it.
 Note: imported data is historical, so guardrails cannot block anything
 retroactively. Blocking still requires the PreToolUse hook.`);
 }
+/**
+ * Re-imports the newest transcripts on an interval.
+ *
+ * This is the hook-free path to *live* data: Claude Code appends to its
+ * transcript as the session runs, and importTranscript is idempotent (ids come
+ * from the transcript, inserts are ON CONFLICT DO NOTHING), so re-reading a
+ * growing file only adds what is new.
+ *
+ * Polling rather than fs.watch: a transcript is appended to constantly, watch
+ * events would fire far more often than there is work to do, and polling is
+ * also what survives network shares and container mounts.
+ */
+/** Newline, kept as a constant so no escape sequence appears in a template. */
+const EOL = String.fromCharCode(10);
+async function followTranscripts(db, initialPaths) {
+    const INTERVAL_MS = 5000;
+    console.log(`
+  Watching ${initialPaths.length} transcript(s) — Ctrl-C to stop.
+  New activity appears within ${INTERVAL_MS / 1000}s. No hooks required.
+`);
+    let stop = false;
+    for (const sig of ['SIGINT', 'SIGTERM']) {
+        process.on(sig, () => {
+            stop = true;
+            console.log(EOL + '  Stopped.');
+            process.exit(0);
+        });
+    }
+    let lastTotal = 0;
+    while (!stop) {
+        // Re-scan every pass: a session started after `watch` began should be
+        // picked up without restarting the command.
+        const current = findTranscripts().filter((t) => Date.now() - t.modifiedAt < 864e5);
+        let calls = 0;
+        for (const t of current) {
+            try {
+                const r = await importTranscript(db, t);
+                calls += r.toolCalls;
+            }
+            catch {
+                // A transcript being written mid-read is normal; the next pass
+                // picks it up.
+            }
+        }
+        if (calls !== lastTotal) {
+            const now = new Date().toLocaleTimeString();
+            process.stdout.write(`
  ${now} - ${calls} tool calls across ${current.length} session(s)   `);
+            lastTotal = calls;
+        }
+        await new Promise((r) => setTimeout(r, INTERVAL_MS));
+    }
+}
 //# sourceMappingURL=import.js.map

package/dist/commands/projects.js

@@ -0,0 +1,34 @@
+/**
+ * `agentobs projects` - spend grouped by working directory.
+ *
+ * Answers "which repo is burning my budget", which is the first question
+ * anyone juggling several codebases asks. Uses the cwd already recorded per
+ * session, so it needs no new data collection.
+ */
+import { openDb } from '../core/db.js';
+import { getProjects } from '../core/queries.js';
+const money = (v) => (v === null ? '—' : `$${v.toFixed(2)}`);
+function toRange(value) {
+    return value === 'today' || value === '7d' || value === '30d' || value === 'all' ? value : '7d';
+}
+export async function projects(opts = {}) {
+    const db = openDb();
+    const rows = getProjects(db, toRange(opts.since));
+    if (opts.json) {
+        console.log(JSON.stringify(rows, null, 2));
+        return;
+    }
+    if (rows.length === 0) {
+        console.log('\n  No sessions recorded yet. Try "agentobs import".\n');
+        return;
+    }
+    const total = rows.reduce((sum, r) => sum + (r.cost_usd ?? 0), 0);
+    console.log('\n  Project              Sessions   Calls       Cost   Share\n  ' + '-'.repeat(58));
+    for (const r of rows.slice(0, 20)) {
+        const share = total > 0 ? `${Math.round(((r.cost_usd ?? 0) / total) * 100)}%` : '—';
+        console.log(`  ${r.project.slice(0, 20).padEnd(20)} ${String(r.sessions).padStart(8)} ` +
+            `${String(r.tool_calls).padStart(7)} ${money(r.cost_usd).padStart(10)} ${share.padStart(7)}`);
+    }
+    console.log(`\n  ${rows.length} project(s) · ${money(total)} total\n`);
+}
+//# sourceMappingURL=projects.js.map

package/dist/core/budget.js

@@ -0,0 +1,131 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * Start of the current period, and a stable key identifying it.
+ *
+ * The key is what makes alerts one-shot: a UNIQUE index on
+ * (budget_id, period_key) means the second insert for the same day simply
+ * fails, so no bookkeeping is needed to avoid repeat warnings.
+ */
+export function periodBounds(period, now = new Date()) {
+    const d = new Date(now);
+    if (period === 'daily') {
+        d.setHours(0, 0, 0, 0);
+        return { start: d.toISOString(), key: `D${localDate(d)}` };
+    }
+    if (period === 'weekly') {
+        // Week starts Monday; getDay() returns 0 for Sunday, hence the shift.
+        const day = (d.getDay() + 6) % 7;
+        d.setDate(d.getDate() - day);
+        d.setHours(0, 0, 0, 0);
+        return { start: d.toISOString(), key: `W${localDate(d)}` };
+    }
+    d.setDate(1);
+    d.setHours(0, 0, 0, 0);
+    return { start: d.toISOString(), key: `M${localDate(d).slice(0, 7)}` };
+}
+/**
+ * Local calendar date as YYYY-MM-DD.
+ *
+ * Deliberately not toISOString().slice(0,10): the boundary is local midnight,
+ * but toISOString converts back to UTC, so east of Greenwich the key lands on
+ * the previous day. A user's "daily budget" means their day, not UTC's.
+ */
+function localDate(d) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+export function listBudgets(db) {
+    return db
+        .prepare('SELECT * FROM budgets ORDER BY period, limit_usd')
+        .all();
+}
+export function setBudget(db, input) {
+    const now = new Date().toISOString();
+    // One budget per (period, scope): setting a daily limit twice updates it
+    // rather than silently stacking two limits that both fire.
+    // IFNULL on both sides so a null scope matches a null scope; a plain
+    // `scope = ?` would never match, since NULL = NULL is not true in SQL.
+    const existing = db
+        .prepare("SELECT id FROM budgets WHERE period = ? AND IFNULL(scope, '') = IFNULL(?, '')")
+        .get(input.period, input.scope ?? null);
+    const id = existing?.id ?? randomUUID();
+    if (existing) {
+        db.prepare('UPDATE budgets SET limit_usd = ?, action = ?, updated_at = ? WHERE id = ?').run(input.limitUsd, input.action ?? 'warn', now, id);
+    }
+    else {
+        db.prepare(`INSERT INTO budgets (id, period, limit_usd, action, scope, created_at, updated_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?)`).run(id, input.period, input.limitUsd, input.action ?? 'warn', input.scope ?? null, now, now);
+    }
+    return db.prepare('SELECT * FROM budgets WHERE id = ?').get(id);
+}
+export function removeBudget(db, id) {
+    const before = db.prepare('SELECT COUNT(*) AS n FROM budgets WHERE id = ?').get(id);
+    if (before.n === 0)
+        return false;
+    db.prepare('DELETE FROM budget_events WHERE budget_id = ?').run(id);
+    db.prepare('DELETE FROM budgets WHERE id = ?').run(id);
+    return true;
+}
+/** Spend since `since`, optionally limited to sessions under a cwd prefix. */
+export function spendSince(db, since, scope) {
+    // Sum both sources: hook/JSONL data costs per tool call, transcript imports
+    // cost per session. Taking the larger avoids double-counting a session that
+    // has both, while never under-reporting one that has only one.
+    const callSum = db
+        .prepare(`SELECT COALESCE(SUM(tc.cost_usd), 0) AS c
+         FROM tool_calls tc
+         JOIN sessions s ON s.id = tc.session_id
+        WHERE tc.started_at >= ?
+          AND (? IS NULL OR s.cwd LIKE ? || '%')`)
+        .get(since, scope ?? null, scope ?? '');
+    const sessionSum = db
+        .prepare(`SELECT COALESCE(SUM(total_cost_usd), 0) AS c
+         FROM sessions
+        WHERE started_at >= ?
+          AND (? IS NULL OR cwd LIKE ? || '%')`)
+        .get(since, scope ?? null, scope ?? '');
+    return Math.max(Number(callSum.c ?? 0), Number(sessionSum.c ?? 0));
+}
+/**
+ * Evaluates every budget against current spend.
+ *
+ * `newlyExceeded` is set only the first time a period crosses its limit, and
+ * recording that fact is what keeps a warning from firing on every subsequent
+ * tool call for the rest of the day.
+ */
+export function checkBudgets(db, opts = {}) {
+    const out = [];
+    for (const budget of listBudgets(db)) {
+        const { start, key } = periodBounds(budget.period);
+        const spent = spendSince(db, start, budget.scope);
+        const exceeded = spent >= budget.limit_usd;
+        let newlyExceeded = false;
+        if (exceeded && opts.record !== false) {
+            try {
+                db.prepare(`INSERT INTO budget_events (id, budget_id, period_key, spent_usd, limit_usd, action, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?)`).run(randomUUID(), budget.id, key, spent, budget.limit_usd, budget.action, new Date().toISOString());
+                newlyExceeded = true;
+            }
+            catch {
+                // UNIQUE(budget_id, period_key) violation: already alerted this
+                // period, which is exactly the intent.
+            }
+        }
+        out.push({
+            budget,
+            spent,
+            limit: budget.limit_usd,
+            ratio: budget.limit_usd === 0 ? 0 : spent / budget.limit_usd,
+            periodKey: key,
+            periodStart: start,
+            exceeded,
+            newlyExceeded,
+        });
+    }
+    return out;
+}
+/** The first budget that should block, if any. */
+export function blockingBudget(statuses) {
+    return statuses.find((s) => s.exceeded && s.budget.action === 'block') ?? null;
+}
+//# sourceMappingURL=budget.js.map

package/dist/core/queries.js

@@ -236,4 +236,76 @@ export function getPolicyDecisions(db, opts = {}) {
         LIMIT ?`)
         .all(limit);
 }
+/**
+ * Spend grouped by working directory - "which repo is burning my budget".
+ *
+ * cwd is already recorded per session, so this needs no new data; the display
+ * name is the last path segment, since a full absolute path is unreadable in
+ * a table and often identical up to the final directory.
+ */
+export function getProjects(db, range) {
+    const since = rangeStart(range);
+    const where = since ? 'WHERE s.started_at >= ?' : '';
+    const args = since ? [since] : [];
+    const rows = db
+        .prepare(`SELECT COALESCE(s.cwd, '(unknown)') AS cwd,
+              COUNT(DISTINCT s.id) AS sessions,
+              COALESCE(SUM(s.tool_call_count), 0) AS tool_calls,
+              COALESCE(SUM(s.error_count), 0) AS errors,
+              SUM(s.total_cost_usd) AS cost_usd,
+              COALESCE(SUM(s.total_tokens_in + s.total_tokens_out), 0) AS tokens,
+              MAX(s.started_at) AS last_seen
+         FROM sessions s
+         ${where}
+        GROUP BY COALESCE(s.cwd, '(unknown)')`)
+        .all(...args);
+    // Merge paths that differ only by case or separator. Windows reports the
+    // same directory as both "i:\AgentObs" and "I:/AgentObs" depending on how
+    // the process was launched, which otherwise splits one project into several
+    // rows and makes the cost share meaningless.
+    const merged = new Map();
+    for (const r of rows) {
+        const key = r.cwd.replace(/[\/]+/g, '/').replace(/\/+$/, '').toLowerCase();
+        const existing = merged.get(key);
+        if (existing) {
+            existing.sessions += r.sessions;
+            existing.tool_calls += r.tool_calls;
+            existing.errors += r.errors;
+            existing.tokens += r.tokens;
+            if (r.cost_usd !== null)
+                existing.cost_usd = (existing.cost_usd ?? 0) + r.cost_usd;
+            if (r.last_seen > existing.last_seen)
+                existing.last_seen = r.last_seen;
+        }
+        else {
+            merged.set(key, {
+                ...r,
+                project: r.cwd.replace(/[\/]+$/, '').split(/[\/]/).pop() || r.cwd,
+            });
+        }
+    }
+    return [...merged.values()].sort((a, b) => (b.cost_usd ?? -1) - (a.cost_usd ?? -1) || b.tool_calls - a.tool_calls);
+}
+/** One session and its tool calls in order - the "what happened here?" view. */
+export function getSessionDetail(db, sessionId) {
+    const session = db
+        .prepare(`SELECT id, agent_name, started_at, ended_at, cwd, fidelity, tool_call_count,
+              error_count, blocked_count, total_cost_usd, total_tokens_in,
+              total_tokens_out, exit_code
+         FROM sessions WHERE id = ?`)
+        .get(sessionId);
+    const calls = db
+        .prepare(`SELECT tc.id, tc.session_id, s.agent_name, tc.tool_name, tc.started_at,
+              tc.duration_ms, tc.status, tc.input_summary, tc.output_summary,
+              tc.cost_usd, tc.error_message,
+              (SELECT pd.rule_matched FROM policy_decisions pd
+                WHERE pd.tool_call_id = tc.id
+                ORDER BY pd.decided_at DESC LIMIT 1) AS rule_matched
+         FROM tool_calls tc
+         LEFT JOIN sessions s ON s.id = tc.session_id
+        WHERE tc.session_id = ?
+        ORDER BY tc.started_at ASC`)
+        .all(sessionId);
+    return { session, calls };
+}
 //# sourceMappingURL=queries.js.map

package/dist/core/schema.sql

@@ -76,3 +76,34 @@ CREATE INDEX IF NOT EXISTS idx_sessions_started     ON sessions(started_at);
 CREATE INDEX IF NOT EXISTS idx_sessions_unsynced    ON sessions(synced_at) WHERE synced_at IS NULL;
 CREATE INDEX IF NOT EXISTS idx_policy_tool_call     ON policy_decisions(tool_call_id);
 CREATE INDEX IF NOT EXISTS idx_policy_decided       ON policy_decisions(decided_at);
+
+-- Budget limits. Kept as a table rather than a config file so the hook can
+-- read the current spend and the limit in one place, on the hot path.
+CREATE TABLE IF NOT EXISTS budgets (
+  id           TEXT PRIMARY KEY,
+  period       TEXT NOT NULL,           -- daily | weekly | monthly
+  limit_usd    REAL NOT NULL,
+  -- "warn" notifies and lets the call through; "block" refuses further tool
+  -- calls once the limit is crossed. Blocking spend is the same idea as
+  -- blocking a dangerous command, applied to money.
+  action       TEXT NOT NULL DEFAULT 'warn',
+  scope        TEXT,                    -- null = all projects, else a cwd prefix
+  created_at   TEXT NOT NULL,
+  updated_at   TEXT NOT NULL
+);
+
+-- One row per time a budget threshold was crossed, so a warning fires once
+-- per period instead of on every subsequent tool call.
+CREATE TABLE IF NOT EXISTS budget_events (
+  id           TEXT PRIMARY KEY,
+  budget_id    TEXT NOT NULL REFERENCES budgets(id),
+  period_key   TEXT NOT NULL,           -- e.g. 2026-08-30 for a daily budget
+  spent_usd    REAL NOT NULL,
+  limit_usd    REAL NOT NULL,
+  action       TEXT NOT NULL,
+  created_at   TEXT NOT NULL
+);
+
+CREATE UNIQUE INDEX IF NOT EXISTS idx_budget_events_once
+  ON budget_events(budget_id, period_key);
+CREATE INDEX IF NOT EXISTS idx_sessions_cwd ON sessions(cwd);

package/dist/server/index.js

@@ -18,8 +18,9 @@ import { dirname, extname, join, normalize } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { timingSafeEqual } from 'node:crypto';
 import { openDb } from '../core/db.js';
-import { getPolicyDecisions, getRecentToolCalls, getSessions, getSparklines, getSummary, getTimeline, getToolsBreakdown, } from '../core/queries.js';
+import { getPolicyDecisions, getRecentToolCalls, getProjects, getSessionDetail, getSessions, getSparklines, getSummary, getTimeline, getToolsBreakdown, } from '../core/queries.js';
 import { loadPolicy } from '../core/policy-engine.js';
+import { checkBudgets } from '../core/budget.js';
 const PUBLIC_DIR = join(dirname(fileURLToPath(import.meta.url)), 'public');
 const MIME = {
     '.html': 'text/html; charset=utf-8',
@@ -114,6 +115,21 @@ export function createDashboardServer(opts) {
                         }),
                     });
                     return;
+                case '/api/projects':
+                    json(res, { projects: getProjects(db, range) });
+                    return;
+                case '/api/session': {
+                    const id = url.searchParams.get('id');
+                    if (!id) {
+                        json(res, { error: 'missing id' }, 400);
+                        return;
+                    }
+                    json(res, getSessionDetail(db, id));
+                    return;
+                }
+                case '/api/budgets':
+                    json(res, { budgets: checkBudgets(db, { record: false }) });
+                    return;
                 case '/api/policy':
                     json(res, {
                         ...loadPolicy(),

package/dist/server/public/app.css

@@ -977,3 +977,90 @@ tbody td:first-child {
   flex: 0 0 auto;
   align-self: flex-start;
 }
+
+/* ---------- session detail drawer ---------- */
+
+.drawer[hidden] {
+  display: none !important;
+}
+
+.drawer {
+  position: fixed;
+  inset: 0;
+  z-index: 20;
+  display: flex;
+  justify-content: flex-end;
+}
+
+.drawer-scrim {
+  position: absolute;
+  inset: 0;
+  background: rgba(11, 11, 11, 0.42);
+  backdrop-filter: blur(2px);
+}
+
+.drawer-panel {
+  position: relative;
+  width: min(760px, 100%);
+  background: var(--surface);
+  border-left: 1px solid var(--border);
+  box-shadow: -24px 0 64px -24px rgba(0, 0, 0, 0.45);
+  display: flex;
+  flex-direction: column;
+  overflow-y: auto;
+}
+
+.drawer-head {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 16px;
+  padding: 18px 20px;
+  border-bottom: 1px solid var(--border);
+  position: sticky;
+  top: 0;
+  background: var(--surface);
+  z-index: 1;
+}
+
+.drawer-head h2 {
+  margin: 0;
+  font-size: 15px;
+  font-weight: 650;
+}
+
+.drawer-stats {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 24px;
+  margin: 0;
+  padding: 16px 20px;
+  border-bottom: 1px solid var(--border);
+  background: linear-gradient(180deg, var(--raised), transparent);
+}
+
+.drawer-stats dt {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--text-muted);
+  font-weight: 600;
+}
+
+.drawer-stats dd {
+  margin: 2px 0 0;
+  font-size: 17px;
+  font-weight: 620;
+  font-variant-numeric: tabular-nums;
+}
+
+/* Rows in the sessions table are clickable, so say so. */
+#sessions-body tr,
+#activity-body tr {
+  cursor: pointer;
+}
+
+#sessions-body tr:hover td:first-child {
+  text-decoration: underline;
+  text-underline-offset: 2px;
+}

package/dist/server/public/app.js

@@ -191,10 +191,10 @@ function renderTools(rows) {
   body.replaceChildren();
   if (rows.length === 0) {
     const tr = document.createElement('tr');
-    const msg =
-      state.summary && state.summary.coarse_sessions > 0
-        ? 'Coarse sessions record no tool calls — connect the Claude Code hook for per-tool detail.'
-        : 'No tool calls recorded yet.';
+    const msg =
+      state.summary && state.summary.coarse_sessions > 0
+        ? 'Coarse sessions record no tool calls — connect the Claude Code hook for per-tool detail.'
+        : 'No tool calls recorded yet.';
     tr.append(Object.assign(cell(msg, 'empty'), { colSpan: 5 }));
     body.append(tr);
     return;
@@ -231,6 +231,8 @@ function renderSessions(rows) {
   }
   for (const row of rows) {
     const tr = document.createElement('tr');
+    tr.dataset.sessionId = row.id;
+    tr.title = 'Click to see what this session did';
     const agent = cell('');
     agent.append(document.createTextNode(row.agent_name));
     // Coarse sessions know only duration and exit code. Labelling them keeps
@@ -267,6 +269,8 @@ function renderActivity(rows) {
   }
   for (const row of rows) {
     const tr = document.createElement('tr');
+    tr.dataset.sessionId = row.session_id;
+    tr.title = 'Click to see the whole session';
 
     const status = document.createElement('td');
     status.append(statusPill(row.status));
@@ -630,6 +634,16 @@ function renderDelta(el, current, previous, { goodWhenUp = true } = {}) {
     return;
   }
   const change = ((current - previous) / previous) * 100;
+  // A tiny previous period produces a huge, meaningless percentage - "+2300%"
+  // says nothing except that yesterday was nearly empty. Cap the display so
+  // the chip stays informative rather than theatrical.
+  if (Math.abs(change) > 999) {
+    el.className = `delta ${change > 0 === goodWhenUp ? 'delta-good' : 'delta-bad'}`;
+    el.textContent = `${change > 0 ? '▲' : '▼'} vs ${previous}`;
+    el.title = `Previous period had only ${previous}; a percentage would be misleading`;
+    el.removeAttribute('hidden');
+    return;
+  }
   if (!Number.isFinite(change) || Math.abs(change) < 0.5) {
     // Below half a percent is noise; a chip there implies a signal that
     // isn't real.
@@ -664,3 +678,120 @@ function drawAllSparks() {
     ctx.clearRect(0, 0, blockedCanvas.width, blockedCanvas.height);
   }
 }
+
+/* ---------- session detail drawer ---------- */
+
+const drawer = document.getElementById('session-drawer');
+
+/**
+ * Opens the per-session view: what the agent actually did, in order.
+ *
+ * The totals answer "how much"; this answers "what happened in that weird
+ * 40-minute session" - which is the question people actually open a dashboard
+ * with. All the data is already stored, so this is presentation only.
+ */
+async function openSession(sessionId) {
+  try {
+    const data = await fetchJson(`/api/session?id=${encodeURIComponent(sessionId)}`);
+    const s = data.session;
+    if (!s) return;
+
+    document.getElementById('drawer-title').textContent = s.agent_name;
+    document.getElementById('drawer-sub').textContent =
+      `${s.cwd ?? 'unknown directory'} · started ${relativeTime(s.started_at)}` +
+      (s.fidelity === 'coarse' ? ' · coarse (no per-call detail)' : '');
+
+    const stats = document.getElementById('drawer-stats');
+    stats.replaceChildren();
+    const pairs = [
+      ['Cost', money(s.total_cost_usd)],
+      ['Tool calls', count(s.tool_call_count)],
+      ['Errors', count(s.error_count)],
+      ['Blocked', count(s.blocked_count)],
+      ['Tokens', count(s.total_tokens_in + s.total_tokens_out)],
+      ['Exit', s.exit_code === null ? '—' : String(s.exit_code)],
+    ];
+    for (const [label, value] of pairs) {
+      const wrap = document.createElement('div');
+      const dt = document.createElement('dt');
+      dt.textContent = label;
+      const dd = document.createElement('dd');
+      dd.textContent = value;
+      wrap.append(dt, dd);
+      stats.append(wrap);
+    }
+
+    const body = document.getElementById('drawer-calls');
+    body.replaceChildren();
+    if (data.calls.length === 0) {
+      const tr = document.createElement('tr');
+      tr.append(
+        Object.assign(
+          cell(
+            s.fidelity === 'coarse'
+              ? 'Process-wrapped: duration and exit code only, no per-call detail.'
+              : 'No tool calls recorded for this session.',
+            'empty',
+          ),
+          { colSpan: 5 },
+        ),
+      );
+      body.append(tr);
+    } else {
+      data.calls.forEach((c, i) => {
+        const tr = document.createElement('tr');
+        const status = document.createElement('td');
+        status.append(statusPill(c.status));
+        const input = document.createElement('td');
+        const code = document.createElement('code');
+        code.className = 'mono truncate';
+        code.textContent = c.input_summary || '—';
+        code.title = c.error_message || c.output_summary || '';
+        input.append(code);
+        tr.append(
+          cell(String(i + 1), 'num'),
+          status,
+          cell(c.tool_name),
+          input,
+          cell(ms(c.duration_ms), 'num'),
+        );
+        body.append(tr);
+      });
+    }
+
+    drawer.hidden = false;
+    document.body.style.overflow = 'hidden';
+  } catch (err) {
+    setConnection(false, `Could not load session: ${err.message}`);
+  }
+}
+
+function closeDrawer() {
+  drawer.hidden = true;
+  document.body.style.overflow = '';
+}
+
+for (const el of document.querySelectorAll('[data-close-drawer]')) {
+  el.addEventListener('click', closeDrawer);
+}
+document.addEventListener('keydown', (e) => {
+  if (e.key === 'Escape' && !drawer.hidden) closeDrawer();
+});
+
+// Event delegation: rows are re-rendered every poll, so per-row listeners
+// would have to be re-attached each time (and would leak).
+document.getElementById('sessions-body').addEventListener('click', (e) => {
+  const tr = e.target.closest('tr');
+  if (tr?.dataset.sessionId) openSession(tr.dataset.sessionId);
+});
+document.getElementById('activity-body').addEventListener('click', (e) => {
+  const tr = e.target.closest('tr');
+  if (tr?.dataset.sessionId) openSession(tr.dataset.sessionId);
+});
+
+// Deep link support: ?session=<id> opens that session on load, so a specific
+// session can be linked to directly rather than hunted for in the table.
+const deepLink = new URLSearchParams(window.location.search).get('session');
+if (deepLink) {
+  setTimeout(() => openSession(deepLink), 300);
+}

package/dist/server/public/index.html

@@ -207,6 +207,35 @@
       <span>Local data only · <code>~/.agentobs/agentobs.db</code></span>
     </footer>
 
+
+    <div class="drawer" id="session-drawer" hidden>
+      <div class="drawer-scrim" data-close-drawer></div>
+      <section class="drawer-panel" role="dialog" aria-modal="true" aria-labelledby="drawer-title">
+        <header class="drawer-head">
+          <div>
+            <h2 id="drawer-title">Session</h2>
+            <p class="panel-sub" id="drawer-sub">&nbsp;</p>
+          </div>
+          <button type="button" class="icon-btn" data-close-drawer aria-label="Close">&times;</button>
+        </header>
+        <dl class="drawer-stats" id="drawer-stats"></dl>
+        <div class="table-wrap">
+          <table>
+            <thead>
+              <tr>
+                <th scope="col">#</th>
+                <th scope="col">Status</th>
+                <th scope="col">Tool</th>
+                <th scope="col">Input</th>
+                <th scope="col" class="num">ms</th>
+              </tr>
+            </thead>
+            <tbody id="drawer-calls"></tbody>
+          </table>
+        </div>
+      </section>
+    </div>
+
     <script type="module" src="/app.js"></script>
   </body>
 </html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klars/agentobs",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Observability and control layer for AI coding agents - see every tool call, token, and dollar your agents spend, and stop them before they do something risky.",
   "license": "MIT",
   "author": "Klars AI",