@cursor/july 0.1.100 → 0.1.102

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
@@ -30,18 +30,19 @@
 
 import type { FileSink } from "../files.js";
 import type { StorageConfig, StorageEntry } from "../storage.js";
-import { STORAGE_KEY_ROOT } from "../storage-protocol.js";
+import { AGENTSDK_STORAGE_KEY_ROOT } from "../storage-protocol.js";
 import type { JsonValue } from "../types.js";
 import { mapBounded } from "./bounded.js";
 
 /**
- * Key kinds (`agentkit/v1/{agent}/{kind}/…`) that live on the framework
+ * Key kinds (`agentsdk/v1/{agent}/{kind}/…`) that live on the framework
  * file store. Everything else stays on the KV sink.
  */
 const FRAMEWORK_FILE_KINDS: ReadonlySet<string> = new Set([
   "session",
   "session-events",
   "session-runs",
+  "logs",
   "continuation",
 ]);
 
@@ -51,10 +52,10 @@ const FRAMEWORK_FILE_KINDS: ReadonlySet<string> = new Set([
  * kind-scoped (`…/{agent}/session/`), so a prefix routes wholly to one side.
  */
 export function isFrameworkFileKey(key: string): boolean {
-  if (!key.startsWith(`${STORAGE_KEY_ROOT}/`)) {
+  if (!key.startsWith(`${AGENTSDK_STORAGE_KEY_ROOT}/`)) {
     return false;
   }
-  const rest = key.slice(STORAGE_KEY_ROOT.length + 1);
+  const rest = key.slice(AGENTSDK_STORAGE_KEY_ROOT.length + 1);
   const agentEnd = rest.indexOf("/");
   if (agentEnd === -1) {
     return false;
@@ -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(`${AGENTSDK_STORAGE_KEY_ROOT}/`)) {
+    return undefined;
+  }
+  const rest = key.slice(AGENTSDK_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 (${

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

@@ -42,20 +42,17 @@
  * pod's filesystem.
  */
 
-import {
-  cursorFrameworkStoreSourceId,
-  cursorHostedFiles,
-} from "../files-backends/cursor-hosted.js";
+import { cursorHostedFiles } from "../files-backends/cursor-hosted.js";
 import { defineStorage, type StorageDefinition } from "../storage.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 { resolveAgentV2Hosting } from "./v2-hosting.js";
 
 export interface FrameworkStorageSelectionInput {
   /** `agent/storage.ts`, when the author wrote one (v1 only: discovery rejects it on v2). */
@@ -87,8 +84,11 @@ export function selectFrameworkStorageDefinition(
       'defineStorage (agent/storage.ts) is not supported on architecture "v2": storage is platform-selected. Delete the file.'
     );
   }
-  const env = input.env ?? process.env;
-  if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined) {
+  const hosting = resolveAgentV2Hosting({
+    architecture: input.architecture,
+    env: input.env as NodeJS.ProcessEnv | undefined,
+  });
+  if (hosting.kind !== "cursor-managed") {
     // Self-hosted v2: the state root is the durable copy.
     return undefined;
   }
@@ -98,7 +98,6 @@ 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 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.
@@ -118,7 +117,8 @@ export function selectFrameworkStorageDefinition(
       kv,
       files: fileSinkStorageCore(
         cursorHostedFiles({
-          resolveStoreSourceId: () => cursorFrameworkStoreSourceId(envSnapshot),
+          resolveStoreSourceId: () =>
+            hosting.resolveStoreIds().frameworkStoreSourceId,
           resolveApiKey,
         })
       ),

package/src/internal/frontmatter.ts

@@ -1,15 +1,48 @@
 /**
- * Minimal frontmatter parser. Supports the flat `key: value` scalar subset
- * used by authored markdown (skill descriptions, schedule cron expressions)
- * without pulling in a YAML dependency.
+ * Frontmatter parsers. Authored markdown (skill descriptions, schedule cron
+ * expressions) uses the flat `key: value` scalar subset; Cursor plugin
+ * markdown is full YAML (folded descriptions, lists).
  */
 
+import { JSON_SCHEMA, load as parseYaml } from "js-yaml";
+
 export interface ParsedFrontmatter {
   data: Record<string, string>;
   body: string;
 }
 
+export interface ParsedYamlFrontmatter {
+  data: Record<string, unknown>;
+  body: string;
+  /** Why the block did not parse as a YAML mapping; `data` is then empty. */
+  error?: string;
+}
+
 const FRONTMATTER_OPEN = /^---\s*$/;
+const YAML_FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/;
+
+/** YAML frontmatter with the JSON schema (no custom tags). */
+export function parseYamlFrontmatter(source: string): ParsedYamlFrontmatter {
+  const match = YAML_FRONTMATTER.exec(source);
+  if (match === null) {
+    return { data: {}, body: source };
+  }
+  const body = match[2] ?? "";
+  let data: unknown;
+  try {
+    data = parseYaml(match[1] ?? "", { schema: JSON_SCHEMA });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { data: {}, body, error: message };
+  }
+  if (data === undefined || data === null) {
+    return { data: {}, body };
+  }
+  if (typeof data !== "object" || Array.isArray(data)) {
+    return { data: {}, body, error: "frontmatter is not a mapping" };
+  }
+  return { data: data as Record<string, unknown>, body };
+}
 
 export function parseFrontmatter(source: string): ParsedFrontmatter {
   const lines = source.split(/\r?\n/);

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);