@cursor/july 0.1.99 → 0.1.101

package/src/internal/distribution.ts

@@ -131,6 +131,11 @@ export const AUTHORING_ENTRY_FILES: ReadonlyArray<
   ["channels/origin", "channels/origin/index.js"],
   ["channels/deployments", "channels/deployments/index.js"],
   ["skills", "skills.js"],
+  ["extensions", "extensions.js"],
+  [
+    "extensions/cursor-cloud-agents",
+    "extensions/cursor-cloud-agents/extension.js",
+  ],
   ["schedules", "schedules.js"],
   ["reminders", "reminders.js"],
   ["connections", "connections.js"],

package/src/internal/framework-file-storage.ts

@@ -15,9 +15,9 @@
  * {@link storageKeys} scheme was designed for exactly this: keys are a
  * stable versioned contract that sinks may route on, so
  * {@link composeFrameworkStorage} splits one {@link StorageConfig} by key
- * kind — `session` / `session-events` / `session-runs` / `continuation`
- * go to the framework file store (file-shaped; the store accepts values
- * up to 64 MiB per
+ * kind — `session` / `session-events` / `session-runs` / `logs` /
+ * `continuation` go to the framework file store (file-shaped; the store
+ * accepts values up to 64 MiB per
  * object without chunking, versus the KV proxy's 1 MiB row cap), while
  * author `kv`, eval runs, A/B samples, and conditional writes stay on the
  * control-plane KV proxy (the dashboard reads them there, and CAS needs a
@@ -42,6 +42,7 @@ const FRAMEWORK_FILE_KINDS: ReadonlySet<string> = new Set([
   "session",
   "session-events",
   "session-runs",
+  "logs",
   "continuation",
 ]);
 
@@ -105,7 +106,7 @@ export function fileSinkStorageCore(sink: FileSink): FileSinkStorageCore {
           `framework file storage: key "${key}" has a path segment the store cannot represent`
         );
       }
-      await sink.put(key, new TextEncoder().encode(JSON.stringify(value)));
+      await sink.put(key, encodeDocument(key, value));
     },
     async get(key): Promise<JsonValue | undefined> {
       if (isUnrepresentableFileKey(key)) {
@@ -151,9 +152,42 @@ export function fileSinkStorageCore(sink: FileSink): FileSinkStorageCore {
   };
 }
 
+function frameworkFileKind(key: string): string | undefined {
+  if (!key.startsWith(`${STORAGE_KEY_ROOT}/`)) {
+    return undefined;
+  }
+  const rest = key.slice(STORAGE_KEY_ROOT.length + 1);
+  const agentEnd = rest.indexOf("/");
+  if (agentEnd === -1) {
+    return undefined;
+  }
+  const afterAgent = rest.slice(agentEnd + 1);
+  const kindEnd = afterAgent.indexOf("/");
+  return kindEnd === -1 ? afterAgent : afterAgent.slice(0, kindEnd);
+}
+
+function isLogKey(key: string): boolean {
+  return frameworkFileKind(key) === "logs";
+}
+
+function encodeDocument(key: string, value: JsonValue): Uint8Array {
+  // start.log is raw UTF-8, not a JSON document. Stringify would quote
+  // every line and store a JSON string literal instead of the tee.
+  if (isLogKey(key)) {
+    return new TextEncoder().encode(
+      typeof value === "string" ? value : JSON.stringify(value)
+    );
+  }
+  return new TextEncoder().encode(JSON.stringify(value));
+}
+
 function decodeDocument(key: string, bytes: Uint8Array): JsonValue {
+  const text = new TextDecoder().decode(bytes);
+  if (isLogKey(key)) {
+    return text;
+  }
   try {
-    return JSON.parse(new TextDecoder().decode(bytes)) as JsonValue;
+    return JSON.parse(text) as JsonValue;
   } catch (error) {
     throw new Error(
       `framework file storage: stored document at "${key}" is not JSON (${
@@ -167,11 +201,8 @@ function decodeDocument(key: string, bytes: Uint8Array): JsonValue {
  * Split one storage core by key kind: framework session state to `files`,
  * everything else to `kv`. Spread over the KV backend when building the
  * full definition so its `evals` / `abs` groups (and the cursor-hosted
- * marker) ride along untouched. A KV `cas` group must not be spread as-is:
- * conditional writes run on a KV database row, so one over a `session/` or
- * `continuation/` key would read and write a different store than the
- * routed plain core — silent split-brain. Nothing in the package CASes
- * those kinds today.
+ * marker) ride along untouched; wrap the KV `cas` group with
+ * {@link frameworkGuardedCas} rather than spreading it as-is.
  */
 export function composeFrameworkStorage(input: {
   kv: FileSinkStorageCore;
@@ -192,3 +223,42 @@ export function composeFrameworkStorage(input: {
     listNewest: undefined,
   };
 }
+
+/**
+ * The KV backend's conditional writes, refusing framework-file keys.
+ *
+ * CAS runs on the KV proxy (a database row version); the plain core routes
+ * framework session state to the file store. A future coordination path
+ * that CASes a `session/` or `continuation/` key would otherwise read and
+ * write a different store than the plain path — silent split-brain. Fail
+ * loudly instead; nothing in the package CASes those kinds today.
+ */
+export function frameworkGuardedCas(
+  cas: NonNullable<StorageConfig["cas"]>
+): NonNullable<StorageConfig["cas"]> {
+  const refuse = (key: string): void => {
+    if (isFrameworkFileKey(key)) {
+      throw new Error(
+        `framework file storage: conditional writes are KV-only, but "${key}" routes to the framework file store`
+      );
+    }
+  };
+  return {
+    getWithVersion: (key, ctx) => {
+      refuse(key);
+      return cas.getWithVersion(key, ctx);
+    },
+    putIfAbsent: (key, value, ctx) => {
+      refuse(key);
+      return cas.putIfAbsent(key, value, ctx);
+    },
+    putIfVersion: (key, value, expectedVersion, ctx) => {
+      refuse(key);
+      return cas.putIfVersion(key, value, expectedVersion, ctx);
+    },
+    listKeys: (prefix, ctx) => {
+      refuse(prefix);
+      return cas.listKeys(prefix, ctx);
+    },
+  };
+}

package/src/internal/framework-storage-selection.ts

@@ -18,18 +18,18 @@
  * - **Cursor-managed hosting** (the deployment-generation environment
  *   variable is set, same signal that registers `GET /v1/manifest`):
  *   the deployment's **framework-level file store**
- *   (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`) holds session records, event
- *   transcripts, and the continuation index — file-shaped state on file
- *   storage, apart from the author-facing user store. The control-plane KV
- *   proxy is *not* used: it authorizes by mapping a pod service account to
- *   a v1 deployment row, which no v2 deployment has, so every call 403s and
- *   fails the delivery that read it. The KV half is inert until the proxy
- *   resolves v2 deployments (see null-kv-storage.ts). Without a framework
- *   store (a deploy predating framework-store provisioning) there is
- *   nothing left to mirror to, so the state root is again the only copy.
- *   The API key resolves through the full credential chain on every call
- *   because hosted freeze snapshots listen unsigned and the binder drops
- *   the key file after restore.
+ *   (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`, bound at task time) holds
+ *   session records, event transcripts, and the continuation index —
+ *   file-shaped state on file storage, apart from the author-facing user
+ *   store. Author `host.kv`, eval runs, A/B samples, and conditional writes
+ *   ride the AgentSDK v2 KV proxy (cursor-hosted-v2.ts), which resolves the
+ *   pod service account to the factorydb deployment row (the v1 Bugbot
+ *   proxy cannot resolve v2 pods at all). Framework session state never
+ *   routes to the KV proxy — the composite splits by key kind — so
+ *   transcripts stay off the author-reachable KV namespace. The API key
+ *   resolves through the full credential chain on every call because hosted
+ *   freeze snapshots listen unsigned and the binder drops the key file
+ *   after restore.
  * - **Self-hosted**: no mirror. `--state-root` is the durable copy, which
  *   is correct when the operator owns the disk.
  *
@@ -47,17 +47,15 @@ import {
   cursorHostedFiles,
 } from "../files-backends/cursor-hosted.js";
 import { defineStorage, type StorageDefinition } from "../storage.js";
-import { CURSOR_HOSTED_STORAGE } from "../storage-backends/cursor-hosted.js";
+import { cursorHostedStorageV2 } from "../storage-backends/cursor-hosted-v2.js";
 import type { AgentArchitecture } from "../types.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
 import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
 import {
   composeFrameworkStorage,
   fileSinkStorageCore,
+  frameworkGuardedCas,
 } from "./framework-file-storage.js";
-import { nullKvStorage } from "./null-kv-storage.js";
-
-const cursorHostedMarker = { [CURSOR_HOSTED_STORAGE]: true } as const;
 
 export interface FrameworkStorageSelectionInput {
   /** `agent/storage.ts`, when the author wrote one (v1 only: discovery rejects it on v2). */
@@ -100,44 +98,33 @@ export function selectFrameworkStorageDefinition(
   // comes up). Follow-ups restore lazily by continuation or session id;
   // GET /v1/sessions lists from the sink either way.
   const policy = { restore: "off" } as const;
-  const frameworkStoreId = cursorFrameworkStoreSourceId(
-    env as NodeJS.ProcessEnv
-  );
-  if (frameworkStoreId === undefined) {
-    // Nothing to mirror to: the KV proxy rejects v2 service accounts, so a
-    // definition over it would fail every delivery that reads it. The state
-    // root is the durable copy, as when self-hosted.
-    return undefined;
-  }
-  // Full chain (env → key file → stored login): frozen engines listen
-  // unsigned and bind CURSOR_API_KEY_FILE at task time, after this
+  const envSnapshot = env as NodeJS.ProcessEnv;
+  // Full chain (env → bind file → stored login): frozen engines listen
+  // unsigned and bind store ids + CURSOR_API_KEY at task time, after this
   // definition is constructed.
   const resolveApiKey = (): string | undefined => resolveApiKeySync()?.apiKey;
-  // Framework session state on the framework-level file store, which
-  // authorizes by store source id and so works for v2. Everything the KV
-  // proxy used to serve — author kv, eval runs, A/B samples, conditional
-  // writes — is inert; `defineStorage` derives the eval/A/B tables over the
-  // core, which means that bookkeeping reads back empty rather than 403ing.
-  //
-  // Restoring `cursorHostedStorage()` here once the proxy resolves v2
-  // deployments also means restoring the guard its `cas` group needs: a
-  // conditional write over a `session/` or `continuation/` key would run on
-  // the KV database while the plain core routes that key to the file store.
-  const kv = nullKvStorage();
+  // v2 pods carry a factorydb-bound service account, which the v1 Bugbot
+  // storage proxy cannot resolve; author KV, CAS coordination, and the
+  // eval/A-B tables speak the AgentSDK v2 KV proxy instead. It also carries
+  // the cursor-hosted marker, so GET /v1/sessions prefers the durable list
+  // (session records are on the framework store, which the composed core
+  // lists).
+  const kv = cursorHostedStorageV2({ resolveApiKey });
   return defineStorage({
     name: "cursor-hosted (framework files)",
     policy,
-    // GET /v1/sessions still prefers the durable list: session records live
-    // on the framework store, which the composed core lists. Spread rather
-    // than named, the way cursorHostedStorage carries it: the marker is a
-    // platform stamp, not part of the authored config surface.
-    ...cursorHostedMarker,
     ...kv,
     ...composeFrameworkStorage({
       kv,
       files: fileSinkStorageCore(
-        cursorHostedFiles({ storeSourceId: frameworkStoreId, resolveApiKey })
+        cursorHostedFiles({
+          resolveStoreSourceId: () => cursorFrameworkStoreSourceId(envSnapshot),
+          resolveApiKey,
+        })
       ),
     }),
+    // CAS stays on the KV proxy but must refuse framework-file keys, or a
+    // future coordination path would split-brain against the plain core.
+    cas: frameworkGuardedCas(kv.cas),
   });
 }

package/src/internal/hosted-delivery.ts

@@ -4,6 +4,7 @@ import type {
   ChannelHandlerArgs,
   SendMessageOptions,
 } from "../types.js";
+import { refreshBoundDeploymentSecrets } from "./cursor/hosted-deployment-secrets.js";
 import {
   createDeferredChannelSession,
   DeferredChannelSessionError,
@@ -28,19 +29,17 @@ import {
 import {
   abortReasonFromTurnStatus,
   HOSTED_EXECUTION_DIAG_RUNNING_STATUS,
-  hostedErrorStackSnippet,
   hostedExecutionDiagId,
-  writeHostedExecutionDiag,
 } from "./hosted-execution-diag.js";
+import {
+  flushHostedExecutionRecord,
+  type HostedExecutionFlushSinks,
+} from "./hosted-execution-flush.js";
 import { recordHostedManagedAutomation } from "./hosted-managed-automation.js";
 import { errorResponse, readJsonObject } from "./http-channel.js";
 import type { LogRingEntry } from "./log-ring.js";
 import type { Router } from "./router.js";
-import {
-  type SessionRunExecutionWrite,
-  serializeSessionRunError,
-  snapshotSessionRunLogs,
-} from "./session-run-log.js";
+import type { SessionRunExecutionWrite } from "./session-run-log.js";
 
 type DispatchInput = {
   delivery: HostedAdmission;
@@ -279,6 +278,8 @@ export function registerHostedDeliveryRoute(input: {
    * store; this path still awaits so a parked pod cannot shed the write.
    */
   persistSessionRun?(write: SessionRunExecutionWrite): Promise<void>;
+  /** Snapshot the local `start.log` tee onto `logs/{ses_…}`. */
+  flushStartLog?(startLogId: string): Promise<void>;
   /** Snapshot of the process log ring at persist time. */
   snapshotLogs?(): LogRingEntry[];
 }): void {
@@ -318,6 +319,7 @@ export function registerHostedDeliveryRoute(input: {
     pattern: `${input.base}${HOSTED_ADMISSION_PATH}`,
     auth: [auth],
     handler: async (request) => {
+      refreshBoundDeploymentSecrets();
       const startedAt = performance.now();
       const finish = (response: Response) =>
         withServerTiming(response, performance.now() - startedAt);
@@ -373,6 +375,7 @@ export function registerHostedDeliveryRoute(input: {
     pattern: `${input.base}${HOSTED_EXECUTION_PATH}`,
     auth: [auth],
     handler: async (request) => {
+      refreshBoundDeploymentSecrets();
       const startedAt = performance.now();
       const finish = (response: Response) =>
         withServerTiming(response, performance.now() - startedAt);
@@ -414,6 +417,20 @@ export function registerHostedDeliveryRoute(input: {
       admitted.execution ??= (async (): Promise<ExecutionReply> => {
         const startedAt = performance.now();
         const executionId = hostedExecutionDiagId(execution.admissionToken);
+        const sinks: HostedExecutionFlushSinks = {
+          ...(input.stateRoot === undefined
+            ? {}
+            : { stateRoot: input.stateRoot }),
+          ...(input.persistSessionRun === undefined
+            ? {}
+            : { persistSessionRun: input.persistSessionRun }),
+          ...(input.flushStartLog === undefined
+            ? {}
+            : { flushStartLog: input.flushStartLog }),
+          ...(input.snapshotLogs === undefined
+            ? {}
+            : { snapshotLogs: input.snapshotLogs }),
+        };
         const writeDiag = async (fields: {
           sessionId: string;
           turnStatus: string;
@@ -423,62 +440,20 @@ export function registerHostedDeliveryRoute(input: {
             | "execute_throw";
           error?: unknown;
         }): Promise<void> => {
-          const durationMs = Math.max(
-            0,
-            Math.round(performance.now() - startedAt)
-          );
-          const message =
-            fields.message === undefined
-              ? undefined
-              : boundedMessage(fields.message);
-          const stack =
-            fields.error === undefined
-              ? undefined
-              : hostedErrorStackSnippet(fields.error);
-          if (input.stateRoot !== undefined) {
-            await writeHostedExecutionDiag(input.stateRoot, {
-              v: 1,
-              executionId,
-              writtenAt: new Date().toISOString(),
-              sessionPublicId: execution.sessionPublicId,
-              sessionId: fields.sessionId,
-              turnStatus: fields.turnStatus,
-              durationMs,
-              ...(message === undefined ? {} : { message }),
-              ...(stack === undefined || stack.length === 0 ? {} : { stack }),
-              ...(message !== undefined && /abort/i.test(message)
-                ? { signalAborted: true }
-                : {}),
-              ...(fields.abortReason === undefined
-                ? {}
-                : { abortReason: fields.abortReason }),
-            });
-          }
-          if (input.persistSessionRun === undefined) {
-            return;
-          }
-          const error =
-            fields.error === undefined
-              ? undefined
-              : serializeSessionRunError(fields.error);
-          try {
-            await input.persistSessionRun({
-              executionId,
-              writtenAt: new Date().toISOString(),
-              sessionPublicId: execution.sessionPublicId,
-              sessionId: fields.sessionId,
-              turnStatus: fields.turnStatus,
-              durationMs,
-              ...(fields.abortReason === undefined
-                ? {}
-                : { abortReason: fields.abortReason }),
-              ...(message === undefined ? {} : { message }),
-              ...(error === undefined ? {} : { error }),
-              logs: snapshotSessionRunLogs(input.snapshotLogs?.() ?? []),
-            });
-          } catch {
-            // Soft-fail: a store outage must not change the HTTP reply.
-          }
+          await flushHostedExecutionRecord(sinks, {
+            executionId,
+            sessionPublicId: execution.sessionPublicId,
+            sessionId: fields.sessionId,
+            turnStatus: fields.turnStatus,
+            durationMs: Math.max(0, Math.round(performance.now() - startedAt)),
+            ...(fields.message === undefined
+              ? {}
+              : { message: fields.message }),
+            ...(fields.abortReason === undefined
+              ? {}
+              : { abortReason: fields.abortReason }),
+            ...(fields.error === undefined ? {} : { error: fields.error }),
+          });
         };
         // Claim the file before the turn runs. The host reads it after its
         // own POST returns, which for a 9-minute timeout is while this turn

package/src/internal/hosted-execution-diag.ts

@@ -1,3 +1,9 @@
+/**
+ * Guest-local TAS diag (`hosted-execution.json`). Flushed with the durable
+ * session-run document and the `start.log` tee by
+ * `hosted-execution-flush.ts`.
+ */
+
 import { createHash, randomBytes } from "node:crypto";
 import { mkdir, rename, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";

package/src/internal/hosted-execution-flush.ts

@@ -0,0 +1,142 @@
+/**
+ * One hosted-execution flush. Two artifacts, same moments:
+ *
+ * - Guest-local `hosted-execution.json` — TAS failed-execute diag.
+ * - Durable `session-runs/{ses_…}` plus the `start.log` tee — dashboard.
+ *
+ * Claim (`running`) → terminal → process-death. Process-death upgrades the
+ * durable document and re-snapshots the tee; the local json stays `running`
+ * so TAS does not treat a previous delivery's terminal record as this one.
+ */
+
+import {
+  type HostedExecutionDiagAbortReason,
+  hostedErrorStackSnippet,
+  writeHostedExecutionDiag,
+} from "./hosted-execution-diag.js";
+import type { LogRingEntry } from "./log-ring.js";
+import {
+  type SessionRunAbortReason,
+  type SessionRunExecutionWrite,
+  serializeSessionRunError,
+  snapshotSessionRunLogs,
+} from "./session-run-log.js";
+
+const MAX_ERROR_MESSAGE_LENGTH = 1024;
+
+function boundedMessage(text: string): string {
+  return text.length > MAX_ERROR_MESSAGE_LENGTH
+    ? `${text.slice(0, MAX_ERROR_MESSAGE_LENGTH)}…`
+    : text;
+}
+
+export type HostedExecutionFlushSinks = {
+  /** Serve `--state-root`. Omit to skip the guest-local TAS diag. */
+  stateRoot?: string;
+  persistSessionRun?(write: SessionRunExecutionWrite): Promise<void>;
+  flushStartLog?(startLogId: string): Promise<void>;
+  snapshotLogs?(): LogRingEntry[];
+};
+
+export type HostedExecutionFlushFields = {
+  executionId: string;
+  sessionPublicId: string;
+  sessionId: string;
+  turnStatus: string;
+  durationMs: number;
+  message?: string;
+  abortReason?: HostedExecutionDiagAbortReason;
+  error?: unknown;
+};
+
+/**
+ * Write the local TAS diag and the durable session-run + tee together.
+ * Soft-fail per sink so a store outage does not change hosted HTTP.
+ */
+export async function flushHostedExecutionRecord(
+  sinks: HostedExecutionFlushSinks,
+  fields: HostedExecutionFlushFields
+): Promise<void> {
+  const writtenAt = new Date().toISOString();
+  const message =
+    fields.message === undefined ? undefined : boundedMessage(fields.message);
+  const stack =
+    fields.error === undefined
+      ? undefined
+      : hostedErrorStackSnippet(fields.error);
+  if (sinks.stateRoot !== undefined) {
+    await writeHostedExecutionDiag(sinks.stateRoot, {
+      v: 1,
+      executionId: fields.executionId,
+      writtenAt,
+      sessionPublicId: fields.sessionPublicId,
+      sessionId: fields.sessionId,
+      turnStatus: fields.turnStatus,
+      durationMs: fields.durationMs,
+      ...(message === undefined ? {} : { message }),
+      ...(stack === undefined || stack.length === 0 ? {} : { stack }),
+      ...(message !== undefined && /abort/i.test(message)
+        ? { signalAborted: true }
+        : {}),
+      ...(fields.abortReason === undefined
+        ? {}
+        : { abortReason: fields.abortReason }),
+    });
+  }
+  if (sinks.persistSessionRun !== undefined) {
+    const error =
+      fields.error === undefined
+        ? undefined
+        : serializeSessionRunError(fields.error);
+    try {
+      await sinks.persistSessionRun({
+        executionId: fields.executionId,
+        writtenAt,
+        sessionPublicId: fields.sessionPublicId,
+        sessionId: fields.sessionId,
+        turnStatus: fields.turnStatus,
+        durationMs: fields.durationMs,
+        ...(fields.abortReason === undefined
+          ? {}
+          : { abortReason: fields.abortReason }),
+        ...(message === undefined ? {} : { message }),
+        ...(error === undefined ? {} : { error }),
+        logs: snapshotSessionRunLogs(sinks.snapshotLogs?.() ?? []),
+      });
+    } catch {
+      // Soft-fail: a store outage must not change the HTTP reply.
+    }
+  }
+  if (sinks.flushStartLog !== undefined) {
+    try {
+      await sinks.flushStartLog(fields.sessionPublicId);
+    } catch {
+      // Soft-fail: same posture as the session-run persist.
+    }
+  }
+}
+
+/**
+ * Durable-only crash flush. Leaves `hosted-execution.json` at `running`.
+ */
+export async function flushHostedExecutionProcessDeath(args: {
+  flushProcessDeath: (
+    reason: Extract<
+      SessionRunAbortReason,
+      "process_exit" | "uncaught_exception" | "unhandled_rejection"
+    >,
+    error?: unknown
+  ) => Promise<void>;
+  flushStartLog?: (startLogId: string) => Promise<void>;
+  startLogId?: string;
+  reason: Extract<
+    SessionRunAbortReason,
+    "process_exit" | "uncaught_exception" | "unhandled_rejection"
+  >;
+  error?: unknown;
+}): Promise<void> {
+  await args.flushProcessDeath(args.reason, args.error);
+  if (args.startLogId !== undefined && args.flushStartLog !== undefined) {
+    await args.flushStartLog(args.startLogId);
+  }
+}

package/src/internal/mcp-endpoint.ts

@@ -326,6 +326,7 @@ function buildConnectionBridgeMcpServer(
       sessionId: sessionId ?? "",
       connectionName,
       toolName: request.params.name,
+      input: request.params.arguments,
     });
     if (answer.answered) {
       return sdkResultToMcpResult(answer.result);