@openplan/dsh-fuse 0.1.0

package/dist/store.js

@@ -0,0 +1,412 @@
+/**
+ * dsh local store — libsql persistence for the plugin (proposal §1: "Store
+ * local libsql — sem build nativa, distribuível sem compilação").
+ *
+ * The local fuse's spentUsd comes from HERE in local-only mode: spend is
+ * recorded per project and windowed on demand, surviving restarts, and the
+ * sync path pulls exactly the rows not yet acknowledged by the SaaS. The
+ * store is pure persistence — enforcement math stays in fuseDecision.
+ *
+ * ## Fidelity
+ *
+ * A stored row carries everything the SaaS needs to answer "quanto queimamos,
+ * quem é o vilão, o que a política travou hoje" (proposal §3): the hashed
+ * session identity, the reasoning effort actually used, and the full disjoint
+ * token accounting the harness reports (`TokenUsage`: uncached input, output,
+ * cache reads, cache writes). Dropping any of them makes a server-side policy
+ * unevaluable or a session dimension unanswerable, so they are part of the
+ * schema rather than of the sync mapping.
+ *
+ * The `usage` table is migrated in place ({@link migrate}) so an existing
+ * `file:local.db` from an earlier version keeps its spend history instead of
+ * being discarded.
+ */
+import { mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { createClient } from "@libsql/client";
+const COLUMNS = {
+    usage: [
+        ["session_id", "TEXT NOT NULL DEFAULT ''"],
+        ["project", "TEXT NOT NULL"],
+        ["cost_usd", "REAL NOT NULL"],
+        ["at", "TEXT NOT NULL"],
+        ["synced", "INTEGER NOT NULL DEFAULT 0"],
+        ["model", "TEXT NOT NULL DEFAULT ''"],
+        ["provider", "TEXT NOT NULL DEFAULT ''"],
+        ["reasoning_effort", "TEXT NOT NULL DEFAULT ''"],
+        ["input_tokens", "INTEGER NOT NULL DEFAULT 0"],
+        ["output_tokens", "INTEGER NOT NULL DEFAULT 0"],
+        ["cache_read_tokens", "INTEGER NOT NULL DEFAULT 0"],
+        ["cache_write_tokens", "INTEGER NOT NULL DEFAULT 0"],
+        ["duration_ms", "INTEGER"],
+        ["unpriced", "INTEGER NOT NULL DEFAULT 0"],
+        ["event_id", "TEXT NOT NULL DEFAULT ''"],
+        ["tools", "TEXT NOT NULL DEFAULT '[]'"],
+    ],
+};
+/**
+ * Create the tables and add any column a previous version lacked. SQLite has
+ * no `ADD COLUMN IF NOT EXISTS`, so the existing column set is read first —
+ * an upgrade keeps its history, a fresh database creates everything at once.
+ */
+async function migrate(client) {
+    await client.execute(`CREATE TABLE IF NOT EXISTS usage (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			session_id TEXT NOT NULL DEFAULT '',
+			project TEXT NOT NULL,
+			cost_usd REAL NOT NULL,
+			at TEXT NOT NULL,
+			synced INTEGER NOT NULL DEFAULT 0,
+			model TEXT NOT NULL DEFAULT '',
+			provider TEXT NOT NULL DEFAULT '',
+			reasoning_effort TEXT NOT NULL DEFAULT '',
+			input_tokens INTEGER NOT NULL DEFAULT 0,
+			output_tokens INTEGER NOT NULL DEFAULT 0,
+			cache_read_tokens INTEGER NOT NULL DEFAULT 0,
+			cache_write_tokens INTEGER NOT NULL DEFAULT 0,
+			duration_ms INTEGER,
+			unpriced INTEGER NOT NULL DEFAULT 0,
+			event_id TEXT NOT NULL DEFAULT '',
+			tools TEXT NOT NULL DEFAULT '[]'
+		)`);
+    const existing = await client.execute("PRAGMA table_info(usage)");
+    const present = new Set(existing.rows.map((row) => String(row.name)));
+    for (const [name, definition] of COLUMNS.usage) {
+        if (present.has(name))
+            continue;
+        await client.execute(`ALTER TABLE usage ADD COLUMN ${name} ${definition}`);
+    }
+    await client.batch([
+        {
+            sql: `CREATE TABLE IF NOT EXISTS cuts (
+				id INTEGER PRIMARY KEY AUTOINCREMENT,
+				project TEXT NOT NULL,
+				rule TEXT NOT NULL,
+				synced INTEGER NOT NULL DEFAULT 0
+			)`,
+            args: [],
+        },
+        {
+            sql: `CREATE TABLE IF NOT EXISTS state (
+				key TEXT PRIMARY KEY,
+				value TEXT NOT NULL
+			)`,
+            args: [],
+        },
+    ]);
+}
+/**
+ * Resolve the DSH home (harness root) the same way the harness itself does:
+ * `$DSH_HOME` when set and non-blank, else `~/.dsh`. The default store path is
+ * anchored here so the ledger is stable regardless of the working directory
+ * the harness happened to be started from — a CWD-relative default silently
+ * split spend across one empty ledger per launch directory.
+ */
+export function dshHome() {
+    const override = process.env.DSH_HOME?.trim();
+    return override ? override : join(homedir(), ".dsh");
+}
+/**
+ * The default store location: `$DSH_HOME/dsh-fuse/local.db` (or the
+ * equivalent under `~/.dsh`). The parent directory is created on demand by
+ * {@link createLocalStore}, so a fresh harness home needs no manual setup.
+ */
+export function defaultStoreUrl() {
+    return `file:${join(dshHome(), "dsh-fuse", "local.db")}`;
+}
+/** Ensure the parent directory of a `file:` store URL exists (libsql does not
+ * create missing directories). A `:memory:` or remote URL is untouched.
+ */
+function ensureStoreParentDir(url) {
+    const filePath = url.startsWith("file:") ? url.slice("file:".length) : "";
+    if (!filePath)
+        return;
+    const parent = dirname(filePath);
+    if (parent && parent !== ".")
+        mkdirSync(parent, { recursive: true });
+}
+/** `url`: file path for the installed plugin, `:memory:` for tests. A relative
+ * `file:` path is only honored when explicitly configured — the default is
+ * the harness-home-anchored {@link defaultStoreUrl}, never the CWD.
+ */
+export function createLocalStore(url = defaultStoreUrl()) {
+    ensureStoreParentDir(url);
+    const client = createClient({ url });
+    const ready = migrate(client);
+    function number(value, fallback = 0) {
+        const parsed = Number(value);
+        return Number.isFinite(parsed) ? parsed : fallback;
+    }
+    /** Parse the JSON-encoded tool-name column, tolerating legacy garbage. */
+    function parseTools(value) {
+        if (typeof value !== "string" || !value)
+            return [];
+        try {
+            const parsed = JSON.parse(value);
+            return Array.isArray(parsed)
+                ? parsed.filter((item) => typeof item === "string")
+                : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    function rowToUsage(row) {
+        const duration = row.duration_ms;
+        return {
+            id: number(row.id),
+            sessionId: String(row.session_id ?? ""),
+            project: String(row.project),
+            costUsd: number(row.cost_usd),
+            at: String(row.at),
+            synced: Boolean(row.synced),
+            model: String(row.model ?? ""),
+            provider: String(row.provider ?? ""),
+            reasoningEffort: String(row.reasoning_effort ?? ""),
+            inputTokens: number(row.input_tokens),
+            outputTokens: number(row.output_tokens),
+            cacheReadTokens: number(row.cache_read_tokens),
+            cacheWriteTokens: number(row.cache_write_tokens),
+            durationMs: duration === null || duration === undefined ? null : number(duration),
+            unpriced: Boolean(row.unpriced),
+            eventId: String(row.event_id ?? ""),
+            tools: parseTools(row.tools),
+        };
+    }
+    return {
+        async record(event) {
+            await ready;
+            await client.execute({
+                sql: `INSERT INTO usage (
+					session_id, project, cost_usd, at, synced, model, provider,
+					reasoning_effort, input_tokens, output_tokens,
+					cache_read_tokens, cache_write_tokens, duration_ms, unpriced,
+					event_id, tools
+				) VALUES (?, ?, ?, ?, 0, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+                args: [
+                    event.sessionId ?? "",
+                    event.project,
+                    event.costUsd,
+                    event.at,
+                    event.model ?? "",
+                    event.provider ?? "",
+                    event.reasoningEffort ?? "",
+                    event.inputTokens ?? 0,
+                    event.outputTokens ?? 0,
+                    event.cacheReadTokens ?? 0,
+                    event.cacheWriteTokens ?? 0,
+                    event.durationMs ?? null,
+                    event.unpriced ? 1 : 0,
+                    event.eventId ?? "",
+                    JSON.stringify(event.tools ?? []),
+                ],
+            });
+        },
+        async spentForWindow({ project, dev, since }) {
+            await ready;
+            const conditions = ["at >= ?"];
+            const args = [since];
+            if (project) {
+                conditions.push("project = ?");
+                args.push(project);
+            }
+            if (dev) {
+                conditions.push("dev = ?");
+                args.push(dev);
+            }
+            const res = await client.execute({
+                sql: `SELECT coalesce(sum(cost_usd), 0) AS total FROM usage WHERE ${conditions.join(" AND ")}`,
+                args,
+            });
+            return number(res.rows[0]?.total);
+        },
+        async pendingSync(limit = 500) {
+            await ready;
+            const res = await client.execute({
+                sql: `SELECT id, session_id, project, cost_usd, at, synced, model,
+					provider, reasoning_effort, input_tokens, output_tokens,
+					cache_read_tokens, cache_write_tokens, duration_ms, unpriced,
+					event_id, tools
+					FROM usage WHERE synced = 0 ORDER BY id LIMIT ?`,
+                args: [limit],
+            });
+            return res.rows.map((row) => rowToUsage(row));
+        },
+        async markSynced(ids) {
+            await ready;
+            for (const id of ids) {
+                await client.execute({
+                    sql: "UPDATE usage SET synced = 1 WHERE id = ?",
+                    args: [id],
+                });
+            }
+        },
+        async recordCut(event) {
+            await ready;
+            await client.execute({
+                sql: "INSERT INTO cuts (project, rule, synced) VALUES (?, ?, 0)",
+                args: [event.project, event.rule],
+            });
+        },
+        async pendingCuts(limit = 100) {
+            await ready;
+            const res = await client.execute({
+                sql: "SELECT id, project, rule FROM cuts WHERE synced = 0 ORDER BY id LIMIT ?",
+                args: [limit],
+            });
+            return res.rows.map((row) => ({
+                id: number(row.id),
+                project: String(row.project),
+                rule: String(row.rule),
+            }));
+        },
+        async markCutsSynced(ids) {
+            await ready;
+            for (const id of ids) {
+                await client.execute({
+                    sql: "UPDATE cuts SET synced = 1 WHERE id = ?",
+                    args: [id],
+                });
+            }
+        },
+        async setRemoteBlock(block) {
+            await ready;
+            if (block === null) {
+                await client.execute({
+                    sql: "DELETE FROM state WHERE key = 'remote_blocks'",
+                    args: [],
+                });
+                return;
+            }
+            // Replacing the whole scope's block: one org, one project, one dev.
+            const res = await client.execute({
+                sql: "SELECT value FROM state WHERE key = 'remote_blocks'",
+                args: [],
+            });
+            let blocks = [];
+            const raw = res.rows[0]?.value;
+            if (raw) {
+                try {
+                    const parsed = JSON.parse(String(raw));
+                    if (Array.isArray(parsed))
+                        blocks = parsed;
+                }
+                catch {
+                    blocks = [];
+                }
+            }
+            const scope = block.scope ?? "org";
+            const reference = block.reference ?? "";
+            // Replacing one scope's block only: same (scope, reference) key.
+            blocks = blocks.filter((b) => (b.scope ?? "org") !== scope || (b.reference ?? "") !== reference);
+            // An expired block self-clears — windows are the release.
+            const now = Date.now();
+            blocks = blocks.filter((b) => new Date(b.resetAt).getTime() > now);
+            blocks.push(block);
+            await client.execute({
+                sql: "INSERT INTO state (key, value) VALUES ('remote_blocks', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+                args: [JSON.stringify(blocks)],
+            });
+        },
+        async remoteBlockFor({ project, dev }) {
+            await ready;
+            const res = await client.execute({
+                sql: "SELECT value FROM state WHERE key = 'remote_blocks'",
+                args: [],
+            });
+            const raw = res.rows[0]?.value;
+            if (!raw)
+                return null;
+            let blocks = [];
+            try {
+                const parsed = JSON.parse(String(raw));
+                if (Array.isArray(parsed))
+                    blocks = parsed;
+            }
+            catch {
+                blocks = [];
+            }
+            const now = Date.now();
+            for (const block of blocks) {
+                if (new Date(block.resetAt).getTime() <= now)
+                    continue;
+                const scope = block.scope ?? "org";
+                const reference = block.reference ?? "";
+                if (scope === "org") {
+                    return { rule: block.rule, resetAt: block.resetAt };
+                }
+                if (scope === "project" && reference === project) {
+                    return { rule: block.rule, resetAt: block.resetAt };
+                }
+                if (scope === "dev" && reference === dev) {
+                    return { rule: block.rule, resetAt: block.resetAt };
+                }
+            }
+            return null;
+        },
+        async setRemotePolicy(policy) {
+            await ready;
+            if (policy === null) {
+                await client.execute({
+                    sql: "DELETE FROM state WHERE key = 'remote_policy'",
+                    args: [],
+                });
+                return;
+            }
+            await client.execute({
+                sql: "INSERT INTO state (key, value) VALUES ('remote_policy', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+                args: [JSON.stringify(policy)],
+            });
+        },
+        async remotePolicy() {
+            await ready;
+            const res = await client.execute({
+                sql: "SELECT value FROM state WHERE key = 'remote_policy'",
+                args: [],
+            });
+            const raw = res.rows[0]?.value;
+            if (!raw)
+                return null;
+            try {
+                return JSON.parse(String(raw));
+            }
+            catch {
+                return null;
+            }
+        },
+        async setPricingTable(table) {
+            await ready;
+            if (table === null) {
+                await client.execute({
+                    sql: "DELETE FROM state WHERE key = 'pricing_table'",
+                    args: [],
+                });
+                return;
+            }
+            await client.execute({
+                sql: "INSERT INTO state (key, value) VALUES ('pricing_table', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+                args: [JSON.stringify(table)],
+            });
+        },
+        async pricingTable() {
+            await ready;
+            const res = await client.execute({
+                sql: "SELECT value FROM state WHERE key = 'pricing_table'",
+                args: [],
+            });
+            const raw = res.rows[0]?.value;
+            if (!raw)
+                return null;
+            try {
+                return JSON.parse(String(raw));
+            }
+            catch {
+                return null;
+            }
+        },
+        async close() {
+            client.close();
+        },
+    };
+}

package/dist/sync.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Batch sync to the SaaS — the secondary gate returns 429 when blocked, and
+ * `GET /v1/policy` pulls the org's enforcement state the other way.
+ *
+ * ## A failed batch must never look like a delivered one
+ *
+ * The sync watermark (`markSynced`) is what stops a row from being re-sent, so
+ * treating any non-429 response as success silently DESTROYS usage rows: a 500,
+ * a 502 from the proxy, or a stray HTML error page would retire the rows
+ * without the SaaS ever storing them. {@link SyncResult.delivered} therefore
+ * states explicitly whether the events reached the SaaS, and the caller only
+ * advances the watermark when it did.
+ */
+import type { RemotePolicy } from "./store.js";
+import type { BatchEvent } from "./wire.js";
+/** A fuse-cut report (proposal §3) — rides the same batch as usage rows. */
+export type { CutEvent } from "./wire.js";
+export interface SyncResult {
+    accepted: number;
+    status: number;
+    blocked: boolean;
+    blockedRule?: string;
+    resetAt?: string;
+    /**
+     * Which budget the 429 came from. An `org` block stops every call on this
+     * machine; a `project` block stops only the referenced project; a `dev`
+     * block only the referenced dev. Absent = treat as org-wide (legacy).
+     */
+    blockScope?: "org" | "project" | "dev";
+    blockReference?: string;
+    /**
+     * True only when the SaaS acknowledged the batch (2xx with `ok`). A blocked
+     * (429) or failed batch is NOT delivered — the caller keeps the rows.
+     */
+    delivered: boolean;
+    /** Transport/HTTP failure detail for the log line, when any. */
+    error?: string;
+}
+/** Shared request shape for the two key-authed endpoints. */
+export interface OrgKeyTarget {
+    baseUrl: string;
+    orgKey: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function syncBatch(input: OrgKeyTarget & {
+    events: BatchEvent[];
+}): Promise<SyncResult>;
+/**
+ * Pull the org's enforcement state (`GET /v1/policy`, key-authed). This is
+ * what makes the panel the control plane for the PRIMARY gate: without it the
+ * local fuse can only enforce whatever the deployment wrote into
+ * `cordis.yml`, and a budget edited in the panel would reach nothing but the
+ * secondary 429.
+ *
+ * Returns `null` when the SaaS has nothing published, or when the request
+ * failed — the caller keeps the last cached policy either way (offline-first:
+ * enforcement never depends on the network being up at boot).
+ */
+export declare function fetchPolicy(input: OrgKeyTarget): Promise<{
+    policy: RemotePolicy | null;
+    error?: string;
+}>;
+/**
+ * Validate the published shape before it reaches the fuse: a malformed policy
+ * must degrade to "no published policy", never to a half-applied rule set
+ * (an `allowedModels` that arrived as a string would otherwise deny every
+ * model, and a `limitUsd` that arrived as a string would compare as NaN and
+ * never cut).
+ */
+export declare function parseRemotePolicy(json: unknown): RemotePolicy | null;

package/dist/sync.js

@@ -0,0 +1,153 @@
+/**
+ * Batch sync to the SaaS — the secondary gate returns 429 when blocked, and
+ * `GET /v1/policy` pulls the org's enforcement state the other way.
+ *
+ * ## A failed batch must never look like a delivered one
+ *
+ * The sync watermark (`markSynced`) is what stops a row from being re-sent, so
+ * treating any non-429 response as success silently DESTROYS usage rows: a 500,
+ * a 502 from the proxy, or a stray HTML error page would retire the rows
+ * without the SaaS ever storing them. {@link SyncResult.delivered} therefore
+ * states explicitly whether the events reached the SaaS, and the caller only
+ * advances the watermark when it did.
+ */
+function keyHeaders(orgKey) {
+    return { "x-org-key": orgKey };
+}
+export async function syncBatch(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    let res;
+    try {
+        res = await fetchImpl(`${input.baseUrl}/v1/usage/batch`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                ...keyHeaders(input.orgKey),
+            },
+            body: JSON.stringify({ events: input.events }),
+        });
+    }
+    catch (err) {
+        return {
+            accepted: 0,
+            status: 0,
+            blocked: false,
+            delivered: false,
+            error: String(err).slice(0, 200),
+        };
+    }
+    const body = (await res.json().catch(() => ({})));
+    if (res.status === 429) {
+        const scope = body.scope === "org" || body.scope === "project" || body.scope === "dev"
+            ? body.scope
+            : undefined;
+        return {
+            accepted: 0,
+            status: 429,
+            blocked: true,
+            blockedRule: body.rule,
+            resetAt: body.reset_at,
+            ...(scope ? { blockScope: scope } : {}),
+            ...(typeof body.reference === "string" && body.reference
+                ? { blockReference: body.reference }
+                : {}),
+            delivered: false,
+        };
+    }
+    if (!res.ok) {
+        return {
+            accepted: 0,
+            status: res.status,
+            blocked: false,
+            delivered: false,
+            error: body.error ?? `status ${res.status}`,
+        };
+    }
+    return {
+        accepted: body.accepted ?? input.events.length,
+        status: res.status,
+        blocked: false,
+        delivered: true,
+    };
+}
+/**
+ * Pull the org's enforcement state (`GET /v1/policy`, key-authed). This is
+ * what makes the panel the control plane for the PRIMARY gate: without it the
+ * local fuse can only enforce whatever the deployment wrote into
+ * `cordis.yml`, and a budget edited in the panel would reach nothing but the
+ * secondary 429.
+ *
+ * Returns `null` when the SaaS has nothing published, or when the request
+ * failed — the caller keeps the last cached policy either way (offline-first:
+ * enforcement never depends on the network being up at boot).
+ */
+export async function fetchPolicy(input) {
+    const fetchImpl = input.fetchImpl ?? fetch;
+    try {
+        const res = await fetchImpl(`${input.baseUrl}/v1/policy`, {
+            method: "GET",
+            headers: keyHeaders(input.orgKey),
+        });
+        if (res.status === 401)
+            return { policy: null, error: "unauthorized" };
+        if (!res.ok)
+            return { policy: null, error: `status ${res.status}` };
+        return { policy: parseRemotePolicy(await res.json()) };
+    }
+    catch (err) {
+        return { policy: null, error: String(err).slice(0, 200) };
+    }
+}
+/**
+ * Validate the published shape before it reaches the fuse: a malformed policy
+ * must degrade to "no published policy", never to a half-applied rule set
+ * (an `allowedModels` that arrived as a string would otherwise deny every
+ * model, and a `limitUsd` that arrived as a string would compare as NaN and
+ * never cut).
+ */
+export function parseRemotePolicy(json) {
+    if (typeof json !== "object" || json === null)
+        return null;
+    const raw = json;
+    const policy = {};
+    if (Array.isArray(raw.budgets)) {
+        const budgets = [];
+        for (const entry of raw.budgets) {
+            if (typeof entry !== "object" || entry === null)
+                continue;
+            const { limitUsd, window, scope, reference } = entry;
+            const limit = Number(limitUsd);
+            if (!Number.isFinite(limit) || limit <= 0)
+                continue;
+            if (window !== "month" && window !== "day")
+                continue;
+            const parsedScope = scope === "org" || scope === "project" || scope === "dev"
+                ? scope
+                : undefined;
+            budgets.push({
+                limitUsd: limit,
+                window,
+                ...(parsedScope ? { scope: parsedScope } : {}),
+                ...(typeof reference === "string" && reference ? { reference } : {}),
+            });
+        }
+        if (budgets.length > 0)
+            policy.budgets = budgets;
+    }
+    if (typeof raw.maxReasoningEffort === "string" && raw.maxReasoningEffort) {
+        policy.maxReasoningEffort = raw.maxReasoningEffort;
+    }
+    if (Array.isArray(raw.allowedModels)) {
+        const models = raw.allowedModels.filter((model) => typeof model === "string" && model.length > 0);
+        if (models.length > 0)
+            policy.allowedModels = models;
+    }
+    if (Array.isArray(raw.denylistedProjects)) {
+        const projects = raw.denylistedProjects.filter((project) => typeof project === "string" && project.length > 0);
+        if (projects.length > 0)
+            policy.denylistedProjects = projects;
+    }
+    if (typeof raw.updatedAt === "string")
+        policy.updatedAt = raw.updatedAt;
+    return policy;
+}

package/dist/wire.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The plugin's outbound wire contract.
+ *
+ * These types are the plugin's OWN because the plugin is distributed
+ * standalone (`dsh plugin add`, npm/tarball) and therefore cannot depend on a
+ * workspace package that is never published. The SaaS declares the same pair
+ * in `apps/dsh/shared` for its own routes; the two are the same wire format,
+ * so a change here is a change there — the api's ingest route is the consumer
+ * and validates every field it reads.
+ *
+ * Only metrics travel: model, provider, tokens, cost, timing and the HASHED
+ * session identity. No prompt, message, tool argument or result ever crosses
+ * this boundary.
+ */
+/** One model call, projected from the harness session log (metrics only). */
+export interface UsageEvent {
+    v: 1;
+    /**
+     * Client-generated stable id for this exact call (UUID). The SaaS inserts
+     * idempotently on (organization_id, event_id), so re-sends after a crash
+     * or a 429 can never double-count spend, tokens or budgets.
+     */
+    event_id: string;
+    /**
+     * SHA-256 of the harness session id, computed on the client — the raw id
+     * never leaves the machine.
+     */
+    session_id: string;
+    project: string;
+    dev: string;
+    provider: string;
+    model: string;
+    reasoning_effort?: string;
+    input_tokens: number;
+    output_tokens: number;
+    cache_read_tokens?: number;
+    cache_write_tokens?: number;
+    cost_usd: number;
+    /** True when no price resolved for this call — visible, never silent. */
+    unpriced?: boolean;
+    started_at: string;
+    duration_ms?: number;
+    tools?: string[];
+}
+/** A fuse-cut report — the local enforcement the panel surfaces (proposal §3). */
+export interface CutEvent {
+    kind: "cut";
+    project: string;
+    rule: string;
+}
+/** Anything that rides a `POST /v1/usage/batch` payload. */
+export type BatchEvent = UsageEvent | CutEvent;