@klars/agentobs 0.1.0

package/dist/adapters/process-wrap.js

@@ -0,0 +1,141 @@
+/**
+ * Process-wrap adapter: `agentobs run -- <command...>`.
+ *
+ * The universal fallback. It works with any agent CLI - present or future,
+ * instrumented or not - because it observes the process rather than the
+ * agent. What it gets in exchange for that generality is coarse data:
+ * start, end, duration, exit code, and nothing about individual tool calls.
+ *
+ * That limit is recorded as fidelity='coarse' and shown in the dashboard, so
+ * a coarse session is never mistaken for a detailed one.
+ */
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { execSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createSink } from './sink.js';
+/** Best-effort current git branch; null outside a repo. */
+function currentBranch(cwd) {
+    try {
+        return execSync('git rev-parse --abbrev-ref HEAD', {
+            cwd,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            encoding: 'utf8',
+            timeout: 1000,
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Runs a command under observation, returning its exit code.
+ *
+ * stdio is inherited so the wrapped agent stays fully interactive - the user
+ * should not be able to tell AgentObs is in the middle. That is also why we
+ * never buffer or parse the output here.
+ */
+export async function runWrapped(command, opts = {}) {
+    if (command.length === 0)
+        throw new Error('no command given to run');
+    const cwd = opts.cwd ?? process.cwd();
+    const agentName = opts.agentName ?? command[0].replace(/\.(exe|cmd|bat)$/i, '');
+    const sessionId = randomUUID();
+    const sink = createSink(agentName);
+    sink({
+        type: 'session_start',
+        sessionId,
+        agentName,
+        cwd,
+        gitBranch: currentBranch(cwd),
+        fidelity: 'coarse',
+    });
+    return new Promise((resolve) => {
+        // On Windows, resolve the executable ourselves rather than reaching for
+        // `shell: true`. Under a shell, arguments are concatenated instead of
+        // escaped (Node DEP0190), so any argument containing a space or a quote
+        // is silently mangled before the wrapped agent ever sees it - which for
+        // an agent CLI means a corrupted prompt.
+        //
+        // Resolving the .cmd/.bat shim directly keeps npm-installed CLIs working
+        // (`agentobs run -- claude`) while spawn still escapes each argument.
+        const executable = process.platform === 'win32' ? resolveWindowsExecutable(command[0]) : command[0];
+        const child = spawn(executable, command.slice(1), {
+            cwd,
+            stdio: 'inherit',
+            // A .cmd shim is a batch script, so it does need a shell interpreter -
+            // but only for the shim itself, and cmd.exe applies its own escaping.
+            shell: /\.(cmd|bat)$/i.test(executable),
+            windowsHide: true,
+        });
+        const finish = (code) => {
+            sink({ type: 'session_end', sessionId, exitCode: code });
+            resolve(code);
+        };
+        child.on('error', (err) => {
+            // Spawn failure (command not found) - record it as a failed session
+            // rather than losing the attempt entirely.
+            console.error(`[agentobs] failed to start ${command[0]}: ${err.message}`);
+            finish(127);
+        });
+        child.on('close', (code, signal) => {
+            // A signal-terminated process reports code=null; map it to the shell
+            // convention (128 + signal number) so the stored value is never null
+            // for a run that genuinely ended.
+            if (code === null && signal) {
+                finish(128 + (signalNumber(signal) ?? 0));
+                return;
+            }
+            finish(code ?? 0);
+        });
+        // Forward interrupts so Ctrl-C reaches the agent rather than only
+        // killing the wrapper and orphaning it.
+        for (const sig of ['SIGINT', 'SIGTERM']) {
+            process.on(sig, () => {
+                if (!child.killed)
+                    child.kill(sig);
+            });
+        }
+    });
+}
+/**
+ * Finds the real file behind a bare command name on Windows.
+ *
+ * Windows has no execvp: `spawn("npm")` fails because the thing on PATH is
+ * `npm.cmd`, not `npm`. The usual workaround is `shell: true`, but that
+ * disables argument escaping (see the call site). Walking PATH + PATHEXT
+ * ourselves keeps both properties: bare names resolve, and arguments stay
+ * escaped.
+ *
+ * Falls back to the original name when nothing matches, so spawn produces its
+ * normal ENOENT rather than this function inventing a different failure.
+ */
+function resolveWindowsExecutable(command) {
+    if (command.includes('/') || command.includes('\\'))
+        return command;
+    const exts = (process.env.PATHEXT ?? '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean);
+    const dirs = (process.env.PATH ?? '').split(';').filter(Boolean);
+    for (const dir of dirs) {
+        for (const ext of ['', ...exts]) {
+            const candidate = join(dir, command + ext.toLowerCase());
+            if (existsSync(candidate))
+                return candidate;
+            const upper = join(dir, command + ext);
+            if (existsSync(upper))
+                return upper;
+        }
+    }
+    return command;
+}
+function signalNumber(signal) {
+    const table = {
+        SIGHUP: 1,
+        SIGINT: 2,
+        SIGQUIT: 3,
+        SIGKILL: 9,
+        SIGTERM: 15,
+    };
+    return table[signal] ?? null;
+}
+//# sourceMappingURL=process-wrap.js.map

package/dist/adapters/sink.js

@@ -0,0 +1,65 @@
+import { openDb } from '../core/db.js';
+import { beginToolCall, completeToolCall, endSession, ensureSession, startSession, } from '../core/repo.js';
+export function applyEvent(db, event, agentName) {
+    switch (event.type) {
+        case 'session_start':
+            startSession(db, {
+                id: event.sessionId,
+                agentName: event.agentName ?? agentName,
+                cwd: event.cwd,
+                gitBranch: event.gitBranch,
+                fidelity: event.fidelity ?? 'rich',
+                startedAt: event.timestamp,
+            });
+            break;
+        case 'session_end':
+            endSession(db, event.sessionId, { exitCode: event.exitCode, endedAt: event.timestamp });
+            break;
+        case 'tool_call_start':
+            // The parent session may never have been announced (agent started
+            // before AgentObs was installed, or no SessionStart hook configured).
+            // Synthesising it beats dropping the tool call.
+            ensureSession(db, event.sessionId, agentName);
+            beginToolCall(db, {
+                id: event.toolCallId,
+                sessionId: event.sessionId,
+                toolName: event.toolName,
+                input: event.input,
+                model: event.model,
+                startedAt: event.timestamp,
+            });
+            break;
+        case 'tool_call_end':
+            completeToolCall(db, event.toolCallId, {
+                status: event.status,
+                output: event.output,
+                tokensIn: event.tokensIn,
+                tokensOut: event.tokensOut,
+                model: event.model,
+                errorMessage: event.errorMessage,
+                endedAt: event.timestamp,
+            });
+            break;
+    }
+}
+/**
+ * Creates a sink bound to the local database.
+ *
+ * Swallows and logs errors by design: an adapter runs inside the user's
+ * agent, so a logging failure must degrade to missing data, never to a
+ * crashed agent.
+ */
+export function createSink(agentName, db) {
+    const handle = db ?? openDb();
+    return (event) => {
+        try {
+            applyEvent(handle, event, agentName);
+        }
+        catch (err) {
+            if (process.env.AGENTOBS_DEBUG) {
+                console.error(`[agentobs] failed to record ${event.type}:`, err);
+            }
+        }
+    };
+}
+//# sourceMappingURL=sink.js.map

package/dist/adapters/transcript.js

@@ -0,0 +1,88 @@
+/**
+ * Token usage recovery from a Claude Code transcript.
+ *
+ * Claude Code's hook payloads carry no token or cost fields - verified
+ * against the hooks reference, and the reason nothing in the hook path ever
+ * sets a token count. The transcript JSONL the agent writes for itself does
+ * carry per-message `usage` blocks, so that is where real numbers come from.
+ *
+ * The trade-off this accepts: usage is per assistant *message*, not per tool
+ * call, so it is attributed to the session rather than split across the
+ * individual calls inside it. Session-level cost is therefore accurate;
+ * per-tool-call cost stays null for hook-sourced data rather than being
+ * fabricated by dividing a total.
+ */
+import { createReadStream, existsSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { computeCost } from '../core/pricing.js';
+/**
+ * Sums the usage blocks in a transcript.
+ *
+ * Streams line-by-line rather than reading the file: a long session's
+ * transcript can be tens of megabytes, and this runs inside a SessionEnd hook
+ * with a tight time budget.
+ */
+export async function readTranscriptUsage(file) {
+    const total = {
+        tokensIn: 0,
+        tokensOut: 0,
+        cacheReadTokens: 0,
+        cacheCreationTokens: 0,
+        model: null,
+        messages: 0,
+    };
+    if (!existsSync(file))
+        return total;
+    const rl = createInterface({
+        input: createReadStream(file, { encoding: 'utf8' }),
+        crlfDelay: Infinity,
+    });
+    for await (const line of rl) {
+        if (!line.trim())
+            continue;
+        let row;
+        try {
+            row = JSON.parse(line);
+        }
+        catch {
+            continue; // a partially-flushed final line is normal while tailing
+        }
+        // The shape has moved between versions, so check both the top level and
+        // a nested `message` object rather than assuming one layout.
+        const message = (row.message ?? row);
+        const usage = message.usage;
+        if (!usage || typeof usage !== 'object')
+            continue;
+        total.tokensIn += usage.input_tokens ?? 0;
+        total.tokensOut += usage.output_tokens ?? 0;
+        total.cacheReadTokens += usage.cache_read_input_tokens ?? 0;
+        total.cacheCreationTokens += usage.cache_creation_input_tokens ?? 0;
+        total.messages += 1;
+        const model = message.model;
+        if (typeof model === 'string' && model)
+            total.model = model;
+    }
+    return total;
+}
+/**
+ * Writes recovered usage onto the session row.
+ *
+ * Cost counts cache-read tokens at the full input rate, which slightly
+ * over-states spend for cache-heavy sessions. That direction is deliberate:
+ * pricing.json has no cache tier for most models, and over-reporting is the
+ * safer error for a spend figure. It is also why the number is only claimed
+ * as session-level.
+ */
+export async function attachTranscriptUsage(db, sessionId, transcriptPath) {
+    const usage = await readTranscriptUsage(transcriptPath);
+    if (usage.messages === 0)
+        return usage;
+    const billableIn = usage.tokensIn + usage.cacheReadTokens + usage.cacheCreationTokens;
+    const cost = computeCost(usage.model, billableIn, usage.tokensOut);
+    db.prepare(`UPDATE sessions
+        SET total_tokens_in = ?, total_tokens_out = ?, total_cost_usd = ?,
+            updated_at = ?, synced_at = NULL
+      WHERE id = ?`).run(billableIn, usage.tokensOut, cost, new Date().toISOString(), sessionId);
+    return usage;
+}
+//# sourceMappingURL=transcript.js.map

package/dist/adapters/types.js

@@ -0,0 +1,12 @@
+/**
+ * The adapter plugin interface.
+ *
+ * An adapter's job is to turn one agent's native output into AgentEvents.
+ * Everything downstream - storage, redaction, pricing, the dashboard - is
+ * shared, so a new agent integration only has to answer "how do I observe
+ * this tool?" and never "how do I store it?".
+ *
+ * See CONTRIBUTING.md for a worked example of adding one.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/cli.js

@@ -0,0 +1,108 @@
+/**
+ * AgentObs CLI.
+ *
+ * Command bodies live in ./commands/*; this file only wires up the grammar so
+ * `--help` stays the single readable map of what the tool does.
+ */
+import { Command } from 'commander';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+export function buildProgram() {
+    const program = new Command();
+    program
+        .name('agentobs')
+        .description('Observability and control for AI coding agents')
+        .version(pkg.version);
+    program
+        .command('init')
+        .description('Create ~/.agentobs, the database, and print the Claude Code hook config')
+        .option('--force', 'overwrite an existing pricing.json / policy.json', false)
+        .action(async (opts) => {
+        const { init } = await import('./commands/init.js');
+        await init(opts);
+    });
+    program
+        .command('dashboard')
+        .description('Serve the local dashboard')
+        .option('-p, --port <number>', 'port to listen on', '4300')
+        .option('--host <address>', 'address to bind (non-loopback requires a token)', '127.0.0.1')
+        .option('--token <value>', 'shared token required when binding a non-loopback address')
+        .option('--no-open', 'do not open a browser window')
+        .action(async (opts) => {
+        const { dashboard } = await import('./commands/dashboard.js');
+        await dashboard(opts);
+    });
+    program
+        .command('stats')
+        .description('Print usage totals')
+        .option('--today', 'today only')
+        .option('--since <range>', 'one of: today, 7d, 30d, all', '7d')
+        .option('--session <id>', 'restrict to one session')
+        .option('--json', 'emit JSON instead of a table', false)
+        .action(async (opts) => {
+        const { stats } = await import('./commands/stats.js');
+        await stats(opts);
+    });
+    program
+        .command('watch')
+        .argument('<file>', 'JSONL file to tail')
+        .description('Ingest a newline-delimited JSON agent log')
+        .option('--agent <name>', 'agent name to record', 'generic')
+        .option('--no-follow', 'process existing lines then exit')
+        .action(async (file, opts) => {
+        const { watch } = await import('./commands/watch.js');
+        await watch(file, opts);
+    });
+    program
+        .command('run')
+        .description('Run a command under observation (coarse: duration and exit code)')
+        .argument('<command...>', 'command to run, after --')
+        .option('--agent <name>', 'agent name to record')
+        .allowUnknownOption()
+        .action(async (command, opts) => {
+        const { run } = await import('./commands/run.js');
+        await run(command, opts);
+    });
+    program
+        .command('export')
+        .description('Export recorded data')
+        .requiredOption('--format <format>', 'csv or json')
+        .option('--out <path>', 'output file (defaults to stdout)')
+        .option('--table <name>', 'sessions, tool-calls, or policy-decisions', 'tool-calls')
+        .option('--since <range>', 'today, 7d, 30d, all', 'all')
+        .action(async (opts) => {
+        const { exportData } = await import('./commands/export.js');
+        await exportData(opts);
+    });
+    const policy = program.command('policy').description('Guardrail policy management');
+    policy
+        .command('init')
+        .description('Write a starter ~/.agentobs/policy.json')
+        .action(async () => {
+        const { policyInit } = await import('./commands/policy.js');
+        await policyInit();
+    });
+    policy
+        .command('check')
+        .description('Validate the policy file and list active rules')
+        .action(async () => {
+        const { policyCheck } = await import('./commands/policy.js');
+        await policyCheck();
+    });
+    policy
+        .command('test')
+        .description('Dry-run a hypothetical tool call against the policy')
+        .argument('<tool>', 'tool name, e.g. Bash')
+        .argument('<input...>', 'the command or path to test')
+        .action(async (tool, input) => {
+        const { policyTest } = await import('./commands/policy.js');
+        await policyTest(tool, input.join(' '));
+    });
+    return program;
+}
+export async function main(argv) {
+    const program = buildProgram();
+    await program.parseAsync(argv);
+}
+//# sourceMappingURL=cli.js.map

package/dist/commands/dashboard.js

@@ -0,0 +1,45 @@
+/**
+ * `agentobs dashboard` - serves the local UI.
+ */
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { isLoopback, startDashboard } from '../server/index.js';
+export async function dashboard(opts) {
+    const port = Number(opts.port) || 4300;
+    const host = opts.host || '127.0.0.1';
+    const loopback = isLoopback(host);
+    // Binding beyond loopback exposes tool inputs and file paths to the local
+    // network, so it always requires a token. One is minted rather than
+    // refusing outright, because sharing a dashboard on a trusted LAN is a
+    // legitimate thing to want.
+    const token = loopback ? null : (opts.token ?? randomBytes(16).toString('hex'));
+    const { port: actual } = await startDashboard({ port, host, token });
+    const url = `http://${loopback ? '127.0.0.1' : host}:${actual}${token ? `?token=${token}` : ''}`;
+    console.log(`AgentObs dashboard: ${url}`);
+    if (!loopback) {
+        console.log(`
+  Bound to ${host} - reachable from your network.
+  A token is required; it is already in the URL above.
+  Never expose this to the public internet.`);
+    }
+    console.log('\nPress Ctrl-C to stop.');
+    if (opts.open !== false)
+        openBrowser(url);
+}
+function openBrowser(url) {
+    const [cmd, args] = process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', url]]
+        : process.platform === 'darwin'
+            ? ['open', [url]]
+            : ['xdg-open', [url]];
+    try {
+        // Detached and unref'd so the browser process never keeps the server
+        // alive, and a headless box without a browser fails silently rather than
+        // taking the dashboard down with it.
+        spawn(cmd, args, { detached: true, stdio: 'ignore' }).unref();
+    }
+    catch {
+        /* no browser available - the URL is printed above */
+    }
+}
+//# sourceMappingURL=dashboard.js.map

package/dist/commands/export.js

@@ -0,0 +1,72 @@
+/**
+ * `agentobs export` - CSV/JSON extraction.
+ *
+ * Exported summaries are already redacted, because redaction happens on write
+ * rather than on read. An export can therefore be shared or attached to a
+ * ticket without a separate scrubbing step.
+ */
+import { writeFileSync } from 'node:fs';
+import { openDb } from '../core/db.js';
+import { getPolicyDecisions, getRecentToolCalls, getSessions } from '../core/queries.js';
+function toRange(value) {
+    return value === 'today' || value === '7d' || value === '30d' || value === 'all' ? value : 'all';
+}
+/**
+ * RFC 4180 CSV escaping.
+ *
+ * Tool inputs routinely contain commas, quotes and newlines, so every field is
+ * quoted and inner quotes doubled - a naive join would silently corrupt the
+ * column layout of any row containing a shell command.
+ */
+function csvCell(value) {
+    if (value === null || value === undefined)
+        return '';
+    const str = String(value);
+    return `"${str.replace(/"/g, '""')}"`;
+}
+function toCsv(rows) {
+    if (rows.length === 0)
+        return '';
+    const headers = Object.keys(rows[0]);
+    const lines = [headers.join(',')];
+    for (const row of rows) {
+        lines.push(headers.map((h) => csvCell(row[h])).join(','));
+    }
+    return lines.join('\n') + '\n';
+}
+export async function exportData(opts) {
+    const format = opts.format.toLowerCase();
+    if (format !== 'csv' && format !== 'json') {
+        console.error(`Unsupported format "${opts.format}". Use csv or json.`);
+        process.exitCode = 2;
+        return;
+    }
+    const db = openDb();
+    const range = toRange(opts.since);
+    const table = opts.table ?? 'tool-calls';
+    let rows;
+    switch (table) {
+        case 'sessions':
+            rows = getSessions(db, { range, limit: 500 });
+            break;
+        case 'policy-decisions':
+            rows = getPolicyDecisions(db, { limit: 500 });
+            break;
+        case 'tool-calls':
+            rows = getRecentToolCalls(db, { range, limit: 500 });
+            break;
+        default:
+            console.error(`Unknown table "${table}". Use sessions, tool-calls, or policy-decisions.`);
+            process.exitCode = 2;
+            return;
+    }
+    const body = format === 'json' ? `${JSON.stringify(rows, null, 2)}\n` : toCsv(rows);
+    if (opts.out) {
+        writeFileSync(opts.out, body, 'utf8');
+        console.log(`Wrote ${rows.length} row(s) to ${opts.out}`);
+    }
+    else {
+        process.stdout.write(body);
+    }
+}
+//# sourceMappingURL=export.js.map

package/dist/commands/hook-config.js

@@ -0,0 +1,59 @@
+/**
+ * Generates the Claude Code hook settings block.
+ *
+ * Shape verified against Claude Code's hooks reference: a `hooks` object keyed
+ * by event name, each holding matcher groups whose `hooks` array carries
+ * `{ type: "command", command }`. The matcher is a pipe-separated list of
+ * literal tool names (or a regex); an empty matcher means "every tool".
+ *
+ * One binary serves every event and branches on `hook_event_name`, which keeps
+ * the user's settings file short and means an upgrade never requires them to
+ * re-paste a different set of commands.
+ */
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { existsSync } from 'node:fs';
+/**
+ * Absolute path to the agentobs-hook entrypoint.
+ *
+ * An absolute path is used rather than the bare command name because Claude
+ * Code runs hooks with a non-login shell whose PATH often omits the npm global
+ * bin directory - the most common reason a hook silently never fires.
+ */
+export function hookCommandPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // dist/commands -> package root
+    const candidate = resolve(here, '..', '..', 'bin', 'agentobs-hook');
+    if (existsSync(candidate))
+        return candidate;
+    return 'agentobs-hook';
+}
+/** The events worth hooking, with the matcher each one needs. */
+const EVENTS = [
+    // Empty matcher: observe (and police) every tool, not a hand-listed subset
+    // that would silently miss MCP tools and anything added in future.
+    { event: 'PreToolUse', matcher: '' },
+    { event: 'PostToolUse', matcher: '' },
+    { event: 'SessionStart' },
+    { event: 'SessionEnd' },
+];
+export function buildHookSettings(command) {
+    const hooks = {};
+    for (const { event, matcher } of EVENTS) {
+        const group = {};
+        if (matcher !== undefined)
+            group.matcher = matcher;
+        group.hooks = [{ type: 'command', command }];
+        hooks[event] = [group];
+    }
+    return { hooks };
+}
+export function renderHookSettings(command) {
+    // Quote the path for JSON; Windows paths carry backslashes that must escape.
+    return JSON.stringify(buildHookSettings(command), null, 2);
+}
+/** Path to the user-level Claude Code settings file, for messaging only. */
+export function claudeSettingsPath(homeDir) {
+    return join(homeDir, '.claude', 'settings.json');
+}
+//# sourceMappingURL=hook-config.js.map

package/dist/commands/init.js

@@ -0,0 +1,45 @@
+/**
+ * `agentobs init` - first-run setup.
+ *
+ * Creates the home directory, the database, a starter pricing table, and
+ * prints the exact Claude Code hook block for the user to paste. The printed
+ * config is the whole onboarding experience, so it is copy-paste ready with
+ * absolute paths already filled in rather than placeholders to edit.
+ */
+import { existsSync, writeFileSync } from 'node:fs';
+import { closeDb, ensureDeviceId, openDb } from '../core/db.js';
+import { ensureHome, paths } from '../core/paths.js';
+import { DEFAULT_PRICING, writeDefaultPricing } from '../core/pricing.js';
+import { hookCommandPath, renderHookSettings } from './hook-config.js';
+export async function init(opts = {}) {
+    const home = ensureHome();
+    const db = openDb();
+    const deviceId = ensureDeviceId(db);
+    closeDb();
+    if (opts.force && existsSync(paths.pricing())) {
+        writeFileSync(paths.pricing(), `${JSON.stringify(DEFAULT_PRICING, null, 2)}\n`, 'utf8');
+    }
+    else {
+        writeDefaultPricing();
+    }
+    console.log(`AgentObs initialised.
+
+  Home      ${home}
+  Database  ${paths.db()}
+  Pricing   ${paths.pricing()}
+  Device    ${deviceId}
+
+Next: add this to your Claude Code settings so tool calls are recorded.
+File: ~/.claude/settings.json  (or .claude/settings.json for one project)
+`);
+    console.log(renderHookSettings(hookCommandPath()));
+    console.log(`
+Then:
+  agentobs dashboard          open the dashboard at http://127.0.0.1:4300
+  agentobs run -- <command>   observe any other agent CLI (coarse detail)
+  agentobs policy init        add guardrails that can block risky tool calls
+
+Nothing leaves this machine. Tool inputs are truncated and secret-redacted
+before they are written to disk.`);
+}
+//# sourceMappingURL=init.js.map