harnery 0.34.1 → 0.36.0

package/dist/core/hooks/adapter/runtime-telemetry.js

@@ -0,0 +1,869 @@
+import { createHash } from "node:crypto";
+import { closeSync, existsSync, openSync, readdirSync, readSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { transcriptPathCandidates } from "../resolve/transcript.js";
+const DEFAULT_TAIL_BYTES = 256 * 1024;
+/**
+ * An active turn can accumulate enough tool traffic to push its native turn
+ * ancestor beyond the ordinary status tail. Keep attribution bounded while
+ * giving long-running interactive turns a larger matching window.
+ */
+const ACTIVE_TURN_TAIL_BYTES = 4 * 1024 * 1024;
+const DEFAULT_MAX_SAMPLE_AGE_MS = 30_000;
+const DEFAULT_MAX_CURSOR_DATABASES = 8;
+const SESSION_CACHE_LIMIT = 128;
+const codexTranscriptCache = new Map();
+const cursorDatabaseCache = new Map();
+/**
+ * Read privacy-safe context telemetry from a local runtime transcript.
+ *
+ * The returned union contains only numeric measurements, timestamps, bounded
+ * I/O counters, and a privacy-safe witness. Transcript bodies and paths never
+ * cross this interface.
+ */
+export function readRuntimeContextTelemetry(request, options = {}) {
+    const startedAt = performance.now();
+    if (!request.session_id)
+        return unsupported("runtime_session_id_not_reported", startedAt);
+    if (request.mode !== "status" && !request.turn_id && request.adapter !== "cursor") {
+        return unsupported("runtime_turn_id_not_reported", startedAt);
+    }
+    if (request.adapter === "codex")
+        return readCodexContext(request, options, startedAt);
+    if (request.adapter === "claude-code")
+        return readClaudeContext(request, options, startedAt);
+    if (request.adapter === "cursor")
+        return readCursorContext(request, options, startedAt);
+    return unsupported("runtime_adapter_not_supported", startedAt);
+}
+/**
+ * Locate a Codex rollout transcript for a session when the hook payload
+ * carries no transcript_path. Codex omits the path on its hook events, which
+ * leaves transcript-backed evidence unavailable unless Harnery resolves the
+ * rollout itself. Discovery reuses the telemetry scanner's roots (native
+ * ~/.codex plus WSL-mounted Windows homes) and its process cache, and returns
+ * undefined on zero or ambiguous matches.
+ *
+ * Callers on repeated hook paths must retain the verified result in their
+ * owner-only session state. The process cache bounds repeated reads inside one
+ * process, but hook processes are intentionally short-lived.
+ */
+export function discoverCodexSessionTranscript(sessionId, transcriptPath, options = {}) {
+    if (!sessionId || !/^[0-9a-f][0-9a-f-]{14,62}[0-9a-f]$/i.test(sessionId))
+        return undefined;
+    const resolution = resolveCodexTranscript({ adapter: "codex", session_id: sessionId, transcript_path: transcriptPath, mode: "status" }, options);
+    return resolution.state === "found" ? resolution.path : undefined;
+}
+/** Status compatibility wrapper: exact pairs render; partial values do not. */
+export function readRuntimeContextUsage(adapter, sessionId, options = {}) {
+    const result = readRuntimeContextTelemetry({ adapter, session_id: sessionId, mode: "status" }, options);
+    return result.state === "observed" && "used_tokens" in result
+        ? { used: result.used_tokens, window: result.limit_tokens }
+        : null;
+}
+export function clearRuntimeTelemetryCachesForTest() {
+    codexTranscriptCache.clear();
+    cursorDatabaseCache.clear();
+}
+/**
+ * Read the newest observed tuning (effort, and speed where reported) for a
+ * session from its local runtime transcript.
+ *
+ * Codex: the newest `turn_context` row carries the EFFECTIVE per-turn effort,
+ * including `-c model_reasoning_effort` overrides (the config default is
+ * deliberately not consulted — it is the default, not the effective value).
+ * CC: the newest assistant row carries effort at the row's top level and
+ * speed inside `message.usage`; model, effort, and speed are read from the
+ * SAME row so a mid-session model swap cannot blend two rows' values.
+ *
+ * Same bounded tail-read and privacy posture as `readRuntimeContextTelemetry`:
+ * only tokens, timestamps, and I/O counters cross this interface.
+ */
+export function readRuntimeTuning(request, options = {}) {
+    const startedAt = performance.now();
+    if (request.adapter === "codex") {
+        if (!request.session_id)
+            return unsupported("runtime_session_id_not_reported", startedAt);
+        return readCodexTuning(request, options, startedAt);
+    }
+    if (request.adapter === "claude-code")
+        return readClaudeTuning(request, options, startedAt);
+    return unsupported("runtime_adapter_not_supported", startedAt);
+}
+function readCodexTuning(request, options, startedAt) {
+    const resolved = resolveCodexTranscript({
+        adapter: "codex",
+        session_id: request.session_id,
+        transcript_path: request.transcript_path,
+        mode: "status",
+    }, options);
+    if (resolved.state === "missing") {
+        return unsupported("runtime_context_telemetry_unavailable", startedAt);
+    }
+    if (resolved.state === "ambiguous") {
+        return tuningPartial("codex_transcript_ambiguous", 0, startedAt);
+    }
+    if (resolved.state === "mismatch") {
+        return tuningPartial("codex_transcript_session_mismatch", 0, startedAt);
+    }
+    const tail = readTail(resolved.path, options.maxTailBytes ?? DEFAULT_TAIL_BYTES);
+    if (!tail)
+        return tuningPartial("codex_transcript_unreadable", 0, startedAt);
+    const fromTail = newestTurnContextTuning(parseRuntimeRows(tail.text), tail.bytes, startedAt);
+    if (fromTail)
+        return fromTail;
+    // `turn_context` is written at the START of a turn, so one long turn pushes
+    // it past the bounded tail. The front of the file is then the reliable
+    // place, but not a fixed-size head: a real interactive rollout opens with
+    // hundreds of KB of session_meta, instruction, and world_state rows before
+    // the first turn_context (observed live: 272KB in a desktop session). Scan
+    // forward in bounded chunks and keep the LAST match inside the cap; rows
+    // between the cap and the tail window stay unscanned, and the stop-time
+    // re-read heals any staleness that gap could cause.
+    const forward = scanForwardTurnContext(resolved.path, TUNING_FORWARD_SCAN_MAX_BYTES);
+    if (forward.row) {
+        const fromForward = newestTurnContextTuning([forward.row], tail.bytes + forward.bytes, startedAt);
+        if (fromForward)
+            return fromForward;
+    }
+    return tuningPartial("codex_transcript_turn_context_missing", tail.bytes + forward.bytes, startedAt);
+}
+/** Forward-scan budget for the first turn_context; generous against
+ * instruction/world_state bloat while still bounding a runaway file. */
+const TUNING_FORWARD_SCAN_MAX_BYTES = 4 * 1024 * 1024;
+const TUNING_FORWARD_CHUNK_BYTES = 256 * 1024;
+/** Stream the file from the start in bounded chunks, returning the last
+ * parseable `turn_context` row inside the budget and the bytes read. */
+function scanForwardTurnContext(path, maxBytes) {
+    let fd;
+    let bytesRead = 0;
+    let remainder = "";
+    let match;
+    try {
+        fd = openSync(path, "r");
+        const buffer = Buffer.alloc(TUNING_FORWARD_CHUNK_BYTES);
+        while (bytesRead < maxBytes) {
+            const read = readSync(fd, buffer, 0, buffer.length, bytesRead);
+            if (read <= 0)
+                break;
+            bytesRead += read;
+            const text = remainder + buffer.subarray(0, read).toString("utf8");
+            const lines = text.split("\n");
+            remainder = lines.pop() ?? "";
+            for (const line of lines) {
+                if (!line.includes('"turn_context"'))
+                    continue;
+                const rows = parseRuntimeRows(line);
+                const row = rows.find((candidate) => candidate.type === "turn_context");
+                if (row)
+                    match = row;
+            }
+            if (read < buffer.length)
+                break;
+        }
+        return { row: match, bytes: bytesRead };
+    }
+    catch {
+        return { row: match, bytes: bytesRead };
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function newestTurnContextTuning(rows, bytesRead, startedAt) {
+    for (let index = rows.length - 1; index >= 0; index--) {
+        const row = rows[index];
+        if (row.type !== "turn_context")
+            continue;
+        const effort = row.payload?.effort;
+        const model = row.payload?.model;
+        if (typeof effort !== "string" || effort.length === 0)
+            continue;
+        return {
+            state: "observed",
+            effort,
+            ...(typeof model === "string" && model.length > 0 ? { model } : {}),
+            ...(row.timestamp ? { measured_at: row.timestamp } : {}),
+            method: "codex_transcript_turn_context",
+            source_event: "codex.rollout_turn_context",
+            bytes_read: bytesRead,
+            io_duration_ms: elapsed(startedAt),
+        };
+    }
+    return undefined;
+}
+function readClaudeTuning(request, options, startedAt) {
+    const readablePath = transcriptPathCandidates(request.transcript_path).find((candidate) => existsSync(candidate));
+    if (!readablePath)
+        return unsupported("runtime_context_telemetry_unavailable", startedAt);
+    const tail = readTail(readablePath, options.maxTailBytes ?? DEFAULT_TAIL_BYTES);
+    if (!tail)
+        return tuningPartial("claude_transcript_unreadable", 0, startedAt);
+    const rows = parseRuntimeRows(tail.text);
+    for (let index = rows.length - 1; index >= 0; index--) {
+        const row = rows[index];
+        if (row.type !== "assistant")
+            continue;
+        const model = row.payload?.model;
+        if (typeof model !== "string" || model.length === 0 || model.startsWith("<"))
+            continue;
+        const usage = objectValue(row.payload?.usage);
+        const speed = usage?.speed;
+        return {
+            state: "observed",
+            model,
+            ...(row.effort ? { effort: row.effort } : {}),
+            ...(typeof speed === "string" && speed.length > 0 ? { speed } : {}),
+            ...(row.timestamp ? { measured_at: row.timestamp } : {}),
+            method: "claude_transcript_assistant_row",
+            source_event: "claude-code.transcript_assistant_row",
+            bytes_read: tail.bytes,
+            io_duration_ms: elapsed(startedAt),
+        };
+    }
+    return tuningPartial("claude_transcript_assistant_row_missing", tail.bytes, startedAt);
+}
+function tuningPartial(reason, bytesRead, startedAt) {
+    return {
+        state: "partial",
+        reason,
+        bytes_read: bytesRead,
+        io_duration_ms: elapsed(startedAt),
+    };
+}
+function readCodexContext(request, options, startedAt) {
+    const resolved = resolveCodexTranscript(request, options);
+    if (resolved.state === "missing") {
+        return unsupported("runtime_context_telemetry_unavailable", startedAt);
+    }
+    if (resolved.state === "ambiguous") {
+        return partial("codex_transcript_ambiguous", 0, startedAt);
+    }
+    if (resolved.state === "mismatch") {
+        return partial("codex_transcript_session_mismatch", 0, startedAt);
+    }
+    const tail = readTail(resolved.path, options.maxTailBytes ??
+        (request.mode === "active_turn" ? ACTIVE_TURN_TAIL_BYTES : DEFAULT_TAIL_BYTES));
+    if (!tail)
+        return partial("codex_transcript_unreadable", 0, startedAt);
+    const rows = parseRuntimeRows(tail.text);
+    if (request.mode === "status") {
+        const token = newestCodexToken(rows);
+        return codexObservation(request, token, undefined, tail.bytes, options, startedAt);
+    }
+    if (request.mode === "active_turn") {
+        const active = tokenWithinActiveTurn(rows, request.turn_id);
+        const token = active.state === "found" ? active.token : tokenAtOrAfter(rows, request.turn_started_at);
+        if (active.state === "turn_missing" && !token) {
+            return partial("codex_transcript_turn_not_found", tail.bytes, startedAt);
+        }
+        return codexObservation(request, token, undefined, tail.bytes, options, startedAt);
+    }
+    const turnId = request.turn_id;
+    const terminalIndex = findCodexTurnTerminal(rows, turnId);
+    if (terminalIndex < 0) {
+        const sawStart = rows.some((row) => row.type === "event_msg" &&
+            row.payload?.type === "task_started" &&
+            row.payload.turn_id === turnId);
+        return partial(sawStart ? "codex_transcript_turn_not_terminal" : "codex_transcript_turn_not_found", tail.bytes, startedAt);
+    }
+    const terminal = rows[terminalIndex];
+    const token = tokenBeforeTerminal(rows, terminalIndex);
+    return codexObservation(request, token, terminal, tail.bytes, options, startedAt);
+}
+function codexObservation(request, token, terminal, bytesRead, options, startedAt) {
+    if (!token)
+        return partial("codex_transcript_token_count_missing", bytesRead, startedAt);
+    if (token.used_tokens === undefined) {
+        return partial("context_used_tokens_not_reported", bytesRead, startedAt);
+    }
+    if (token.limit_tokens === undefined) {
+        return partial("context_limit_tokens_not_reported", bytesRead, startedAt, token);
+    }
+    if (token.limit_tokens <= 0) {
+        return partial("context_limit_tokens_invalid", bytesRead, startedAt, token);
+    }
+    if (!token.measured_at || !Number.isFinite(Date.parse(token.measured_at))) {
+        return partial("codex_transcript_token_count_missing", bytesRead, startedAt);
+    }
+    if (terminal?.timestamp) {
+        const age = Date.parse(terminal.timestamp) - Date.parse(token.measured_at);
+        if (age < 0 || age > (options.maxSampleAgeMs ?? DEFAULT_MAX_SAMPLE_AGE_MS)) {
+            return partial("codex_transcript_sample_stale", bytesRead, startedAt, token);
+        }
+    }
+    if (request.mode === "active_turn" && request.observed_at) {
+        const age = Date.parse(request.observed_at) - Date.parse(token.measured_at);
+        if (!Number.isFinite(age) ||
+            age < -5_000 ||
+            age > (options.maxSampleAgeMs ?? DEFAULT_MAX_SAMPLE_AGE_MS)) {
+            return partial("codex_transcript_sample_stale", bytesRead, startedAt, token);
+        }
+    }
+    const witness = [
+        request.session_id,
+        request.turn_id ?? "status",
+        token.ordinal ?? "unknown",
+        token.measured_at,
+        token.used_tokens,
+        token.limit_tokens,
+    ].join("\0");
+    return {
+        state: "observed",
+        used_tokens: token.used_tokens,
+        limit_tokens: token.limit_tokens,
+        measured_at: token.measured_at,
+        method: "codex_transcript_token_count",
+        source_event: "codex.rollout_token_count",
+        source_witness: createHash("sha256").update(witness).digest("hex"),
+        attestation: "derived",
+        confidence: "exact",
+        bytes_read: bytesRead,
+        io_duration_ms: elapsed(startedAt),
+    };
+}
+function readClaudeContext(request, options, startedAt) {
+    const readablePath = transcriptPathCandidates(request.transcript_path).find((candidate) => existsSync(candidate));
+    if (!readablePath)
+        return unsupported("runtime_context_telemetry_unavailable", startedAt);
+    const tail = readTail(readablePath, options.maxTailBytes ??
+        (request.mode === "active_turn" ? ACTIVE_TURN_TAIL_BYTES : DEFAULT_TAIL_BYTES));
+    if (!tail)
+        return partial("claude_transcript_unreadable", 0, startedAt);
+    const rows = parseRuntimeRows(tail.text);
+    const sessionRows = rows.filter((row) => row.session_id === undefined || row.session_id === request.session_id);
+    if (rows.some((row) => row.session_id !== undefined) && sessionRows.length === 0) {
+        return partial("claude_transcript_session_mismatch", tail.bytes, startedAt);
+    }
+    const turnAttributed = request.mode === "turn" || request.mode === "active_turn";
+    const candidateRows = turnAttributed
+        ? claudeAssistantRowsForTurn(sessionRows, request.turn_id)
+        : sessionRows.filter((row) => row.type === "assistant");
+    if (turnAttributed && candidateRows.length === 0) {
+        return partial("claude_transcript_turn_not_found", tail.bytes, startedAt);
+    }
+    for (let index = candidateRows.length - 1; index >= 0; index--) {
+        const row = candidateRows[index];
+        if (row.type !== "assistant")
+            continue;
+        const message = row.payload;
+        const usage = objectValue(message?.usage);
+        if (!usage)
+            continue;
+        const used = sumNumbers(usage.input_tokens, usage.cache_creation_input_tokens, usage.cache_read_input_tokens);
+        if (used === undefined) {
+            return partial("context_used_tokens_not_reported", tail.bytes, startedAt);
+        }
+        const model = stringValue(message?.model);
+        const capability = model ? claudeModelContextCapability(model) : undefined;
+        if (capability && row.timestamp) {
+            if (request.mode === "active_turn" && request.observed_at) {
+                const age = Date.parse(request.observed_at) - Date.parse(row.timestamp);
+                if (!Number.isFinite(age) ||
+                    age < -5_000 ||
+                    age > (options.maxSampleAgeMs ?? DEFAULT_MAX_SAMPLE_AGE_MS)) {
+                    return partial("claude_transcript_sample_stale", tail.bytes, startedAt, {
+                        used_tokens: used,
+                        measured_at: row.timestamp,
+                    });
+                }
+            }
+            const witness = [
+                request.session_id,
+                request.turn_id ?? "status",
+                row.timestamp,
+                used,
+                model,
+                capability.limit_tokens,
+                capability.authority,
+            ].join("\0");
+            return {
+                state: "observed",
+                used_tokens: used,
+                limit_tokens: capability.limit_tokens,
+                measured_at: row.timestamp,
+                method: "claude_transcript_usage_model_capability",
+                source_event: "claude.transcript_usage_model_capability",
+                source_witness: createHash("sha256").update(witness).digest("hex"),
+                attestation: "inferred",
+                confidence: "high",
+                bytes_read: tail.bytes,
+                io_duration_ms: elapsed(startedAt),
+            };
+        }
+        return partial("claude_context_limit_tokens_not_reported", tail.bytes, startedAt, {
+            used_tokens: used,
+            measured_at: row.timestamp,
+        });
+    }
+    return partial("context_used_tokens_not_reported", tail.bytes, startedAt);
+}
+/**
+ * Versioned exact-name families from Anthropic's published model capability
+ * table. Unknown aliases deliberately stay missing: matching a product label
+ * or guessing from a family name would turn an estimate into fake precision.
+ */
+function claudeModelContextCapability(model) {
+    const normalized = model.toLowerCase();
+    const oneMillionTokenModels = new Set([
+        "claude-fable-5",
+        "claude-opus-5",
+        "claude-sonnet-5",
+        "claude-opus-4-8",
+        "claude-opus-4-7",
+        "claude-opus-4-6",
+        "claude-sonnet-4-6",
+    ]);
+    if (oneMillionTokenModels.has(normalized)) {
+        return { limit_tokens: 1_000_000, authority: "anthropic_model_capabilities_2026_08" };
+    }
+    if (normalized === "claude-haiku-4-5" || normalized === "claude-haiku-4-5-20251001") {
+        return { limit_tokens: 200_000, authority: "anthropic_model_capabilities_2026_08" };
+    }
+    return undefined;
+}
+function readCursorContext(request, options, startedAt) {
+    const cached = cursorDatabaseCache.get(request.session_id);
+    if (cached && existsSync(cached)) {
+        const sample = readCursorDatabase(cached, request.session_id);
+        if (sample.state === "found") {
+            return cursorObservation(request, sample.sample, options, startedAt);
+        }
+        cursorDatabaseCache.delete(request.session_id);
+    }
+    const databases = cursorDatabasePaths(options);
+    if (databases.length === 0) {
+        return partial("cursor_context_database_unavailable", 0, startedAt);
+    }
+    const matches = [];
+    let bytesRead = 0;
+    let unreadable = 0;
+    for (const databasePath of databases) {
+        const result = readCursorDatabase(databasePath, request.session_id);
+        bytesRead += result.state === "found" ? result.sample.bytes_read : result.bytes_read;
+        if (result.state === "unreadable")
+            unreadable += 1;
+        if (result.state !== "found")
+            continue;
+        matches.push(result.sample);
+    }
+    if (matches.length === 0) {
+        return partial(unreadable === databases.length
+            ? "cursor_context_database_unreadable"
+            : "cursor_context_session_not_found", bytesRead, startedAt);
+    }
+    matches.sort((left, right) => Date.parse(right.measured_at) - Date.parse(left.measured_at));
+    const newest = matches[0];
+    const tied = matches.filter((sample) => sample.measured_at === newest.measured_at);
+    if (tied.some((sample) => sample.used_percent !== newest.used_percent)) {
+        return partial("cursor_context_sample_ambiguous", bytesRead, startedAt);
+    }
+    cacheCursorDatabase(request.session_id, newest.database_path);
+    return cursorObservation(request, newest, options, startedAt);
+}
+function cursorObservation(request, sample, options, startedAt) {
+    if (!Number.isFinite(sample.used_percent) ||
+        sample.used_percent < 0 ||
+        sample.used_percent > 100) {
+        return partial("cursor_context_usage_invalid", sample.bytes_read, startedAt);
+    }
+    const sampleMs = Date.parse(sample.measured_at);
+    if (!Number.isFinite(sampleMs)) {
+        return partial("cursor_context_sample_time_not_reported", sample.bytes_read, startedAt);
+    }
+    if ((request.mode === "turn" || request.mode === "active_turn") && request.observed_at) {
+        const observedMs = Date.parse(request.observed_at);
+        const age = observedMs - sampleMs;
+        if (!Number.isFinite(observedMs) ||
+            age < -5_000 ||
+            age > (options.maxSampleAgeMs ?? DEFAULT_MAX_SAMPLE_AGE_MS)) {
+            return partial("cursor_context_sample_stale", sample.bytes_read, startedAt);
+        }
+    }
+    const witness = [request.session_id, sample.measured_at, sample.used_percent].join("\0");
+    return {
+        state: "observed",
+        used_percent: sample.used_percent,
+        measured_at: sample.measured_at,
+        method: "cursor_composer_context_percent",
+        source_event: "cursor.composer_context_percent",
+        source_witness: createHash("sha256").update(witness).digest("hex"),
+        attestation: "derived",
+        confidence: "high",
+        bytes_read: sample.bytes_read,
+        io_duration_ms: elapsed(startedAt),
+    };
+}
+function readCursorDatabase(databasePath, sessionId) {
+    try {
+        // Bun is the primary hook runtime. Node fallback processes fail closed here
+        // instead of importing a Bun-only module at startup.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { Database } = require("bun:sqlite");
+        const database = new Database(databasePath, { readonly: true });
+        const row = database
+            .query("SELECT value FROM ItemTable WHERE key = 'composer.composerData'")
+            .get();
+        database.close();
+        if (!row?.value)
+            return { state: "missing", bytes_read: 0 };
+        const text = typeof row.value === "string" ? row.value : Buffer.from(row.value).toString("utf8");
+        const bytesRead = Buffer.byteLength(text);
+        const parsed = objectValue(JSON.parse(text));
+        const composers = Array.isArray(parsed?.allComposers) ? parsed.allComposers : [];
+        for (const candidate of composers) {
+            const composer = objectValue(candidate);
+            if (stringValue(composer?.composerId) !== sessionId)
+                continue;
+            const usedPercent = numberValue(composer?.contextUsagePercent);
+            if (usedPercent === undefined)
+                return { state: "missing", bytes_read: bytesRead };
+            const measuredAt = cursorMeasuredAt(composer?.lastUpdatedAt);
+            if (!measuredAt)
+                return { state: "missing", bytes_read: bytesRead };
+            return {
+                state: "found",
+                sample: {
+                    used_percent: usedPercent,
+                    measured_at: measuredAt,
+                    bytes_read: bytesRead,
+                    database_path: databasePath,
+                },
+            };
+        }
+        return { state: "missing", bytes_read: bytesRead };
+    }
+    catch {
+        return { state: "unreadable", bytes_read: 0 };
+    }
+}
+function cursorMeasuredAt(value) {
+    if (typeof value === "string" && Number.isFinite(Date.parse(value))) {
+        return new Date(value).toISOString();
+    }
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0)
+        return undefined;
+    const milliseconds = value < 10_000_000_000 ? value * 1_000 : value;
+    const date = new Date(milliseconds);
+    return Number.isFinite(date.getTime()) ? date.toISOString() : undefined;
+}
+function cursorDatabasePaths(options) {
+    const roots = options.cursorRoots ?? defaultCursorRoots();
+    const limit = Math.max(1, Math.floor(options.maxCursorDatabases ?? DEFAULT_MAX_CURSOR_DATABASES));
+    const candidates = [];
+    for (const root of roots) {
+        let names;
+        try {
+            names = readdirSync(root).sort();
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            const databasePath = join(root, name, "state.vscdb");
+            try {
+                candidates.push({ path: databasePath, modified_ms: statSync(databasePath).mtimeMs });
+            }
+            catch {
+                // Removed or unreadable workspaces are not candidates.
+            }
+        }
+    }
+    return candidates
+        .sort((left, right) => right.modified_ms - left.modified_ms)
+        .slice(0, limit)
+        .map((candidate) => candidate.path);
+}
+function defaultCursorRoots() {
+    const roots = [resolve(homedir(), ".config", "Cursor", "User", "workspaceStorage")];
+    try {
+        if (existsSync("/mnt/c/Users")) {
+            for (const user of readdirSync("/mnt/c/Users")) {
+                roots.push(`/mnt/c/Users/${user}/AppData/Roaming/Cursor/User/workspaceStorage`);
+            }
+        }
+    }
+    catch {
+        // Non-WSL hosts do not expose this mount.
+    }
+    return roots;
+}
+function cacheCursorDatabase(sessionId, databasePath) {
+    cursorDatabaseCache.delete(sessionId);
+    cursorDatabaseCache.set(sessionId, databasePath);
+    while (cursorDatabaseCache.size > SESSION_CACHE_LIMIT) {
+        cursorDatabaseCache.delete(cursorDatabaseCache.keys().next().value);
+    }
+}
+/** Join assistant rows to the native CC prompt id through the transcript's
+ * parent UUID chain. No UUID or prompt value crosses the reader boundary. */
+function claudeAssistantRowsForTurn(rows, turnId) {
+    const byUuid = new Map(rows.filter((row) => row.uuid).map((row) => [row.uuid, row]));
+    return rows.filter((row) => {
+        if (row.type !== "assistant")
+            return false;
+        let parentUuid = row.parent_uuid;
+        const seen = new Set();
+        for (let depth = 0; parentUuid && depth < 64 && !seen.has(parentUuid); depth += 1) {
+            seen.add(parentUuid);
+            const parent = byUuid.get(parentUuid);
+            if (!parent)
+                return false;
+            if (parent.type === "user" && parent.prompt_id)
+                return parent.prompt_id === turnId;
+            parentUuid = parent.parent_uuid;
+        }
+        return false;
+    });
+}
+function newestCodexToken(rows) {
+    for (let index = rows.length - 1; index >= 0; index--) {
+        const token = codexToken(rows[index]);
+        if (token)
+            return token;
+    }
+    return undefined;
+}
+function tokenWithinActiveTurn(rows, turnId) {
+    let startIndex = -1;
+    for (let index = rows.length - 1; index >= 0; index -= 1) {
+        const row = rows[index];
+        if (row.type === "event_msg" &&
+            row.payload?.type === "task_started" &&
+            row.payload.turn_id === turnId) {
+            startIndex = index;
+            break;
+        }
+    }
+    if (startIndex < 0)
+        return { state: "turn_missing" };
+    let token;
+    for (let index = startIndex + 1; index < rows.length; index += 1) {
+        const row = rows[index];
+        if (row.type === "event_msg" &&
+            (row.payload?.type === "task_started" || row.payload?.type === "task_complete")) {
+            break;
+        }
+        token = codexToken(row) ?? token;
+    }
+    return { state: "found", token };
+}
+function tokenAtOrAfter(rows, turnStartedAt) {
+    if (!turnStartedAt || !Number.isFinite(Date.parse(turnStartedAt)))
+        return undefined;
+    const token = newestCodexToken(rows);
+    if (!token?.measured_at)
+        return undefined;
+    return Date.parse(token.measured_at) >= Date.parse(turnStartedAt) ? token : undefined;
+}
+function tokenBeforeTerminal(rows, terminalIndex) {
+    for (let index = terminalIndex - 1; index >= 0; index--) {
+        const row = rows[index];
+        const type = row.payload?.type;
+        if (type === "task_started" || type === "task_complete")
+            break;
+        const token = codexToken(row);
+        if (token)
+            return token;
+    }
+    return undefined;
+}
+function codexToken(row) {
+    if (row.type !== "event_msg" || row.payload?.type !== "token_count")
+        return undefined;
+    const info = objectValue(row.payload.info);
+    const usage = objectValue(info?.last_token_usage);
+    return {
+        used_tokens: safeInteger(usage?.input_tokens),
+        limit_tokens: safeInteger(info?.model_context_window),
+        measured_at: timestamp(row.timestamp),
+        ordinal: safeInteger(row.ordinal),
+    };
+}
+function findCodexTurnTerminal(rows, turnId) {
+    for (let index = rows.length - 1; index >= 0; index--) {
+        const row = rows[index];
+        if (row.type === "event_msg" &&
+            row.payload?.type === "task_complete" &&
+            row.payload.turn_id === turnId) {
+            return index;
+        }
+    }
+    return -1;
+}
+function parseRuntimeRows(text) {
+    const rows = [];
+    for (const line of text.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const value = JSON.parse(line);
+            const row = objectValue(value);
+            if (!row)
+                continue;
+            rows.push({
+                timestamp: timestamp(row.timestamp),
+                ordinal: safeInteger(row.ordinal),
+                type: typeof row.type === "string" ? row.type : undefined,
+                uuid: stringValue(row.uuid),
+                parent_uuid: stringValue(row.parentUuid),
+                prompt_id: stringValue(row.promptId) ?? stringValue(row.prompt_id),
+                session_id: stringValue(row.sessionId) ?? stringValue(row.session_id),
+                ...(typeof row.effort === "string" && row.effort.length > 0 ? { effort: row.effort } : {}),
+                payload: objectValue(row.payload) ?? objectValue(row.message) ?? undefined,
+            });
+        }
+        catch {
+            // The first line may be cut by the bounded tail or a writer may be mid-flush.
+        }
+    }
+    return rows;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function numberValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function readTail(path, maxBytes) {
+    let fd;
+    try {
+        const size = statSync(path).size;
+        const bytes = Math.max(0, Math.min(size, Math.max(1, Math.floor(maxBytes))));
+        const start = size - bytes;
+        fd = openSync(path, "r");
+        const buffer = Buffer.alloc(bytes);
+        const read = readSync(fd, buffer, 0, bytes, start);
+        const text = buffer.subarray(0, read).toString("utf8");
+        return {
+            text: start > 0 ? text.slice(Math.max(0, text.indexOf("\n") + 1)) : text,
+            bytes: read,
+        };
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function resolveCodexTranscript(request, options) {
+    const sessionId = request.session_id;
+    const cached = codexTranscriptCache.get(sessionId);
+    if (cached && existsSync(cached))
+        return { state: "found", path: cached };
+    const supplied = transcriptPathCandidates(request.transcript_path).filter((candidate) => existsSync(candidate));
+    const verifiedSupplied = supplied.filter((candidate) => transcriptMatches(candidate, sessionId));
+    if (verifiedSupplied.length === 1)
+        return cacheTranscript(sessionId, verifiedSupplied[0]);
+    if (verifiedSupplied.length > 1)
+        return { state: "ambiguous" };
+    if (supplied.length > 0)
+        return { state: "mismatch" };
+    const matches = codexRoots(options)
+        .flatMap((root) => findTranscriptMatches(root, sessionId))
+        .filter((path, index, values) => values.indexOf(path) === index);
+    if (matches.length === 1)
+        return cacheTranscript(sessionId, matches[0]);
+    if (matches.length > 1)
+        return { state: "ambiguous" };
+    return { state: "missing" };
+}
+function cacheTranscript(sessionId, path) {
+    codexTranscriptCache.delete(sessionId);
+    codexTranscriptCache.set(sessionId, path);
+    while (codexTranscriptCache.size > SESSION_CACHE_LIMIT) {
+        codexTranscriptCache.delete(codexTranscriptCache.keys().next().value);
+    }
+    return { state: "found", path };
+}
+function codexRoots(options) {
+    if (options.codexRoots)
+        return options.codexRoots;
+    const roots = [resolve(homedir(), ".codex", "sessions")];
+    try {
+        if (existsSync("/mnt/c/Users")) {
+            for (const user of readdirSync("/mnt/c/Users")) {
+                roots.push(`/mnt/c/Users/${user}/.codex/sessions`);
+            }
+        }
+    }
+    catch {
+        // Non-WSL hosts do not expose this mount.
+    }
+    return roots;
+}
+function findTranscriptMatches(root, sessionId) {
+    if (!existsSync(root))
+        return [];
+    const matches = [];
+    const stack = [{ path: root, depth: 0 }];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (current.depth > 4)
+            continue;
+        let names;
+        try {
+            names = readdirSync(current.path);
+        }
+        catch {
+            continue;
+        }
+        for (const name of names) {
+            const path = join(current.path, name);
+            try {
+                const stat = statSync(path);
+                if (stat.isDirectory())
+                    stack.push({ path, depth: current.depth + 1 });
+                else if (transcriptMatches(path, sessionId))
+                    matches.push(path);
+            }
+            catch {
+                // A concurrently removed partition is simply unavailable.
+            }
+        }
+    }
+    return matches;
+}
+function transcriptMatches(path, sessionId) {
+    return basename(path).endsWith(`-${sessionId}.jsonl`);
+}
+/** Narrow return: this exact shape is a member of both telemetry unions. */
+function unsupported(reason, startedAt) {
+    return { state: "unsupported", reason, bytes_read: 0, io_duration_ms: elapsed(startedAt) };
+}
+function partial(reason, bytesRead, startedAt, sample) {
+    return {
+        state: "partial",
+        reason,
+        ...(sample?.used_tokens !== undefined ? { used_tokens: sample.used_tokens } : {}),
+        ...(sample?.measured_at ? { measured_at: sample.measured_at } : {}),
+        bytes_read: bytesRead,
+        io_duration_ms: elapsed(startedAt),
+    };
+}
+function elapsed(startedAt) {
+    return Math.max(0, Math.round((performance.now() - startedAt) * 1000) / 1000);
+}
+function objectValue(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function safeInteger(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : undefined;
+}
+function timestamp(value) {
+    if (typeof value !== "string" || !Number.isFinite(Date.parse(value)))
+        return undefined;
+    return new Date(value).toISOString();
+}
+function sumNumbers(...values) {
+    const numbers = values.map(safeInteger);
+    return numbers.some((value) => value !== undefined)
+        ? numbers.reduce((total, value) => total + (value ?? 0), 0)
+        : undefined;
+}