@compaction/cli 0.2.0 → 0.3.1

package/dist/core/gateway/recovery.js

@@ -0,0 +1,68 @@
+/**
+ * Compaction Gateway APPLY recovery store (PUBLIC CLI/SDK core — engine-free). Charter run-17.2.
+ *
+ * When apply mode changes a request body, the ORIGINAL body is retained LOCALLY here so the exact
+ * pre-mutation request is always recoverable. This is the ONE place gateway request content is persisted
+ * — deliberately, for recovery — and it is:
+ *   - local-only under `<cwd>/.compaction/gateway/recovery/` (gitignored; NEVER uploaded),
+ *   - written with restrictive `0600` permissions where the OS supports it,
+ *   - referenced from receipts by `recovery_id` ONLY (the content-free receipt never carries the body).
+ *
+ * `compaction gateway recover <recovery_id>` reads it back. Nothing here ever leaves the machine.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, chmodSync } from "node:fs";
+import path from "node:path";
+export const GATEWAY_RECOVERY_DIR = ".compaction/gateway/recovery";
+function recoveryDir(cwd) {
+    return path.join(cwd, GATEWAY_RECOVERY_DIR);
+}
+function recoveryPath(cwd, recoveryId) {
+    return path.join(recoveryDir(cwd), `${recoveryId}.json`);
+}
+/**
+ * Persist the original request body for recovery and return a fresh `recovery_id`. Best-effort restrictive
+ * permissions (0700 dir, 0600 file). Synchronous + fail-safe: throws only if the write genuinely fails
+ * (the caller treats a failure as "do NOT mutate" — apply must never proceed without a saved original).
+ */
+export function saveOriginalForRecovery(cwd, params) {
+    const recoveryId = (params.id ?? (() => randomUUID()))();
+    const dir = recoveryDir(cwd);
+    mkdirSync(dir, { recursive: true });
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        /* best-effort — some filesystems (e.g. Windows) ignore POSIX modes */
+    }
+    const record = {
+        recovery_id: recoveryId,
+        captured_at: (params.now ?? (() => new Date().toISOString()))(),
+        endpoint: params.endpoint,
+        policy: params.policy,
+        original_body: params.originalBody
+    };
+    const file = recoveryPath(cwd, recoveryId);
+    writeFileSync(file, `${JSON.stringify(record, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    try {
+        chmodSync(file, 0o600);
+    }
+    catch {
+        /* best-effort */
+    }
+    return recoveryId;
+}
+/** Read a recovery record back by id, or null when it does not exist / cannot be parsed. */
+export function readRecovery(cwd, recoveryId) {
+    const file = recoveryPath(cwd, recoveryId);
+    if (!existsSync(file))
+        return null;
+    try {
+        const rec = JSON.parse(readFileSync(file, "utf8"));
+        return rec && typeof rec.original_body === "string" ? rec : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=recovery.js.map

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

@@ -0,0 +1,51 @@
+/**
+ * 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 type { GatewayReceipt } from "./receipt.js";
+/** The server's configured gateway mode. Default `record`; `apply`/`dry-run` require explicit opt-in. */
+export type GatewayServerMode = "record" | "apply" | "dry-run";
+export interface GatewayServerOptions {
+    provider: string;
+    /** The upstream provider base (only its ORIGIN is used; the client's request path is authoritative). */
+    upstream: string;
+    /** `record` (default, byte-safe), or the explicit `apply`/`dry-run` deterministic modes (run-17.2). */
+    mode: GatewayServerMode;
+    /** Deterministic apply policy (run-17.2). Only `deterministic-dedupe` is implemented. */
+    policy?: string;
+    /** Where receipts are written (defaults to process.cwd()). */
+    cwd?: string;
+    /** Test/observability hook fired after each receipt is built (before/independent of the file append). */
+    onReceipt?: (receipt: GatewayReceipt) => void;
+    /** Best-effort logger for content-free operational lines (defaults to no-op). */
+    log?: (line: string) => void;
+}
+/**
+ * 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 declare function createGatewayServer(options: GatewayServerOptions): http.Server;
+export interface StartedGateway {
+    server: http.Server;
+    /** The bound address (host + port). */
+    address: {
+        host: string;
+        port: number;
+    };
+    close: () => Promise<void>;
+}
+/** Start the gateway on `host:port`. Resolves once it is listening. */
+export declare function startGatewayServer(options: GatewayServerOptions & {
+    host: string;
+    port: number;
+}): Promise<StartedGateway>;

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;