@cursor/july 0.1.101 → 0.1.102

package/src/internal/session-engine.ts

@@ -34,6 +34,7 @@ import {
   isCursorHostedFilesAvailable,
   isCursorUserStoreFilesAvailable,
 } from "../files-backends/cursor-hosted.js";
+import { storageKeysForArchitecture } from "../storage.js";
 import {
   type AgentProject,
   type AgentRuntime,
@@ -168,6 +169,7 @@ import {
 import { TurnGovernor } from "./turn-governor.js";
 import { TurnLeaseStore } from "./turn-lease-store.js";
 import { TurnOutbox } from "./turn-outbox.js";
+import { resolveAgentV2Hosting } from "./v2-hosting.js";
 import {
   buildAgentsMdContent,
   buildCloudMemorySection,
@@ -537,20 +539,36 @@ export class SessionEngine {
             agentName: options.project.name,
             projectRoot: options.project.rootDir,
             logger: this.logger,
+            keys: storageKeysForArchitecture(
+              options.project.agent.architecture
+            ),
           });
     this.kvApi = createHostKvApi({
       agentName: options.project.name,
       stateRoot: options.stateRoot,
       ...(this.storage === undefined ? {} : { storage: this.storage }),
     });
+    const v2Hosting = resolveAgentV2Hosting({
+      architecture: options.project.agent.architecture,
+    });
+    const managedV2Files =
+      v2Hosting.kind === "cursor-managed"
+        ? () =>
+            cursorHostedFiles({
+              resolveStoreSourceId: () =>
+                v2Hosting.resolveStoreIds().deploymentStoreSourceId,
+            })
+        : undefined;
     this.filesApi = createHostFilesApi({
       agentName: options.project.name,
       stateRoot: options.stateRoot,
+      sink: managedV2Files?.(),
     });
     this.artifactsStore = new ArtifactsStore({
       stateRoot: options.stateRoot,
       agentName: options.project.name,
       config: options.project.artifacts,
+      sink: managedV2Files?.(),
     });
     this.abCollector = new ABCollector(
       options.project.abs,
@@ -2148,7 +2166,20 @@ export class SessionEngine {
         label: string;
       }
     | undefined {
-    if (isCursorHostedFilesAvailable()) {
+    const v2Hosting = resolveAgentV2Hosting({
+      architecture: this.project.agent.architecture,
+    });
+    if (v2Hosting.kind === "cursor-managed") {
+      return {
+        sink: cursorHostedFiles({
+          resolveStoreSourceId: () =>
+            v2Hosting.resolveStoreIds().deploymentStoreSourceId,
+        }),
+        skillsPrefix: agentStoreKeys.skillsPrefix(),
+        label: "deployment store",
+      };
+    }
+    if (v2Hosting.kind === "not-v2" && isCursorHostedFilesAvailable()) {
       return {
         sink: cursorHostedFiles(),
         skillsPrefix: agentStoreKeys.skillsPrefix(),
@@ -2747,6 +2778,7 @@ export class SessionEngine {
         this.getChannelSession(channelId, sessionId),
       emit: args.emit,
       now: sessionClock(args.record.asOf),
+      ...(args.record.asOf === undefined ? {} : { asOf: args.record.asOf }),
     };
     try {
       // Before the approval gate: a dry run is unattended, so parking a write
@@ -2815,15 +2847,24 @@ export class SessionEngine {
       }
       const started = Date.now();
       this.logger(`[session] tool ${args.tool.name} start`);
-      const result = await mcpAuthAls.run(
+      const result = await this.runToolExecute(
         {
-          sessionId: args.record.sessionId,
+          record: args.record,
           turnId: args.turnId,
           callId: toolCallId,
           toolName: args.tool.name,
-          emit: args.emit,
         },
-        () => execute(validation.value as never, toolCtx)
+        () =>
+          mcpAuthAls.run(
+            {
+              sessionId: args.record.sessionId,
+              turnId: args.turnId,
+              callId: toolCallId,
+              toolName: args.tool.name,
+              emit: args.emit,
+            },
+            () => execute(validation.value as never, toolCtx)
+          )
       );
       this.logger(
         `[session] tool ${args.tool.name} done (${Date.now() - started}ms)`
@@ -2839,6 +2880,36 @@ export class SessionEngine {
     }
   }
 
+  /**
+   * Bind outbound inject (Factory / Cursor API `traceparent`) to the
+   * tool span. No-op when OTel is off.
+   */
+  private runToolExecute<T>(
+    args: {
+      record: SessionRecord;
+      turnId: string;
+      callId: string;
+      toolName: string;
+    },
+    fn: () => T | Promise<T>
+  ): Promise<T> {
+    const otel = this.otel;
+    const run = (): Promise<T> => Promise.resolve(fn());
+    if (otel === undefined) {
+      return run();
+    }
+    return otel.runInCall(
+      {
+        sessionId: args.record.sessionId,
+        session: this.sessionInfo(args.record),
+        turnId: args.turnId,
+        callId: args.callId,
+        toolName: args.toolName,
+      },
+      run
+    );
+  }
+
   /**
    * Park a server-tool call until a human approves or denies. Emits
    * `action.approval_requested` / `action.approval_resolved` on the
@@ -3712,20 +3783,34 @@ export class SessionEngine {
               this.getChannelSession(channelId, sessionId),
             emit,
             now: sessionClock(record?.asOf),
+            ...(record?.asOf === undefined ? {} : { asOf: record.asOf }),
           });
-        result = normalizeToolResult(
+        const executeBody =
           record !== undefined && emit !== undefined
-            ? await mcpAuthAls.run(
+            ? () =>
+                mcpAuthAls.run(
+                  {
+                    sessionId: record.sessionId,
+                    turnId: callId,
+                    callId,
+                    toolName,
+                    emit,
+                  },
+                  run
+                )
+            : run;
+        result = normalizeToolResult(
+          record !== undefined
+            ? await this.runToolExecute(
                 {
-                  sessionId: record.sessionId,
+                  record,
                   turnId: callId,
                   callId,
                   toolName,
-                  emit,
                 },
-                run
+                executeBody
               )
-            : await run()
+            : await executeBody()
         );
         isError = isErrorEnvelope(result);
       }

package/src/internal/session-run-log.ts

@@ -15,21 +15,19 @@
  * persist so a store outage never changes the hosted-execution HTTP reply.
  *
  * Same flush moments as `hosted-execution.json` and the start.log tee —
- * see `hosted-execution-flush.ts`. Keys: {@link storageKeys.sessionRun}.
+ * see `hosted-execution-flush.ts`. Keys:
+ * {@link agentSdkStorageKeys.sessionRun}.
  */
 
 import type { FileSink } from "../files.js";
-import {
-  cursorFrameworkStoreSourceId,
-  cursorHostedFiles,
-} from "../files-backends/cursor-hosted.js";
-import { storageKeys } from "../storage-protocol.js";
+import { cursorHostedFiles } from "../files-backends/cursor-hosted.js";
+import { agentSdkStorageKeys } from "../storage-protocol.js";
 import type { AgentProject } from "../types.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
-import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
 import { describeError } from "./describe-error.js";
 import type { HostedExecutionDiagAbortReason } from "./hosted-execution-diag.js";
 import type { LogRingEntry } from "./log-ring.js";
+import { resolveAgentV2Hosting } from "./v2-hosting.js";
 
 export const SESSION_RUN_LOG_VERSION = 1;
 /** Last N log-ring lines kept on each execution. */
@@ -442,7 +440,7 @@ export function createSessionRunLogStore(input: {
   const readDocument = async (
     sessionPublicId: string
   ): Promise<SessionRunLogDocument | undefined> => {
-    const key = storageKeys.sessionRun(agentName, sessionPublicId);
+    const key = agentSdkStorageKeys.sessionRun(agentName, sessionPublicId);
     const body = await sink.get(key);
     if (body === undefined) {
       return undefined;
@@ -479,7 +477,10 @@ export function createSessionRunLogStore(input: {
       updatedAt: fitted.writtenAt,
       executions,
     });
-    const key = storageKeys.sessionRun(agentName, document.sessionPublicId);
+    const key = agentSdkStorageKeys.sessionRun(
+      agentName,
+      document.sessionPublicId
+    );
     try {
       await sink.put(key, new TextEncoder().encode(JSON.stringify(document)));
     } catch (error) {
@@ -558,17 +559,17 @@ export function selectSessionRunLogStore(input: {
   env?: Record<string, string | undefined>;
   snapshotLogs?: () => readonly LogRingEntry[];
 }): SessionRunLogStore | undefined {
-  if (input.project.agent.architecture !== "v2") {
-    return undefined;
-  }
-  const env = input.env ?? process.env;
-  if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined) {
+  const hosting = resolveAgentV2Hosting({
+    architecture: input.project.agent.architecture,
+    env: input.env as NodeJS.ProcessEnv | undefined,
+  });
+  if (hosting.kind !== "cursor-managed") {
     return undefined;
   }
-  const envSnapshot = env as NodeJS.ProcessEnv;
   return createSessionRunLogStore({
     sink: cursorHostedFiles({
-      resolveStoreSourceId: () => cursorFrameworkStoreSourceId(envSnapshot),
+      resolveStoreSourceId: () =>
+        hosting.resolveStoreIds().frameworkStoreSourceId,
       resolveApiKey: () => resolveApiKeySync()?.apiKey,
     }),
     agentName: input.project.name,

package/src/internal/start-log-store.ts

@@ -8,21 +8,18 @@
  * after park/discard.
  *
  * Same flush moments as `hosted-execution.json` and session-runs —
- * see `hosted-execution-flush.ts`. Keys: {@link storageKeys.log}.
+ * see `hosted-execution-flush.ts`. Keys: {@link agentSdkStorageKeys.log}.
  * Values are raw UTF-8, not JSON.
  */
 
 import { readFile } from "node:fs/promises";
 import type { FileSink } from "../files.js";
-import {
-  cursorFrameworkStoreSourceId,
-  cursorHostedFiles,
-} from "../files-backends/cursor-hosted.js";
-import { storageKeys } from "../storage-protocol.js";
+import { cursorHostedFiles } from "../files-backends/cursor-hosted.js";
+import { agentSdkStorageKeys } from "../storage-protocol.js";
 import type { AgentProject } from "../types.js";
 import { resolveApiKeySync } from "./cursor/credentials.js";
-import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
 import { describeError } from "./describe-error.js";
+import { resolveAgentV2Hosting } from "./v2-hosting.js";
 
 /**
  * Last N bytes flushed to the store. Matches the Temporal catch-up cap
@@ -102,7 +99,7 @@ export function createStartLogStore(input: {
 
   return {
     async persist(startLogId, contents) {
-      const key = storageKeys.log(agentName, startLogId);
+      const key = agentSdkStorageKeys.log(agentName, startLogId);
       const body = tailStartLogText(contents, START_LOG_STORE_MAX_BYTES);
       try {
         await sink.put(key, new TextEncoder().encode(body));
@@ -114,7 +111,7 @@ export function createStartLogStore(input: {
     },
 
     async read(startLogId) {
-      const key = storageKeys.log(agentName, startLogId);
+      const key = agentSdkStorageKeys.log(agentName, startLogId);
       try {
         const body = await sink.get(key);
         if (body === undefined) {
@@ -140,17 +137,17 @@ export function selectStartLogStore(input: {
   logger?: (line: string) => void;
   env?: Record<string, string | undefined>;
 }): StartLogStore | undefined {
-  if (input.project.agent.architecture !== "v2") {
-    return undefined;
-  }
-  const env = input.env ?? process.env;
-  if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined) {
+  const hosting = resolveAgentV2Hosting({
+    architecture: input.project.agent.architecture,
+    env: input.env as NodeJS.ProcessEnv | undefined,
+  });
+  if (hosting.kind !== "cursor-managed") {
     return undefined;
   }
-  const envSnapshot = env as NodeJS.ProcessEnv;
   return createStartLogStore({
     sink: cursorHostedFiles({
-      resolveStoreSourceId: () => cursorFrameworkStoreSourceId(envSnapshot),
+      resolveStoreSourceId: () =>
+        hosting.resolveStoreIds().frameworkStoreSourceId,
       resolveApiKey: () => resolveApiKeySync()?.apiKey,
     }),
     agentName: input.project.name,

package/src/internal/storage-coordinator.ts

@@ -31,6 +31,7 @@ import {
   type StorageContext,
   type StorageDefinition,
   type StorageEntry,
+  type StorageKeys,
   storageKeys,
 } from "../storage.js";
 import { isCursorHostedStorage } from "../storage-backends/cursor-hosted.js";
@@ -79,7 +80,7 @@ const AB_SNAPSHOT_MIN_INTERVAL_MS = 60_000;
 
 /** One queued sink call (KV put/delete or a dedicated-table write). */
 interface StorageOp {
-  /** Human-readable op label for failure logs, e.g. `put(agentkit/v1/...)`. */
+  /** Human-readable op label for failure logs, e.g. `put({root}/...)`. */
   label: string;
   run: (ctx: StorageContext) => void | Promise<void>;
 }
@@ -89,6 +90,8 @@ export interface StorageCoordinatorOptions {
   agentName: string;
   projectRoot: string;
   logger: (line: string) => void;
+  /** Defaults to the architecture-v1 key contract. */
+  keys?: StorageKeys;
 }
 
 interface SessionBuffer {
@@ -116,6 +119,7 @@ export class StorageCoordinator
   readonly policy: ResolvedStoragePolicy;
 
   private readonly definition: StorageDefinition;
+  private readonly keys: StorageKeys;
   private readonly agentName: string;
   private readonly projectRoot: string;
   private readonly logger: (line: string) => void;
@@ -137,6 +141,7 @@ export class StorageCoordinator
 
   constructor(options: StorageCoordinatorOptions) {
     this.definition = options.definition;
+    this.keys = options.keys ?? storageKeys;
     this.policy = resolveStoragePolicy(options.definition.policy);
     this.agentName = options.agentName;
     this.projectRoot = options.projectRoot;
@@ -215,7 +220,7 @@ export class StorageCoordinator
     if (first !== undefined) {
       ops.push(
         this.putOp(
-          storageKeys.sessionEvents(this.agentName, sessionId, first.index),
+          this.keys.sessionEvents(this.agentName, sessionId, first.index),
           buffer.events as unknown as JsonValue
         )
       );
@@ -223,7 +228,7 @@ export class StorageCoordinator
     if (buffer.record !== undefined) {
       ops.push(
         this.putOp(
-          storageKeys.session(this.agentName, sessionId),
+          this.keys.session(this.agentName, sessionId),
           buffer.record as unknown as JsonValue
         )
       );
@@ -249,14 +254,14 @@ export class StorageCoordinator
     if (previous != null) {
       ops.push(
         this.deleteOp(
-          storageKeys.continuation(this.agentName, record.channelId, previous)
+          this.keys.continuation(this.agentName, record.channelId, previous)
         )
       );
     }
     if (next != null) {
       ops.push(
         this.putOp(
-          storageKeys.continuation(this.agentName, record.channelId, next),
+          this.keys.continuation(this.agentName, record.channelId, next),
           { sessionId: record.sessionId }
         )
       );
@@ -303,9 +308,7 @@ export class StorageCoordinator
    * serve start.
    */
   async listSessions(): Promise<SessionRecord[]> {
-    const entries = await this.tryList(
-      storageKeys.sessionPrefix(this.agentName)
-    );
+    const entries = await this.tryList(this.keys.sessionPrefix(this.agentName));
     return entries
       .map((entry) => entry.value as unknown as SessionRecord)
       .filter((record) => record != null);
@@ -322,7 +325,7 @@ export class StorageCoordinator
       throw new Error("storage sink has no list");
     }
     const entries = await list(
-      storageKeys.sessionPrefix(this.agentName),
+      this.keys.sessionPrefix(this.agentName),
       this.context("restore")
     );
     if (!Array.isArray(entries)) {
@@ -345,7 +348,7 @@ export class StorageCoordinator
       return undefined;
     }
     const entries = await listNewest(
-      storageKeys.sessionPrefix(this.agentName),
+      this.keys.sessionPrefix(this.agentName),
       limit,
       this.context("restore")
     );
@@ -362,7 +365,7 @@ export class StorageCoordinator
    */
   async listSessionEvents(sessionId: string): Promise<SessionEvent[]> {
     const entries = await this.tryList(
-      storageKeys.sessionEventsPrefix(this.agentName, sessionId)
+      this.keys.sessionEventsPrefix(this.agentName, sessionId)
     );
     const events: SessionEvent[] = [];
     for (const entry of entries) {
@@ -389,7 +392,7 @@ export class StorageCoordinator
     }
     const ctx = this.context("restore");
     const record = (await get(
-      storageKeys.session(this.agentName, sessionId),
+      this.keys.session(this.agentName, sessionId),
       ctx
     )) as SessionRecord | null | undefined;
     if (record == null) {
@@ -422,7 +425,7 @@ export class StorageCoordinator
     }
     const ctx = this.context("restore");
     const pointer = await get(
-      storageKeys.continuation(this.agentName, channelId, continuationKey),
+      this.keys.continuation(this.agentName, channelId, continuationKey),
       ctx
     );
     if (pointer == null) {
@@ -482,7 +485,7 @@ export class StorageCoordinator
     if (get === undefined) {
       throw new Error("storage get is not configured");
     }
-    const key = storageKeys.kv(this.agentName, authorKey);
+    const key = this.keys.kv(this.agentName, authorKey);
     // Preserve stored JSON `null` (distinct from a missing key).
     return await get(key, this.context("restore"));
   }
@@ -492,13 +495,13 @@ export class StorageCoordinator
    * at-most-once delivery queue) so callers observe durable success/failure.
    */
   async kvPut(authorKey: string, value: JsonValue): Promise<void> {
-    const key = storageKeys.kv(this.agentName, authorKey);
+    const key = this.keys.kv(this.agentName, authorKey);
     await this.definition.put(key, value, this.context("policy"));
   }
 
   /** Awaited author KV delete. No-op when the sink omits `delete`. */
   async kvDelete(authorKey: string): Promise<void> {
-    const key = storageKeys.kv(this.agentName, authorKey);
+    const key = this.keys.kv(this.agentName, authorKey);
     await this.definition.delete?.(key, this.context("policy"));
   }
 

package/src/internal/tool-catalog.ts

@@ -23,13 +23,16 @@ import type {
  * presentation concern is not worth the authoring surface).
  */
 const WELL_KNOWN_TOOL_TITLES: Readonly<Record<string, string>> = {
-  diff: "Show change diffs",
-  glob: "Find files by pattern",
-  grep: "Search file contents",
-  ls: "List a directory",
-  read: "Read a file",
+  Delete: "Delete a file",
+  Diff: "Show change diffs",
+  Glob: "Find files by pattern",
+  Grep: "Search file contents",
+  LS: "List a directory",
+  Read: "Read a file",
+  StrReplace: "Replace text in a file",
+  Write: "Write a file",
+  script: "Run a TypeScript program",
   search: "Search with a typed query",
-  write: "Write a file",
 };
 
 function catalogTitle(tool: DiscoveredTool): string | undefined {

package/src/internal/turn-cost.ts

@@ -28,6 +28,45 @@ export function modelSettingId(model: ModelSetting): string {
   return typeof model === "string" ? model : model.id;
 }
 
+/**
+ * This estimate-cost client treats OpenAI-compat usage as **provider-gross**
+ * (local playground: `prompt_tokens` includes `cachedPromptTokens`). Catalog
+ * `costForBaseTier` assumes Anthropic / billing-style disjoint nets and ADDs
+ * `cacheRead × cachedRate` on top of `input × inputRate`, so we send
+ * `input − cache` for Grok / xAI / GPT / o-series.
+ *
+ * Non-OpenAI-compat models are left alone. `input < cache` is only a
+ * defensive clamp (avoid a negative uncached count), not a detector for
+ * billed / openaiProxy-shaped tokens. Cloud catalog fallback with already-
+ * netted OpenAI-compat usage is out of scope here.
+ */
+export function isOpenAiCompatGrossCacheModel(model: ModelSetting): boolean {
+  const id = modelSettingId(model).toLowerCase();
+  return (
+    id.includes("grok") ||
+    id.includes("xai") ||
+    id.includes("gpt") ||
+    /(^|[-_/])o[1-9]/.test(id)
+  );
+}
+
+export function toCatalogDisjointUsage(
+  usage: TurnUsage,
+  model?: ModelSetting
+): TurnUsage {
+  if (model === undefined || !isOpenAiCompatGrossCacheModel(model)) {
+    return usage;
+  }
+  const cachedTokens = usage.cacheReadTokens + usage.cacheWriteTokens;
+  if (cachedTokens === 0 || usage.inputTokens < cachedTokens) {
+    return usage;
+  }
+  return {
+    ...usage,
+    inputTokens: usage.inputTokens - cachedTokens,
+  };
+}
+
 export function roundCostUsd(usd: number): number {
   return Math.round(usd * 1e6) / 1e6;
 }
@@ -67,6 +106,10 @@ export async function estimateTurnCostFromApi(
     return undefined;
   }
   const model = modelSettingId(input.model);
+  const catalogUsage =
+    input.usage === undefined
+      ? undefined
+      : toCatalogDisjointUsage(input.usage, input.model);
   const response = await fetch(
     `${cursorExternalApiUrl()}/v1/models/estimate-cost`,
     {
@@ -77,10 +120,10 @@ export async function estimateTurnCostFromApi(
       },
       body: JSON.stringify({
         model,
-        inputTokens: input.usage?.inputTokens,
-        outputTokens: input.usage?.outputTokens,
-        cacheReadTokens: input.usage?.cacheReadTokens,
-        cacheWriteTokens: input.usage?.cacheWriteTokens,
+        inputTokens: catalogUsage?.inputTokens,
+        outputTokens: catalogUsage?.outputTokens,
+        cacheReadTokens: catalogUsage?.cacheReadTokens,
+        cacheWriteTokens: catalogUsage?.cacheWriteTokens,
         agentId: input.agentId,
         conversationId: input.conversationId,
         runId: input.runId,

package/src/internal/v2-hosting.ts

@@ -0,0 +1,38 @@
+import type { AgentArchitecture } from "../types.js";
+import {
+  type CursorManagedV2StoreIds,
+  requireCursorManagedV2StoreIdsSync,
+} from "./cursor/hosted-store-secrets.js";
+import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
+
+export type AgentV2Hosting =
+  | { kind: "not-v2" }
+  | { kind: "self-hosted" }
+  | {
+      kind: "cursor-managed";
+      resolveStoreIds: () => CursorManagedV2StoreIds;
+    };
+
+/**
+ * Close the architecture/hosting inputs into a compiler-owned union.
+ *
+ * Managed freeze processes exist before task bind, so store resolution stays
+ * lazy. Consumers can branch once on `kind`; managed storage operations then
+ * receive a resolver whose successful result always contains both ids.
+ */
+export function resolveAgentV2Hosting(input: {
+  architecture: AgentArchitecture | undefined;
+  env?: NodeJS.ProcessEnv;
+}): AgentV2Hosting {
+  if (input.architecture !== "v2") {
+    return { kind: "not-v2" };
+  }
+  const env = input.env ?? process.env;
+  if (env[AGENT_SERVE_GENERATION_ENV_VAR] === undefined) {
+    return { kind: "self-hosted" };
+  }
+  return {
+    kind: "cursor-managed",
+    resolveStoreIds: () => requireCursorManagedV2StoreIdsSync(env),
+  };
+}

package/src/otel.ts

@@ -12,6 +12,7 @@
  * ```
  */
 
+import { context, trace } from "@opentelemetry/api";
 import { brandDefinition } from "./internal/brand.js";
 
 export type OtelSignal = "traces" | "metrics" | "logs";
@@ -153,3 +154,40 @@ function assertSampleRatio(traces: OtelConfig["traces"]): void {
     throw new Error("defineOtel: traces.sampleRatio must be in [0, 1]");
   }
 }
+
+export const TRACEPARENT_HEADER = "traceparent";
+/** Cursor backend prefers this; `remoteSpanContextFromRequest` falls back to W3C. */
+export const BACKEND_TRACEPARENT_HEADER = "backend-traceparent";
+
+export function formatTraceparent(spanContext: {
+  traceId: string;
+  spanId: string;
+  traceFlags: number;
+}): string | undefined {
+  if (!trace.isSpanContextValid(spanContext)) {
+    return undefined;
+  }
+  return `00-${spanContext.traceId}-${
+    spanContext.spanId
+  }-${spanContext.traceFlags.toString(16).padStart(2, "0")}`;
+}
+
+/**
+ * Copy the active span onto outbound headers as W3C `traceparent` and
+ * Cursor `backend-traceparent`. No-op when no valid span is active.
+ */
+export function injectActiveTraceContext(headers: {
+  get(name: string): string | null;
+  set(name: string, value: string): void;
+}): void {
+  const span = trace.getSpan(context.active());
+  if (span === undefined) {
+    return;
+  }
+  const traceparent = formatTraceparent(span.spanContext());
+  if (traceparent === undefined) {
+    return;
+  }
+  headers.set(TRACEPARENT_HEADER, traceparent);
+  headers.set(BACKEND_TRACEPARENT_HEADER, traceparent);
+}