costhawk 1.5.11 → 1.5.13

package/dist/build-info.d.ts

@@ -1,2 +1,2 @@
-export declare const BUILD_COMMIT_SHA = "b4c5b65";
+export declare const BUILD_COMMIT_SHA = "1ed40d7";
 //# sourceMappingURL=build-info.d.ts.map

package/dist/build-info.js

@@ -1,3 +1,3 @@
 // Auto-generated during release builds. Values may be empty in dev.
-export const BUILD_COMMIT_SHA = "b4c5b65";
+export const BUILD_COMMIT_SHA = "1ed40d7";
 //# sourceMappingURL=build-info.js.map

package/dist/cursor-parser.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Cursor Local SQLite Parser
+ *
+ * Parses Cursor IDE chat history from the local SQLite database to extract
+ * token usage and timestamps. Read-only. Does not push to any backend.
+ *
+ * Storage:
+ *   macOS:   ~/Library/Application Support/Cursor/User/globalStorage/state.vscdb
+ *   Linux:   ~/.config/Cursor/User/globalStorage/state.vscdb
+ *   Windows: %APPDATA%/Cursor/User/globalStorage/state.vscdb
+ *
+ * Schema:
+ *   Table cursorDiskKV (key TEXT, value BLOB)
+ *   Conversations: composerData:<composerId>
+ *   Messages:      bubbleId:<composerId>:<bubbleId>
+ *
+ * Token data lives at $.tokenCount.inputTokens and $.tokenCount.outputTokens
+ * on bubble rows. Model name at $.modelInfo.modelName. Server-side dedup id
+ * at $.serverBubbleId.
+ *
+ * Timestamps (verified in Task #30 against a real state.vscdb):
+ *   - $.createdAt on bubbles is an ISO 8601 string (~56% coverage, all-or-
+ *     nothing per composer — likely added in a newer Cursor version).
+ *   - $.createdAt on composerData rows is a Unix milliseconds number (100%
+ *     coverage). Same field name, different type — parser handles both.
+ *   - $.lastUpdatedAt on composerData rows is Unix ms (~13% coverage).
+ *   - $.timingInfo.client* on bubbles is performance.now()-style relative
+ *     (seconds since Cursor process start), NOT absolute — never use it as
+ *     a wall-clock timestamp.
+ *
+ * Fallback ladder for per-session timestamps: prefer min/max of bubble
+ * createdAt when present, otherwise use composerData.createdAt with optional
+ * composerData.lastUpdatedAt as end time. Every session gets non-null
+ * timestamps; the `timestampSource` / `timestampQuality` fields surface
+ * whether the values are precise or approximate.
+ *
+ * Workspace metadata fields (workspaceHash/workspaceName) remain unverified
+ * and return null. composerData.name is a candidate for workspaceName but
+ * has not been confirmed yet.
+ */
+import type { TokenUsage } from "./transcript-parser.js";
+/**
+ * Single Cursor session in parser output.
+ *
+ * Shape is intentionally distinct from Claude/Codex SessionUsage because
+ * Cursor's timestamp coverage is partial — provenance fields surface
+ * whether startTime/endTime/dailyUsage came from per-bubble timestamps
+ * (precise) or a composer-level fallback (approximate).
+ *
+ * workspaceHash / workspaceName remain null — composerData.name is a
+ * candidate for workspaceName but was not verified in Task #30 and is
+ * deferred to a later release.
+ */
+export interface CursorSessionUsage {
+    sessionId: string;
+    workspaceHash: string | null;
+    workspaceName: string | null;
+    model: string;
+    tokens: TokenUsage;
+    messageCount: number;
+    filePath: string;
+    startTime: string | null;
+    endTime: string | null;
+    timestampSource: "bubble" | "composer" | "mixed" | "none";
+    timestampQuality: "precise" | "approximate" | "none";
+    dailyUsage: Record<string, TokenUsage>;
+    dailyUsageSource: "bubble" | "composer" | "none";
+}
+/**
+ * Backward-compat alias. PR1 shipped `CursorSessionUsageDryRun` in the
+ * published `.d.ts`; removing it in a patch release would be a breaking
+ * change for anyone who imported the type. The alias will be kept for at
+ * least one release after the rename.
+ */
+export type CursorSessionUsageDryRun = CursorSessionUsage;
+/**
+ * Transparency payload for the `what_we_read` MCP mode. Describes where
+ * the parser is reading from and what it sees at the table/prefix level,
+ * without leaking conversation content. UUIDs in sample keys are
+ * truncated to 8 characters — enough to distinguish keys at a glance,
+ * not enough to be a stable correlation handle.
+ */
+export interface CursorMeta {
+    filePath: string;
+    dbFileSize: number;
+    tables: string[];
+    keyPrefixes: Record<string, number>;
+    sampleBubbleKeys: string[];
+    sampleComposerKeys: string[];
+}
+/**
+ * Output of the `self_test` MCP mode. Runs the full parser pipeline and
+ * reports health + coverage + invariant checks. overallStatus semantics:
+ *   PASS     — parser ran, invariants held, coverage looks healthy
+ *   DEGRADED — parser ran but some bubbles lack timestamps / invariants
+ *              tripped warnings / coverage is partial. Not an error.
+ *   FAIL     — parser could not run (missing DB, missing sqlite3, query
+ *              failure, or corrupt top-level output). Surfaces as
+ *              MCP isError:true at the tool boundary.
+ */
+export interface CursorSelfTestResult {
+    filePath: string;
+    dbExists: boolean;
+    sqlite3Path: string;
+    canQuery: boolean;
+    tokenBubbleCount: number;
+    composerCount: number;
+    sessionsWithTokens: number;
+    timestampCoverage: {
+        bubblesWithCreatedAt: number;
+        totalBubbles: number;
+        composersWithCreatedAt: number;
+        totalComposers: number;
+    };
+    invariantChecks: Array<{
+        name: string;
+        passed: boolean;
+        details?: string;
+    }>;
+    warnings: string[];
+    errors: string[];
+    overallStatus: "PASS" | "DEGRADED" | "FAIL";
+}
+export interface CursorParserError {
+    code: "CURSOR_DB_NOT_FOUND" | "CURSOR_SQLITE3_NOT_FOUND" | "CURSOR_SQLITE_QUERY_FAILED";
+    message: string;
+}
+export interface CursorParserResult {
+    sessions: CursorSessionUsage[];
+    filePath: string;
+}
+/**
+ * Get the default Cursor SQLite path for the current platform, honoring
+ * the COSTHAWK_CURSOR_DB_PATH environment override.
+ */
+export declare function getCursorDbPath(): string;
+/**
+ * Check whether the Cursor SQLite database exists at the resolved path.
+ */
+export declare function cursorDbExists(): boolean;
+/**
+ * Type guard — narrows an unknown error to a CursorParserError.
+ */
+declare function isCursorParserError(value: unknown): value is CursorParserError;
+/**
+ * Parse Cursor usage from local SQLite. Read-only — does NOT push anything
+ * to the costcanary backend.
+ *
+ * Returns aggregated session data per composer with per-session token totals,
+ * message counts, start/end timestamps, and daily usage buckets. Throws
+ * CursorParserError on unrecoverable failures (missing DB, missing sqlite3
+ * binary, malformed SQLite output).
+ *
+ * Dedup strategy: per composer, keep one entry per (serverBubbleId ?? bubbleId).
+ * On collision, keep the candidate with the larger token total.
+ *
+ * Mixed-model handling: if a composer contains multiple non-empty model names,
+ * the returned `model` field is "mixed". If no model info is present on any
+ * bubble, the field is "unknown".
+ *
+ * Sort order: total tokens descending.
+ */
+export declare function parseCursorUsage(): CursorParserResult;
+/**
+ * Backward-compat alias. PR1 consumers called this function name; keep it
+ * working for one release after the rename.
+ */
+export declare const parseCursorUsageDryRun: typeof parseCursorUsage;
+/**
+ * Return transparency metadata about the Cursor SQLite: file size, table
+ * list, key-prefix histogram, and a small sample of bubble and composer
+ * keys with their UUIDs truncated. Powers the `what_we_read` MCP mode so
+ * users can see exactly what data CostHawk is reading.
+ *
+ * Throws CursorParserError on missing DB, missing sqlite3, or query failure.
+ */
+export declare function getCursorMeta(): CursorMeta;
+/**
+ * Run a full parser health check against the live DB. Reports coverage
+ * numbers, validates invariants, and classifies the result as PASS,
+ * DEGRADED, or FAIL.
+ *
+ * - FAIL is reserved for unrecoverable failures (DB missing, sqlite3
+ *   missing, query error). The MCP tool surfaces FAIL as isError:true.
+ * - DEGRADED means the parser ran but flagged warnings — e.g., invariant
+ *   tolerance exceeded, partial timestamp coverage, unexpected row shapes.
+ * - PASS means the parser ran cleanly with full coverage and no warnings.
+ *
+ * Never throws — catches errors and reports them as FAIL so callers can
+ * present the full structured payload to users.
+ */
+export declare function runCursorSelfTest(): CursorSelfTestResult;
+export { isCursorParserError };
+//# sourceMappingURL=cursor-parser.d.ts.map

package/dist/cursor-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cursor-parser.d.ts","sourceRoot":"","sources":["../src/cursor-parser.ts"],"names":[],"mappings":"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"}