@cursor/july 0.1.43 → 0.1.45

package/src/internal/otel/collector.ts

@@ -27,6 +27,15 @@ const CONTENT_MAX = 2_048;
 export interface OtelCollector {
   onEvent(event: SessionEvent, session: SessionInfo): void;
   close(): void;
+  /** Merge author tags onto the session; paints open spans immediately. */
+  setSessionAttributes(
+    sessionId: string,
+    attributes: Record<string, AttrValue>
+  ): void;
+  /** Session tags previously set by {@link setSessionAttributes}. */
+  getSessionAttributes(
+    sessionId: string
+  ): Record<string, AttrValue> | undefined;
 }
 
 interface TurnState {
@@ -49,6 +58,7 @@ export function createOtelCollector(
   log: (line: string) => void
 ): OtelCollector {
   const sessions = new Map<string, SessionState>();
+  const extraBySession = new Map<string, Record<string, AttrValue>>();
   const metrics = runtime.meter ? buildMetrics(runtime.meter) : undefined;
   const logOpts =
     runtime.config.logs === false ? undefined : runtime.config.logs;
@@ -71,6 +81,17 @@ export function createOtelCollector(
         state.span.end();
         sessions.delete(sessionId);
       }
+      extraBySession.clear();
+    },
+    setSessionAttributes(sessionId, attributes) {
+      const bag = extraBySession.get(sessionId) ?? {};
+      Object.assign(bag, attributes);
+      extraBySession.set(sessionId, bag);
+      paintOpenSpans(sessionId, attributes);
+    },
+    getSessionAttributes(sessionId) {
+      const bag = extraBySession.get(sessionId);
+      return bag === undefined ? undefined : { ...bag };
     },
   };
 
@@ -215,7 +236,7 @@ export function createOtelCollector(
             {
               kind: SpanKind.INTERNAL,
               startTime,
-              attributes: attrs({
+              attributes: join(event.sessionId, {
                 "cursor.conversation.id": event.sessionId,
                 "cursor.tool.name": call.toolName,
                 "cursor.tool.kind": "builtin",
@@ -287,12 +308,15 @@ export function createOtelCollector(
           span.end(startTime);
           turn?.tools.delete(event.data.callId);
         }
-        metrics?.toolCalls.add(1, {
-          "cursor.tool.name": event.data.toolName,
-          "cursor.tool.kind": "builtin",
-          "cursor.tool.status": status,
-          "agent_sdk.agent": agentName,
-        });
+        metrics?.toolCalls.add(
+          1,
+          join(event.sessionId, {
+            "cursor.tool.name": event.data.toolName,
+            "cursor.tool.kind": "builtin",
+            "cursor.tool.status": status,
+            "agent_sdk.agent": agentName,
+          })
+        );
         emitLog(
           "action.result",
           event.data.isError ? SeverityNumber.ERROR : SeverityNumber.INFO,
@@ -327,7 +351,7 @@ export function createOtelCollector(
           {
             kind: SpanKind.INTERNAL,
             startTime,
-            attributes: attrs({
+            attributes: join(event.sessionId, {
               "cursor.conversation.id": event.sessionId,
               "agent_sdk.agent": agentName,
               "agent_sdk.turn_id": event.turnId,
@@ -343,10 +367,13 @@ export function createOtelCollector(
           trace.setSpan(context.active(), turn.span)
         );
         turn.subagents.set(event.data.callId, span);
-        metrics?.subagents.add(1, {
-          "agent_sdk.agent": agentName,
-          "agent_sdk.subagent_name": event.data.name ?? "unknown",
-        });
+        metrics?.subagents.add(
+          1,
+          join(event.sessionId, {
+            "agent_sdk.agent": agentName,
+            "agent_sdk.subagent_name": event.data.name ?? "unknown",
+          })
+        );
         return;
       }
       case "subagent.completed": {
@@ -389,7 +416,7 @@ export function createOtelCollector(
               "agent_sdk.usage.reasoning_tokens": usage.reasoningTokens,
             })
           );
-          recordTokens(usage);
+          recordTokens(event.sessionId, usage);
         }
         if (cost !== undefined) {
           turn.span.setAttributes(
@@ -399,18 +426,24 @@ export function createOtelCollector(
               "agent_sdk.cost_source": cost.source,
             })
           );
-          metrics?.cost.add(cost.totalUsd, {
-            "cursor.model.name": cost.model,
-            "agent_sdk.agent": agentName,
-          });
+          metrics?.cost.add(
+            cost.totalUsd,
+            join(event.sessionId, {
+              "cursor.model.name": cost.model,
+              "agent_sdk.agent": agentName,
+            })
+          );
         }
         turn.span.setStatus({ code: SpanStatusCode.OK });
         turn.span.end(startTime);
         sessions.get(event.sessionId)?.turns.delete(event.turnId);
-        metrics?.turns.add(1, {
-          "agent_sdk.agent": agentName,
-          "agent_sdk.turn_status": "completed",
-        });
+        metrics?.turns.add(
+          1,
+          join(event.sessionId, {
+            "agent_sdk.agent": agentName,
+            "agent_sdk.turn_status": "completed",
+          })
+        );
         emitLog(
           "turn.completed",
           SeverityNumber.INFO,
@@ -441,10 +474,13 @@ export function createOtelCollector(
         }
         turn.span.end(startTime);
         sessions.get(event.sessionId)?.turns.delete(event.turnId);
-        metrics?.turns.add(1, {
-          "agent_sdk.agent": agentName,
-          "agent_sdk.turn_status": "failed",
-        });
+        metrics?.turns.add(
+          1,
+          join(event.sessionId, {
+            "agent_sdk.agent": agentName,
+            "agent_sdk.turn_status": "failed",
+          })
+        );
         emitLog(
           "turn.failed",
           SeverityNumber.ERROR,
@@ -531,7 +567,7 @@ export function createOtelCollector(
       {
         kind: SpanKind.INTERNAL,
         startTime: args.startTime,
-        attributes: attrs({
+        attributes: join(args.sessionId, {
           "cursor.conversation.id": args.sessionId,
           "agent_sdk.agent": agentName,
           "agent_sdk.channel": args.channelId,
@@ -549,10 +585,13 @@ export function createOtelCollector(
     };
     sessions.set(args.sessionId, state);
     if (!args.restored) {
-      metrics?.sessions.add(1, {
-        "agent_sdk.agent": agentName,
-        "agent_sdk.channel": args.channelId,
-      });
+      metrics?.sessions.add(
+        1,
+        join(args.sessionId, {
+          "agent_sdk.agent": agentName,
+          "agent_sdk.channel": args.channelId,
+        })
+      );
     }
     return state;
   }
@@ -600,7 +639,7 @@ export function createOtelCollector(
       {
         kind: SpanKind.INTERNAL,
         startTime: args.startTime,
-        attributes: attrs({
+        attributes: join(args.sessionId, {
           "cursor.conversation.id": args.sessionId,
           "agent_sdk.agent": agentName,
           "agent_sdk.turn_id": args.turnId,
@@ -666,34 +705,77 @@ export function createOtelCollector(
     );
     state.span.end(args.endTime);
     sessions.delete(args.sessionId);
+    extraBySession.delete(args.sessionId);
   }
 
-  function recordTokens(usage: {
-    inputTokens: number;
-    outputTokens: number;
-    cacheReadTokens: number;
-    cacheWriteTokens: number;
-    reasoningTokens?: number;
-  }): void {
+  function extra(sessionId: string): Record<string, AttrValue> {
+    return extraBySession.get(sessionId) ?? {};
+  }
+
+  function join(
+    sessionId: string,
+    rest: Record<string, AttrValue | undefined>
+  ): Record<string, AttrValue> {
+    return attrs({ ...extra(sessionId), ...rest });
+  }
+
+  function paintOpenSpans(
+    sessionId: string,
+    incoming: Record<string, AttrValue>
+  ): void {
+    const state = sessions.get(sessionId);
+    if (state === undefined) {
+      return;
+    }
+    const painted = attrs(incoming);
+    if (Object.keys(painted).length === 0) {
+      return;
+    }
+    state.span.setAttributes(painted);
+    for (const turn of state.turns.values()) {
+      turn.span.setAttributes(painted);
+      for (const span of turn.tools.values()) {
+        span.setAttributes(painted);
+      }
+      for (const span of turn.subagents.values()) {
+        span.setAttributes(painted);
+      }
+    }
+  }
+
+  function recordTokens(
+    sessionId: string,
+    usage: {
+      inputTokens: number;
+      outputTokens: number;
+      cacheReadTokens: number;
+      cacheWriteTokens: number;
+      reasoningTokens?: number;
+    }
+  ): void {
     if (metrics === undefined) {
       return;
     }
     const agent = agentName;
     // Wire token types match enterprise export (`cache_creation`, not write).
-    addTokens(usage.inputTokens, "input", agent);
-    addTokens(usage.outputTokens, "output", agent);
-    addTokens(usage.cacheReadTokens, "cache_read", agent);
-    addTokens(usage.cacheWriteTokens, "cache_creation", agent);
+    addTokens(sessionId, usage.inputTokens, "input", agent);
+    addTokens(sessionId, usage.outputTokens, "output", agent);
+    addTokens(sessionId, usage.cacheReadTokens, "cache_read", agent);
+    addTokens(sessionId, usage.cacheWriteTokens, "cache_creation", agent);
     if (usage.reasoningTokens !== undefined) {
       // Reasoning is Agent-SDK-only; enterprise wire has no reasoning enum.
-      metrics.tokens.add(usage.reasoningTokens, {
-        "cursor.token.type": "reasoning",
-        "agent_sdk.agent": agent,
-      });
+      metrics.tokens.add(
+        usage.reasoningTokens,
+        join(sessionId, {
+          "cursor.token.type": "reasoning",
+          "agent_sdk.agent": agent,
+        })
+      );
     }
   }
 
   function addTokens(
+    sessionId: string,
     value: number,
     type: "input" | "output" | "cache_read" | "cache_creation",
     agent: string
@@ -701,10 +783,13 @@ export function createOtelCollector(
     if (metrics === undefined || value === 0) {
       return;
     }
-    metrics.tokens.add(value, {
-      "cursor.token.type": type,
-      "agent_sdk.agent": agent,
-    });
+    metrics.tokens.add(
+      value,
+      join(sessionId, {
+        "cursor.token.type": type,
+        "agent_sdk.agent": agent,
+      })
+    );
   }
 
   /** Content opt-in for failure text (same gate as tool payloads). */

package/src/internal/sdk-runner.ts

@@ -52,6 +52,7 @@ export type RunnerPrewarmRequest = Pick<
   | "workspaceDir"
   | "runnerStateDir"
   | "sandbox"
+  | "tools"
   | "mcpServers"
   | "subagents"
   | "model"
@@ -373,6 +374,11 @@ export class CursorSdkRunner implements AgentRunner {
       this.options.store ?? (await this.getStore(request.runnerStateDir));
     return {
       ...this.buildSharedOptions(request),
+      // The built-in tool allowlist rides AgentOptions, not `local`, and is
+      // deliberately absent from openCloudAgent's options: the SDK rejects
+      // tool restrictions on cloud agents. Passed on create *and* resume
+      // (both flow through here) — the SDK does not persist it across runs.
+      ...(request.tools === undefined ? {} : { tools: request.tools }),
       local: {
         cwd: request.workspaceDir,
         settingSources: ["project"],

package/src/internal/server.ts

@@ -435,6 +435,7 @@ export async function startServer(
       logger,
       platforms: hostPlatforms,
       otel: otelCollector,
+      otelMeter: otelRuntime?.meter,
     });
     // Rehydrate sessions from the authored storage sink before any
     // channel or route can address them (continuation tokens must resolve).

package/src/internal/session-engine.ts

@@ -10,6 +10,7 @@
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import type { SDKCustomTool, SDKCustomToolResult } from "@cursor/sdk";
+import type { Meter } from "@opentelemetry/api";
 import {
   type ABDefinition,
   mergeABInstructions,
@@ -95,6 +96,7 @@ import { TurnEventMapper } from "./event-mapper.js";
 import { selectFrameworkStorageDefinition } from "./framework-storage-selection.js";
 import { createHostFilesApi } from "./host-files.js";
 import { createHostKvApi } from "./host-kv.js";
+import { createHostOtelApi, type HostOtelSessionApi } from "./host-otel.js";
 import {
   createHostPlatforms,
   createHostSlackClient,
@@ -246,6 +248,8 @@ export interface SessionEngineOptions {
   durableSessionStore?: HostKvApi;
   /** Process-level OTel collector; observe-only, never fatal. */
   otel?: OtelCollector;
+  /** Process-level meter for {@link HostContext.otel}. Absent → no-op counters. */
+  otelMeter?: Meter;
 }
 
 /**
@@ -362,6 +366,7 @@ export class SessionEngine {
   private readonly approvals = new ApprovalGate();
   private readonly abCollector: ABCollector;
   private readonly otel: OtelCollector | undefined;
+  private readonly otelHost: HostOtelSessionApi;
   private reminderApi: HostContext["reminders"];
   private evalsApi: HostContext["evals"];
   private readonly kvApi: HostContext["kv"];
@@ -395,6 +400,11 @@ export class SessionEngine {
     this.getCloudUsage = options.getCloudUsage ?? defaultGetCloudUsage;
     this.estimateTurnCost = options.estimateTurnCost ?? estimateTurnCostFromApi;
     this.otel = options.otel;
+    this.otelHost = createHostOtelApi({
+      agentName: options.project.name,
+      meter: options.otelMeter,
+      collector: options.otel,
+    });
     this.turnGovernor = new TurnGovernor(options.project.agent.concurrency);
     this.sessions = new SessionStore(join(options.stateRoot, "sessions"));
     this.nudgeStore = new SlackNudgeStore(
@@ -574,7 +584,7 @@ export class SessionEngine {
     this.cloudServerToolsConnection = connection;
   }
 
-  /** Shared host services (MCP / GitHub / Slack / reminders / evals / kv / Slack nudges). */
+  /** Shared host services (MCP / GitHub / Slack / reminders / evals / kv / files / otel / Slack nudges). */
   get host(): HostContext {
     return {
       mcp: this.mcpHost,
@@ -584,6 +594,7 @@ export class SessionEngine {
       evals: this.evalsApi,
       kv: this.kvApi,
       files: this.filesApi,
+      otel: this.otelHost,
       slackNudges: this.slackNudgeHostApi(),
     };
   }
@@ -598,7 +609,11 @@ export class SessionEngine {
     const host = this.host;
     return sessionId === undefined
       ? host
-      : { ...host, files: this.filesApi.forSession(sessionId) };
+      : {
+          ...host,
+          files: this.filesApi.forSession(sessionId),
+          otel: this.otelHost.forSession(sessionId),
+        };
   }
 
   /** Unbound `ctx.artifacts` facade (channel handlers, scratch tool calls). */
@@ -1359,6 +1374,9 @@ export class SessionEngine {
         workspaceDir,
         runnerStateDir: join(this.stateRoot, "runner"),
         sandbox: agent.local?.sandbox === true,
+        ...(agent.allowedTools === undefined
+          ? {}
+          : { tools: agent.allowedTools }),
         mcpServers: this.buildMcpServers("local"),
         subagents: buildRunnerSubagents(agent),
         ...(agent.model === undefined ? {} : { model: agent.model }),
@@ -1614,6 +1632,15 @@ export class SessionEngine {
       agentRuntime: agent.runtime,
       cloudOverride: record.cloudOverride,
     });
+    // Fail closed: the SDK cannot enforce the built-in tool allowlist on
+    // cloud agents yet, and a restriction that silently does not apply is
+    // worse than a refused turn. Cloud-runtime agents already fail
+    // discovery; this guards hybrid agents' per-send cloud sessions.
+    if (runtime === "cloud" && agent.allowedTools !== undefined) {
+      throw new Error(
+        `Agent "${agent.name}" declares a built-in tool allowlist (tools), which cannot be enforced on cloud turns yet. Refusing the cloud session rather than running it unrestricted.`
+      );
+    }
     const mergedCloud =
       runtime === "cloud"
         ? mergeCloudOptions({
@@ -1668,6 +1695,9 @@ export class SessionEngine {
         : { sdkAgentId: record.sdkAgentId }),
       workspaceDir: this.harnessCwd(record),
       sandbox: this.project.agent.local?.sandbox === true,
+      ...(runtime === "local" && agent.allowedTools !== undefined
+        ? { tools: agent.allowedTools }
+        : {}),
       runnerStateDir: join(this.stateRoot, "runner"),
       prompt: turnPrompt,
       isFirstTurn,

package/src/types.ts

@@ -8,7 +8,7 @@
  * SDK as the execution harness.
  */
 
-import type { InteractionUpdate, SDKCustomTool } from "@cursor/sdk";
+import type { InteractionUpdate, SDKCustomTool, ToolName } from "@cursor/sdk";
 import type { z } from "zod";
 import type { ABConfigFile } from "./ab.js";
 import type { OtelConfig, OtelDefinition } from "./otel.js";
@@ -206,6 +206,40 @@ export interface AgentConfig {
    * {@link BuiltinToolsConfig}.
    */
   builtinTools?: BuiltinToolsConfig;
+  /**
+   * Allowlist of built-in harness tools offered to the model
+   * (`AgentOptions.tools` on the SDK). Opt-in by design: unset keeps the
+   * model's full standard toolset, and once set the agent gets exactly
+   * what it names — nothing more, `[]` meaning no native built-in tools.
+   * There is deliberately no exclusion form: an agent that restricts
+   * tools states what it keeps, so tools the platform adds later stay
+   * off until someone opts in.
+   *
+   * `"mcp"` is always granted alongside a configured allowlist. It is
+   * transport, not capability: this kit's own server tools reach the
+   * model over the SDK custom-tool MCP path, so omitting it would
+   * silently strand `agent/tools/`. What MCP actually exposes stays
+   * governed by the second layer — the tools you author, the connections
+   * you declare, and the harness cwd's ambient `.cursor` config (point
+   * `local.cwd` outside checkouts whose MCP servers the agent must not
+   * see, and `local.sandbox` makes MCP calls fail closed).
+   *
+   * Names use the SDK's public tool vocabulary (`"shell"`, `"read"`,
+   * `"edit"`, `"grep"`, `"glob"`, `"ls"`, `"task"`, ...). `"shell"` is a
+   * capability group that also grants shell stdin writes — and is what
+   * `execution: "agent"` tool scripts run through, so an allowlist
+   * without it strands them (discovery warns). `"task"` gates subagents.
+   * Unknown names fail the turn (`ConfigurationError` at `Agent.create`).
+   *
+   * The allowlist states runtime-agnostic intent, but the SDK cannot
+   * enforce tool restrictions on cloud agents yet, and it must never
+   * silently not apply: a `runtime: "cloud"` agent that sets it fails at
+   * serve start (error diagnostic), and a hybrid agent's per-send cloud
+   * sessions are refused (the turn errors) rather than run unrestricted.
+   * Not a security boundary against the serve host: like `local.sandbox`,
+   * it only shapes what the model can call.
+   */
+  tools?: ToolName[];
   /**
    * How the serve host coordinates event delivery and turn execution. See
    * {@link AgentServingMode}. Defaults to `"resident"`; opt in to
@@ -506,6 +540,12 @@ export interface HostContext {
    * process.
    */
   files: HostFilesApi;
+  /**
+   * Author-facing OpenTelemetry metrics and session tags. Always present.
+   * Counters and histograms no-op when no meter is running. `setAttributes`
+   * still tags the open session when a collector is attached.
+   */
+  otel: HostOtelApi;
 }
 
 /** Host-facing JSON key-value API attached to {@link HostContext.kv}. */
@@ -706,6 +746,39 @@ export interface HostFilesApi {
   ): string | undefined;
 }
 
+/** Attribute bag accepted by {@link HostOtelApi}. `undefined` values are dropped. */
+export type HostOtelAttributes = Record<
+  string,
+  string | number | boolean | undefined
+>;
+
+/**
+ * Author-facing OpenTelemetry surface on {@link HostContext.otel}.
+ *
+ * Metrics and tags only — no custom spans, and no raw OTel `Meter` /
+ * `Tracer`. First-party names (`cursor.token.usage`, …) and join keys
+ * (`cursor.conversation.id`, `agent_sdk.agent`, …) are reserved.
+ */
+export interface HostOtelApi {
+  /** True when a meter is running and `increment` / `record` export. */
+  readonly enabled: boolean;
+
+  /**
+   * Merge tags onto this host binding. On a session-bound host they join
+   * the open session span and later first-party metrics. Unbound tags
+   * stay on this host instance only.
+   */
+  setAttributes(attributes: HostOtelAttributes): void;
+
+  /** Add 1 to a counter. */
+  increment(name: string, attributes?: HostOtelAttributes): void;
+  /** Add `value` to a counter. */
+  increment(name: string, value: number, attributes?: HostOtelAttributes): void;
+
+  /** Record one histogram observation. */
+  record(name: string, value: number, attributes?: HostOtelAttributes): void;
+}
+
 /** Runtime context handed to a tool's `execute`. */
 export interface ToolContext {
   /** Correlates with `actions.requested` / `action.result` stream events. */
@@ -1838,7 +1911,12 @@ export interface ChannelMeta {
 }
 
 export interface ChannelConfig<TState = JsonValue> {
-  /** Route auth chain. Defaults to `[localDevStrict()]`. */
+  /**
+   * Route auth chain. Defaults to `[localDevStrict()]`. Include
+   * `publicEndpoint()` to serve this channel WITHOUT the platform alias
+   * token on Cursor hosting (for webhook senders that cannot attach custom
+   * headers — the handler must verify deliveries itself).
+   */
   auth?: AuthPolicy[];
   routes?: ChannelRoute[];
   /**
@@ -2347,6 +2425,13 @@ export interface ResolvedAgent {
    * (`cwd` is absolute — relative paths resolved against the project root).
    */
   local?: AgentLocalOptions;
+  /**
+   * Built-in harness tool allowlist from {@link AgentConfig.tools}, with
+   * the "mcp" transport grant injected. Named apart from {@link tools}
+   * (the authored `agent/tools/` list). Applied to local turns; cloud
+   * turns fail closed (cloud-runtime agents already fail discovery).
+   */
+  allowedTools?: ToolName[];
   /** Managed-hosting declarations from {@link AgentConfig.hosting}. */
   hosting?: AgentHostingOptions;
   /** Validated turn admission limits from {@link AgentConfig.concurrency}. */
@@ -2503,6 +2588,8 @@ export interface RunnerTurnRequest {
   workspaceDir: string;
   /** Run the local harness sandboxed ({@link AgentLocalOptions.sandbox}). */
   sandbox?: boolean;
+  /** Built-in tool allowlist ({@link AgentConfig.tools}, resolved). */
+  tools?: ToolName[];
   /** Absolute path for runner-owned durable state (conversation store). */
   runnerStateDir: string;
   prompt: string;