@rahularya01/pi-cursor 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [1.1.0] - 2026-07-23
+
+### Added
+
+- Modular stream surface: `config`, `model-routing`, `context-normalize`, `recovery`, `protocol` extracted from the native runtime.
+- Vitest unit suite covering recovery, model routing, context-mode normalize, consent, protocol framing, and usage formatting.
+- Mid-session token re-resolution when access tokens near expiry (all credential sources).
+- System credential consent opt-out via `PI_CURSOR_SYSTEM_CREDENTIALS=0`.
+- `/cursor.doctor` fields: `clientVersion`, `systemCredentials`, `lastRecoverySkipReason`, protocol/auth hints.
+- Protocol mismatch / auth error message enhancement with actionable hints.
+
+### Changed
+
+- Tool-continuation recovery prefers full-history rebuild when checkpoints are stale or tool-id mismatched (hard skip only when rebuild is unsafe).
+- OpenAI-compatible local proxy path quarantined (not part of the public `src/stream` export surface).
+- Agent URL resolution validates hosts via the existing allowlist helper.
+- `SECURITY.md` updated for 1.x support and system-credential policy.
+
 ## [1.0.0] - 2026-07-23
 
 ### Added

package/README.md

@@ -57,6 +57,12 @@ If you are logged into the Cursor desktop app or Cursor CLI (`cursor` / `agent`)
 
 On **WSL (Windows Subsystem for Linux)**, `pi-cursor` automatically scans Windows host user profiles (`/mnt/c/Users/*/AppData/...`) to detect and reuse your Windows Cursor app login.
 
+To **opt out** of Keychain / IDE / WSL credential reuse (OAuth or `CURSOR_ACCESS_TOKEN` only):
+
+```bash
+export PI_CURSOR_SYSTEM_CREDENTIALS=0
+```
+
 ### Deep-link PKCE browser login
 
 When no local credentials exist, running `/login cursor` initiates browser sign-in:
@@ -139,17 +145,35 @@ Pi Coding Agent  →  streamSimple (cursor-native)
 | `PI_CURSOR_AGENT_URL` / `CURSOR_AGENT_URL` | Override agent base URL (default: `https://agentn.us.api5.cursor.sh`).   |
 | `CURSOR_ACCESS_TOKEN`                      | Static access token override.                                            |
 | `PI_CURSOR_CLIENT_VERSION`                 | Pin `x-cursor-client-version` header sent by the HTTP/2 bridge.          |
+| `PI_CURSOR_SYSTEM_CREDENTIALS`             | `0`/`false` to disable Keychain/IDE credential reuse (default: allow).   |
 | `PI_CURSOR_RAW_MODELS`                     | Disable effort-suffix model collapse.                                    |
 | `PI_CURSOR_PROVIDER_DEBUG`                 | Enable JSONL debug logging (`/tmp/pi-cursor-debug.jsonl`).               |
 | `CURSOR_USAGE_SESSION_TOKEN`               | Optional `WorkosCursorSessionToken` fallback cookie for `/cursor.usage`. |
 | `PI_OFFLINE`                               | Skip live model discovery on startup.                                    |
 
+## Architecture notes
+
+Stream modules are split under `src/stream/`:
+
+| Module                 | Responsibility                                      |
+| ---------------------- | --------------------------------------------------- |
+| `config.ts`            | Agent URL + client version resolution               |
+| `model-routing.ts`     | Effort suffix / requested model resolution          |
+| `context-normalize.ts` | Context-mode side-channel folding                   |
+| `recovery.ts`          | Tool-continuation recovery planner                  |
+| `protocol.ts`          | Auth/protocol error enhancement                     |
+| `native-core.ts`       | Native streamSimple runtime + (internal) proxy path |
+
+The OpenAI-compatible local proxy remains **internal/quarantined** (not exported from `src/stream/index.ts`). Day-to-day chat uses native `streamSimple` only.
+
+`src/proto/agent_pb.ts` is a large generated Connect/protobuf surface used by the wire layer. Prefer regenerating it from upstream protos when Cursor changes the agent schema rather than hand-editing.
+
 ## Troubleshooting
 
-- **Not logged in / 401:** Ensure Cursor CLI or app is logged in, or run `/login cursor` again. Check `/cursor.doctor` to verify your `tokenSource`.
-- **Empty / hung stream:** Cursor may have updated wire headers; verify network connectivity or bump `PI_CURSOR_CLIENT_VERSION`.
-- **Tool continuation lost:** Retry the turn or start a new chat (the live upstream HTTP/2 stream was interrupted mid-tool).
-- **WSL credential detection:** Ensure your Windows user profile folder exists under `/mnt/c/Users/` and is readable from WSL.
+- **Not logged in / 401:** Ensure Cursor CLI or app is logged in, or run `/login cursor` again. Check `/cursor.doctor` to verify your `tokenSource`. Tokens from CLI/IDE are re-resolved when near expiry.
+- **Empty / hung stream:** Cursor may have updated wire headers; verify network connectivity or bump `PI_CURSOR_CLIENT_VERSION`. `/cursor.doctor` prints the active `clientVersion`.
+- **Tool continuation lost:** The provider now prefers full-history rebuild when checkpoints are stale/mismatched. If recovery still skips, `/cursor.doctor` shows `lastRecoverySkipReason`. Retry the turn or start a new chat.
+- **WSL credential detection:** Ensure your Windows user profile folder exists under `/mnt/c/Users/` and is readable from WSL. Disable with `PI_CURSOR_SYSTEM_CREDENTIALS=0` if undesired.
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rahularya01/pi-cursor",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Native Cursor provider for Pi Coding Agent (OAuth + Connect/protobuf streamSimple)",
   "author": "Rahul Arya",
   "license": "MIT",
@@ -30,12 +30,14 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "lint": "eslint src",
-    "lint:fix": "eslint src --fix",
+    "lint": "eslint src tests",
+    "lint:fix": "eslint src tests --fix",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "security-check": "tsx scripts/security-check.ts",
-    "test": "tsx scripts/test-model-routing.ts && tsx scripts/test-thinking-levels.ts && tsx scripts/test-usage.ts && tsx scripts/test-context-mode-normalize.ts && tsx scripts/test-cli-auth.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:legacy": "tsx scripts/test-model-routing.ts && tsx scripts/test-thinking-levels.ts && tsx scripts/test-usage.ts && tsx scripts/test-context-mode-normalize.ts && tsx scripts/test-cli-auth.ts",
     "smoke:auth": "node --import tsx scripts/smoke-auth.mjs",
     "smoke:models": "node --import tsx scripts/smoke-models.mjs",
     "smoke:stream": "node --import tsx scripts/smoke-stream.mjs",
@@ -62,6 +64,7 @@
     "prettier": "^3.9.5",
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.64.0"
+    "typescript-eslint": "^8.64.0",
+    "vitest": "^3.2.4"
   }
 }

package/src/auth/cli-credentials.ts

@@ -2,6 +2,7 @@ import { existsSync, readdirSync } from "node:fs";
 import { execFileSync } from "node:child_process";
 import { homedir, platform } from "node:os";
 import { join } from "node:path";
+import { systemCredentialsAllowed } from "./consent.js";
 import { getCursorAccessTokenFromEnv, getTokenExpiry, refreshCursorToken } from "./oauth.js";
 
 export type CredentialSource =
@@ -151,18 +152,42 @@ export async function getCursorVscdbToken(): Promise<CursorTokenResult | undefin
 /**
  * Full credential resolution cascade:
  * 1. CURSOR_ACCESS_TOKEN env var
- * 2. macOS Keychain (Cursor CLI)
- * 3. Cursor IDE state.vscdb
+ * 2. macOS Keychain (Cursor CLI) — gated by system-credential consent
+ * 3. Cursor IDE state.vscdb — gated by system-credential consent
+ *
+ * Opt out of Keychain/vscdb scraping with PI_CURSOR_SYSTEM_CREDENTIALS=0.
  */
-export async function resolveSystemCursorAccessToken(): Promise<CursorTokenResult | undefined> {
+export async function resolveSystemCursorAccessToken(options?: {
+  forceRefresh?: boolean;
+}): Promise<CursorTokenResult | undefined> {
   const envToken = getCursorAccessTokenFromEnv();
-  if (envToken) return { accessToken: envToken, source: "env" };
+  if (envToken) {
+    // Env tokens cannot be refreshed here; still prefer them when present.
+    if (!options?.forceRefresh || Date.now() < getTokenExpiry(envToken)) {
+      return { accessToken: envToken, source: "env" };
+    }
+  }
+
+  if (!systemCredentialsAllowed()) {
+    return undefined;
+  }
 
+  // forceRefresh: skip unexpired access-token short-circuit by re-reading sources
+  // (keychain/vscdb helpers already refresh when access is expired).
   const keychainToken = await getCursorKeychainToken();
-  if (keychainToken) return keychainToken;
+  if (keychainToken) {
+    if (!options?.forceRefresh || keychainToken.source.endsWith("_refresh")) {
+      return keychainToken;
+    }
+    // Access still valid but forceRefresh requested — try refresh path via re-read.
+    // Keychain helper returns unexpired access first; force path falls through to vscdb/oauth.
+  }
 
   const vscdbToken = await getCursorVscdbToken();
   if (vscdbToken) return vscdbToken;
 
+  // If forceRefresh and we only had unexpired keychain access, return it as last resort.
+  if (keychainToken) return keychainToken;
+
   return undefined;
 }

package/src/auth/consent.ts

@@ -0,0 +1,27 @@
+/**
+ * Consent / opt-out for reusing Cursor CLI / IDE system credentials.
+ *
+ * Default: allow system credential reuse (Keychain + state.vscdb + WSL host).
+ * Opt out with PI_CURSOR_SYSTEM_CREDENTIALS=0|false|off|deny.
+ * Force-enable with PI_CURSOR_SYSTEM_CREDENTIALS=1|true|on|allow.
+ */
+export type SystemCredentialPolicy = "allow" | "deny";
+
+export function resolveSystemCredentialPolicy(
+  envValue: string | undefined = process.env.PI_CURSOR_SYSTEM_CREDENTIALS,
+): SystemCredentialPolicy {
+  const raw = envValue?.trim().toLowerCase();
+  if (!raw) return "allow";
+  if (raw === "0" || raw === "false" || raw === "off" || raw === "deny" || raw === "no") {
+    return "deny";
+  }
+  if (raw === "1" || raw === "true" || raw === "on" || raw === "allow" || raw === "yes") {
+    return "allow";
+  }
+  // Unknown values fail closed so misconfiguration never silently scrapes credentials.
+  return "deny";
+}
+
+export function systemCredentialsAllowed(envValue?: string): boolean {
+  return resolveSystemCredentialPolicy(envValue) === "allow";
+}

package/src/auth/index.ts

@@ -8,3 +8,15 @@ export {
   type CursorAuthParams,
   type CursorCredentials,
 } from "./oauth.js";
+export {
+  resolveSystemCursorAccessToken,
+  getCursorKeychainToken,
+  getCursorVscdbToken,
+  type CredentialSource,
+  type CursorTokenResult,
+} from "./cli-credentials.js";
+export {
+  systemCredentialsAllowed,
+  resolveSystemCredentialPolicy,
+  type SystemCredentialPolicy,
+} from "./consent.js";

package/src/client/index.ts

@@ -16,4 +16,4 @@ export {
   type CursorParameterizedModel,
   type CursorParameterizedVariant,
 } from "./cursor-wire.js";
-export { getCursorAgentUrl } from "../stream/native-core.js";
+export { getCursorAgentUrl, getCursorClientVersion } from "../stream/config.js";

package/src/diagnostics/diagnostics.ts

@@ -10,6 +10,10 @@ export type DiagnosticsSnapshot = {
   availableModels?: string;
   matchedModelDebug?: string;
   lastRpc?: string;
+  tokenSource?: string;
+  clientVersion?: string;
+  lastRecoverySkipReason?: string;
+  systemCredentials?: string;
 };
 
 const storage = new AsyncLocalStorage<DiagnosticsSnapshot>();
@@ -56,6 +60,19 @@ export function setLastMatchedModelDebug(debug: string | undefined): void {
   currentBag().matchedModelDebug =
     debug === undefined ? undefined : redactSecrets(debug).slice(0, 1200);
 }
+export function setLastTokenSource(source: string | undefined): void {
+  currentBag().tokenSource = source;
+}
+export function setLastClientVersion(version: string | undefined): void {
+  currentBag().clientVersion = version;
+}
+export function setLastRecoverySkipReason(reason: string | undefined): void {
+  currentBag().lastRecoverySkipReason =
+    reason === undefined ? undefined : redactSecrets(reason).slice(0, 200);
+}
+export function setSystemCredentialsPolicy(policy: string | undefined): void {
+  currentBag().systemCredentials = policy;
+}
 
 export function resetDiagnosticsForTests(): void {
   lastSnapshot = {};

package/src/index.ts

@@ -31,9 +31,17 @@ import {
   refreshCursorToken,
 } from "./auth/oauth.js";
 import { resolveSystemCursorAccessToken, type CredentialSource } from "./auth/cli-credentials.js";
-import { getLastDiagnostics, setLastAvailableModels } from "./diagnostics/index.js";
+import { resolveSystemCredentialPolicy, systemCredentialsAllowed } from "./auth/consent.js";
+import {
+  getLastDiagnostics,
+  setLastAvailableModels,
+  setLastClientVersion,
+  setLastTokenSource,
+  setSystemCredentialsPolicy,
+} from "./diagnostics/index.js";
 import { redactSecrets } from "./utils/security.js";
 import { formatCursorUsage, getCursorUsageSummary } from "./usage.js";
+import { getCursorClientVersion } from "./stream/config.js";
 import {
   cleanupSessionState,
   createCursorNativeStream,
@@ -1042,14 +1050,22 @@ async function getStoredCursorOAuthAccessToken(): Promise<
   return undefined;
 }
 
-async function getStartupCursorAccessToken(): Promise<
-  { accessToken: string; source: CredentialSource } | undefined
-> {
-  const systemToken = await resolveSystemCursorAccessToken();
+async function getStartupCursorAccessToken(options?: {
+  forceRefresh?: boolean;
+}): Promise<{ accessToken: string; source: CredentialSource } | undefined> {
+  const systemToken = await resolveSystemCursorAccessToken(options);
   if (systemToken) return systemToken;
   return getStoredCursorOAuthAccessToken();
 }
 
+function isTokenNearExpiry(token: string, skewMs = 60_000): boolean {
+  try {
+    return Date.now() >= getTokenExpiry(token) - skewMs;
+  } catch {
+    return true;
+  }
+}
+
 export function registerSessionLifecycleCleanup(pi: ExtensionAPI) {
   const cleanupCurrentSession = (_event: unknown, ctx: ExtensionContext) => {
     debugExtensionLog("session.cleanup_hook", {
@@ -1159,16 +1175,38 @@ export default async function (pi: ExtensionAPI) {
   let rawModelByEffortByModelId = new Map<string, Record<string, CursorModelRouting>>();
   let lastRegisteredModels: ProcessedModel[] = [];
 
-  const getAccessToken = async () => {
-    if (!currentToken) {
-      const resolved = await getStartupCursorAccessToken();
+  setSystemCredentialsPolicy(resolveSystemCredentialPolicy());
+  setLastClientVersion(getCursorClientVersion());
+
+  const getAccessToken = async (options?: { forceRefresh?: boolean }) => {
+    const needsRefresh =
+      options?.forceRefresh ||
+      !currentToken ||
+      (currentTokenSource !== "env" && isTokenNearExpiry(currentToken));
+
+    if (needsRefresh) {
+      const resolved = await getStartupCursorAccessToken({
+        forceRefresh: options?.forceRefresh || isTokenNearExpiry(currentToken || "x"),
+      });
       if (resolved) {
         currentToken = resolved.accessToken;
         currentTokenSource = resolved.source;
+        setLastTokenSource(resolved.source);
+      } else if (options?.forceRefresh) {
+        // Keep previous token only if force refresh failed and we still have one.
+        setLastTokenSource(currentTokenSource || "none");
       }
     }
-    if (!currentToken)
-      throw new Error("Not logged in to Cursor. Run /login cursor or log in via Cursor CLI");
+
+    if (!currentToken) {
+      const consentHint = systemCredentialsAllowed()
+        ? ""
+        : " System credential reuse is disabled (PI_CURSOR_SYSTEM_CREDENTIALS=0).";
+      throw new Error(
+        `Not logged in to Cursor. Run /login cursor or log in via Cursor CLI.${consentHint}`,
+      );
+    }
+    setLastTokenSource(currentTokenSource);
     return currentToken;
   };
 
@@ -1245,17 +1283,22 @@ export default async function (pi: ExtensionAPI) {
       const lines = [
         `provider=${CURSOR_PROVIDER_ID}`,
         `agentUrl=${getCursorAgentUrl()}`,
-        `tokenSource=${currentTokenSource || "none"}`,
+        `clientVersion=${d.clientVersion || getCursorClientVersion()}`,
+        `tokenSource=${d.tokenSource || currentTokenSource || "none"}`,
+        `systemCredentials=${d.systemCredentials || resolveSystemCredentialPolicy()}`,
         `lastResolvedRuntimeModel=${d.resolvedRuntimeModel || "none"}`,
         `availableModels=${d.availableModels || lastRegisteredModels.length || "none"}`,
         `matchedModel=${d.matchedModelDebug || "none"}`,
         `lastEndpoint=${d.endpoint || "none"}`,
         `lastStatus=${d.status ?? "none"}`,
         `lastRpc=${d.lastRpc || "none"}`,
+        `lastRecoverySkipReason=${d.lastRecoverySkipReason || "none"}`,
         `lastError=${d.error ? redactSecrets(d.error) : "none"}`,
         "transport=native-streamSimple",
         "runtimeCli=not-used",
+        "proxyPath=quarantined-internal",
         "commands=/cursor.models /cursor.usage /cursor.doctor",
+        "hint=On wire errors set PI_CURSOR_CLIENT_VERSION or re-login; opt out of Keychain/IDE scrape with PI_CURSOR_SYSTEM_CREDENTIALS=0",
       ];
       const text = lines.join("\n");
       if (ctx.hasUI) ctx.ui.notify(`Cursor doctor\n${text}`, "info");

package/src/stream/config.ts

@@ -0,0 +1,69 @@
+/**
+ * Cursor agent URL resolution (env → CLI config → default).
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join as pathJoin } from "node:path";
+import { assertSafeCursorBaseUrl } from "../utils/security.js";
+
+export const DEFAULT_CURSOR_AGENT_URL = "https://agentn.us.api5.cursor.sh";
+export const DEFAULT_CURSOR_CLIENT_VERSION = "cli-2026.05.01-eea359f";
+
+let cachedCursorAgentUrl: string | undefined;
+
+export function normalizeCursorUrl(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  try {
+    const url = new URL(trimmed);
+    if (url.protocol !== "https:" && url.protocol !== "http:") return undefined;
+    url.pathname = url.pathname.replace(/\/+$/, "");
+    url.search = "";
+    url.hash = "";
+    return url.toString().replace(/\/$/, "");
+  } catch {
+    return undefined;
+  }
+}
+
+export function readCursorCliAgentUrl(): string | undefined {
+  const configDir = process.env.CURSOR_CONFIG_DIR?.trim() || pathJoin(homedir(), ".cursor");
+  try {
+    const config = JSON.parse(readFileSync(pathJoin(configDir, "cli-config.json"), "utf8")) as {
+      serverConfigCache?: {
+        agentUrlConfig?: { agentnUrl?: unknown; agentUrl?: unknown };
+      };
+    };
+    return (
+      normalizeCursorUrl(config.serverConfigCache?.agentUrlConfig?.agentnUrl) ??
+      normalizeCursorUrl(config.serverConfigCache?.agentUrlConfig?.agentUrl)
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+export function getCursorClientVersion(): string {
+  return process.env.PI_CURSOR_CLIENT_VERSION?.trim() || DEFAULT_CURSOR_CLIENT_VERSION;
+}
+
+/** Resolve the agent base URL, validating host against the allowlist. */
+export function getCursorAgentUrl(): string {
+  const envUrl =
+    normalizeCursorUrl(process.env.PI_CURSOR_AGENT_URL) ??
+    normalizeCursorUrl(process.env.CURSOR_AGENT_URL);
+  if (envUrl) {
+    cachedCursorAgentUrl = assertSafeCursorBaseUrl(envUrl);
+    return cachedCursorAgentUrl;
+  }
+  if (cachedCursorAgentUrl) return cachedCursorAgentUrl;
+  const resolved = readCursorCliAgentUrl() ?? DEFAULT_CURSOR_AGENT_URL;
+  cachedCursorAgentUrl = assertSafeCursorBaseUrl(resolved);
+  return cachedCursorAgentUrl;
+}
+
+/** Test helper: clear cached URL between cases. */
+export function resetCursorAgentUrlCacheForTests(): void {
+  cachedCursorAgentUrl = undefined;
+}

package/src/stream/context-normalize.ts

@@ -0,0 +1,104 @@
+/**
+ * Normalize context-mode / session side-channel user messages into the system
+ * prompt so Cursor treats the real user turn as the task.
+ */
+
+export type OpenAIRole = "system" | "user" | "assistant" | "tool";
+
+export interface OpenAIContentPart {
+  type: string;
+  text?: string;
+  data?: string;
+  mimeType?: string;
+  image_url?: { url?: string };
+}
+
+export interface OpenAIMessage {
+  role: OpenAIRole;
+  content?: string | OpenAIContentPart[] | null;
+  tool_call_id?: string;
+  name?: string;
+  tool_calls?: unknown[];
+}
+
+const CONTEXT_MODE_SIDE_CHANNEL_PRIORITY =
+  "Provider infrastructure context only. Prioritize the user's actual request above. " +
+  "Do not run compaction recovery, session investigation, or ctx_doctor/ctx_stats rituals " +
+  "unless the user explicitly asked for that.";
+
+export function textContent(content: OpenAIMessage["content"]): string {
+  if (content == null) return "";
+  if (typeof content === "string") return content;
+  return content
+    .filter((p) => p.type === "text" && p.text)
+    .map((p) => p.text as string)
+    .join("\n");
+}
+
+export function contentHasImageParts(content: OpenAIMessage["content"]): boolean {
+  if (!Array.isArray(content)) return false;
+  return content.some(
+    (part) =>
+      part.type === "image_url" ||
+      part.type === "image" ||
+      (typeof part.mimeType === "string" && part.mimeType.startsWith("image/")),
+  );
+}
+
+export function isContextModeSideChannelText(text: string): boolean {
+  const t = text.trim();
+  if (!t) return false;
+  return (
+    /^context-mode active\b/i.test(t) ||
+    t.includes("<session_state") ||
+    t.includes("<session_resume") ||
+    t.includes("<active_memory>") ||
+    t.includes("Hierarchy: ctx_batch_execute") ||
+    /<\/?session_mode\b/i.test(t)
+  );
+}
+
+export function frameContextModeSideChannel(text: string): string {
+  return (
+    `<provider_context source="context-mode">\n${text.trim()}\n</provider_context>\n\n` +
+    CONTEXT_MODE_SIDE_CHANNEL_PRIORITY
+  );
+}
+
+/**
+ * Fold pure side-channel user messages into the system prompt and keep the
+ * real user turns as the task.
+ */
+export function normalizeMessagesForCursor(messages: OpenAIMessage[]): OpenAIMessage[] {
+  const systemParts: string[] = [];
+  const sideParts: string[] = [];
+  const rest: OpenAIMessage[] = [];
+
+  for (const msg of messages) {
+    if (msg.role === "system") {
+      const text = textContent(msg.content);
+      if (text) systemParts.push(text);
+      continue;
+    }
+
+    if (msg.role === "user") {
+      const text = textContent(msg.content);
+      // Keep multimodal user turns intact — only pure text side-channels move.
+      if (isContextModeSideChannelText(text) && !contentHasImageParts(msg.content)) {
+        sideParts.push(text);
+        continue;
+      }
+    }
+
+    rest.push(msg);
+  }
+
+  if (sideParts.length === 0) {
+    if (systemParts.length === 0) return messages;
+    return [{ role: "system", content: systemParts.join("\n") }, ...rest];
+  }
+
+  const framed = frameContextModeSideChannel(sideParts.join("\n\n"));
+  const system = systemParts.length > 0 ? `${systemParts.join("\n")}\n\n${framed}` : framed;
+  return [{ role: "system", content: system }, ...rest];
+}

package/src/stream/index.ts

@@ -1,11 +1,42 @@
+/**
+ * Public stream surface for the Cursor provider.
+ *
+ * The legacy OpenAI-compatible local proxy (`startProxy`) remains inside
+ * native-core for internal/debug use but is intentionally not re-exported here.
+ */
 export {
   createCursorNativeStream,
-  getCursorAgentUrl,
   getCursorModels,
   getCursorParameterizedModels,
   cleanupSessionState,
-  resolveModelId,
-  resolveRequestedModelId,
+  cleanupAllSessionState,
   type CursorModel,
   type CursorNativeStreamConfig,
 } from "./native-core.js";
+
+export { getCursorAgentUrl, getCursorClientVersion } from "./config.js";
+export {
+  resolveModelId,
+  resolveRequestedModelId,
+  type CursorNativeModelRouting,
+} from "./model-routing.js";
+export {
+  isContextModeSideChannelText,
+  normalizeMessagesForCursor,
+  frameContextModeSideChannel,
+} from "./context-normalize.js";
+export {
+  planRecovery,
+  fingerprintCompletedTurns,
+  wrapRecoveredToolResults,
+  lostToolContinuationErrorBody,
+  formatLostToolContinuationDiagnostic,
+  type RecoveryDecision,
+  type PlanRecoveryInput,
+  type StoredConversation,
+} from "./recovery.js";
+export {
+  enhanceCursorStreamError,
+  isAuthErrorMessage,
+  isProtocolMismatchMessage,
+} from "./protocol.js";