@cursor/july 0.1.101 → 0.1.102

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

@@ -30,12 +30,12 @@
 
 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([
@@ -52,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;
@@ -153,10 +153,10 @@ export function fileSinkStorageCore(sink: FileSink): FileSinkStorageCore {
 }
 
 function frameworkFileKind(key: string): string | undefined {
-  if (!key.startsWith(`${STORAGE_KEY_ROOT}/`)) {
+  if (!key.startsWith(`${AGENTSDK_STORAGE_KEY_ROOT}/`)) {
     return undefined;
   }
-  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 undefined;

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/mcp-host.ts

@@ -26,6 +26,11 @@ import {
 } from "../types.js";
 import { CLI_COMMAND_NAME as CLI } from "./distribution.js";
 import { createHostMcpOAuthProvider } from "./mcp-oauth.js";
+import {
+  instrumentedMcpFetch,
+  mcpTraceMeta,
+  runMcpClientSpan,
+} from "./otel/mcp.js";
 
 export class McpNeedsAuthError extends Error {
   readonly connection: string;
@@ -115,12 +120,16 @@ export class McpHost implements HostMcpRegistry {
 
   async listTools(connectionName: string): Promise<HostMcpToolInfo[]> {
     const connection = this.requireConnection(connectionName);
-    return this.withClient(connectionName, async (client) => {
-      const listed = await client.listTools();
-      return listed.tools
-        .map(toToolInfo)
-        .filter((tool) => connectionAllowsTool(connection, tool.name));
-    });
+    return runMcpClientSpan(
+      { method: "tools/list", connection: connectionName },
+      () =>
+        this.withClient(connectionName, async (client) => {
+          const listed = await client.listTools(mcpListParams());
+          return listed.tools
+            .map(toToolInfo)
+            .filter((tool) => connectionAllowsTool(connection, tool.name));
+        })
+    );
   }
 
   /**
@@ -146,24 +155,37 @@ export class McpHost implements HostMcpRegistry {
     };
     return {
       listTools: () =>
-        withFreshClient(async (client) => {
-          const listed = await client.listTools();
-          return listed.tools
-            .map(toToolInfo)
-            .filter((tool) => connectionAllowsTool(connection, tool.name));
-        }),
+        runMcpClientSpan(
+          { method: "tools/list", connection: connection.name },
+          () =>
+            withFreshClient(async (client) => {
+              const listed = await client.listTools(mcpListParams());
+              return listed.tools
+                .map(toToolInfo)
+                .filter((tool) => connectionAllowsTool(connection, tool.name));
+            })
+        ),
       callTool: (toolName, args = {}) => {
         assertConnectionAllowsTool(connection, toolName);
-        return withFreshClient(async (client) => {
-          const result = await client.callTool({
-            name: toolName,
-            arguments: args,
-          });
-          return throwIfCallNeedsAuth(
-            connection.name,
-            normalizeCallResult(result)
-          );
-        });
+        return runMcpClientSpan(
+          {
+            method: "tools/call",
+            connection: connection.name,
+            toolName,
+          },
+          () =>
+            withFreshClient(async (client) => {
+              const result = await client.callTool({
+                name: toolName,
+                arguments: args,
+                ...mcpCallMeta(),
+              });
+              return throwIfCallNeedsAuth(
+                connection.name,
+                normalizeCallResult(result)
+              );
+            })
+        );
       },
     };
   }
@@ -175,13 +197,21 @@ export class McpHost implements HostMcpRegistry {
   ): Promise<HostMcpCallResult> {
     const connection = this.requireConnection(connectionName);
     assertConnectionAllowsTool(connection, toolName);
-    return this.withClient(connectionName, async (client) => {
-      const result = await client.callTool({
-        name: toolName,
-        arguments: args,
-      });
-      return throwIfCallNeedsAuth(connectionName, normalizeCallResult(result));
-    });
+    return runMcpClientSpan(
+      { method: "tools/call", connection: connectionName, toolName },
+      () =>
+        this.withClient(connectionName, async (client) => {
+          const result = await client.callTool({
+            name: toolName,
+            arguments: args,
+            ...mcpCallMeta(),
+          });
+          return throwIfCallNeedsAuth(
+            connectionName,
+            normalizeCallResult(result)
+          );
+        })
+    );
   }
 
   async dropClient(name: string): Promise<void> {
@@ -460,10 +490,33 @@ async function createTransport(
         })
       : undefined;
 
+  const fetchImpl = instrumentedMcpFetch();
+  const fetchLike = (url: string | URL, init?: RequestInit) =>
+    fetchImpl(url, init);
   if (transport.type === "sse") {
-    return new SSEClientTransport(url, { requestInit, authProvider });
+    return new SSEClientTransport(url, {
+      requestInit,
+      authProvider,
+      fetch: fetchLike,
+    });
   }
-  return new StreamableHTTPClientTransport(url, { requestInit, authProvider });
+  return new StreamableHTTPClientTransport(url, {
+    requestInit,
+    authProvider,
+    fetch: fetchLike,
+  });
+}
+
+function mcpListParams(): { _meta: { traceparent: string } } | undefined {
+  const meta = mcpTraceMeta();
+  return meta === undefined ? undefined : { _meta: meta };
+}
+
+function mcpCallMeta():
+  | { _meta: { traceparent: string } }
+  | Record<string, never> {
+  const meta = mcpTraceMeta();
+  return meta === undefined ? {} : { _meta: meta };
 }
 
 function isOauthHttpTransport(

package/src/internal/otel/collector.ts

@@ -24,9 +24,23 @@ import type { OtelRuntime } from "./runtime.js";
 
 const CONTENT_MAX = 2_048;
 
+export interface OtelCallContext {
+  sessionId: string;
+  session: SessionInfo;
+  turnId: string;
+  callId: string;
+  toolName: string;
+}
+
 export interface OtelCollector {
   onEvent(event: SessionEvent, session: SessionInfo): void;
   close(): void;
+  /**
+   * Run `fn` under the tool span so outbound inject sees that context.
+   * Opens the session / turn / tool span if the event stream has not
+   * reached `actions.requested` yet (dispatch is async).
+   */
+  runInCall<T>(args: OtelCallContext, fn: () => T | Promise<T>): Promise<T>;
   /** Merge author tags onto the session; paints open spans immediately. */
   setSessionAttributes(
     sessionId: string,
@@ -93,6 +107,12 @@ export function createOtelCollector(
       const bag = extraBySession.get(sessionId);
       return bag === undefined ? undefined : { ...bag };
     },
+    runInCall(args, fn) {
+      const span = ensureCallSpan(args);
+      return context.with(trace.setSpan(context.active(), span), () =>
+        Promise.resolve(fn())
+      );
+    },
   };
 
   function handle(event: SessionEvent, session: SessionInfo): void {
@@ -101,6 +121,9 @@ export function createOtelCollector(
 
     switch (event.type) {
       case "session.started": {
+        if (sessions.get(event.sessionId) !== undefined) {
+          return;
+        }
         openSession({
           sessionId: event.sessionId,
           session,
@@ -174,6 +197,15 @@ export function createOtelCollector(
         if (state === undefined) {
           return;
         }
+        // `runInCall` can open a synthetic turn before this event is
+        // applied. Keep that entry (and its in-flight tool spans) and
+        // just mark it real so `action.result` will not auto-close it.
+        const existing = state.turns.get(event.turnId);
+        if (existing !== undefined) {
+          existing.synthetic = false;
+          existing.span.setAttribute("agent_sdk.turn_synthetic", false);
+          return;
+        }
         openTurn({
           state,
           sessionId: event.sessionId,
@@ -227,32 +259,14 @@ export function createOtelCollector(
           return;
         }
         for (const call of event.data.calls) {
-          const parentCtx = parentCtxFor(
+          openToolSpan({
             turn,
-            event.data.parentCallId ?? call.parentCallId
-          );
-          const span = runtime.tracer.startSpan(
-            "agent_sdk.tool",
-            {
-              kind: SpanKind.INTERNAL,
-              startTime,
-              attributes: join(event.sessionId, {
-                "cursor.conversation.id": event.sessionId,
-                "cursor.tool.name": call.toolName,
-                "cursor.tool.kind": "builtin",
-                "agent_sdk.agent": agentName,
-                "agent_sdk.turn_id": event.turnId,
-                "agent_sdk.call_id": call.callId,
-                "agent_sdk.parent_call_id": call.parentCallId,
-                "agent_sdk.tool_args":
-                  logOpts?.toolContent === true && call.args !== undefined
-                    ? truncate(json(call.args))
-                    : undefined,
-              }),
-            },
-            parentCtx
-          );
-          turn.tools.set(call.callId, span);
+            sessionId: event.sessionId,
+            turnId: event.turnId,
+            call,
+            parentCallId: event.data.parentCallId ?? call.parentCallId,
+            startTime,
+          });
         }
         return;
       }
@@ -702,6 +716,92 @@ export function createOtelCollector(
     return trace.setSpan(context.active(), turn.span);
   }
 
+  function openToolSpan(args: {
+    turn: TurnState;
+    sessionId: string;
+    turnId: string | undefined;
+    call: {
+      callId: string;
+      toolName: string;
+      args?: unknown;
+      parentCallId?: string;
+    };
+    parentCallId?: string;
+    startTime: number | undefined;
+  }): Span {
+    const existing = args.turn.tools.get(args.call.callId);
+    if (existing !== undefined) {
+      // Early `runInCall` opens with callId/toolName only. Fill in
+      // parent linkage and opt-in args when `actions.requested` arrives.
+      // The OTel parent is fixed at start; `parent_call_id` still records
+      // the event-stream hierarchy for nested/subagent calls.
+      existing.setAttributes(
+        join(args.sessionId, {
+          "agent_sdk.parent_call_id":
+            args.parentCallId ?? args.call.parentCallId,
+          "agent_sdk.tool_args":
+            logOpts?.toolContent === true && args.call.args !== undefined
+              ? truncate(json(args.call.args))
+              : undefined,
+        })
+      );
+      return existing;
+    }
+    const span = runtime.tracer.startSpan(
+      "agent_sdk.tool",
+      {
+        kind: SpanKind.INTERNAL,
+        startTime: args.startTime,
+        attributes: join(args.sessionId, {
+          "cursor.conversation.id": args.sessionId,
+          "cursor.tool.name": args.call.toolName,
+          "cursor.tool.kind": "builtin",
+          "agent_sdk.agent": agentName,
+          "agent_sdk.turn_id": args.turnId,
+          "agent_sdk.call_id": args.call.callId,
+          "agent_sdk.parent_call_id": args.call.parentCallId,
+          "agent_sdk.tool_args":
+            logOpts?.toolContent === true && args.call.args !== undefined
+              ? truncate(json(args.call.args))
+              : undefined,
+        }),
+      },
+      parentCtxFor(args.turn, args.parentCallId ?? args.call.parentCallId)
+    );
+    args.turn.tools.set(args.call.callId, span);
+    return span;
+  }
+
+  function ensureCallSpan(args: OtelCallContext): Span {
+    const startTime = Date.now();
+    const state =
+      sessions.get(args.sessionId) ??
+      openSession({
+        sessionId: args.sessionId,
+        session: args.session,
+        channelId: args.session.channelId,
+        startTime,
+        restored: true,
+      });
+    const turn =
+      state.turns.get(args.turnId) ??
+      openTurn({
+        state,
+        sessionId: args.sessionId,
+        turnId: args.turnId,
+        session: args.session,
+        startTime,
+        synthetic: true,
+      });
+    return openToolSpan({
+      turn,
+      sessionId: args.sessionId,
+      turnId: args.turnId,
+      call: { callId: args.callId, toolName: args.toolName },
+      startTime,
+    });
+  }
+
   function endOpenChildren(turn: TurnState, endTime: number | undefined): void {
     for (const span of turn.tools.values()) {
       span.end(endTime);

package/src/internal/otel/http.ts

@@ -11,19 +11,9 @@ import {
   SpanStatusCode,
   trace,
 } from "@opentelemetry/api";
-import { W3CTraceContextPropagator } from "@opentelemetry/core";
+import { ensureW3cPropagator } from "./propagation.js";
 import type { OtelRuntime } from "./runtime.js";
 
-let propagatorInstalled = false;
-
-function ensurePropagator(): void {
-  if (propagatorInstalled) {
-    return;
-  }
-  propagation.setGlobalPropagator(new W3CTraceContextPropagator());
-  propagatorInstalled = true;
-}
-
 interface HttpSpanHandle {
   context: Context;
   end(statusCode: number, error?: unknown): void;
@@ -61,7 +51,7 @@ function startHttpSpan(
   if (runtime === undefined || runtime.config.traces === false) {
     return undefined;
   }
-  ensurePropagator();
+  ensureW3cPropagator();
   const headers: Record<string, string> = {};
   for (const [key, value] of Object.entries(req.headers)) {
     if (typeof value === "string") {

package/src/internal/otel/mcp.ts

@@ -0,0 +1,69 @@
+/**
+ * Client-side MCP instrumentation: W3C / Cursor HTTP inject on Streamable
+ * HTTP + SSE fetches, SEP-414 `_meta.traceparent` on JSON-RPC params, and
+ * CLIENT spans for `tools/list` / `tools/call`.
+ */
+
+import { context, SpanKind, SpanStatusCode, trace } from "@opentelemetry/api";
+import { formatTraceparent, injectActiveTraceContext } from "../../otel.js";
+import { attrs } from "./attrs.js";
+
+const TRACER = "agent_sdk";
+
+export function instrumentedMcpFetch(base: typeof fetch = fetch): typeof fetch {
+  return (input, init) => {
+    if (input instanceof Request && init === undefined) {
+      const headers = new Headers(input.headers);
+      injectActiveTraceContext(headers);
+      return base(new Request(input, { headers }));
+    }
+    const headers = new Headers(init?.headers);
+    injectActiveTraceContext(headers);
+    return base(input, { ...init, headers });
+  };
+}
+
+/** SEP-414 / OTel MCP carrier for `params._meta`. */
+export function mcpTraceMeta(): { traceparent: string } | undefined {
+  const span = trace.getSpan(context.active());
+  if (span === undefined) {
+    return undefined;
+  }
+  const traceparent = formatTraceparent(span.spanContext());
+  if (traceparent === undefined) {
+    return undefined;
+  }
+  return { traceparent };
+}
+
+export function runMcpClientSpan<T>(
+  args: {
+    method: string;
+    connection: string;
+    toolName?: string;
+  },
+  fn: () => Promise<T>
+): Promise<T> {
+  const span = trace.getTracer(TRACER).startSpan(args.method, {
+    kind: SpanKind.CLIENT,
+    attributes: attrs({
+      "rpc.system": "mcp",
+      "mcp.method.name": args.method,
+      "mcp.tool.name": args.toolName,
+      "agent_sdk.mcp.connection": args.connection,
+    }),
+  });
+  return context.with(trace.setSpan(context.active(), span), async () => {
+    try {
+      return await fn();
+    } catch (error) {
+      span.setStatus({
+        code: SpanStatusCode.ERROR,
+        message: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    } finally {
+      span.end();
+    }
+  });
+}

package/src/internal/otel/propagation.ts

@@ -0,0 +1,17 @@
+/**
+ * Process-global W3C `traceparent` propagator. Inbound HTTP extracts;
+ * outbound Factory / Cursor API calls inject.
+ */
+
+import { propagation } from "@opentelemetry/api";
+import { W3CTraceContextPropagator } from "@opentelemetry/core";
+
+let installed = false;
+
+export function ensureW3cPropagator(): void {
+  if (installed) {
+    return;
+  }
+  propagation.setGlobalPropagator(new W3CTraceContextPropagator());
+  installed = true;
+}

package/src/internal/otel/runtime.ts

@@ -41,6 +41,7 @@ import {
 } from "@opentelemetry/semantic-conventions";
 import type { OtelExporterConfig, OtelSignal } from "../../otel.js";
 import { exportersForSignal, type ResolvedOtelConfig } from "./config.js";
+import { ensureW3cPropagator } from "./propagation.js";
 
 const INSTRUMENTATION = "agent_sdk";
 
@@ -66,6 +67,7 @@ export function createOtelRuntime(
       "[agent-sdk:otel] OTEL_EXPORTER_OTLP_PROTOCOL=grpc is unsupported; using http/protobuf"
     );
   }
+  ensureW3cPropagator();
   const sdk = startOtelSdk(config, log);
   const meter =
     config.metrics === false