@kill-switch/agent-guard 0.1.0

package/dist/ops.js

@@ -0,0 +1,98 @@
+/**
+ * Operations shared by the standalone `agent-guard` CLI and the `ks guard`
+ * subcommands, so both drive the same logic instead of duplicating it (or
+ * shelling out). Pure side-effecting helpers over config + Claude Code settings.
+ */
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir } from "node:os";
+import { configPath, ensureGuardDir, DEFAULT_BUDGET } from "./config.js";
+import { loadLedger, saveLedger, emptyLedger } from "./ledger.js";
+/**
+ * Wire the agent-guard hook into Claude Code settings for PreToolUse,
+ * UserPromptSubmit, and Stop. Idempotent: re-running adds nothing if the hook
+ * command is already present.
+ */
+export function installHook(cliPath, execPath, opts = {}) {
+    const settingsPath = opts.global
+        ? join(homedir(), ".claude", "settings.json")
+        : join(opts.cwd ?? process.cwd(), ".claude", "settings.json");
+    const command = opts.command || `"${execPath}" "${cliPath}" hook`;
+    let settings = {};
+    try {
+        settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    }
+    catch {
+        /* new file */
+    }
+    settings.hooks ??= {};
+    const ensure = (event, withMatcher) => {
+        settings.hooks[event] ??= [];
+        const blob = JSON.stringify(settings.hooks[event]);
+        if (blob.includes("agent-guard") || blob.includes("cli.js") || blob.includes(command))
+            return false;
+        const entry = { hooks: [{ type: "command", command }] };
+        if (withMatcher)
+            entry.matcher = "*";
+        settings.hooks[event].push(entry);
+        return true;
+    };
+    const added = [];
+    if (ensure("PreToolUse", true))
+        added.push("PreToolUse");
+    if (ensure("UserPromptSubmit", false))
+        added.push("UserPromptSubmit");
+    if (ensure("Stop", false))
+        added.push("Stop");
+    mkdirSync(dirname(settingsPath), { recursive: true });
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    return { settingsPath, command, added };
+}
+/** Write budget/webhook overrides to the config file. Returns the saved budget. */
+export function setBudget(patch) {
+    let file = {};
+    try {
+        file = JSON.parse(readFileSync(configPath(), "utf8"));
+    }
+    catch {
+        /* new */
+    }
+    const budget = { ...DEFAULT_BUDGET, ...(file.budget ?? {}) };
+    const set = (k, v) => {
+        if (v !== undefined && Number.isFinite(v))
+            budget[k] = v;
+    };
+    set("sessionSoftUSD", patch.sessionSoftUSD);
+    set("sessionHardUSD", patch.sessionHardUSD);
+    set("dailySoftUSD", patch.dailySoftUSD);
+    set("dailyHardUSD", patch.dailyHardUSD);
+    file.budget = budget;
+    if (patch.slackWebhook)
+        file.slackWebhook = patch.slackWebhook;
+    ensureGuardDir();
+    writeFileSync(configPath(), JSON.stringify(file, null, 2) + "\n");
+    return budget;
+}
+/** Clear the spend ledger. Scope: all | a single session | today's sessions. */
+export function resetLedger(opts) {
+    if (opts.all) {
+        saveLedger(emptyLedger());
+        return "Ledger wiped.";
+    }
+    const ledger = loadLedger();
+    if (opts.session) {
+        delete ledger.sessions[opts.session];
+        saveLedger(ledger);
+        return `Cleared session ${opts.session}.`;
+    }
+    if (opts.today) {
+        const today = new Date().toISOString().slice(0, 10);
+        for (const [id, s] of Object.entries(ledger.sessions)) {
+            if (new Date(s.lastAt).toISOString().slice(0, 10) === today)
+                delete ledger.sessions[id];
+        }
+        saveLedger(ledger);
+        return "Cleared today's sessions.";
+    }
+    return "Specify all, session <id>, or today.";
+}

package/dist/pricing.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Model pricing table — USD per 1M tokens.
+ *
+ * Mirrors the rates used by the Anthropic/OpenAI provider checkers in the API
+ * package, but adds the cache rates an agent loop actually hits: a coding agent
+ * re-sends its whole context every turn, so cache reads dominate token volume.
+ *
+ * `cacheWrite` / `cacheRead` default to Anthropic's multipliers when omitted:
+ *   cache write (5m) = input * 1.25,  cache read = input * 0.10
+ * Override any of this via ~/.kill-switch/agent-guard/pricing.json (see config.ts).
+ */
+export interface ModelPricing {
+    /** USD per 1M input tokens */
+    input: number;
+    /** USD per 1M output tokens */
+    output: number;
+    /** USD per 1M cache-write tokens (defaults to input * 1.25) */
+    cacheWrite?: number;
+    /** USD per 1M cache-read tokens (defaults to input * 0.10) */
+    cacheRead?: number;
+}
+/**
+ * Keys are normalized model ids (see {@link normalizeModel}). We match by
+ * longest-prefix so dated variants like `claude-3-5-sonnet-20241022` resolve
+ * to the base `claude-3-5-sonnet` entry without enumerating every snapshot.
+ */
+export declare const MODEL_PRICING: Record<string, ModelPricing>;
+/** Used when a model id matches nothing in the table — assume premium Sonnet-class rates so we under-estimate spend never. */
+export declare const FALLBACK_PRICING: ModelPricing;
+/**
+ * Lowercase and strip provider prefixes (`anthropic/`, `openai/`) so ids from
+ * different agents normalize to the same key space.
+ */
+export declare function normalizeModel(model: string): string;
+/**
+ * Resolve pricing for a model id by longest-matching-prefix against the table.
+ * Falls back to {@link FALLBACK_PRICING} (premium rates) when nothing matches —
+ * a kill switch should over-count an unknown model, not under-count it.
+ */
+export declare function pricingFor(model: string, table?: Record<string, ModelPricing>): ModelPricing;

package/dist/pricing.js

@@ -0,0 +1,63 @@
+/**
+ * Model pricing table — USD per 1M tokens.
+ *
+ * Mirrors the rates used by the Anthropic/OpenAI provider checkers in the API
+ * package, but adds the cache rates an agent loop actually hits: a coding agent
+ * re-sends its whole context every turn, so cache reads dominate token volume.
+ *
+ * `cacheWrite` / `cacheRead` default to Anthropic's multipliers when omitted:
+ *   cache write (5m) = input * 1.25,  cache read = input * 0.10
+ * Override any of this via ~/.kill-switch/agent-guard/pricing.json (see config.ts).
+ */
+/**
+ * Keys are normalized model ids (see {@link normalizeModel}). We match by
+ * longest-prefix so dated variants like `claude-3-5-sonnet-20241022` resolve
+ * to the base `claude-3-5-sonnet` entry without enumerating every snapshot.
+ */
+export const MODEL_PRICING = {
+    // Anthropic — Claude
+    "claude-opus-4": { input: 15.0, output: 75.0 },
+    "claude-sonnet-4": { input: 3.0, output: 15.0 },
+    "claude-haiku-4": { input: 0.8, output: 4.0 },
+    "claude-3-7-sonnet": { input: 3.0, output: 15.0 },
+    "claude-3-5-sonnet": { input: 3.0, output: 15.0 },
+    "claude-3-5-haiku": { input: 0.8, output: 4.0 },
+    "claude-3-opus": { input: 15.0, output: 75.0 },
+    "claude-3-sonnet": { input: 3.0, output: 15.0 },
+    "claude-3-haiku": { input: 0.25, output: 1.25 },
+    // OpenAI
+    "gpt-4o": { input: 2.5, output: 10.0 },
+    "gpt-4o-mini": { input: 0.15, output: 0.6 },
+    "gpt-4.1": { input: 2.0, output: 8.0 },
+    "gpt-4.1-mini": { input: 0.4, output: 1.6 },
+    "o3": { input: 2.0, output: 8.0 },
+    "o4-mini": { input: 1.1, output: 4.4 },
+};
+/** Used when a model id matches nothing in the table — assume premium Sonnet-class rates so we under-estimate spend never. */
+export const FALLBACK_PRICING = { input: 3.0, output: 15.0 };
+/**
+ * Lowercase and strip provider prefixes (`anthropic/`, `openai/`) so ids from
+ * different agents normalize to the same key space.
+ */
+export function normalizeModel(model) {
+    return model.toLowerCase().replace(/^(anthropic|openai)\//, "").trim();
+}
+/**
+ * Resolve pricing for a model id by longest-matching-prefix against the table.
+ * Falls back to {@link FALLBACK_PRICING} (premium rates) when nothing matches —
+ * a kill switch should over-count an unknown model, not under-count it.
+ */
+export function pricingFor(model, table = MODEL_PRICING) {
+    const id = normalizeModel(model);
+    if (table[id])
+        return table[id];
+    let best;
+    let bestLen = -1;
+    for (const [key, price] of Object.entries(table)) {
+        if (id.startsWith(key) && key.length > bestLen) {
+            best = price;
+            bestLen = key.length;
+        }
+    }
+    return best ?? FALLBACK_PRICING;
+}

package/dist/proxy.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Token-metering proxy — `agent-guard proxy`.
+ *
+ * A local reverse proxy you point an agent's API base URL at:
+ *   ANTHROPIC_BASE_URL=http://localhost:8787 claude
+ *   OPENAI_BASE_URL=http://localhost:8787/v1 aider
+ *
+ * It forwards every request to the real upstream, parses the *real* usage out of
+ * the response (streaming or not), prices it, and accumulates spend in the shared
+ * ledger. Once the hard cap is reached it stops forwarding and returns HTTP 402 —
+ * a wall the agent cannot argue its way past, regardless of whether it supports
+ * hooks. This is the agent-agnostic backstop to the Claude Code hook.
+ *
+ * Double-count caveat: don't run Claude Code through BOTH the hook and the proxy
+ * — they'd each meter the same dollars. Hook for Claude Code; proxy for everything
+ * else (Cursor, Aider, raw scripts). See README.
+ */
+import { type TokenUsage } from "./cost.js";
+export interface ProxyOptions {
+    port: number;
+    /** Upstream origin, e.g. https://api.anthropic.com */
+    upstream: string;
+    /** "anthropic" | "openai" — controls usage parsing. */
+    flavor: "anthropic" | "openai";
+}
+/** Parse a non-streaming JSON body into usage + model. Exported for testing. */
+export declare function parseJsonUsage(flavor: string, text: string): {
+    model: string;
+    usage: TokenUsage;
+} | null;
+/** Parse accumulated SSE text into usage + model (Anthropic message_start/message_delta, OpenAI final chunk). Exported for testing. */
+export declare function parseStreamUsage(flavor: string, sse: string): {
+    model: string;
+    usage: TokenUsage;
+} | null;
+export declare function startProxy(opts: ProxyOptions): void;
+export declare function resolveUpstream(flavor: string, explicit?: string): string;

package/dist/proxy.js

@@ -0,0 +1,256 @@
+/**
+ * Token-metering proxy — `agent-guard proxy`.
+ *
+ * A local reverse proxy you point an agent's API base URL at:
+ *   ANTHROPIC_BASE_URL=http://localhost:8787 claude
+ *   OPENAI_BASE_URL=http://localhost:8787/v1 aider
+ *
+ * It forwards every request to the real upstream, parses the *real* usage out of
+ * the response (streaming or not), prices it, and accumulates spend in the shared
+ * ledger. Once the hard cap is reached it stops forwarding and returns HTTP 402 —
+ * a wall the agent cannot argue its way past, regardless of whether it supports
+ * hooks. This is the agent-agnostic backstop to the Claude Code hook.
+ *
+ * Double-count caveat: don't run Claude Code through BOTH the hook and the proxy
+ * — they'd each meter the same dollars. Hook for Claude Code; proxy for everything
+ * else (Cursor, Aider, raw scripts). See README.
+ */
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { loadConfig, mergedPricing, isPaused } from "./config.js";
+import { MODEL_PRICING } from "./pricing.js";
+import { costForUsage, fmtUSD } from "./cost.js";
+import { loadLedger, saveLedger, addSessionCost, rollingDailyCost, prune, } from "./ledger.js";
+import { evaluate } from "./budget.js";
+import { dispatchAlert } from "./alert.js";
+const UPSTREAMS = {
+    anthropic: "https://api.anthropic.com",
+    openai: "https://api.openai.com",
+};
+function todayKey(now) {
+    return new Date(now).toISOString().slice(0, 10);
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (c) => chunks.push(c));
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+/** Parse a non-streaming JSON body into usage + model. Exported for testing. */
+export function parseJsonUsage(flavor, text) {
+    try {
+        const body = JSON.parse(text);
+        const u = body.usage;
+        if (!u)
+            return null;
+        if (flavor === "openai") {
+            return {
+                model: body.model || "unknown",
+                usage: { inputTokens: u.prompt_tokens || 0, outputTokens: u.completion_tokens || 0 },
+            };
+        }
+        return {
+            model: body.model || "unknown",
+            usage: {
+                inputTokens: u.input_tokens || 0,
+                outputTokens: u.output_tokens || 0,
+                cacheCreationTokens: u.cache_creation_input_tokens || 0,
+                cacheReadTokens: u.cache_read_input_tokens || 0,
+            },
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Parse accumulated SSE text into usage + model (Anthropic message_start/message_delta, OpenAI final chunk). Exported for testing. */
+export function parseStreamUsage(flavor, sse) {
+    let model = "unknown";
+    const usage = { inputTokens: 0, outputTokens: 0, cacheCreationTokens: 0, cacheReadTokens: 0 };
+    let found = false;
+    for (const line of sse.split("\n")) {
+        const t = line.trim();
+        if (!t.startsWith("data:"))
+            continue;
+        const payload = t.slice(5).trim();
+        if (!payload || payload === "[DONE]")
+            continue;
+        let data;
+        try {
+            data = JSON.parse(payload);
+        }
+        catch {
+            continue;
+        }
+        if (flavor === "anthropic") {
+            if (data.type === "message_start" && data.message?.usage) {
+                const u = data.message.usage;
+                model = data.message.model || model;
+                usage.inputTokens += u.input_tokens || 0;
+                usage.cacheCreationTokens = (usage.cacheCreationTokens || 0) + (u.cache_creation_input_tokens || 0);
+                usage.cacheReadTokens = (usage.cacheReadTokens || 0) + (u.cache_read_input_tokens || 0);
+                found = true;
+            }
+            else if (data.type === "message_delta" && data.usage) {
+                usage.outputTokens += data.usage.output_tokens || 0;
+                found = true;
+            }
+        }
+        else {
+            // OpenAI: usage arrives on the final chunk when stream_options.include_usage is set.
+            if (data.usage) {
+                model = data.model || model;
+                usage.inputTokens += data.usage.prompt_tokens || 0;
+                usage.outputTokens += data.usage.completion_tokens || 0;
+                found = true;
+            }
+        }
+    }
+    return found ? { model, usage } : null;
+}
+function send402(res, sessionUSD, dailyUSD, reasons) {
+    const body = JSON.stringify({
+        type: "error",
+        error: {
+            type: "kill_switch_budget_exceeded",
+            message: `Kill Switch blocked this request: hard spend cap reached. ` +
+                `Session ${fmtUSD(sessionUSD)}, daily ${fmtUSD(dailyUSD)}. ${reasons.join(" ")} ` +
+                `Raise the cap (AGENT_GUARD_SESSION_HARD / AGENT_GUARD_DAILY_HARD) or run \`agent-guard reset\`.`,
+        },
+    });
+    res.writeHead(402, { "content-type": "application/json", "x-kill-switch": "blocked" });
+    res.end(body);
+}
+/** Meter a completed response's usage into the ledger. */
+function meter(cfg, ledger, sessionId, parsed, now) {
+    if (!parsed)
+        return;
+    const pricing = mergedPricing(cfg, MODEL_PRICING);
+    const delta = costForUsage(parsed.model, parsed.usage, pricing);
+    addSessionCost(ledger, sessionId, delta, parsed.usage.inputTokens, parsed.usage.outputTokens, now);
+    prune(ledger, now);
+    saveLedger(ledger);
+}
+export function startProxy(opts) {
+    const cfg = loadConfig();
+    const upstreamOrigin = opts.upstream.replace(/\/$/, "");
+    const blockedNotified = {};
+    const server = createServer(async (req, res) => {
+        const now = Date.now();
+        const sessionId = req.headers["x-agent-guard-session"] || `proxy:${todayKey(now)}`;
+        // 1) Pre-flight budget check — block before spending anything.
+        // Escape hatch: while a human has paused enforcement, never block (but still meter).
+        const ledger = loadLedger();
+        const sessionUSD = ledger.sessions[sessionId]?.costUSD ?? 0;
+        const dailyUSD = rollingDailyCost(ledger, now);
+        const verdict = evaluate({ sessionUSD, dailyUSD }, cfg.budget);
+        if (verdict.level === "block" && !isPaused(now)) {
+            if (!blockedNotified[sessionId]) {
+                blockedNotified[sessionId] = true;
+                dispatchAlert(cfg, {
+                    ts: now, source: "proxy", sessionId, level: "block",
+                    sessionUSD, dailyUSD, reasons: verdict.reasons, action: "returned HTTP 402",
+                }).catch(() => { });
+            }
+            send402(res, sessionUSD, dailyUSD, verdict.reasons);
+            return;
+        }
+        // 2) Forward to upstream.
+        let reqBody;
+        try {
+            reqBody = await readBody(req);
+        }
+        catch {
+            res.writeHead(400).end("bad request body");
+            return;
+        }
+        const targetUrl = `${upstreamOrigin}${req.url ?? "/"}`;
+        const headers = new Headers();
+        for (const [k, v] of Object.entries(req.headers)) {
+            if (v === undefined)
+                continue;
+            const key = k.toLowerCase();
+            if (["host", "content-length", "connection"].includes(key))
+                continue;
+            headers.set(k, Array.isArray(v) ? v.join(", ") : v);
+        }
+        let upstream;
+        try {
+            upstream = await fetch(targetUrl, {
+                method: req.method,
+                headers,
+                body: req.method === "GET" || req.method === "HEAD" ? undefined : new Uint8Array(reqBody),
+            });
+        }
+        catch (err) {
+            res.writeHead(502, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: "kill-switch proxy: upstream fetch failed", detail: String(err) }));
+            return;
+        }
+        // 3) Relay status + headers.
+        const respHeaders = {};
+        upstream.headers.forEach((v, k) => {
+            if (!["content-encoding", "content-length", "transfer-encoding", "connection"].includes(k.toLowerCase())) {
+                respHeaders[k] = v;
+            }
+        });
+        res.writeHead(upstream.status, respHeaders);
+        const isStream = (upstream.headers.get("content-type") || "").includes("text/event-stream");
+        if (!upstream.body) {
+            res.end();
+            return;
+        }
+        // 4) Tee the body: one branch to the client, one to accumulate for metering.
+        const [toClient, toMeter] = upstream.body.tee();
+        // Pipe to client.
+        Readable.fromWeb(toClient).pipe(res);
+        // Accumulate the meter branch, then price it.
+        (async () => {
+            try {
+                const reader = toMeter.getReader();
+                const decoder = new TextDecoder();
+                let buf = "";
+                // Cap accumulation for non-stream JSON to avoid holding giant bodies; SSE we need fully.
+                for (;;) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    buf += decoder.decode(value, { stream: true });
+                }
+                const parsed = isStream
+                    ? parseStreamUsage(opts.flavor, buf)
+                    : parseJsonUsage(opts.flavor, buf);
+                // Re-load ledger (the request may have been concurrent) and meter.
+                const fresh = loadLedger();
+                meter(cfg, fresh, sessionId, parsed, Date.now());
+                // Post-meter soft-cap alert (once).
+                const after = fresh.sessions[sessionId]?.costUSD ?? 0;
+                const afterDaily = rollingDailyCost(fresh, Date.now());
+                const v2 = evaluate({ sessionUSD: after, dailyUSD: afterDaily }, cfg.budget);
+                if (v2.level === "warn" && !blockedNotified[`warn:${sessionId}`]) {
+                    blockedNotified[`warn:${sessionId}`] = true;
+                    dispatchAlert(cfg, {
+                        ts: Date.now(), source: "proxy", sessionId, level: "warn",
+                        sessionUSD: after, dailyUSD: afterDaily, reasons: v2.reasons, action: "soft cap warning",
+                    }).catch(() => { });
+                }
+            }
+            catch {
+                /* metering must never break the proxied response */
+            }
+        })();
+    });
+    server.listen(opts.port, () => {
+        process.stdout.write(`🛡  agent-guard proxy on http://localhost:${opts.port} → ${upstreamOrigin} (${opts.flavor})\n` +
+            `   Caps: session hard ${fmtUSD(cfg.budget.sessionHardUSD)}, daily hard ${fmtUSD(cfg.budget.dailyHardUSD)}\n` +
+            `   Point your agent at it, e.g.:\n` +
+            (opts.flavor === "anthropic"
+                ? `     ANTHROPIC_BASE_URL=http://localhost:${opts.port} claude\n`
+                : `     OPENAI_BASE_URL=http://localhost:${opts.port}/v1 aider\n`));
+    });
+}
+export function resolveUpstream(flavor, explicit) {
+    return explicit || UPSTREAMS[flavor] || UPSTREAMS.anthropic;
+}

package/dist/report.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Shared status report — the single computation behind `agent-guard status` and
+ * `ks guard status`, so both emit an identical JSON shape and never drift.
+ */
+import { type SessionRecord } from "./ledger.js";
+import { type Budget, type VerdictLevel } from "./budget.js";
+export interface StatusReport {
+    budget: Budget;
+    dailyUSD: number;
+    verdict: VerdictLevel;
+    reasons: string[];
+    paused: boolean;
+    /** Epoch ms the pause auto-expires, or null (indefinite / not paused). */
+    pauseUntil: number | null;
+    sessions: Array<{
+        id: string;
+    } & SessionRecord>;
+}
+/** Build the current status report from the on-disk config + ledger. */
+export declare function buildStatusReport(now?: number): StatusReport;

package/dist/report.js

@@ -0,0 +1,30 @@
+/**
+ * Shared status report — the single computation behind `agent-guard status` and
+ * `ks guard status`, so both emit an identical JSON shape and never drift.
+ */
+import { loadConfig } from "./config.js";
+import { isPaused, pauseExpiry } from "./config.js";
+import { loadLedger, rollingDailyCost } from "./ledger.js";
+import { evaluate } from "./budget.js";
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Build the current status report from the on-disk config + ledger. */
+export function buildStatusReport(now = Date.now()) {
+    const cfg = loadConfig();
+    const ledger = loadLedger();
+    const dailyUSD = rollingDailyCost(ledger, now);
+    const sessions = Object.entries(ledger.sessions)
+        .filter(([, s]) => now - s.lastAt < DAY_MS)
+        .sort((a, b) => b[1].lastAt - a[1].lastAt)
+        .map(([id, s]) => ({ id, ...s }));
+    const topSession = sessions[0]?.costUSD ?? 0;
+    const verdict = evaluate({ sessionUSD: topSession, dailyUSD }, cfg.budget);
+    return {
+        budget: cfg.budget,
+        dailyUSD,
+        verdict: verdict.level,
+        reasons: verdict.reasons,
+        paused: isPaused(now),
+        pauseUntil: pauseExpiry(),
+        sessions,
+    };
+}

package/dist/transcript.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Parse a Claude Code transcript (JSONL) into total token usage by model.
+ *
+ * Claude Code passes `transcript_path` in every hook payload. Each line is a
+ * JSON event; assistant turns carry `message.usage` with input/output and the
+ * two cache buckets, plus `message.model`. We sum per model so the hook can
+ * price a mixed-model session correctly. Malformed lines are skipped — a parse
+ * error must never wedge the kill switch.
+ */
+import type { TokenUsage } from "./cost.js";
+export interface TranscriptTotals {
+    byModel: Map<string, TokenUsage>;
+    lines: number;
+}
+export declare function parseTranscript(path: string): TranscriptTotals;

package/dist/transcript.js

@@ -0,0 +1,52 @@
+/**
+ * Parse a Claude Code transcript (JSONL) into total token usage by model.
+ *
+ * Claude Code passes `transcript_path` in every hook payload. Each line is a
+ * JSON event; assistant turns carry `message.usage` with input/output and the
+ * two cache buckets, plus `message.model`. We sum per model so the hook can
+ * price a mixed-model session correctly. Malformed lines are skipped — a parse
+ * error must never wedge the kill switch.
+ */
+import { readFileSync } from "node:fs";
+function addUsage(into, u) {
+    into.inputTokens += u.input_tokens || 0;
+    into.outputTokens += u.output_tokens || 0;
+    into.cacheCreationTokens = (into.cacheCreationTokens || 0) + (u.cache_creation_input_tokens || 0);
+    into.cacheReadTokens = (into.cacheReadTokens || 0) + (u.cache_read_input_tokens || 0);
+}
+export function parseTranscript(path) {
+    const byModel = new Map();
+    let lines = 0;
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return { byModel, lines };
+    }
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        lines++;
+        let evt;
+        try {
+            evt = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        const msg = evt?.message;
+        const usage = msg?.usage;
+        if (!usage)
+            continue;
+        const model = msg.model || "unknown";
+        let acc = byModel.get(model);
+        if (!acc) {
+            acc = { inputTokens: 0, outputTokens: 0, cacheCreationTokens: 0, cacheReadTokens: 0 };
+            byModel.set(model, acc);
+        }
+        addUsage(acc, usage);
+    }
+    return { byModel, lines };
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@kill-switch/agent-guard",
+  "version": "0.1.0",
+  "description": "Kill Switch for coding agents — stop runaway Claude Code / Cursor / Aider sessions from racking up an LLM bill. Native hook + token-metering proxy with per-session and daily-rolling budgets.",
+  "type": "module",
+  "bin": {
+    "agent-guard": "./dist/cli.js",
+    "ksg": "./dist/cli.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "keywords": [
+    "kill-switch",
+    "claude-code",
+    "coding-agent",
+    "llm-cost",
+    "token-budget",
+    "anthropic",
+    "openai",
+    "cursor",
+    "aider",
+    "finops",
+    "guardrail"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/divinci-ai/kill-switch",
+    "directory": "packages/agent-guard"
+  },
+  "homepage": "https://kill-switch.net",
+  "license": "MIT"
+}