pi-provider-cursor-ask 0.1.0

package/src/stream/context-usage.ts

@@ -0,0 +1,168 @@
+/** Cursor-only context estimates. Billing totals must never become a context fallback. */
+import { createHash, type Hash } from "node:crypto";
+import type { Api, AssistantMessage, Context, Message, Model } from "@earendil-works/pi-ai";
+import type { CursorBillingInfo } from "./run-usage.js";
+
+export interface CursorUsageMetadata {
+  version: 1;
+  billing?: CursorBillingInfo;
+  context: {
+    tokens: number;
+    source: "checkpoint" | "estimate";
+    scope: string;
+    history: string;
+  };
+}
+
+type ContextMessage = Message & { cursorUsage?: CursorUsageMetadata };
+export type CursorAssistantMessage = AssistantMessage & { cursorUsage?: CursorUsageMetadata };
+
+export function positiveContextTokens(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+    ? Math.ceil(value)
+    : undefined;
+}
+
+function textTokens(text: string): number {
+  return Math.ceil(Buffer.byteLength(text, "utf8") / 4);
+}
+
+/** A bounded image heuristic, not base64 length or an assertion of upstream tokenization. */
+export function estimateMessageTokens(message: Pick<Message, "content">): number {
+  if (typeof message.content === "string") return 4 + textTokens(message.content);
+  let tokens = 4;
+  for (const block of message.content) {
+    switch (block.type) {
+      case "text":
+        tokens += textTokens(block.text);
+        break;
+      case "thinking":
+        tokens += textTokens(block.thinking);
+        break;
+      case "image":
+        tokens += 1200;
+        break;
+      case "toolCall":
+        tokens += textTokens(block.name) + textTokens(JSON.stringify(block.arguments));
+        break;
+    }
+  }
+  return tokens;
+}
+
+function appendMessageHash(hash: Hash, message: Message): void {
+  // Exclude accounting metadata/timestamps, but bind the anchor to the actual message prefix.
+  hash.update(JSON.stringify({ role: message.role, content: message.content }));
+  hash.update("\n");
+}
+
+export function createCursorContextTracker(
+  model: Model<Api>,
+  context: Context = { messages: [] },
+  options?: { sessionId?: string; reasoning?: string },
+) {
+  const scope = createHash("sha256")
+    .update(
+      JSON.stringify({
+        provider: model.provider,
+        model: model.id,
+        window: model.contextWindow,
+        session: options?.sessionId,
+        reasoning: options?.reasoning,
+        system: context.systemPrompt,
+        tools: context.tools,
+      }),
+    )
+    .digest("hex");
+  const history = createHash("sha256");
+  let inputTokens =
+    textTokens(context.systemPrompt ?? "") + textTokens(JSON.stringify(context.tools ?? []));
+  let rawInputTokens = inputTokens;
+  let anchorTokens: number | undefined;
+  let trailingTokens = 0;
+  for (const message of context.messages) {
+    appendMessageHash(history, message);
+    const estimated = estimateMessageTokens(message);
+    inputTokens += estimated;
+    rawInputTokens += estimated;
+    trailingTokens += estimated;
+    const saved = (message as ContextMessage).cursorUsage;
+    if (
+      message.role === "assistant" &&
+      message.provider === model.provider &&
+      message.model === model.id &&
+      saved?.version === 1 &&
+      saved.context &&
+      positiveContextTokens(saved.context.tokens) &&
+      saved.context.scope === scope &&
+      saved.context.history === history.copy().digest("hex")
+    ) {
+      // An unchanged same-session prefix preserves Cursor's otherwise invisible prompt overhead.
+      // A fork/new session, compaction, history edit, model or system/tools change invalidates it.
+      inputTokens = saved.context.tokens;
+      anchorTokens = saved.context.tokens;
+      trailingTokens = 0;
+    }
+  }
+  const anchoredInputTokens = inputTokens;
+  let snapshot:
+    | { tokens: number; generatedAtSnapshot: number; checkpoint?: Uint8Array; fresh: boolean }
+    | undefined;
+  return {
+    begin(
+      mode: "history" | "checkpoint" | "live",
+      inheritedTokens?: number,
+      checkpoint?: Uint8Array,
+    ): void {
+      const previous = snapshot;
+      snapshot = undefined;
+      // A server-side summary cannot calibrate a request that re-expanded the full Pi history.
+      inputTokens = mode === "history" ? rawInputTokens : anchoredInputTokens;
+      const inherited = positiveContextTokens(inheritedTokens);
+      if (mode !== "history" && inherited !== undefined) {
+        // The request actually resumes this checkpoint, even before the first Pi reply exists.
+        // Its observation may also be smaller than an older message anchor.
+        inputTokens = inherited + (anchorTokens !== undefined ? trailingTokens : 0);
+      }
+      if (
+        mode !== "history" &&
+        previous &&
+        (inherited === undefined ||
+          (checkpoint !== undefined &&
+            checkpoint === previous.checkpoint &&
+            inherited === previous.tokens))
+      ) {
+        // Same-writer continuation must not lose its measured output boundary. Compare the
+        // actual checkpoint object, not token counts alone. A placeholder still retains the
+        // last observation as an estimate; neither case is a fresh post-recovery measurement.
+        snapshot = { ...previous, fresh: false };
+      }
+    },
+    observe(tokens: number, output: AssistantMessage, checkpoint?: Uint8Array): void {
+      const valid = positiveContextTokens(tokens);
+      if (valid === undefined) return;
+      // A genuine smaller positive snapshot (e.g. upstream summarization) must be accepted too.
+      snapshot = {
+        tokens: valid,
+        generatedAtSnapshot: estimateMessageTokens(output),
+        checkpoint,
+        fresh: true,
+      };
+    },
+    finish(output: CursorAssistantMessage): CursorUsageMetadata["context"] {
+      const generated = estimateMessageTokens(output);
+      const suffix = snapshot ? Math.max(0, generated - snapshot.generatedAtSnapshot) : generated;
+      const tokens = Math.max(1, Math.ceil((snapshot?.tokens ?? inputTokens) + suffix));
+      const finalHistory = history.copy();
+      appendMessageHash(finalHistory, output);
+      const result: CursorUsageMetadata["context"] = {
+        tokens,
+        source: snapshot?.fresh && suffix === 0 ? "checkpoint" : "estimate",
+        scope,
+        history: finalHistory.digest("hex"),
+      };
+      output.cursorUsage = { version: 1, context: result };
+      return result;
+    },
+  };
+}

package/src/stream/debug-log.ts

@@ -0,0 +1,316 @@
+/**
+ * Diagnostics sinks for the stream runtime.
+ *
+ * Four separate channels, deliberately:
+ *   - `debugLog`             verbose JSONL, opt-in via PI_CURSOR_PROVIDER_DEBUG
+ *   - `lifecycleLog`         always-on compact log for diagnosing multi-minute stalls
+ *   - `emitMetric`           structured counters; defaults to lifecycleLog (never TUI)
+ *   - `reportCursorAnomaly`  key user-visible recoveries: lifecycle + optional TUI notify
+ *
+ * Everything here swallows its own errors: diagnostics must never break a turn.
+ * Payloads pass through `sanitizeForDebug`, which truncates strings, summarizes
+ * binary/image data, and redacts access tokens.
+ */
+import { createHash } from "node:crypto";
+import { appendFile } from "node:fs";
+import { join as pathJoin } from "node:path";
+
+import { getCacheDir } from "../utils/cache-dir.js";
+import { redactSecrets } from "../utils/security.js";
+import { normalizeImageMimeType } from "./images.js";
+import type { CursorRequestDebugSummary } from "./types.js";
+
+let debugRequestCounter = 0;
+
+let debugLogFilePath: string | undefined;
+
+export const requestDebugByBody = new WeakMap<Uint8Array, CursorRequestDebugSummary>();
+
+// `debugLog` guards every call site on this, including one per server message on the streaming
+// hot path. `process.env` is a native-backed proxy whose property reads cost ~100x an ordinary
+// one, so resolve the flag once instead of on every token. Resolution stays lazy so a value pi
+// exports after this module loads is still picked up.
+let streamDebugEnabled: boolean | undefined;
+
+export function isStreamDebugEnabled(): boolean {
+  if (streamDebugEnabled === undefined) {
+    const raw = process.env.PI_CURSOR_PROVIDER_DEBUG?.trim().toLowerCase();
+    streamDebugEnabled = !!raw && raw !== "0" && raw !== "false" && raw !== "off";
+  }
+  return streamDebugEnabled;
+}
+
+/** Test seam: re-read PI_CURSOR_PROVIDER_DEBUG after mutating process.env. */
+export function resetStreamDebugForTests(): void {
+  streamDebugEnabled = undefined;
+}
+
+export function truncateDebugString(value: string, max = 4000): string {
+  return value.length > max
+    ? `${value.slice(0, max)}…<truncated ${value.length - max} chars>`
+    : value;
+}
+
+export function debugByteSummary(bytes: Uint8Array): { byteLength: number; sha256: string } {
+  return {
+    byteLength: bytes.length,
+    sha256: createHash("sha256").update(bytes).digest("hex").slice(0, 16),
+  };
+}
+
+export function debugBase64ImageSummary(data: string): {
+  base64Length: number;
+  byteLength?: number;
+  sha256?: string;
+  decodeError?: boolean;
+} {
+  const stripped = data.replace(/\s/g, "");
+  const bytes = Buffer.from(stripped, "base64");
+  if (bytes.length > 0) {
+    return { base64Length: data.length, ...debugByteSummary(new Uint8Array(bytes)) };
+  }
+  if (stripped.length > 0) {
+    return { base64Length: data.length, decodeError: true };
+  }
+  return { base64Length: data.length };
+}
+
+function summarizeDebugImageUrl(url: string): unknown {
+  const trimmed = url.trim();
+  const match = trimmed.match(/^data:([^;,]+)(?:;[^,]*)?;base64,(.*)$/is);
+  if (match) {
+    return {
+      mimeType: normalizeImageMimeType(match[1]!),
+      ...debugBase64ImageSummary(match[2]!),
+    };
+  }
+  return {
+    url: trimmed.startsWith("data:image/")
+      ? `<redacted data image ${trimmed.length} chars>`
+      : truncateDebugString(trimmed),
+  };
+}
+
+function summarizeDebugImageObject(value: Record<string, unknown>): unknown | undefined {
+  const imageUrl = value.image_url;
+  if (imageUrl && typeof imageUrl === "object") {
+    const url = (imageUrl as Record<string, unknown>).url;
+    if (typeof url === "string")
+      return { type: value.type ?? "image_url", image_url: summarizeDebugImageUrl(url) };
+  }
+
+  const mimeType =
+    typeof value.mimeType === "string" ? normalizeImageMimeType(value.mimeType) : undefined;
+  if (!mimeType?.startsWith("image/")) return undefined;
+  const data = value.data;
+  if (typeof data === "string") {
+    return { type: value.type, mimeType, ...debugBase64ImageSummary(data) };
+  }
+  if (data instanceof Uint8Array || Buffer.isBuffer(data)) {
+    const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+    return { type: value.type, mimeType, ...debugByteSummary(bytes) };
+  }
+  return undefined;
+}
+
+const SENSITIVE_DEBUG_KEYS = new Set([
+  "accesstoken",
+  "refreshtoken",
+  "authorization",
+  "access_token",
+  "refresh_token",
+  "code_verifier",
+  "cookie",
+  "workoscursorsessiontoken",
+  "apikey",
+  "api_key",
+]);
+
+function isSensitiveDebugKey(key: string): boolean {
+  const normalized = key.replace(/[_-]/g, "").toLowerCase();
+  return (
+    SENSITIVE_DEBUG_KEYS.has(key.toLowerCase()) ||
+    SENSITIVE_DEBUG_KEYS.has(normalized) ||
+    key === "access" ||
+    key === "refresh"
+  );
+}
+
+export function sanitizeForDebug(value: unknown): unknown {
+  if (value == null) return value;
+  if (typeof value === "string") return redactSecrets(truncateDebugString(value));
+  if (typeof value === "number" || typeof value === "boolean") return value;
+  if (value instanceof Uint8Array || Buffer.isBuffer(value)) {
+    const bytes = value instanceof Uint8Array ? value : new Uint8Array(value);
+    return {
+      __type: value instanceof Uint8Array ? "Uint8Array" : "Buffer",
+      ...debugByteSummary(bytes),
+    };
+  }
+  if (Array.isArray(value)) return value.map((item) => sanitizeForDebug(item));
+  if (value instanceof Map) {
+    return {
+      __type: "Map",
+      size: value.size,
+      entries: Array.from(value.entries())
+        .slice(0, 20)
+        .map(([k, v]) => [sanitizeForDebug(k), sanitizeForDebug(v)]),
+    };
+  }
+  if (typeof value === "object") {
+    const imageSummary = summarizeDebugImageObject(value as Record<string, unknown>);
+    if (imageSummary) return imageSummary;
+    const entries = Object.entries(value as Record<string, unknown>).map(([key, inner]) => {
+      if (isSensitiveDebugKey(key)) return [key, "<redacted>"] as const;
+      if (key === "data" && typeof inner === "string")
+        return [key, `<redacted base64 ${inner.length} chars>`] as const;
+      if (key === "url" && typeof inner === "string" && inner.startsWith("data:image/")) {
+        return [key, `<redacted data image ${inner.length} chars>`] as const;
+      }
+      return [key, sanitizeForDebug(inner)] as const;
+    });
+    return Object.fromEntries(entries);
+  }
+  return String(value);
+}
+
+export function getDebugLogFilePath(): string {
+  const configured = process.env.PI_CURSOR_PROVIDER_DEBUG_FILE?.trim();
+  if (configured) return configured;
+  if (debugLogFilePath) return debugLogFilePath;
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  debugLogFilePath = pathJoin(
+    getCacheDir() ?? process.cwd(),
+    `pi-cursor-provider-debug-${stamp}-${process.pid}.log`,
+  );
+  return debugLogFilePath;
+}
+
+export function debugLog(event: string, data?: Record<string, unknown>): void {
+  if (!isStreamDebugEnabled()) return;
+  try {
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      pid: process.pid,
+      event,
+      ...(data ? (sanitizeForDebug(data) as Record<string, unknown>) : {}),
+    });
+    const file = getDebugLogFilePath();
+    appendFile(file, `${line}\n`, { encoding: "utf8", mode: 0o600 }, (error) => {
+      if (error) console.error("[pi-cursor-provider] failed to write debug log", error);
+    });
+  } catch (error) {
+    console.error("[pi-cursor-provider] failed to write debug log", error);
+  }
+}
+
+/** Always-on compact lifecycle log for diagnosing multi-minute stalls. */
+let lifecycleLogPath: string | undefined;
+const MAX_LIFECYCLE_LOG_BYTES = 10 * 1024 * 1024;
+let lifecycleBytesWritten = 0;
+
+export function getLifecycleLogPath(): string {
+  const configured = process.env.PI_CURSOR_LIFECYCLE_LOG?.trim();
+  if (configured) return configured;
+  if (lifecycleLogPath) return lifecycleLogPath;
+  lifecycleLogPath = pathJoin(
+    getCacheDir() ?? process.cwd(),
+    `pi-cursor-lifecycle-${process.pid}.jsonl`,
+  );
+  return lifecycleLogPath;
+}
+
+export function lifecycleLog(event: string, data?: Record<string, unknown>): void {
+  try {
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      pid: process.pid,
+      event,
+      ...(data ? (sanitizeForDebug(data) as Record<string, unknown>) : {}),
+    });
+    const encodedBytes = Buffer.byteLength(line) + 1;
+    if (lifecycleBytesWritten + encodedBytes > MAX_LIFECYCLE_LOG_BYTES) return;
+    lifecycleBytesWritten += encodedBytes;
+    appendFile(getLifecycleLogPath(), `${line}\n`, { encoding: "utf8", mode: 0o600 }, () => {});
+  } catch {
+    // Never throw from diagnostics.
+  }
+  // Also mirror into verbose debug log when enabled.
+  debugLog(`lifecycle.${event}`, data);
+}
+
+export type MetricEmitter = (event: string, data: Record<string, unknown>) => void;
+
+const defaultMetricEmitter: MetricEmitter = (event, data) => {
+  lifecycleLog(event, data);
+};
+
+let metricEmitter: MetricEmitter = defaultMetricEmitter;
+
+export function emitMetric(event: string, data: Record<string, unknown>): void {
+  try {
+    metricEmitter(event, data);
+  } catch (error) {
+    console.error("[pi-cursor-provider] failed to emit metric", error);
+  }
+}
+
+export type CursorNotifyLevel = "info" | "warning" | "error";
+export type CursorNotifySink = (message: string, level?: CursorNotifyLevel) => void;
+
+let cursorNotifySink: CursorNotifySink | undefined;
+
+/** Register a TUI notify sink from extension context. Omit to clear. */
+export function setCursorNotifySink(sink?: CursorNotifySink): void {
+  cursorNotifySink = sink;
+}
+
+/**
+ * Persist a rare user-visible anomaly to the lifecycle file.
+ * Notifies the TUI when a sink is registered; otherwise no-op unless this is a
+ * real failure with no other sink, in which case a short human line goes to stderr.
+ */
+export function reportCursorAnomaly(
+  event: string,
+  message: string,
+  data?: Record<string, unknown>,
+  options?: { level?: CursorNotifyLevel; stderrIfNoSink?: boolean },
+): void {
+  lifecycleLog(event, data);
+  const level = options?.level ?? "warning";
+  if (cursorNotifySink) {
+    try {
+      cursorNotifySink(message, level);
+    } catch {
+      // Never throw from diagnostics.
+    }
+    return;
+  }
+  if (options?.stderrIfNoSink) {
+    try {
+      console.error(message);
+    } catch {
+      // Never throw from diagnostics.
+    }
+  }
+}
+
+export function nextDebugRequestId(): string {
+  debugRequestCounter += 1;
+  return `req-${debugRequestCounter}`;
+}
+
+export function decodeRequestForTests(requestBody: Uint8Array): CursorRequestDebugSummary {
+  return requestDebugByBody.get(requestBody) ?? { systemPrompt: "", selectedImages: [] };
+}
+
+export function redactForDebug(value: string): string {
+  return value
+    .replace(/([A-Z0-9_]*TOKEN[A-Z0-9_]*=)[^\s,;]+/gi, "$1[redacted]")
+    .replace(/(Bearer\s+)[A-Za-z0-9._~+/-]+/gi, "$1[redacted]");
+}
+
+/** Test seam: replace the metric sink (used by __testInternals). */
+export function setMetricEmitter(factory?: MetricEmitter): void {
+  metricEmitter = factory ?? defaultMetricEmitter;
+}

package/src/stream/drift.ts

@@ -0,0 +1,122 @@
+/**
+ * Wire-protocol drift detection.
+ *
+ * Cursor can change `agent.v1` at any time, and the failure mode that costs the
+ * most to debug is the quiet one: a server message case we don't know about is
+ * skipped, nothing is answered, and the turn parks until the idle watchdog fires
+ * with a generic timeout. The user sees "it hung"; the log says nothing.
+ *
+ * So every unrecognized case and every unknown protobuf field is recorded here
+ * instead of being silently dropped. Signals are:
+ *   - counted in-process and surfaced by `/cursor.doctor`
+ *   - written to the always-on lifecycle log
+ *   - appended to the stream error message when a turn actually fails
+ *
+ * Recording a signal is not itself an error. Unknown *fields* are routine when
+ * Cursor ships ahead of our schema and are usually harmless. Unknown *message
+ * cases* are the ones that strand a turn — `kind` keeps them distinguishable.
+ */
+import { lifecycleLog } from "./debug-log.js";
+import { setLastDriftSignal } from "../diagnostics/diagnostics.js";
+import { DriftKind, type DriftKindType } from "../types/enums.js";
+
+export { DriftKind, type DriftKindType } from "../types/enums.js";
+
+/** Cases that can strand a turn, as opposed to being merely informational. */
+const STRANDING_KINDS = new Set<DriftKind>([
+  DriftKind.ServerMessage,
+  DriftKind.ExecMessage,
+  DriftKind.InteractionQuery,
+  DriftKind.KvMessage,
+]);
+
+export interface DriftSignal {
+  kind: DriftKind;
+  detail: string;
+  count: number;
+  firstSeenIso: string;
+  lastSeenIso: string;
+}
+
+const signals = new Map<string, DriftSignal>();
+
+/** Bounded so a pathological stream cannot grow this map without limit. */
+const MAX_TRACKED_SIGNALS = 64;
+
+function signalKey(kind: DriftKind | DriftKindType, detail: string): string {
+  return `${kind}:${detail}`;
+}
+
+/**
+ * Records one drift observation. Safe to call on a hot path: repeat observations
+ * only bump a counter, and only the first of each kind+detail is logged.
+ */
+export function recordDriftSignal(
+  kind: DriftKind | DriftKindType,
+  detail: string | undefined,
+): void {
+  const normalized = (detail ?? "unknown").slice(0, 80);
+  const key = signalKey(kind, normalized);
+  const now = new Date().toISOString();
+
+  const existing = signals.get(key);
+  if (existing) {
+    existing.count += 1;
+    existing.lastSeenIso = now;
+    return;
+  }
+
+  if (signals.size >= MAX_TRACKED_SIGNALS) return;
+  signals.set(key, {
+    kind: kind as DriftKind,
+    detail: normalized,
+    count: 1,
+    firstSeenIso: now,
+    lastSeenIso: now,
+  });
+
+  // Log only on first sighting — a drifted stream would otherwise spam the log.
+  lifecycleLog("wire_drift", {
+    kind,
+    detail: normalized,
+    stranding: STRANDING_KINDS.has(kind as DriftKind),
+  });
+  setLastDriftSignal(`${kind}:${normalized}`);
+}
+
+/**
+ * Records unknown protobuf fields on a decoded message. `$unknown` is populated
+ * by @bufbuild/protobuf whenever the wire carries fields our schema lacks, which
+ * is the earliest signal that `proto/agent.proto` is behind Cursor.
+ */
+export function recordUnknownFields(context: string, message: unknown): void {
+  const unknown = (message as { $unknown?: readonly { no: number }[] } | null)?.$unknown;
+  if (!unknown || unknown.length === 0) return;
+  const fields = [...new Set(unknown.map((f) => f.no))].sort((a, b) => a - b).join(",");
+  recordDriftSignal(DriftKind.UnknownFields, `${context}#${fields}`);
+}
+
+export function getDriftSignals(): DriftSignal[] {
+  return [...signals.values()].sort((a, b) => b.count - a.count);
+}
+
+/** True when something was seen that can actually strand a turn. */
+export function hasStrandingDrift(): boolean {
+  return [...signals.values()].some((s) => STRANDING_KINDS.has(s.kind));
+}
+
+/** One-line summary for `/cursor.doctor` and error messages; empty when clean. */
+export function formatDriftSummary(limit = 4): string {
+  const all = getDriftSignals();
+  if (all.length === 0) return "";
+  const shown = all
+    .slice(0, limit)
+    .map((s) => `${s.kind}:${s.detail}${s.count > 1 ? `x${s.count}` : ""}`)
+    .join(", ");
+  const rest = all.length > limit ? ` (+${all.length - limit} more)` : "";
+  return `${shown}${rest}`;
+}
+
+export function resetDriftSignalsForTests(): void {
+  signals.clear();
+}