@cursor/july 0.1.94 → 0.1.96

package/src/internal/conversation-mirror.ts

@@ -0,0 +1,406 @@
+/**
+ * Durable mirror for the SDK runner's conversation store.
+ *
+ * The Cursor SDK keeps each local conversation in SQLite under the engine's
+ * state root (`runner/index.db` + `runner/agents/agent-<hash>/store.db`).
+ * That disk dies with the pod: on architecture v2, session **records** and
+ * event chunks survive replacement through the control-plane storage mirror
+ * (framework-storage-selection.ts), but the conversation itself was never
+ * hydrated anywhere — a replacement pod resumed every thread as a fresh
+ * conversation.
+ *
+ * This module mirrors the conversation through the SDK's own store APIs —
+ * the agent document (which carries `sdkMetadata.blobEncryptionKey`, without
+ * which the checkpoint blobs cannot be decrypted) plus its content-addressed
+ * checkpoint blobs — into the deployment's **framework-level** file store
+ * (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`), alongside session records and
+ * transcripts and apart from the author-facing user store. The store is an
+ * Agent Store reached over `/v0/agent-serve-files` presigned URLs — **not
+ * mounted** as a filesystem in the engine VM (the FUSE mount at
+ * {@link DEPLOYMENT_STORE_MOUNT_PATH} exists only on cloud-runtime VMs) —
+ * so the mirror moves bytes through the {@link FileSink} contract instead.
+ *
+ * Going through the store APIs rather than copying `store.db` files sidesteps
+ * WAL consistency and the shared `index.db` (per-session raw copies would
+ * clobber other sessions' rows); checkpoint blobs are content-addressed, so
+ * repeat persists upload only what is new.
+ *
+ * Timing: the runner hydrates before `Agent.resume` (so a follow-up landing
+ * on a fresh pod — including a v2 hosted-execution delivery — finds the
+ * conversation before the turn runs) and persists after each local turn
+ * settles, **awaited**, because a hosted pod can be parked immediately after
+ * the execution reply.
+ *
+ * Run rows and run events are deliberately not mirrored: they are per-pod
+ * bookkeeping (turn numbers, stream offsets), and the durable session event
+ * stream already lives in the control-plane storage mirror.
+ */
+
+import type { LocalAgentDocument, LocalAgentStore } from "@cursor/sdk";
+import { agentStoreKeys, type FileSink } from "../files.js";
+import {
+  cursorFrameworkStoreSourceId,
+  cursorHostedFiles,
+} from "../files-backends/cursor-hosted.js";
+import type { AgentProject } from "../types.js";
+import { mapBounded } from "./bounded.js";
+import { resolveApiKeySync } from "./cursor/credentials.js";
+import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
+import { describeError } from "./describe-error.js";
+
+/**
+ * Persist/restore one SDK conversation between a {@link LocalAgentStore} and
+ * durable file storage. Implemented by {@link createConversationMirror};
+ * consumed by the SDK runner.
+ */
+export interface ConversationMirror {
+  /**
+   * Restore `sdkAgentId`'s conversation into `store` when the store does not
+   * already hold it. Resolves `true` when a conversation was restored,
+   * `false` on a definitive miss (never persisted, or already local — the
+   * caller falls through to its fresh-conversation path). A sink **failure**
+   * propagates: an outage must fail the turn (retryable) rather than
+   * silently fork the thread onto a fresh conversation.
+   */
+  hydrate(store: LocalAgentStore, sdkAgentId: string): Promise<boolean>;
+  /**
+   * Mirror `sdkAgentId`'s conversation from `store` to the sink
+   * (last write wins). No-op until the conversation has a checkpoint.
+   */
+  persist(store: LocalAgentStore, sdkAgentId: string): Promise<void>;
+}
+
+/** Wire shape at {@link agentStoreKeys.conversationManifest}. */
+interface ConversationManifestV1 {
+  v: 1;
+  /** The SDK agent document, verbatim apart from `activeRunId` (nulled). */
+  agent: LocalAgentDocument;
+  /** Checkpoint blob ids present under the conversation's blob prefix. */
+  blobIds: string[];
+  persistedAtMs: number;
+}
+
+export interface CreateConversationMirrorOptions {
+  sink: FileSink;
+  /** Agent name baked into every minted key. */
+  agentName: string;
+  logger?: (line: string) => void;
+}
+
+/** Build a {@link ConversationMirror} over a {@link FileSink}. */
+export function createConversationMirror(
+  options: CreateConversationMirrorOptions
+): ConversationMirror {
+  const { sink, agentName } = options;
+  const logger = options.logger ?? (() => {});
+  /**
+   * Blob ids known to be in the sink, per SDK agent id (upload dedupe).
+   * Bounded oldest-out like the files backend's etag cache: a resident
+   * engine touches an unbounded number of conversations over its lifetime,
+   * and a miss costs one manifest read, never correctness.
+   */
+  const mirrored = new Map<string, Set<string>>();
+  const rememberMirrored = (sdkAgentId: string, blobIds: Set<string>): void => {
+    if (
+      !mirrored.has(sdkAgentId) &&
+      mirrored.size >= MAX_TRACKED_CONVERSATIONS
+    ) {
+      const oldest = mirrored.keys().next();
+      if (!oldest.done) {
+        mirrored.delete(oldest.value);
+      }
+    }
+    mirrored.set(sdkAgentId, blobIds);
+  };
+  /**
+   * Per-conversation serialization so a persist cannot interleave with a
+   * hydrate (or another persist) for the same conversation. Entries are
+   * removed once their chain settles as the tail, so the map tracks only
+   * conversations with work in flight.
+   */
+  const chains = new Map<string, Promise<unknown>>();
+
+  function serialize<T>(sdkAgentId: string, run: () => Promise<T>): Promise<T> {
+    const previous = chains.get(sdkAgentId) ?? Promise.resolve();
+    const next = previous.then(run, run);
+    const stored = next
+      .catch(() => {})
+      .then(() => {
+        if (chains.get(sdkAgentId) === stored) {
+          chains.delete(sdkAgentId);
+        }
+      });
+    chains.set(sdkAgentId, stored);
+    return next;
+  }
+
+  async function mirroredBlobIds(sdkAgentId: string): Promise<Set<string>> {
+    const cached = mirrored.get(sdkAgentId);
+    if (cached !== undefined) {
+      return cached;
+    }
+    // Seed from the previous manifest so a fresh pod does not re-upload the
+    // whole history on its first persist. A miss, an unusable manifest, or
+    // a failed read seeds empty — re-uploading is wasteful, never wrong.
+    const seeded = new Set<string>();
+    try {
+      const read = await readManifest(sink, agentName, sdkAgentId);
+      if (read.outcome === "found") {
+        for (const blobId of read.manifest.blobIds) {
+          seeded.add(blobId);
+        }
+      }
+    } catch (error) {
+      logger(
+        `[agent-sdk] conversation mirror: could not read the prior manifest for ${sdkAgentId} (${describeError(error)}); re-uploading blobs`
+      );
+    }
+    rememberMirrored(sdkAgentId, seeded);
+    return seeded;
+  }
+
+  return {
+    persist(store, sdkAgentId): Promise<void> {
+      return serialize(sdkAgentId, async () => {
+        const document = await store.agents.get({ agentId: sdkAgentId });
+        if (document === null || document.latestCheckpoint == null) {
+          // Nothing restorable yet (no conversation, or no checkpoint).
+          return;
+        }
+        const uploaded = await mirroredBlobIds(sdkAgentId);
+        const blobIds = await listCheckpointBlobIds(store, sdkAgentId);
+        for (const blobId of blobIds) {
+          if (uploaded.has(blobId)) {
+            continue;
+          }
+          const bytes = await store.checkpoints.get({
+            agentId: sdkAgentId,
+            blobId,
+          });
+          if (bytes === null) {
+            continue;
+          }
+          await sink.put(
+            agentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId),
+            bytes
+          );
+          // Content-addressed: once in the sink, never re-uploaded.
+          uploaded.add(blobId);
+        }
+        const manifest: ConversationManifestV1 = {
+          v: 1,
+          // The referenced run is pod-local bookkeeping and is not mirrored;
+          // a hydrated store must not point at a run row it does not hold.
+          agent: { ...document, activeRunId: null },
+          blobIds: blobIds.filter((blobId) => uploaded.has(blobId)),
+          persistedAtMs: Date.now(),
+        };
+        // Manifest last: it only ever references blobs already uploaded.
+        await sink.put(
+          agentStoreKeys.conversationManifest(agentName, sdkAgentId),
+          new TextEncoder().encode(JSON.stringify(manifest))
+        );
+      });
+    },
+
+    hydrate(store, sdkAgentId): Promise<boolean> {
+      return serialize(sdkAgentId, async () => {
+        const existing = await store.agents.get({ agentId: sdkAgentId });
+        if (existing !== null) {
+          return false;
+        }
+        const read = await readManifest(sink, agentName, sdkAgentId);
+        if (read.outcome === "miss") {
+          return false;
+        }
+        if (read.outcome === "unusable") {
+          // Definitive, non-transient state (a future manifest version
+          // during a rolling redeploy, or corruption): retrying would fail
+          // identically forever, so fall through to the caller's
+          // fresh-conversation path instead of wedging the session.
+          logger(
+            `[agent-sdk] conversation mirror: the manifest for ${sdkAgentId} is unusable (${read.reason}); treating the conversation as unrestorable`
+          );
+          return false;
+        }
+        const manifest = read.manifest;
+        const rootBlobId = manifest.agent.latestCheckpoint?.rootBlobId;
+        if (
+          rootBlobId === undefined ||
+          !manifest.blobIds.includes(rootBlobId)
+        ) {
+          logger(
+            `[agent-sdk] conversation mirror: the manifest for ${sdkAgentId} does not list its root checkpoint blob; treating the conversation as unrestorable`
+          );
+          return false;
+        }
+        // Bounded-parallel downloads: this sits on the resume critical path
+        // (a presign plus an object GET per blob against the hosted sink).
+        const bodies = await mapBounded(
+          manifest.blobIds,
+          HYDRATE_DOWNLOAD_CONCURRENCY,
+          async (blobId) => ({
+            blobId,
+            body: await sink.get(
+              agentStoreKeys.conversationBlob(agentName, sdkAgentId, blobId)
+            ),
+          })
+        );
+        const missing = bodies.filter((entry) => entry.body === undefined);
+        if (missing.length > 0) {
+          // The manifest lists exactly what a previous persist uploaded, so
+          // any definitive absence is store loss — and the checkpoint graph
+          // may reach any listed blob, not just the root. Restoring a
+          // partial graph would create an agent row whose resume succeeds
+          // and whose checkpoint walk then fails unrecoverably.
+          logger(
+            `[agent-sdk] conversation mirror: ${missing.length} checkpoint blob(s) for ${sdkAgentId} are missing from the sink; treating the conversation as unrestorable`
+          );
+          return false;
+        }
+        const restored = new Set<string>();
+        for (const entry of bodies) {
+          const body = entry.body as NonNullable<typeof entry.body>;
+          const bytes = body instanceof Uint8Array ? body : body.body;
+          if (
+            (await store.checkpoints.get({
+              agentId: sdkAgentId,
+              blobId: entry.blobId,
+            })) === null
+          ) {
+            await store.checkpoints.create({
+              agentId: sdkAgentId,
+              blobId: entry.blobId,
+              data: bytes,
+            });
+          }
+          restored.add(entry.blobId);
+        }
+        await store.agents.create({
+          agent: { ...manifest.agent, activeRunId: null },
+        });
+        rememberMirrored(sdkAgentId, restored);
+        logger(
+          `[agent-sdk] conversation mirror: restored the conversation for ${sdkAgentId} (${restored.size} checkpoint blob(s))`
+        );
+        return true;
+      });
+    },
+  };
+}
+
+/** Oldest-out cap on the per-conversation upload-dedupe cache. */
+const MAX_TRACKED_CONVERSATIONS = 1_000;
+
+/** Parallel blob downloads during hydrate (resume critical path). */
+const HYDRATE_DOWNLOAD_CONCURRENCY = 8;
+
+type ManifestRead =
+  /** No manifest was ever persisted (definitive miss). */
+  | { outcome: "miss" }
+  /**
+   * A manifest exists but cannot be used (future version, corruption,
+   * wrong agent). Definitive and non-transient — callers must not retry,
+   * and must not treat it as a sink outage.
+   */
+  | { outcome: "unusable"; reason: string }
+  | { outcome: "found"; manifest: ConversationManifestV1 };
+
+/**
+ * Read the persisted manifest. Sink transport failures propagate (an
+ * outage must fail the follow-up, not fork the thread); everything the
+ * bytes themselves can be wrong about is reported as `unusable`.
+ */
+async function readManifest(
+  sink: FileSink,
+  agentName: string,
+  sdkAgentId: string
+): Promise<ManifestRead> {
+  const body = await sink.get(
+    agentStoreKeys.conversationManifest(agentName, sdkAgentId)
+  );
+  if (body === undefined) {
+    return { outcome: "miss" };
+  }
+  const bytes = body instanceof Uint8Array ? body : body.body;
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(bytes));
+  } catch {
+    return { outcome: "unusable", reason: "not JSON" };
+  }
+  if (
+    parsed === null ||
+    typeof parsed !== "object" ||
+    (parsed as { v?: unknown }).v !== 1
+  ) {
+    return { outcome: "unusable", reason: "unsupported manifest version" };
+  }
+  const manifest = parsed as ConversationManifestV1;
+  if (
+    manifest.agent === null ||
+    typeof manifest.agent !== "object" ||
+    manifest.agent.agentId !== sdkAgentId ||
+    !Array.isArray(manifest.blobIds)
+  ) {
+    return { outcome: "unusable", reason: "malformed manifest" };
+  }
+  return { outcome: "found", manifest };
+}
+
+async function listCheckpointBlobIds(
+  store: LocalAgentStore,
+  sdkAgentId: string
+): Promise<string[]> {
+  const blobIds: string[] = [];
+  let cursor: string | undefined;
+  do {
+    const page = await store.checkpoints.list({
+      filter: { agentIds: [sdkAgentId], cursor },
+    });
+    blobIds.push(...page.items);
+    cursor = page.nextCursor;
+  } while (cursor !== undefined);
+  return blobIds;
+}
+
+/**
+ * Whether (and over which sink) this serve process mirrors conversations.
+ *
+ * Selected for architecture-v2 agents on Cursor-managed hosting — the same
+ * generation signal as framework-storage-selection.ts, plus a provisioned
+ * **framework-level** file store: conversation state is engine-owned, so it
+ * lives with session records and transcripts, never on the author-facing
+ * user store. Self-hosted v2 keeps everything on the state root (the
+ * operator owns the disk), and v1 keeps today's behavior while it runs.
+ */
+export function selectConversationMirror(input: {
+  project: AgentProject;
+  logger?: (line: string) => void;
+  env?: Record<string, string | undefined>;
+}): ConversationMirror | undefined {
+  if (input.project.agent.architecture !== "v2") {
+    return undefined;
+  }
+  const env = input.env ?? process.env;
+  const frameworkStoreId = cursorFrameworkStoreSourceId(
+    env as NodeJS.ProcessEnv
+  );
+  if (
+    env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined ||
+    frameworkStoreId === undefined
+  ) {
+    return undefined;
+  }
+  return createConversationMirror({
+    sink: cursorHostedFiles({
+      storeSourceId: frameworkStoreId,
+      // Full chain (env → key file → stored login): frozen engines listen
+      // unsigned and bind CURSOR_API_KEY_FILE at task time, after this sink
+      // is constructed.
+      resolveApiKey: () => resolveApiKeySync()?.apiKey,
+    }),
+    agentName: input.project.name,
+    logger: input.logger,
+  });
+}

package/src/internal/cursor/backend-client.ts

@@ -17,14 +17,15 @@ import { randomUUID } from "node:crypto";
 import { z } from "zod";
 import type { McpToolAnnotations } from "../../types.js";
 import { boundedToolAnnotations } from "../mcp-host.js";
+import {
+  CURSOR_SESSION_EXCHANGE_PATH,
+  CursorSessionExchangeError,
+  exchangeCursorApiKeyForSession,
+  SESSION_TOKEN_EXPIRY_LEEWAY_MS,
+} from "./session-token.js";
 
 const CLIENT_VERSION = "agent-serve-0.1.0";
-const EXCHANGE_PATH = "/auth/exchange_user_api_key";
 const SERVICE_PREFIX = "/aiserver.v1.DashboardService";
-/** Re-exchange when the cached token is within this window of expiry. */
-const TOKEN_EXPIRY_LEEWAY_MS = 5 * 60 * 1000;
-/** Fallback token lifetime when the JWT `exp` claim cannot be parsed. */
-const FALLBACK_TOKEN_LIFETIME_MS = 30 * 60 * 1000;
 const LIST_TIMEOUT_MS = 60_000;
 /** Backend-executed tools call out to third-party servers; be generous. */
 const EXECUTE_TIMEOUT_MS = 120_000;
@@ -550,7 +551,7 @@ export class CursorBackendClient {
     }
     if (
       this.token !== undefined &&
-      Date.now() < this.token.expiresAtMs - TOKEN_EXPIRY_LEEWAY_MS
+      Date.now() < this.token.expiresAtMs - SESSION_TOKEN_EXPIRY_LEEWAY_MS
     ) {
       return Promise.resolve(this.token.value);
     }
@@ -565,44 +566,39 @@ export class CursorBackendClient {
 
   private async exchangeApiKey(): Promise<string> {
     const apiKey = this.currentApiKey();
-    let response: Response;
+    let session: { token: string; expiresAtMs: number };
     try {
-      response = await this.fetchImpl(`${this.backendUrl}${EXCHANGE_PATH}`, {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-          authorization: `Bearer ${apiKey}`,
-        },
-        body: "{}",
-        signal: AbortSignal.timeout(30_000),
+      session = await exchangeCursorApiKeyForSession({
+        exchangeUrl: `${this.backendUrl}${CURSOR_SESSION_EXCHANGE_PATH}`,
+        apiKey,
+        fetchImpl: this.fetchImpl,
       });
     } catch (error) {
-      throw new CursorBackendError(
-        `Could not reach the Cursor backend at ${this.backendUrl}: ${describeError(error)}`
-      );
-    }
-    const text = await response.text();
-    if (!response.ok) {
-      throw new CursorBackendError(
-        response.status === 401
-          ? "The Cursor API key was rejected. Run `agent-serve login` again or update CURSOR_API_KEY."
-          : `Cursor API key exchange failed (${response.status}).`,
-        response.status
-      );
-    }
-    const body = accessTokenResponseSchema.safeParse(safeJsonParse(text));
-    if (!body.success || body.data.accessToken === "") {
-      throw new CursorBackendError(
-        "Cursor API key exchange returned no access token."
-      );
+      if (error instanceof CursorSessionExchangeError) {
+        if (error.status === undefined) {
+          throw new CursorBackendError(
+            `Could not reach the Cursor backend at ${this.backendUrl}: ${error.message}`
+          );
+        }
+        if (error.status >= 200 && error.status < 300) {
+          // 2xx without a token in the body.
+          throw new CursorBackendError(
+            "Cursor API key exchange returned no access token."
+          );
+        }
+        throw new CursorBackendError(
+          error.status === 401
+            ? "The Cursor API key was rejected. Run `agent-serve login` again or update CURSOR_API_KEY."
+            : `Cursor API key exchange failed (${error.status}).`,
+          error.status
+        );
+      }
+      throw error;
     }
-    this.token = {
-      value: body.data.accessToken,
-      expiresAtMs: jwtExpiryMs(body.data.accessToken),
-    };
+    this.token = { value: session.token, expiresAtMs: session.expiresAtMs };
     this.lastExchangedApiKey = apiKey;
     this.logger("[agent-sdk] cursor account: minted a fresh access token");
-    return body.data.accessToken;
+    return session.token;
   }
 }
 
@@ -705,8 +701,6 @@ export async function revokeMintedUserApiKey(args: {
 // Helpers
 // ============================================================================
 
-const accessTokenResponseSchema = z.object({ accessToken: z.string() });
-
 function safeJsonParse(text: string): unknown {
   try {
     return JSON.parse(text) as unknown;
@@ -883,24 +877,6 @@ function retryAfterMsFromResponse(response: Response): number | undefined {
   return Math.min(retryAfter * 1000, MAX_GITHUB_TOKEN_RETRY_AFTER_MS);
 }
 
-function jwtExpiryMs(token: string): number {
-  try {
-    const payload = token.split(".")[1];
-    if (payload === undefined) {
-      throw new Error("not a JWT");
-    }
-    const claims = JSON.parse(
-      Buffer.from(payload, "base64url").toString("utf8")
-    ) as { exp?: unknown };
-    if (typeof claims.exp === "number") {
-      return claims.exp * 1000;
-    }
-  } catch {
-    // Opaque token — assume a conservative lifetime.
-  }
-  return Date.now() + FALLBACK_TOKEN_LIFETIME_MS;
-}
-
 function describeError(error: unknown): string {
   return error instanceof Error ? error.message : String(error);
 }

package/src/internal/cursor/session-token.ts

@@ -0,0 +1,115 @@
+/**
+ * Shared `CURSOR_API_KEY` → Cursor session-token exchange primitive
+ * (`POST /auth/exchange_user_api_key`, ~1h session).
+ *
+ * Both `CursorBackendClient` (dashboard RPCs) and the Origin channel's
+ * session provider (`cursorSessionTokenProvider` in
+ * `../../channels/origin/api.ts`) mint through this module, so the URL,
+ * request shape, response parsing, JWT-expiry handling, and renewal
+ * constants cannot drift between the two. Callers own their caching and
+ * retry policies; this module owns exactly one exchange round trip.
+ */
+
+export const CURSOR_SESSION_EXCHANGE_PATH = "/auth/exchange_user_api_key";
+/** Re-exchange when the cached session is within this window of expiry. */
+export const SESSION_TOKEN_EXPIRY_LEEWAY_MS: number = 5 * 60 * 1000;
+/** Fallback session lifetime when the JWT `exp` claim cannot be parsed. */
+export const SESSION_TOKEN_FALLBACK_LIFETIME_MS: number = 30 * 60 * 1000;
+const EXCHANGE_TIMEOUT_MS = 30_000;
+
+/**
+ * Exchange failure. `status` is the HTTP status when the backend answered,
+ * and undefined for network/transport errors. `detail` carries the server's
+ * `error` field when present so callers can surface the reason verbatim.
+ */
+export class CursorSessionExchangeError extends Error {
+  constructor(
+    message: string,
+    readonly status?: number,
+    readonly detail?: string
+  ) {
+    super(message);
+    this.name = "CursorSessionExchangeError";
+  }
+}
+
+/** Epoch-ms expiry from a JWT `exp` claim, or undefined when unparsable. */
+export function jwtExpiryMs(token: string): number | undefined {
+  try {
+    const payload = token.split(".")[1];
+    if (payload === undefined) {
+      return undefined;
+    }
+    const claims = JSON.parse(
+      Buffer.from(payload, "base64url").toString("utf8")
+    ) as { exp?: unknown };
+    return typeof claims.exp === "number" ? claims.exp * 1000 : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * One exchange round trip. Throws {@link CursorSessionExchangeError} on
+ * transport failure, a non-2xx response, or a token-free body. `expiresAtMs`
+ * comes from the session JWT's `exp` claim, falling back to
+ * {@link SESSION_TOKEN_FALLBACK_LIFETIME_MS} for opaque tokens.
+ */
+export async function exchangeCursorApiKeyForSession(args: {
+  /** Full exchange URL (base + {@link CURSOR_SESSION_EXCHANGE_PATH}). */
+  exchangeUrl: string;
+  apiKey: string;
+  fetchImpl?: typeof fetch;
+  nowMs?: number;
+}): Promise<{ token: string; expiresAtMs: number }> {
+  const fetchImpl = args.fetchImpl ?? fetch;
+  let response: Response;
+  try {
+    response = await fetchImpl(args.exchangeUrl, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        authorization: `Bearer ${args.apiKey}`,
+      },
+      body: "{}",
+      signal: AbortSignal.timeout(EXCHANGE_TIMEOUT_MS),
+    });
+  } catch (error) {
+    throw new CursorSessionExchangeError(
+      `Could not reach the Cursor session exchange at ${args.exchangeUrl}: ${
+        error instanceof Error ? error.message : String(error)
+      }`
+    );
+  }
+  const body: unknown = await response.json().catch(() => undefined);
+  const record =
+    typeof body === "object" && body !== null && !Array.isArray(body)
+      ? (body as Record<string, unknown>)
+      : {};
+  const detail =
+    typeof record.error === "string" && record.error !== ""
+      ? record.error
+      : undefined;
+  if (!response.ok) {
+    throw new CursorSessionExchangeError(
+      `Cursor session exchange failed with HTTP ${response.status}${
+        detail === undefined ? "" : ` (${detail})`
+      }.`,
+      response.status,
+      detail
+    );
+  }
+  const token = record.accessToken;
+  if (typeof token !== "string" || token === "") {
+    throw new CursorSessionExchangeError(
+      "Cursor session exchange returned no access token.",
+      response.status
+    );
+  }
+  const nowMs = args.nowMs ?? Date.now();
+  return {
+    token,
+    expiresAtMs:
+      jwtExpiryMs(token) ?? nowMs + SESSION_TOKEN_FALLBACK_LIFETIME_MS,
+  };
+}

package/src/internal/cursor-agent-template.ts

@@ -4,6 +4,7 @@ import { join } from "node:path";
 const MAX = 64;
 const TEMPLATE_NAMES = [
   "agentic-owners",
+  "code-wiki",
   "demo",
   "pr-autofixer",
   "security-help",