harnery 0.35.0 → 0.37.0

package/src/core/hooks/adapter/runtime-telemetry.ts

@@ -7,7 +7,14 @@ import type { Adapter } from "../../adapter.ts";
 import { transcriptPathCandidates } from "../resolve/transcript.ts";
 
 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;
 
 export type RuntimeContextTelemetry =
@@ -16,9 +23,23 @@ export type RuntimeContextTelemetry =
       used_tokens: number;
       limit_tokens: number;
       measured_at: string;
-      method: "codex_transcript_token_count";
+      method: "codex_transcript_token_count" | "claude_transcript_usage_model_capability";
       source_event: string;
       source_witness: string;
+      attestation: "derived" | "inferred";
+      confidence: "exact" | "high" | "medium";
+      bytes_read: number;
+      io_duration_ms: number;
+    }
+  | {
+      state: "observed";
+      used_percent: number;
+      measured_at: string;
+      method: "cursor_composer_context_percent";
+      source_event: string;
+      source_witness: string;
+      attestation: "derived";
+      confidence: "high";
       runtime_version?: string;
       bytes_read: number;
       io_duration_ms: number;
@@ -50,9 +71,17 @@ export type RuntimeContextMissingReason =
   | "context_limit_tokens_not_reported"
   | "context_limit_tokens_invalid"
   | "claude_context_limit_tokens_not_reported"
+  | "claude_transcript_sample_stale"
   | "claude_transcript_session_mismatch"
   | "claude_transcript_turn_not_found"
-  | "claude_transcript_unreadable";
+  | "claude_transcript_unreadable"
+  | "cursor_context_database_unavailable"
+  | "cursor_context_database_unreadable"
+  | "cursor_context_session_not_found"
+  | "cursor_context_sample_ambiguous"
+  | "cursor_context_sample_stale"
+  | "cursor_context_sample_time_not_reported"
+  | "cursor_context_usage_invalid";
 
 export type RuntimeContextUnsupportedReason =
   | "runtime_context_telemetry_unavailable"
@@ -64,15 +93,25 @@ export interface RuntimeContextRequest {
   adapter: Adapter;
   session_id?: string;
   turn_id?: string;
+  /** Canonical producer turn boundary used when task_started has left the bounded tail. */
+  turn_started_at?: string;
   transcript_path?: string;
-  /** Status callers may request the newest session sample without claiming turn attribution. */
-  mode: "turn" | "status";
+  observed_at?: string;
+  /**
+   * Status reads the newest session sample without turn attribution. Active
+   * turn reads require a matching task_started boundary but not task_complete.
+   */
+  mode: "turn" | "active_turn" | "status";
 }
 
 export interface RuntimeTelemetryOptions {
   codexRoots?: string[];
+  cursorRoots?: string[];
+  maxCursorDatabases?: number;
   maxTailBytes?: number;
   maxSampleAgeMs?: number;
+  /** Recorder-only cadence override used by deterministic tests. */
+  activeContextProbeIntervalMs?: number;
 }
 
 interface TailRead {
@@ -101,6 +140,7 @@ interface CodexTokenSample {
 }
 
 const codexTranscriptCache = new Map<string, string>();
+const cursorDatabaseCache = new Map<string, string>();
 
 /**
  * Read privacy-safe context telemetry from a local runtime transcript.
@@ -115,11 +155,12 @@ export function readRuntimeContextTelemetry(
 ): RuntimeContextTelemetry {
   const startedAt = performance.now();
   if (!request.session_id) return unsupported("runtime_session_id_not_reported", startedAt);
-  if (request.mode === "turn" && !request.turn_id) {
+  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);
 }
 
@@ -158,13 +199,14 @@ export function readRuntimeContextUsage(
     { adapter, session_id: sessionId, mode: "status" },
     options,
   );
-  return result.state === "observed"
+  return result.state === "observed" && "used_tokens" in result
     ? { used: result.used_tokens, window: result.limit_tokens }
     : null;
 }
 
 export function clearRuntimeTelemetryCachesForTest(): void {
   codexTranscriptCache.clear();
+  cursorDatabaseCache.clear();
 }
 
 export type RuntimeTuningMissingReason =
@@ -422,7 +464,11 @@ function readCodexContext(
     return partial("codex_transcript_session_mismatch", 0, startedAt);
   }
 
-  const tail = readTail(resolved.path, options.maxTailBytes ?? DEFAULT_TAIL_BYTES);
+  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") {
@@ -430,6 +476,16 @@ function readCodexContext(
     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) {
@@ -478,6 +534,16 @@ function codexObservation(
       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",
@@ -494,6 +560,8 @@ function codexObservation(
     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),
   };
@@ -508,7 +576,11 @@ function readClaudeContext(
     existsSync(candidate),
   );
   if (!readablePath) return unsupported("runtime_context_telemetry_unavailable", startedAt);
-  const tail = readTail(readablePath, options.maxTailBytes ?? DEFAULT_TAIL_BYTES);
+  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(
@@ -517,11 +589,11 @@ function readClaudeContext(
   if (rows.some((row) => row.session_id !== undefined) && sessionRows.length === 0) {
     return partial("claude_transcript_session_mismatch", tail.bytes, startedAt);
   }
-  const candidateRows =
-    request.mode === "turn"
-      ? claudeAssistantRowsForTurn(sessionRows, request.turn_id!)
-      : sessionRows.filter((row) => row.type === "assistant");
-  if (request.mode === "turn" && candidateRows.length === 0) {
+  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--) {
@@ -538,6 +610,45 @@ function readClaudeContext(
     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,
@@ -546,6 +657,244 @@ function readClaudeContext(
   return partial("context_used_tokens_not_reported", tail.bytes, startedAt);
 }
 
+interface ClaudeModelContextCapability {
+  limit_tokens: number;
+  authority: string;
+}
+
+/**
+ * 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: string): ClaudeModelContextCapability | undefined {
+  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;
+}
+
+interface CursorContextSample {
+  used_percent: number;
+  measured_at: string;
+  bytes_read: number;
+  database_path: string;
+}
+
+function readCursorContext(
+  request: RuntimeContextRequest,
+  options: RuntimeTelemetryOptions,
+  startedAt: number,
+): RuntimeContextTelemetry {
+  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: CursorContextSample[] = [];
+  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: RuntimeContextRequest,
+  sample: CursorContextSample,
+  options: RuntimeTelemetryOptions,
+  startedAt: number,
+): RuntimeContextTelemetry {
+  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),
+  };
+}
+
+type CursorDatabaseResult =
+  | { state: "found"; sample: CursorContextSample }
+  | { state: "missing"; bytes_read: number }
+  | { state: "unreadable"; bytes_read: number };
+
+function readCursorDatabase(databasePath: string, sessionId: string): CursorDatabaseResult {
+  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") as {
+      Database: new (
+        path: string,
+        options: { readonly: boolean },
+      ) => {
+        query(sql: string): { get(): { value: string | Uint8Array } | null };
+        close(): void;
+      };
+    };
+    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: unknown): string | undefined {
+  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: RuntimeTelemetryOptions): string[] {
+  const roots = options.cursorRoots ?? defaultCursorRoots();
+  const limit = Math.max(1, Math.floor(options.maxCursorDatabases ?? DEFAULT_MAX_CURSOR_DATABASES));
+  const candidates: Array<{ path: string; modified_ms: number }> = [];
+  for (const root of roots) {
+    let names: string[];
+    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(): string[] {
+  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: string, databasePath: string): void {
+  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: ParsedRuntimeRow[], turnId: string): ParsedRuntimeRow[] {
@@ -573,6 +922,48 @@ function newestCodexToken(rows: ParsedRuntimeRow[]): CodexTokenSample | undefine
   return undefined;
 }
 
+function tokenWithinActiveTurn(
+  rows: ParsedRuntimeRow[],
+  turnId: string,
+): { state: "found"; token?: CodexTokenSample } | { state: "turn_missing" } {
+  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: CodexTokenSample | undefined;
+  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: ParsedRuntimeRow[],
+  turnStartedAt: string | undefined,
+): CodexTokenSample | undefined {
+  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: ParsedRuntimeRow[],
   terminalIndex: number,
@@ -643,6 +1034,10 @@ function stringValue(value: unknown): string | undefined {
   return typeof value === "string" && value.length > 0 ? value : undefined;
 }
 
+function numberValue(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
 function readTail(path: string, maxBytes: number): TailRead | undefined {
   let fd: number | undefined;
   try {