@cruxy/cli 0.18.0 → 0.20.0

package/dist/lsp/tools/get-diagnostics.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { runLspTool } from "./common.js";
+const parameters = z.object({
+    file: z
+        .string()
+        .min(1)
+        .describe("Project-relative path to the file to diagnose."),
+});
+/**
+ * LSP diagnostics (C.12): the language server's errors/warnings for a file.
+ * Read-only — no approval. Returns each diagnostic as
+ * `severity path:line:col message [source]`, capped to `lsp.maxResults`. A
+ * missing server is a coded error; a clean file is an honest empty result.
+ */
+export const getDiagnosticsTool = {
+    name: "get_diagnostics",
+    description: "Get the language server's diagnostics (errors, warnings) for a file. Give the project-relative path. Returns diagnostics as 'severity path:line:col message'. Read-only, no approval. Use this after an edit to see type errors the compiler/linter reports, without running a build.",
+    parameters,
+    execute(input, ctx) {
+        return runLspTool(ctx, input.file, async (service, absFile) => {
+            const diagnostics = await service.diagnostics(absFile);
+            if (diagnostics.length === 0) {
+                return { ok: true, output: "(no diagnostics)" };
+            }
+            return {
+                ok: true,
+                output: formatDiagnostics(diagnostics, ctx.config.lsp.maxResults),
+            };
+        });
+    },
+};
+function formatDiagnostics(diagnostics, max) {
+    const shown = diagnostics.slice(0, max);
+    const lines = shown.map((d) => {
+        const src = d.source ? ` [${d.source}]` : "";
+        return `${d.severity} ${d.path}:${d.range.startLine}:${d.range.startCol} ${d.message}${src}`;
+    });
+    const omitted = diagnostics.length - shown.length;
+    if (omitted > 0) {
+        lines.push(`… [${omitted} more diagnostic(s) omitted]`);
+    }
+    return lines.join("\n");
+}

package/dist/lsp/tools/hover.d.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+import type { Tool } from "../../tools/types.js";
+declare const parameters: z.ZodObject<{
+    file: z.ZodString;
+    line: z.ZodNumber;
+    column: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    file: string;
+    line: number;
+    column: number;
+}, {
+    file: string;
+    line: number;
+    column: number;
+}>;
+/**
+ * LSP hover (C.12): type signature / documentation for the symbol at a position.
+ * Read-only — no approval. Returns the server's hover text (markup flattened to
+ * plain text). A missing server is a coded error; a symbol with no hover info is
+ * an honest empty result.
+ */
+export declare const hoverTool: Tool<typeof parameters>;
+export {};

package/dist/lsp/tools/hover.js

@@ -0,0 +1,38 @@
+import { z } from "zod";
+import { runLspTool } from "./common.js";
+const parameters = z.object({
+    file: z
+        .string()
+        .min(1)
+        .describe("Project-relative path to the file containing the symbol."),
+    line: z
+        .number()
+        .int()
+        .positive()
+        .describe("1-based line number of the symbol."),
+    column: z
+        .number()
+        .int()
+        .positive()
+        .describe("1-based column of the symbol (position of the identifier)."),
+});
+/**
+ * LSP hover (C.12): type signature / documentation for the symbol at a position.
+ * Read-only — no approval. Returns the server's hover text (markup flattened to
+ * plain text). A missing server is a coded error; a symbol with no hover info is
+ * an honest empty result.
+ */
+export const hoverTool = {
+    name: "hover",
+    description: "Get type information and documentation for a symbol using the project's language server (hover). Give the file and the 1-based line/column of the identifier. Returns the symbol's type signature and docs. Read-only, no approval. Use this to learn a symbol's type without opening and reading its declaration.",
+    parameters,
+    execute(input, ctx) {
+        return runLspTool(ctx, input.file, async (service, absFile) => {
+            const hover = await service.hover(absFile, input.line, input.column);
+            if (!hover) {
+                return { ok: true, output: "(no hover information)" };
+            }
+            return { ok: true, output: hover.contents };
+        });
+    },
+};

package/dist/lsp/tools/index.d.ts

@@ -0,0 +1,4 @@
+export { findDefinitionTool } from "./find-definition.js";
+export { findReferencesTool } from "./find-references.js";
+export { getDiagnosticsTool } from "./get-diagnostics.js";
+export { hoverTool } from "./hover.js";

package/dist/lsp/tools/index.js

@@ -0,0 +1,4 @@
+export { findDefinitionTool } from "./find-definition.js";
+export { findReferencesTool } from "./find-references.js";
+export { getDiagnosticsTool } from "./get-diagnostics.js";
+export { hoverTool } from "./hover.js";

package/dist/lsp/transport.d.ts

@@ -0,0 +1,48 @@
+import type { LspTransport, ServerSpec } from "./types.js";
+export declare class StdioTransport implements LspTransport {
+    private readonly child;
+    private nextId;
+    private readonly pending;
+    private readonly notificationHandlers;
+    private crashHandler;
+    /** stdout parse buffer (header + body may arrive across chunks). */
+    private buffer;
+    private disposed;
+    /** Deregisters this process from the process-exit kill-tree backstop. */
+    private readonly unregisterCleanup;
+    constructor(spec: ServerSpec, root: string);
+    request(method: string, params: unknown, timeoutMs: number): Promise<unknown>;
+    notify(method: string, params: unknown): void;
+    onNotification(method: string, handler: (params: unknown) => void): void;
+    onCrash(handler: (info: {
+        code: number | null;
+        signal: string | null;
+    }) => void): void;
+    dispose(force?: boolean): Promise<void>;
+    private send;
+    private onStdout;
+    private dispatch;
+    private onExit;
+    private onSpawnError;
+}
+/** A per-request timeout, distinguishable from an ordinary LSP error response. */
+export declare class TransportTimeoutError extends Error {
+    readonly method: string;
+    readonly timeoutMs: number;
+    constructor(method: string, timeoutMs: number);
+}
+/**
+ * Kill the process's entire group (POSIX negative-PID `SIGKILL`), same helper
+ * shape as run_command's `killTree`. Swallows errors — the process may be gone.
+ */
+export declare function killTree(pid: number | undefined): void;
+/**
+ * Force-kill the process group of every tracked-but-not-yet-shut-down server,
+ * then forget them. This is exactly what the `exit`/`SIGINT`/`SIGTERM`/`SIGHUP`
+ * handlers run — the last line against orphaned language servers on a hard exit.
+ * Exported so it is directly testable (like `resetIndexServices`) without having
+ * to raise real process signals. Idempotent: a second call is a no-op.
+ */
+export declare function killTrackedServers(): void;
+/** Number of servers currently tracked by the exit backstop (for tests). */
+export declare function trackedServerCount(): number;

package/dist/lsp/transport.js

@@ -0,0 +1,264 @@
+import { spawn } from "node:child_process";
+/**
+ * JSON-RPC 2.0 over a language server's stdio (C.12). Owns the child process:
+ * spawns it in its OWN process group (`detached`) so the whole tree is killable,
+ * frames messages with `Content-Length` headers, correlates responses to
+ * requests by id, times out per request, and detects a crash (unexpected exit).
+ *
+ * This is the real {@link LspTransport}; tests inject a fake peer instead, so no
+ * real language-server binary is required in CI.
+ */
+const GRACE_MS = 2000;
+export class StdioTransport {
+    child;
+    nextId = 1;
+    pending = new Map();
+    notificationHandlers = new Map();
+    crashHandler = null;
+    /** stdout parse buffer (header + body may arrive across chunks). */
+    buffer = Buffer.alloc(0);
+    disposed = false;
+    /** Deregisters this process from the process-exit kill-tree backstop. */
+    unregisterCleanup;
+    constructor(spec, root) {
+        // `detached` makes the child a process-group leader so the whole tree can be
+        // killed via a negative-PID signal — same discipline as run_command (C.16).
+        this.child = spawn(spec.command, spec.args, {
+            cwd: root,
+            detached: true,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.unregisterCleanup = registerForCleanup(this.child.pid);
+        this.child.stdout?.on("data", (chunk) => this.onStdout(chunk));
+        // Server stderr is diagnostic only; surface nothing by default (it's noisy).
+        this.child.stderr?.on("data", () => { });
+        this.child.on("exit", (code, signal) => this.onExit(code, signal));
+        this.child.on("error", (err) => this.onSpawnError(err));
+    }
+    request(method, params, timeoutMs) {
+        if (this.disposed) {
+            return Promise.reject(new Error("transport disposed"));
+        }
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new TransportTimeoutError(method, timeoutMs));
+            }, timeoutMs);
+            // Don't let a pending request keep the event loop alive.
+            timer.unref?.();
+            this.pending.set(id, { resolve, reject, timer });
+            this.send({ jsonrpc: "2.0", id, method, params });
+        });
+    }
+    notify(method, params) {
+        if (this.disposed)
+            return;
+        this.send({ jsonrpc: "2.0", method, params });
+    }
+    onNotification(method, handler) {
+        const list = this.notificationHandlers.get(method) ?? [];
+        list.push(handler);
+        this.notificationHandlers.set(method, list);
+    }
+    onCrash(handler) {
+        this.crashHandler = handler;
+    }
+    async dispose(force = false) {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        this.unregisterCleanup();
+        // Reject anything still in flight so callers never hang on teardown.
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(new Error("transport disposed"));
+        }
+        this.pending.clear();
+        if (!this.child.pid || this.child.exitCode !== null)
+            return;
+        if (force) {
+            killTree(this.child.pid);
+            return;
+        }
+        // Give the process a grace window to exit on its own (the caller has
+        // already sent the LSP `exit` notification), then force-kill the group.
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                killTree(this.child.pid);
+                resolve();
+            }, GRACE_MS);
+            timer.unref?.();
+            this.child.once("exit", () => {
+                clearTimeout(timer);
+                resolve();
+            });
+        });
+    }
+    // ── framing ─────────────────────────────────────────────────────────────────
+    send(message) {
+        const body = Buffer.from(JSON.stringify(message), "utf8");
+        const header = Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, "ascii");
+        this.child.stdin?.write(Buffer.concat([header, body]));
+    }
+    onStdout(chunk) {
+        this.buffer = Buffer.concat([this.buffer, chunk]);
+        // Drain every fully-received message currently in the buffer.
+        for (;;) {
+            const headerEnd = this.buffer.indexOf("\r\n\r\n");
+            if (headerEnd === -1)
+                return;
+            const header = this.buffer.subarray(0, headerEnd).toString("ascii");
+            const match = /content-length:\s*(\d+)/i.exec(header);
+            if (!match) {
+                // Malformed header — drop it and resync past the separator.
+                this.buffer = this.buffer.subarray(headerEnd + 4);
+                continue;
+            }
+            const length = Number(match[1]);
+            const bodyStart = headerEnd + 4;
+            if (this.buffer.length < bodyStart + length)
+                return; // body not complete yet
+            const body = this.buffer.subarray(bodyStart, bodyStart + length);
+            this.buffer = this.buffer.subarray(bodyStart + length);
+            this.dispatch(body.toString("utf8"));
+        }
+    }
+    dispatch(text) {
+        let msg;
+        try {
+            msg = JSON.parse(text);
+        }
+        catch {
+            return; // ignore unparseable frames
+        }
+        // Response to one of our requests.
+        if (typeof msg.id === "number" && (msg.result !== undefined || msg.error)) {
+            const pending = this.pending.get(msg.id);
+            if (!pending)
+                return;
+            this.pending.delete(msg.id);
+            clearTimeout(pending.timer);
+            if (msg.error)
+                pending.reject(new Error(msg.error.message ?? "LSP error"));
+            else
+                pending.resolve(msg.result);
+            return;
+        }
+        // Server → client notification (e.g. textDocument/publishDiagnostics).
+        if (typeof msg.method === "string" && msg.id === undefined) {
+            for (const handler of this.notificationHandlers.get(msg.method) ?? []) {
+                handler(msg.params);
+            }
+        }
+        // Server → client requests (e.g. workspace/configuration) are unsupported;
+        // we intentionally don't reply — our advertised capabilities don't ask for
+        // features that require a mandatory response.
+    }
+    onExit(code, signal) {
+        this.unregisterCleanup();
+        if (this.disposed)
+            return; // an expected shutdown, not a crash
+        // Unexpected exit → a crash. The server's OWN child processes (e.g. gopls's
+        // `go`, rust-analyzer's `cargo`) can outlive it — reap the whole group so a
+        // crash never orphans them. The group persists as long as any member lives,
+        // so the negative-pid signal still lands even though the leader is gone.
+        killTree(this.child.pid);
+        // Reject everything in flight, then notify.
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(new Error(`language server exited (code ${code}, signal ${signal})`));
+        }
+        this.pending.clear();
+        this.crashHandler?.({ code, signal });
+    }
+    onSpawnError(err) {
+        // The binary vanished between the presence check and spawn, or is not
+        // executable. Treat as a crash so the pool surfaces a coded error.
+        if (this.disposed)
+            return;
+        for (const [, p] of this.pending) {
+            clearTimeout(p.timer);
+            p.reject(err);
+        }
+        this.pending.clear();
+        this.crashHandler?.({ code: null, signal: null });
+    }
+}
+/** A per-request timeout, distinguishable from an ordinary LSP error response. */
+export class TransportTimeoutError extends Error {
+    method;
+    timeoutMs;
+    constructor(method, timeoutMs) {
+        super(`LSP request "${method}" timed out after ${timeoutMs}ms`);
+        this.method = method;
+        this.timeoutMs = timeoutMs;
+        this.name = "TransportTimeoutError";
+    }
+}
+/**
+ * Kill the process's entire group (POSIX negative-PID `SIGKILL`), same helper
+ * shape as run_command's `killTree`. Swallows errors — the process may be gone.
+ */
+export function killTree(pid) {
+    if (pid === undefined)
+        return;
+    try {
+        process.kill(-pid, "SIGKILL");
+    }
+    catch {
+        try {
+            // Fall back to a direct kill if there was no group (or on win32).
+            process.kill(pid, "SIGKILL");
+        }
+        catch {
+            /* already exited */
+        }
+    }
+}
+// ── process-exit kill-tree backstop ───────────────────────────────────────────
+//
+// Language servers are long-lived child processes. A per-session shutdown covers
+// the normal path, but a hard exit (Ctrl-C, an uncaught throw) would otherwise
+// orphan them — so every live server's process group is tracked here and killed
+// on process teardown. Handlers are registered ONCE, lazily, on the first spawn,
+// so unit tests using the fake transport never install them.
+const livePids = new Set();
+let handlersInstalled = false;
+/**
+ * Force-kill the process group of every tracked-but-not-yet-shut-down server,
+ * then forget them. This is exactly what the `exit`/`SIGINT`/`SIGTERM`/`SIGHUP`
+ * handlers run — the last line against orphaned language servers on a hard exit.
+ * Exported so it is directly testable (like `resetIndexServices`) without having
+ * to raise real process signals. Idempotent: a second call is a no-op.
+ */
+export function killTrackedServers() {
+    for (const pid of livePids)
+        killTree(pid);
+    livePids.clear();
+}
+/** Number of servers currently tracked by the exit backstop (for tests). */
+export function trackedServerCount() {
+    return livePids.size;
+}
+function installExitHandlers() {
+    if (handlersInstalled)
+        return;
+    handlersInstalled = true;
+    process.once("exit", killTrackedServers);
+    for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+        process.once(sig, () => {
+            killTrackedServers();
+            // Restore default behavior and re-raise so the exit code is correct.
+            process.exit(130);
+        });
+    }
+}
+/** Track a live child for the exit backstop; returns a deregister callback. */
+function registerForCleanup(pid) {
+    if (pid === undefined)
+        return () => { };
+    installExitHandlers();
+    livePids.add(pid);
+    return () => livePids.delete(pid);
+}

package/dist/lsp/types.d.ts

@@ -0,0 +1,107 @@
+import type { LspConfig } from "../config/index.js";
+/**
+ * Per-language LSP integration (C.12) — the shared vocabulary. Results here are
+ * NORMALIZED (1-based lines/columns, project-relative paths, plain severities):
+ * the LSP wire format's 0-based positions and `file://` URIs are converted at
+ * the edge (`server.ts`) so nothing downstream speaks raw LSP.
+ */
+export type { LspConfig };
+/**
+ * A source range, normalized to 1-based lines and columns (LSP is 0-based; we
+ * add 1 at the boundary). `path` is project-relative for display.
+ */
+export interface LspLocation {
+    /** Project-relative file path. */
+    path: string;
+    /** 1-based start line. */
+    startLine: number;
+    /** 1-based start column. */
+    startCol: number;
+    /** 1-based end line. */
+    endLine: number;
+    /** 1-based end column. */
+    endCol: number;
+}
+/** A normalized diagnostic (severity mapped off the LSP 1–4 integer scale). */
+export interface LspDiagnostic {
+    /** Project-relative file path. */
+    path: string;
+    /** Where the diagnostic applies (1-based). */
+    range: LspLocation;
+    severity: "error" | "warning" | "info" | "hint";
+    message: string;
+    /** The producing tool, when the server reports it (e.g. "tsc", "gopls"). */
+    source?: string;
+}
+/** A normalized hover result — markdown/markup flattened to plain text. */
+export interface LspHover {
+    contents: string;
+    /** The symbol range the hover describes, when the server reports it. */
+    range?: LspLocation;
+}
+/**
+ * A single, initialized language server (≈ one live child process). Queries are
+ * absolute-path in / normalized-out; the client relativizes paths against the
+ * workspace root. A method resolving to `[]`/`null` is an honest "no result" —
+ * unavailability is signalled by a thrown coded error from the pool, never here.
+ */
+export interface LanguageServer {
+    readonly language: string;
+    /** True until the process exits (crash detection flips this to false). */
+    readonly alive: boolean;
+    definition(file: string, line: number, col: number): Promise<LspLocation[]>;
+    references(file: string, line: number, col: number): Promise<LspLocation[]>;
+    diagnostics(file: string): Promise<LspDiagnostic[]>;
+    hover(file: string, line: number, col: number): Promise<LspHover | null>;
+    /** LSP `shutdown` → `exit`, then force-kill the process group after a grace. */
+    shutdown(force?: boolean): Promise<void>;
+}
+/** How to launch one language's server, resolved from config ∪ the default table. */
+export interface ServerSpec {
+    language: string;
+    /** Executable name or absolute path. */
+    command: string;
+    /** Argument vector (e.g. `["--stdio"]`). */
+    args: string[];
+    /** Concrete install instruction, surfaced when the binary is missing. */
+    installHint?: string;
+}
+/**
+ * The registry's answer for a language. Availability is EXPLICIT: an
+ * unavailable server carries the reason so the caller raises a coded,
+ * actionable error rather than silently returning nothing.
+ */
+export type ServerResolution = {
+    available: true;
+    spec: ServerSpec;
+} | {
+    available: false;
+    language: string;
+    spec: ServerSpec | null;
+    reason: "no-spec" | "binary-missing";
+};
+/**
+ * The one seam tests replace: a live JSON-RPC peer over the server's stdio. A
+ * fake implementation lets the whole stack run with NO real language-server
+ * binary (mirroring `RecordingRuntime` for the sandbox).
+ */
+export interface LspTransport {
+    /** Send a request and await its response, rejecting after `timeoutMs`. */
+    request(method: string, params: unknown, timeoutMs: number): Promise<unknown>;
+    /** Fire-and-forget notification (no response expected). */
+    notify(method: string, params: unknown): void;
+    /** Register a handler for a server→client notification (e.g. diagnostics). */
+    onNotification(method: string, handler: (params: unknown) => void): void;
+    /** Register a one-shot crash callback (process exited unexpectedly). */
+    onCrash(handler: (info: {
+        code: number | null;
+        signal: string | null;
+    }) => void): void;
+    /** LSP graceful path already sent by the caller; drop the transport,
+     * force-killing the process group after the grace when `force` is set. */
+    dispose(force?: boolean): Promise<void>;
+}
+/** Builds a transport for a resolved spec, rooted at `root`. Injectable in tests. */
+export type TransportFactory = (spec: ServerSpec, root: string) => LspTransport;
+/** Predicate: is `command` runnable (on PATH, or an existing executable path)? */
+export type BinaryPresent = (command: string) => boolean;

package/dist/lsp/types.js

@@ -0,0 +1 @@
+export {};

package/dist/plan/service.d.ts

@@ -1,4 +1,4 @@
-import type { Message, Provider } from "@cruxy/sdk";
+import type { Message, Provider, Usage } from "@cruxy/sdk";
 import type { CruxyConfig } from "../config/index.js";
 import type { PromptIO } from "../approval/index.js";
 import { ToolRegistry, type ToolContext } from "../tools/index.js";
@@ -45,5 +45,14 @@ export interface PlanSessionArgs {
      * and step execution on `main-turn`; omitted → the provider default.
      */
     router?: Router;
+    /**
+     * Usage telemetry (C.22): forwarded to every model request the plan turn
+     * drives (propose + each execution step), so plan-mode usage is captured and
+     * tier-attributed exactly like a normal turn.
+     */
+    onRequestUsage?: (req: {
+        tier?: string;
+        usage?: Usage;
+    }) => void;
 }
 export declare function runPlanSession(args: PlanSessionArgs): Promise<AgentResult>;

package/dist/plan/service.js

@@ -78,6 +78,7 @@ export async function runPlanSession(args) {
             planMode: true,
             router: args.router,
             taskClass: "plan",
+            onRequestUsage: args.onRequestUsage,
         }));
         if (!holder.plan) {
             throw planInvalid("the model ended its turn without calling submit_plan");
@@ -112,6 +113,7 @@ export async function runPlanSession(args) {
                     renderer: args.renderer,
                     router: args.router,
                     taskClass: "main-turn",
+                    onRequestUsage: args.onRequestUsage,
                 }));
             };
             await executePlan(plan, {

package/dist/tools/file/grep-files.d.ts

@@ -9,15 +9,15 @@ declare const parameters: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     pattern: string;
     path?: string | undefined;
+    maxResults?: number | undefined;
     glob?: string | undefined;
     ignoreCase?: boolean | undefined;
-    maxResults?: number | undefined;
 }, {
     pattern: string;
     path?: string | undefined;
+    maxResults?: number | undefined;
     glob?: string | undefined;
     ignoreCase?: boolean | undefined;
-    maxResults?: number | undefined;
 }>;
 /**
  * Search file *contents* for a regex within the project root. Read-only — no

package/dist/usage/collect.d.ts

@@ -0,0 +1,40 @@
+import type { Usage } from "@cruxy/sdk";
+import type { UsageRecord } from "./types.js";
+/**
+ * Usage collection (C.22). Accumulates per-request usage exactly as the agent
+ * loop reports it — one {@link UsageEntry} per completed model request — and
+ * emits a {@link UsageRecord} for the run.
+ *
+ * The one honesty invariant: `usage: undefined` (the loop's signal that the
+ * provider returned NO usage event for a request) is recorded as `undefined`
+ * token counts — the honest "unknown". A provider-reported `0` arrives as a real
+ * `Usage` and is stored as `0`. Nothing is estimated, re-tokenized, or
+ * zero-filled, and this module makes ZERO network calls.
+ */
+/** What the loop hands over for one completed request. */
+export interface RequestUsage {
+    /** The routing tier (C.30) the request ran on, if routing was active. */
+    tier?: string;
+    /**
+     * The provider's usage for THIS request, or `undefined` when the provider
+     * emitted no usage event (⇒ tokens are unknown, not zero).
+     */
+    usage?: Usage;
+}
+/** Wall clock as an injectable seam so tests are deterministic. */
+export type Clock = () => string;
+export declare class UsageCollector {
+    private readonly now;
+    private readonly entries;
+    constructor(now?: Clock);
+    /**
+     * Record one completed request. When `req.usage` is absent the entry's token
+     * counts stay `undefined` — the provider reported nothing, so we assert
+     * nothing. A real reported `0` is preserved as `0`.
+     */
+    record(req: RequestUsage): void;
+    /** How many requests have been recorded so far. */
+    get count(): number;
+    /** Snapshot the collected entries into a persistable {@link UsageRecord}. */
+    toRecord(runId: string, sessionId: string | undefined, startedAt: string): UsageRecord;
+}

package/dist/usage/collect.js

@@ -0,0 +1,34 @@
+const systemClock = () => new Date().toISOString();
+export class UsageCollector {
+    now;
+    entries = [];
+    constructor(now = systemClock) {
+        this.now = now;
+    }
+    /**
+     * Record one completed request. When `req.usage` is absent the entry's token
+     * counts stay `undefined` — the provider reported nothing, so we assert
+     * nothing. A real reported `0` is preserved as `0`.
+     */
+    record(req) {
+        this.entries.push({
+            tier: req.tier,
+            inputTokens: req.usage?.input_tokens,
+            outputTokens: req.usage?.output_tokens,
+            at: this.now(),
+        });
+    }
+    /** How many requests have been recorded so far. */
+    get count() {
+        return this.entries.length;
+    }
+    /** Snapshot the collected entries into a persistable {@link UsageRecord}. */
+    toRecord(runId, sessionId, startedAt) {
+        return {
+            runId,
+            ...(sessionId !== undefined ? { sessionId } : {}),
+            startedAt,
+            entries: [...this.entries],
+        };
+    }
+}