@compaction/cli 0.1.4 → 0.3.0

package/dist/core/gateway/server.js

@@ -0,0 +1,276 @@
+/**
+ * Compaction Gateway server — RECORD MODE (PUBLIC CLI/SDK code — engine-free). Charter run-15.
+ *
+ * A LOCAL, byte-safe, OpenAI-compatible reverse proxy: a developer points their OpenAI client's base URL
+ * at this gateway; the gateway forwards the request to the real provider BYTE-FOR-BYTE, streams the
+ * response back BYTE-FOR-BYTE, and records ONE content-free receipt (`receipt.ts`) with the provider's
+ * reported token/cache usage. It NEVER mutates the request or the response (model-visible bytes
+ * unchanged), NEVER stores content, and NEVER persists the client's API key.
+ *
+ * Run-15 implements ONLY `record` mode (no cache-optimization, no apply, no LCM). Built on `node:http`
+ * (the repo's server style — see `apps/api/src/server.ts`); zero new dependency.
+ */
+import http from "node:http";
+import https from "node:https";
+import { URL } from "node:url";
+import { buildGatewayReceipt, appendGatewayReceipt, formatFreshBilledInputReduction } from "./receipt.js";
+import { usageFromResponseBody } from "./openai-usage.js";
+import { resolveApplyActivation } from "./apply-activation.js";
+import { planDeterministicDedupe } from "./apply-policy.js";
+import { saveOriginalForRecovery } from "./recovery.js";
+import { buildApplyReceipt } from "./apply-receipt.js";
+/** How much of the RESPONSE tail to keep for usage parsing (bounded — never the whole body). */
+const USAGE_TAIL_BYTES = 64 * 1024;
+/** Cap the buffered REQUEST body (forwarded verbatim). Large enough for any normal chat request. */
+const MAX_REQUEST_BYTES = 25 * 1024 * 1024;
+/** Hop-by-hop headers that must NOT be blindly forwarded (node manages the connection). */
+const HOP_BY_HOP = new Set(["connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer", "transfer-encoding", "upgrade"]);
+/** Best-effort, content-free extraction of the `model` field from a request body (metadata, not content). */
+function requestModel(body) {
+    const text = body.toString("utf8").trim();
+    if (!text.startsWith("{"))
+        return undefined;
+    try {
+        const obj = JSON.parse(text);
+        return typeof obj.model === "string" ? obj.model : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read the full request body into a Buffer (byte-exact, for verbatim forwarding). */
+function readRequestBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (c) => {
+            size += c.length;
+            if (size > MAX_REQUEST_BYTES) {
+                reject(new Error("request body exceeds gateway limit"));
+                req.destroy();
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+/**
+ * Create (but do not start) the gateway record-mode server. `createGatewayServer` is exported so tests
+ * can bind an ephemeral port. Every request is forwarded byte-for-byte; the receipt append is
+ * best-effort and NEVER alters or delays the client's response bytes.
+ */
+export function createGatewayServer(options) {
+    if (options.mode !== "record" && options.mode !== "apply" && options.mode !== "dry-run") {
+        // The server refuses to pretend to support a mode it does not implement.
+        throw new Error(`gateway mode '${options.mode}' is not implemented (record | apply | dry-run)`);
+    }
+    const log = options.log ?? (() => { });
+    const upstreamOrigin = new URL(options.upstream).origin;
+    return http.createServer((req, res) => {
+        void handleProxy(req, res, options, upstreamOrigin, log);
+    });
+}
+async function handleProxy(req, res, options, upstreamOrigin, log) {
+    const endpoint = (req.url ?? "/").split("?")[0];
+    // Optional CLIENT-SET proof-run grouping id — READ ONLY (an opaque label, not content). The gateway
+    // never injects/mutates the request; this header (when the client sends it) is forwarded to the
+    // upstream unchanged AND recorded on the receipt so a manual proof run can pair its receipts.
+    const proofHeader = req.headers["x-compaction-proof-run"];
+    const proofRunId = typeof proofHeader === "string" && proofHeader.trim() !== "" ? proofHeader : undefined;
+    let requestBody;
+    try {
+        requestBody = await readRequestBody(req);
+    }
+    catch {
+        if (!res.headersSent)
+            res.writeHead(413, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: { message: "compaction gateway: request body too large", type: "gateway_error" } }));
+        return;
+    }
+    // Resolve EXPLICIT apply activation (default record → byte-safe passthrough, exactly as before). Apply
+    // requires the server's `--mode apply --policy …` OR the request's x-compaction-mode/-policy headers;
+    // a conflict fails closed (record). The ORIGINAL request bytes are the default forwarded body.
+    const activation = resolveApplyActivation({
+        serverMode: options.mode,
+        ...(options.policy ? { serverPolicy: options.policy } : {}),
+        ...(headerValue(req.headers["x-compaction-mode"]) ? { headerMode: headerValue(req.headers["x-compaction-mode"]) } : {}),
+        ...(headerValue(req.headers["x-compaction-policy"]) ? { headerPolicy: headerValue(req.headers["x-compaction-policy"]) } : {})
+    });
+    let bodyToForward = requestBody;
+    const apply = resolveApplyOutcome(activation, endpoint, req.method, requestBody, options, log);
+    if (apply?.applied && apply.mutatedBody)
+        bodyToForward = apply.mutatedBody;
+    const target = new URL((req.url ?? "/"), upstreamOrigin);
+    const client = target.protocol === "http:" ? http : https;
+    // Forward headers verbatim EXCEPT host (must be the upstream host), content-length (recomputed from the
+    // forwarded body), hop-by-hop headers, and Compaction's own control headers (mode/policy are local-only
+    // and are NEVER sent upstream). The client's Authorization rides through untouched and is NEVER read,
+    // stored, or logged by the gateway.
+    const headers = {};
+    for (const [k, v] of Object.entries(req.headers)) {
+        if (v === undefined)
+            continue;
+        const key = k.toLowerCase();
+        if (key === "host" || key === "content-length" || key === "x-compaction-mode" || key === "x-compaction-policy" || HOP_BY_HOP.has(key))
+            continue;
+        headers[k] = v;
+    }
+    headers["host"] = target.host;
+    if (bodyToForward.length > 0)
+        headers["content-length"] = String(bodyToForward.length);
+    const upstreamReq = client.request({ protocol: target.protocol, hostname: target.hostname, port: target.port, path: target.pathname + target.search, method: req.method, headers }, (upstreamRes) => {
+        // Forward status + headers VERBATIM, then stream the body byte-for-byte to the client.
+        res.writeHead(upstreamRes.statusCode ?? 502, upstreamRes.headers);
+        upstreamRes.pipe(res); // byte-safe: the client sees the exact upstream bytes (streaming or not)
+        // Tee a bounded TAIL of the response for usage parsing (usage rides in the final JSON/SSE chunk).
+        // This is a READ-ONLY copy — it never touches the bytes the client receives.
+        const tail = [];
+        let tailBytes = 0;
+        upstreamRes.on("data", (c) => {
+            tail.push(c);
+            tailBytes += c.length;
+            while (tailBytes > USAGE_TAIL_BYTES && tail.length > 1) {
+                tailBytes -= tail[0].length;
+                tail.shift();
+            }
+        });
+        upstreamRes.on("end", () => {
+            const shared = {
+                endpoint,
+                upstreamStatus: upstreamRes.statusCode ?? 0,
+                responseTail: Buffer.concat(tail).toString("utf8"),
+                requestModel: requestModel(requestBody), // content-free model label from the ORIGINAL body
+                ...(proofRunId ? { proofRunId } : {})
+            };
+            if (activation.requested && apply) {
+                void recordApplyReceiptFor({ options, activation, apply, log, ...shared });
+            }
+            else {
+                void recordReceipt({ options, log, ...shared });
+            }
+        });
+    });
+    upstreamReq.on("error", (err) => {
+        // The gateway itself failed to reach upstream — an honest gateway error (never a faked success).
+        log(`compaction gateway: upstream error for ${endpoint}: ${err.message}`);
+        if (!res.headersSent) {
+            res.writeHead(502, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: { message: `compaction gateway: upstream request failed (${err.message})`, type: "gateway_error" } }));
+        }
+        else {
+            res.end();
+        }
+    });
+    if (bodyToForward.length > 0)
+        upstreamReq.write(bodyToForward);
+    upstreamReq.end();
+}
+/** First string value of a (possibly array) header, trimmed to non-empty, else undefined. */
+function headerValue(v) {
+    const s = Array.isArray(v) ? v[0] : v;
+    return typeof s === "string" && s.trim() !== "" ? s : undefined;
+}
+/**
+ * Decide what apply does for this request. NEVER mutates unless: apply mode is active, the shape is
+ * supported, a safe duplicate exists, AND the original was successfully retained for recovery FIRST.
+ * dry-run always forwards the original. Any uncertainty → fail closed (forward original, record the reason).
+ */
+function resolveApplyOutcome(activation, endpoint, method, originalBody, options, log) {
+    if (!activation.requested)
+        return null;
+    if (activation.failClosedReason)
+        return { applied: false, failClosedReason: activation.failClosedReason };
+    if (method !== "POST")
+        return { applied: false, failClosedReason: `apply supports only POST requests; got ${method ?? "unknown"} — forwarded unchanged` };
+    const plan = planDeterministicDedupe(endpoint, originalBody.toString("utf8"));
+    if (!plan.supported)
+        return { plan, applied: false, ...(plan.failClosedReason ? { failClosedReason: plan.failClosedReason } : {}) };
+    if (activation.mode === "dry-run")
+        return { plan, applied: false }; // preview only — original forwarded
+    if (!plan.changed || !plan.mutatedBody)
+        return { plan, applied: false }; // no safe duplicate → forward original
+    // APPLY: retain the exact original locally FIRST; only then forward the mutated body. If retention
+    // fails we fail closed (never mutate without a recoverable original).
+    try {
+        const recoveryId = saveOriginalForRecovery(options.cwd ?? process.cwd(), {
+            endpoint,
+            policy: activation.policy ?? "deterministic-dedupe",
+            originalBody: originalBody.toString("utf8")
+        });
+        return { plan, applied: true, mutatedBody: Buffer.from(plan.mutatedBody, "utf8"), recoveryId };
+    }
+    catch (e) {
+        log(`compaction gateway: apply retention failed — forwarding original unchanged (${e.message})`);
+        return { plan, applied: false, failClosedReason: `could not retain the original for recovery — forwarded unchanged (${e.message})` };
+    }
+}
+/** Build + append the content-free APPLY/dry-run receipt. Best-effort: never affects the client. */
+async function recordApplyReceiptFor(params) {
+    try {
+        const usage = usageFromResponseBody(params.responseTail);
+        const receipt = buildApplyReceipt({
+            provider: params.options.provider,
+            endpoint: params.endpoint,
+            upstreamStatus: params.upstreamStatus,
+            usage,
+            activation: params.activation,
+            applied: params.apply.applied,
+            ...(params.apply.plan ? { plan: params.apply.plan } : {}),
+            ...(params.apply.recoveryId ? { recoveryId: params.apply.recoveryId } : {}),
+            ...(params.apply.failClosedReason ? { failClosedReason: params.apply.failClosedReason } : {}),
+            ...(params.requestModel ? { requestModel: params.requestModel } : {}),
+            ...(params.proofRunId ? { proofRunId: params.proofRunId } : {})
+        });
+        params.options.onReceipt?.(receipt);
+        await appendGatewayReceipt(receipt, params.options.cwd ?? process.cwd());
+        params.log(`compaction gateway: apply receipt ${receipt.receipt_id.slice(0, 8)}… policy=${receipt.policy} ` +
+            `request_mutated=${receipt.request_mutated} ${receipt.recovery_id ? `recovery=${receipt.recovery_id.slice(0, 8)}… ` : ""}` +
+            `${receipt.fail_closed_reason ? `(fail-closed: ${receipt.fail_closed_reason}) ` : ""}— response unchanged; content-free.`);
+    }
+    catch {
+        // Never let receipt recording break the proxy; the client's response already completed.
+    }
+}
+/** Build + append the content-free receipt. Best-effort: a failure here never affects the client. */
+async function recordReceipt(params) {
+    try {
+        const usage = usageFromResponseBody(params.responseTail);
+        const receipt = buildGatewayReceipt({
+            provider: params.options.provider,
+            endpoint: params.endpoint,
+            mode: "record",
+            upstreamStatus: params.upstreamStatus,
+            usage,
+            ...(params.requestModel ? { requestModel: params.requestModel } : {}),
+            ...(params.proofRunId ? { proofRunId: params.proofRunId } : {})
+        });
+        params.options.onReceipt?.(receipt);
+        await appendGatewayReceipt(receipt, params.options.cwd ?? process.cwd());
+        const t = receipt.tokens;
+        params.log(`compaction gateway: receipt ${receipt.receipt_id.slice(0, 8)}… (${receipt.token_source}) ` +
+            `input=${t.prompt_input ?? "-"} cached=${t.cached_input ?? "-"} billed=${t.billed_fresh_input ?? "-"} output=${t.output ?? "-"} ` +
+            `· ${formatFreshBilledInputReduction(receipt.fresh_billed_input_reduction)} — content-free, no mutation (model-visible bytes unchanged).`);
+    }
+    catch {
+        // Never let receipt recording break the proxy; the client's response already completed.
+    }
+}
+/** Start the gateway on `host:port`. Resolves once it is listening. */
+export function startGatewayServer(options) {
+    const server = createGatewayServer(options);
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(options.port, options.host, () => {
+            const addr = server.address();
+            const port = typeof addr === "object" && addr ? addr.port : options.port;
+            resolve({
+                server,
+                address: { host: options.host, port },
+                close: () => new Promise((r) => server.close(() => r()))
+            });
+        });
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/core/gateway/status.d.ts

@@ -0,0 +1,45 @@
+import { type GatewayReceipt } from "./receipt.js";
+import { type CacheProofSummary } from "./cache-proof.js";
+export declare const GATEWAY_PID_FILE = "gateway.json";
+/** Content-free record of a running gateway (no request/response content). */
+export interface GatewayPidRecord {
+    pid: number;
+    host: string;
+    port: number;
+    upstream: string;
+    provider: string;
+    mode: string;
+    startedAt: string;
+}
+export declare function writeGatewayPid(rec: GatewayPidRecord, cwd?: string): void;
+export declare function readGatewayPid(cwd?: string): GatewayPidRecord | null;
+export declare function removeGatewayPid(cwd?: string): void;
+/** True if a process with `pid` is alive (signal 0). EPERM means it exists but is owned by another user. */
+export declare function isProcessAlive(pid: number): boolean;
+/** Probe whether something is listening on host:port (TCP connect, short timeout). Never throws. */
+export declare function probeListening(host: string, port: number, timeoutMs?: number): Promise<boolean>;
+/** Read the local-only content-free receipts (each line is a GatewayReceipt). */
+export declare function readReceipts(cwd?: string): GatewayReceipt[];
+export interface GatewayStatus {
+    running: boolean;
+    pid?: number;
+    base?: string;
+    provider?: string;
+    mode?: string;
+    /** Total local receipts (= requests observed through the gateway in this project). */
+    receiptsCount: number;
+    /** ISO timestamp of the most recent request observed, when any. */
+    lastRequestAt?: string;
+    /** True when ANY observed request reported provider cached input tokens. */
+    cachedObserved: boolean;
+    /** When a `since` is given: were any requests observed at/after it (this-session traffic)? */
+    observedSince?: boolean;
+    /** Content-free summary over the local receipts (best provider-backed fresh/billed input reduction). */
+    summary: CacheProofSummary;
+}
+/**
+ * Resolve the current gateway status: running (pidfile present + process alive + port listening),
+ * plus a content-free rollup of the local receipts. When `since` (ISO) is given, `observedSince`
+ * reports whether any request was observed at/after it (for "traffic observed this session"). Never throws.
+ */
+export declare function getGatewayStatus(cwd?: string, since?: string): Promise<GatewayStatus>;

package/dist/core/gateway/status.js

@@ -0,0 +1,109 @@
+/**
+ * Gateway lifecycle status + local pidfile (PUBLIC CLI/SDK code — engine-free). Charter run-17.
+ *
+ * Supports `compaction gateway status|stop` and the guided onboarding. CONTENT-FREE: the pidfile holds
+ * only the process id + listen/upstream metadata (host/port/provider/mode/timestamps) — never any
+ * request/response content; the receipts it reads are already content-free. Local-only under
+ * `<cwd>/.compaction/gateway/` (gitignored).
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync, rmSync } from "node:fs";
+import net from "node:net";
+import path from "node:path";
+import { DEFAULT_GATEWAY_RECEIPTS_DIR, GATEWAY_RECEIPTS_FILE } from "./receipt.js";
+import { summarizeCacheProof } from "./cache-proof.js";
+export const GATEWAY_PID_FILE = "gateway.json";
+function pidPath(cwd) {
+    return path.join(cwd, DEFAULT_GATEWAY_RECEIPTS_DIR, GATEWAY_PID_FILE);
+}
+export function writeGatewayPid(rec, cwd = process.cwd()) {
+    mkdirSync(path.join(cwd, DEFAULT_GATEWAY_RECEIPTS_DIR), { recursive: true });
+    writeFileSync(pidPath(cwd), `${JSON.stringify(rec, null, 2)}\n`, "utf8");
+}
+export function readGatewayPid(cwd = process.cwd()) {
+    try {
+        const r = JSON.parse(readFileSync(pidPath(cwd), "utf8"));
+        return r && typeof r.pid === "number" ? r : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function removeGatewayPid(cwd = process.cwd()) {
+    try {
+        rmSync(pidPath(cwd), { force: true });
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** True if a process with `pid` is alive (signal 0). EPERM means it exists but is owned by another user. */
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === "EPERM";
+    }
+}
+/** Probe whether something is listening on host:port (TCP connect, short timeout). Never throws. */
+export function probeListening(host, port, timeoutMs = 400) {
+    return new Promise((resolve) => {
+        const sock = net.connect({ host, port });
+        let done = false;
+        const finish = (v) => {
+            if (done)
+                return;
+            done = true;
+            sock.destroy();
+            resolve(v);
+        };
+        sock.setTimeout(timeoutMs);
+        sock.on("connect", () => finish(true));
+        sock.on("timeout", () => finish(false));
+        sock.on("error", () => finish(false));
+    });
+}
+/** Read the local-only content-free receipts (each line is a GatewayReceipt). */
+export function readReceipts(cwd = process.cwd()) {
+    const p = path.join(cwd, DEFAULT_GATEWAY_RECEIPTS_DIR, GATEWAY_RECEIPTS_FILE);
+    if (!existsSync(p))
+        return [];
+    return readFileSync(p, "utf8")
+        .trim()
+        .split("\n")
+        .filter(Boolean)
+        .map((l) => JSON.parse(l));
+}
+/**
+ * Resolve the current gateway status: running (pidfile present + process alive + port listening),
+ * plus a content-free rollup of the local receipts. When `since` (ISO) is given, `observedSince`
+ * reports whether any request was observed at/after it (for "traffic observed this session"). Never throws.
+ */
+export async function getGatewayStatus(cwd = process.cwd(), since) {
+    const rec = readGatewayPid(cwd);
+    let running = false;
+    let base;
+    if (rec) {
+        const alive = isProcessAlive(rec.pid);
+        const listening = await probeListening(rec.host, rec.port);
+        running = alive && listening;
+        base = `http://${rec.host}:${rec.port}`;
+    }
+    const receipts = readReceipts(cwd);
+    const times = receipts.map((r) => r.captured_at).filter((t) => typeof t === "string").sort();
+    const lastRequestAt = times.length > 0 ? times[times.length - 1] : undefined;
+    const cachedObserved = receipts.some((r) => typeof r.tokens?.cached_input === "number" && r.tokens.cached_input > 0);
+    const observedSince = since ? receipts.some((r) => typeof r.captured_at === "string" && r.captured_at >= since) : undefined;
+    return {
+        running,
+        ...(rec ? { pid: rec.pid, provider: rec.provider, mode: rec.mode } : {}),
+        ...(base ? { base } : {}),
+        receiptsCount: receipts.length,
+        ...(lastRequestAt ? { lastRequestAt } : {}),
+        cachedObserved,
+        ...(observedSince !== undefined ? { observedSince } : {}),
+        summary: summarizeCacheProof(receipts)
+    };
+}
+//# sourceMappingURL=status.js.map

package/dist/core/hook-usage-aggregate.d.ts

@@ -0,0 +1,47 @@
+import { type ClaudeCodeHookRecord } from "./claude-code-hook-record.js";
+export declare const HOOK_USAGE_AGGREGATE_SCHEMA: "compaction.hook-usage-aggregate.v1";
+/** Load + validate all hook usage records under baseDir (default `.compaction/hooks`). Invalid files skipped. */
+export declare function loadHookUsageRecords(baseDir?: string): Promise<ClaudeCodeHookRecord[]>;
+export interface HookUsageToolAggregate {
+    tool: string;
+    /** Deduped record count for this tool. */
+    events: number;
+    /** Sum of input tokens across records that HAVE input; null when none do (never 0-for-missing). */
+    inputTokens: number | null;
+    outputTokens: number | null;
+    /** Reasoning tokens are not separately reported by Claude Code session usage → always null here. */
+    reasoningTokens: number | null;
+    /** Distinct honest token sources, preserved exactly (e.g. ["provider-reported"]). */
+    tokenSources: string[];
+    providers: string[];
+    models: string[];
+    /** Records whose output tokens are present. */
+    outputRecorded: number;
+    /** Records flagged provider-reported. */
+    providerReportedEvents: number;
+    /** Records with NO input and NO output token data (usage unavailable). */
+    unavailableEvents: number;
+    /** Distinct session ids seen. */
+    sessions: number;
+    firstRecordedAt: string | null;
+    lastRecordedAt: string | null;
+}
+export interface HookUsageAggregate {
+    schema: typeof HOOK_USAGE_AGGREGATE_SCHEMA;
+    /** Records loaded before dedup. */
+    totalRecords: number;
+    /** Records after dedup by dedupKey. */
+    dedupedRecords: number;
+    /** Optional ISO lower bound applied to recordedAt. */
+    since: string | null;
+    tools: HookUsageToolAggregate[];
+}
+export interface AggregateOptions {
+    /** Only include records with recordedAt >= this ISO timestamp (time-window filter). */
+    since?: string;
+}
+/**
+ * Aggregate hook records into a content-free source-status view. Dedups by `dedupKey`. Missing token
+ * counts stay null. Token source labels preserved exactly. No savings, no content.
+ */
+export declare function aggregateHookUsageRecords(records: ClaudeCodeHookRecord[], options?: AggregateOptions): HookUsageAggregate;

package/dist/core/hook-usage-aggregate.js

@@ -0,0 +1,161 @@
+/**
+ * Aggregate the content-free Claude Code hook usage records (PUBLIC CLI/SDK code, engine-free).
+ * Rolls up the records written by `capture claude-code --from-hook`
+ * (`.compaction/hooks/**​/records/*.json`) into a CONTENT-FREE source-status view — by tool, by session,
+ * and over a time window — mirroring the `/app` source-status model (events / input / output / token
+ * sources / providers / models / provider-reported-vs-unavailable). Local-first; no network.
+ *
+ * Honesty rails (binding):
+ *  - Content-free in / content-free out: counts, honest source, ids, providers, models, timestamps only.
+ *    No prompt/completion/message content, no transcript content, no `last_assistant_message`.
+ *  - Missing usage stays **null / unavailable**, never 0. A tool with no recorded input tokens reports
+ *    `inputTokens: null`, not 0.
+ *  - Token source labels are preserved exactly (provider-reported / local-estimate / unknown).
+ *  - Idempotent: records are deduped by `dedupKey` so the same Stop/session state is counted once.
+ *  - NO savings claim — this surfaces usage only.
+ */
+import { readdir, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { CLAUDE_CODE_HOOK_RECORD_SCHEMA } from "./claude-code-hook-record.js";
+export const HOOK_USAGE_AGGREGATE_SCHEMA = "compaction.hook-usage-aggregate.v1";
+/** A loaded record plus nothing else — we only ever read the content-free fields. */
+function isHookRecord(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return v.schema === CLAUDE_CODE_HOOK_RECORD_SCHEMA && typeof v.dedupKey === "string" && typeof v.tool === "string";
+}
+/** Recursively find `*.json` files under any `records/` directory below baseDir. */
+async function findRecordFiles(baseDir) {
+    const out = [];
+    async function walk(dir) {
+        let names;
+        try {
+            names = await readdir(dir);
+        }
+        catch {
+            return; // missing dir → no records (not an error)
+        }
+        for (const name of names) {
+            const full = path.join(dir, name);
+            let isDir = false;
+            try {
+                isDir = (await stat(full)).isDirectory();
+            }
+            catch {
+                continue;
+            }
+            if (isDir) {
+                await walk(full);
+            }
+            else if (name.endsWith(".json") && path.basename(dir) === "records") {
+                out.push(full);
+            }
+        }
+    }
+    await walk(baseDir);
+    return out;
+}
+/** Load + validate all hook usage records under baseDir (default `.compaction/hooks`). Invalid files skipped. */
+export async function loadHookUsageRecords(baseDir = ".compaction/hooks") {
+    const files = await findRecordFiles(baseDir);
+    const records = [];
+    for (const file of files) {
+        try {
+            const parsed = JSON.parse(await readFile(file, "utf8"));
+            if (isHookRecord(parsed))
+                records.push(parsed);
+        }
+        catch {
+            // skip unreadable/invalid record file (never throw — local-first, best-effort)
+        }
+    }
+    return records;
+}
+function addToken(acc, value) {
+    if (value === null)
+        return acc; // missing contributes nothing and never coerces to 0
+    return (acc ?? 0) + value;
+}
+/**
+ * Aggregate hook records into a content-free source-status view. Dedups by `dedupKey`. Missing token
+ * counts stay null. Token source labels preserved exactly. No savings, no content.
+ */
+export function aggregateHookUsageRecords(records, options = {}) {
+    const since = options.since ?? null;
+    // Apply the time-window filter first, then dedup by dedupKey (records are already deduped at write time;
+    // this is defensive). `totalRecords` counts records IN the window so "deduped from N" reads accurately
+    // under --since. When `since` is set, a record with a missing/non-string recordedAt is EXCLUDED (a record
+    // with no timestamp cannot be proven to fall inside the window).
+    let totalRecords = 0;
+    const deduped = new Map();
+    for (const r of records) {
+        if (since !== null && (typeof r.recordedAt !== "string" || r.recordedAt < since))
+            continue;
+        totalRecords += 1;
+        if (!deduped.has(r.dedupKey))
+            deduped.set(r.dedupKey, r);
+    }
+    const byTool = new Map();
+    const sessionsByTool = new Map();
+    for (const r of deduped.values()) {
+        let agg = byTool.get(r.tool);
+        if (!agg) {
+            agg = {
+                tool: r.tool,
+                events: 0,
+                inputTokens: null,
+                outputTokens: null,
+                reasoningTokens: null,
+                tokenSources: [],
+                providers: [],
+                models: [],
+                outputRecorded: 0,
+                providerReportedEvents: 0,
+                unavailableEvents: 0,
+                sessions: 0,
+                firstRecordedAt: null,
+                lastRecordedAt: null
+            };
+            byTool.set(r.tool, agg);
+            sessionsByTool.set(r.tool, new Set());
+        }
+        agg.events += 1;
+        agg.inputTokens = addToken(agg.inputTokens, r.inputTokens ?? null);
+        agg.outputTokens = addToken(agg.outputTokens, r.outputTokens ?? null);
+        if (typeof r.outputTokens === "number")
+            agg.outputRecorded += 1;
+        if (r.providerReported === true)
+            agg.providerReportedEvents += 1;
+        if ((r.inputTokens ?? null) === null && (r.outputTokens ?? null) === null)
+            agg.unavailableEvents += 1;
+        if (r.tokenSource && !agg.tokenSources.includes(r.tokenSource))
+            agg.tokenSources.push(r.tokenSource);
+        if (r.provider && !agg.providers.includes(r.provider))
+            agg.providers.push(r.provider);
+        if (r.model && !agg.models.includes(r.model))
+            agg.models.push(r.model);
+        if (r.sessionId)
+            sessionsByTool.get(r.tool).add(r.sessionId);
+        if (typeof r.recordedAt === "string") {
+            if (agg.firstRecordedAt === null || r.recordedAt < agg.firstRecordedAt)
+                agg.firstRecordedAt = r.recordedAt;
+            if (agg.lastRecordedAt === null || r.recordedAt > agg.lastRecordedAt)
+                agg.lastRecordedAt = r.recordedAt;
+        }
+    }
+    for (const [tool, agg] of byTool) {
+        agg.sessions = sessionsByTool.get(tool).size;
+        agg.tokenSources.sort();
+        agg.providers.sort();
+        agg.models.sort();
+    }
+    return {
+        schema: HOOK_USAGE_AGGREGATE_SCHEMA,
+        totalRecords,
+        dedupedRecords: deduped.size,
+        since,
+        tools: Array.from(byTool.values()).sort((a, b) => a.tool.localeCompare(b.tool))
+    };
+}
+//# sourceMappingURL=hook-usage-aggregate.js.map