@cursor/bdk 0.2.1 → 0.2.2

package/src/extensions/cursor-cloud-agents/tools/cancel.ts

@@ -1,6 +1,7 @@
 import { defineTool } from "../../../tools.js";
 import type { ToolDefinition } from "../../../types.js";
 import { cloudAgentsBackend } from "../lib/backend.js";
+import { assertWriteChannel } from "../lib/channels.js";
 import { assertOwned } from "../lib/fleet.js";
 import { agentRef } from "../lib/inputs.js";
 
@@ -10,6 +11,7 @@ const cancel: ToolDefinition = defineTool({
   effect: "write",
   inputSchema: agentRef,
   async execute(input, ctx) {
+    assertWriteChannel(ctx);
     await assertOwned(ctx, input.agent_id);
     await cloudAgentsBackend().pause(input.agent_id);
     return { agentId: input.agent_id, cancelled: true };

package/src/extensions/cursor-cloud-agents/tools/launch.ts

@@ -3,6 +3,7 @@ import { defineTool } from "../../../tools.js";
 import type { ToolDefinition } from "../../../types.js";
 import extension from "../extension.js";
 import { cloudAgentsBackend } from "../lib/backend.js";
+import { assertWriteChannel } from "../lib/channels.js";
 import { recordLaunch } from "../lib/fleet.js";
 import { launchRepos } from "../lib/repos.js";
 
@@ -21,7 +22,7 @@ const launch: ToolDefinition = defineTool({
       .url()
       .optional()
       .describe(
-        "GitHub repository URL, one of the configured repositories. Defaults to the configured repository.",
+        "Repository clone URL (GitHub or Origin), one of the configured repositories. Defaults to the configured repository when there is exactly one.",
       ),
     starting_ref: z
       .string()
@@ -39,6 +40,7 @@ const launch: ToolDefinition = defineTool({
       .describe("Display name; derived from the prompt when omitted."),
   }),
   async execute(input, ctx) {
+    assertWriteChannel(ctx);
     const { cloud, model } = extension.config;
     const launched = await cloudAgentsBackend().launch({
       prompt: input.prompt,

package/src/extensions/cursor-cloud-agents/tools/reply.ts

@@ -3,6 +3,7 @@ import { defineTool } from "../../../tools.js";
 import type { ToolDefinition } from "../../../types.js";
 import extension from "../extension.js";
 import { cloudAgentsBackend } from "../lib/backend.js";
+import { assertWriteChannel } from "../lib/channels.js";
 import { assertOwned } from "../lib/fleet.js";
 import { agentRef } from "../lib/inputs.js";
 
@@ -21,6 +22,7 @@ const reply: ToolDefinition = defineTool({
       ),
   }),
   async execute(input, ctx) {
+    assertWriteChannel(ctx);
     await assertOwned(ctx, input.agent_id);
     const { runId } = await cloudAgentsBackend().followUp(
       input.agent_id,

package/src/files-backends/cursor-hosted.ts

@@ -925,10 +925,10 @@ export function cursorHostedFiles(options: CursorHostedFilesOptions = {}): Hoste
         if (files.wire !== "flush") {
           return false;
         }
-        // The flush wire's deletes are conditional server-side: when this
-        // process has no observed etag, the server resolves the current one —
-        // the lookup that costs a stat round trip on `/v0` — and a key that
-        // is already absent settles as `already_deleted`.
+        // With an observed etag the flush delete is If-Match on that version.
+        // Without one, the server tombstones whatever live object occupies
+        // the key (no directory walk here) and an absent key settles as
+        // `already_deleted`.
         const cached = observedEtags.get(key);
         const response = await flushPost<FlushWireResponse>(options, "/flush", {
           store: files.store,

package/src/internal/artifacts-store.ts

@@ -107,6 +107,12 @@ export interface CreateArtifactsStoreOptions {
   config?: ArtifactsConfig;
   /** Explicit sink override (tests). Omitted → hosted store or local disk. */
   sink?: FileSink;
+  /**
+   * Whether `tag` enforces {@link ArtifactsConfig.max} by listing and
+   * deleting. Default true. Hosted architecture v2 passes false: the
+   * installation store is allowed to grow, and a tag must not list the prefix.
+   */
+  enforceCap?: () => boolean;
 }
 
 /** Kind used by freeform tags when no kinds are declared. */
@@ -114,8 +120,11 @@ export const ARTIFACT_DEFAULT_KIND = "artifact";
 
 /**
  * Upsert + list semantics over one {@link ArtifactRowStore}: kind/schema
- * validation, deterministic ids for keyed tags, and `max` eviction. The
- * engine wraps this into the per-context {@link ArtifactsApi} facades and
+ * validation, deterministic ids for keyed tags, and `max` eviction.
+ * Architecture v1 and self-hosted v2 evict. Hosted architecture v2 sets
+ * {@link CreateArtifactsStoreOptions.enforceCap} false and does not list
+ * or delete on tag. The engine wraps this into the per-context
+ * {@link ArtifactsApi} facades and
  * owns the `artifact.tagged` event append.
  */
 export class ArtifactsStore {
@@ -123,6 +132,7 @@ export class ArtifactsStore {
   private readonly content: ArtifactContentStore;
   private readonly config: ArtifactsConfig | undefined;
   private readonly max: number;
+  private readonly enforceCap: () => boolean;
   /** Serializes tags so read-modify-write upserts and eviction don't race. */
   private tagChain: Promise<unknown> = Promise.resolve();
 
@@ -137,6 +147,7 @@ export class ArtifactsStore {
     }
     this.config = options.config;
     this.max = resolveArtifactsMax(options.config);
+    this.enforceCap = options.enforceCap ?? (() => true);
   }
 
   tag(input: ArtifactTagInput): Promise<ArtifactRecord> {
@@ -181,7 +192,7 @@ export class ArtifactsStore {
       }
     }
     await this.rows.put(record);
-    if (existing === undefined) {
+    if (existing === undefined && this.enforceCap()) {
       await this.evictPastCap();
     }
     return record;

package/src/internal/event-mapper.ts

@@ -5,7 +5,7 @@
  */
 
 import type { InteractionUpdate as SdkInteractionUpdate, ToolCall } from "@cursor/sdk";
-import type { SessionEventPayload, TurnUsage } from "../types.js";
+import type { ActionCall, ActionResult, SessionEventPayload, TurnUsage } from "../types.js";
 
 const CUSTOM_TOOLS_PROVIDER = "custom-user-tools";
 /** Authored server tools on cloud turns; keep in sync with `SERVER_TOOLS_MCP_SERVER_NAME`. */
@@ -39,7 +39,8 @@ type NestedTaskUpdate =
       modelCallId: string;
     }
   | { type: "step-started"; stepId: number }
-  | { type: "step-completed"; stepId: number; stepDurationMs: number };
+  | { type: "step-completed"; stepId: number; stepDurationMs: number }
+  | { type: "tool-requests-listed"; callCount: number };
 
 type ToolCallDeltaUpdate = {
   type: "tool-call-delta";
@@ -48,8 +49,13 @@ type ToolCallDeltaUpdate = {
   taskUpdate: NestedTaskUpdate;
 };
 
-/** SDK updates plus nested task deltas once the SDK exposes them. */
-type InteractionUpdate = SdkInteractionUpdate | ToolCallDeltaUpdate;
+type ToolRequestsListedUpdate = {
+  type: "tool-requests-listed";
+  callCount: number;
+};
+
+/** SDK updates plus list-closed / nested task deltas ahead of `@cursor/sdk`. */
+type InteractionUpdate = SdkInteractionUpdate | ToolCallDeltaUpdate | ToolRequestsListedUpdate;
 
 function asToolCallDelta(update: InteractionUpdate): ToolCallDeltaUpdate | undefined {
   if ((update as { type: string }).type !== "tool-call-delta") {
@@ -58,6 +64,12 @@ function asToolCallDelta(update: InteractionUpdate): ToolCallDeltaUpdate | undef
   return update as ToolCallDeltaUpdate;
 }
 
+function modelCallIdOf(update: { modelCallId?: unknown }): string | undefined {
+  return typeof update.modelCallId === "string" && update.modelCallId !== ""
+    ? update.modelCallId
+    : undefined;
+}
+
 export interface ToolCallDescription {
   toolName: string;
   args?: unknown;
@@ -74,6 +86,17 @@ interface NestedAccumulators {
   reasoning: string;
 }
 
+type ToolWave = {
+  key: string;
+  modelCallId?: string;
+  parentCallId?: string;
+  calls: ActionCall[];
+  results: ActionResult[];
+  expectedCalls?: number;
+  requestedEmitted: boolean;
+  completedEmitted: boolean;
+};
+
 export class TurnEventMapper {
   private textAccumulator = "";
   private reasoningAccumulator = "";
@@ -82,6 +105,17 @@ export class TurnEventMapper {
   private summaryTitle: string | undefined;
   /** Per-parent-call accumulators for nested subagent streams. */
   private readonly nested = new Map<string, NestedAccumulators>();
+  /** One wave per model step (or per call when the step id is missing). */
+  private readonly waves = new Map<string, ToolWave>();
+  /**
+   * Keys of waves that already emitted `actions.completed`, plus each
+   * finished call's singleton key. A late duplicate cannot reopen the
+   * batch or emit a second pair for the same callId. A new late callId
+   * still gets its own singleton.
+   */
+  private readonly sealedWaveKeys = new Set<string>();
+  /** Listed-call count from `tool-requests-listed`, keyed by parentCallId. */
+  private readonly listedCounts = new Map<string, number>();
 
   /**
    * @param isStubbed Reports whether a finished tool call was answered by the
@@ -173,17 +207,25 @@ export class TurnEventMapper {
       }
       case "tool-call-started": {
         this.flushAssistantText("tool_call");
-        this.emitToolStarted(update.callId, update.toolCall);
+        this.noteToolStarted(update.callId, update.toolCall, {
+          modelCallId: modelCallIdOf(update),
+        });
         return;
       }
       case "tool-call-completed": {
-        this.emitToolCompleted(update.callId, update.toolCall);
+        this.noteToolCompleted(update.callId, update.toolCall, {
+          modelCallId: modelCallIdOf(update),
+        });
         return;
       }
       case "step-started": {
         this.emit({ type: "step.started", data: { stepId: update.stepId } });
         return;
       }
+      case "tool-requests-listed": {
+        this.noteRequestsListed(undefined, update.callCount);
+        return;
+      }
       case "step-completed": {
         this.emit({
           type: "step.completed",
@@ -223,6 +265,8 @@ export class TurnEventMapper {
 
   /** Close out the turn: finalize any open assistant text block. */
   finish(): void {
+    this.sealOpenRequests();
+    this.flushOpenResults();
     this.flushAssistantText("stop");
     for (const parentCallId of this.nested.keys()) {
       this.flushNestedAssistantText(parentCallId, "stop");
@@ -273,15 +317,26 @@ export class TurnEventMapper {
       }
       case "tool-call-started": {
         this.flushNestedAssistantText(parentCallId, "tool_call");
-        this.emitToolStarted(update.callId, update.toolCall, parentCallId);
+        this.noteToolStarted(update.callId, update.toolCall, {
+          parentCallId,
+          modelCallId: modelCallIdOf(update),
+        });
         return;
       }
       case "tool-call-completed": {
-        this.emitToolCompleted(update.callId, update.toolCall, parentCallId);
+        this.noteToolCompleted(update.callId, update.toolCall, {
+          parentCallId,
+          modelCallId: modelCallIdOf(update),
+        });
         return;
       }
       case "partial-tool-call":
+        return;
       case "step-started":
+        return;
+      case "tool-requests-listed":
+        this.noteRequestsListed(parentCallId, update.callCount);
+        return;
       case "step-completed":
         return;
       default: {
@@ -290,22 +345,36 @@ export class TurnEventMapper {
     }
   }
 
-  private emitToolStarted(callId: string, toolCall: ToolCall, parentCallId?: string): void {
+  private noteToolStarted(
+    callId: string,
+    toolCall: ToolCall,
+    ids?: { parentCallId?: string; modelCallId?: string },
+  ): void {
+    const parentCallId = ids?.parentCallId;
+    const modelCallId = ids?.modelCallId;
     const description = describeToolCall(toolCall);
-    this.emit({
-      type: "actions.requested",
-      data: {
-        calls: [
-          {
-            callId,
-            toolName: description.toolName,
-            args: description.args,
-            parentCallId,
-          },
-        ],
+    const call: ActionCall = {
+      callId,
+      toolName: description.toolName,
+      args: description.args,
+      parentCallId,
+      modelCallId,
+    };
+    if (modelCallId !== undefined) {
+      this.sealOpenRequests({
         parentCallId,
-      },
-    });
+        exceptModelCallId: modelCallId,
+      });
+    }
+    const wave = this.waveForStart({ parentCallId, modelCallId, callId });
+    if (wave === undefined) {
+      return;
+    }
+    if (wave.calls.every(existing => existing.callId !== callId)) {
+      wave.calls.push(call);
+    }
+    this.adoptSingletonResults(wave, parentCallId, callId);
+    this.maybeSealListedWave(wave);
     // Subagent bookends only fire for the top-level task tool, not nested
     // tools inside a subagent (nested subagents aren't supported).
     if (description.subagent !== undefined && parentCallId === undefined) {
@@ -318,22 +387,44 @@ export class TurnEventMapper {
         },
       });
     }
+    if (wave.modelCallId === undefined) {
+      this.sealWaveRequests(wave);
+    }
   }
 
-  private emitToolCompleted(callId: string, toolCall: ToolCall, parentCallId?: string): void {
+  private noteToolCompleted(
+    callId: string,
+    toolCall: ToolCall,
+    ids?: { parentCallId?: string; modelCallId?: string },
+  ): void {
+    const parentCallId = ids?.parentCallId;
+    const modelCallId = ids?.modelCallId;
     const description = describeToolCall(toolCall);
     const result = describeToolResult(toolCall);
-    this.emit({
-      type: "action.result",
-      data: {
-        callId,
-        toolName: description.toolName,
-        output: result.output,
-        isError: result.isError,
-        ...(this.isStubbed(callId) ? { stubbed: true as const } : {}),
-        parentCallId,
-      },
-    });
+    const actionResult: ActionResult = {
+      callId,
+      toolName: description.toolName,
+      output: result.output,
+      isError: result.isError,
+      stubbed: this.isStubbed(callId) ? true : undefined,
+      parentCallId,
+      modelCallId,
+    };
+    const wave = this.waveForComplete({ parentCallId, modelCallId, callId });
+    if (wave === undefined) {
+      return;
+    }
+    const isNew = wave.results.every(existing => existing.callId !== callId);
+    if (isNew) {
+      wave.results.push(actionResult);
+    }
+    if (wave.requestedEmitted && isNew) {
+      this.emit({
+        type: "action.result",
+        data: actionResult,
+      });
+      this.maybeEmitActionsCompleted(wave);
+    }
     if (description.subagent !== undefined && parentCallId === undefined) {
       this.flushNestedAssistantText(callId, "stop");
       this.nested.delete(callId);
@@ -344,6 +435,242 @@ export class TurnEventMapper {
     }
   }
 
+  private callBelongsToWave(wave: ToolWave, callId: string): boolean {
+    return (
+      wave.calls.some(existing => existing.callId === callId) ||
+      wave.results.some(existing => existing.callId === callId)
+    );
+  }
+
+  private singletonWave(parentCallId: string | undefined, callId: string): ToolWave | undefined {
+    const key = waveKey({ parentCallId, callId });
+    if (this.sealedWaveKeys.has(key) && !this.waves.has(key)) {
+      return undefined;
+    }
+    return this.ensureWave(key, { parentCallId });
+  }
+
+  /**
+   * Starts join the open model-step wave until `actions.requested` seals.
+   * A later start for that same step is its own singleton pair so completed
+   * cannot list tools the matching requested envelope never had.
+   */
+  private waveForStart(ids: {
+    parentCallId?: string;
+    modelCallId?: string;
+    callId: string;
+  }): ToolWave | undefined {
+    const groupedKey = waveKey(ids);
+    const grouped = this.waves.get(groupedKey);
+    if (grouped !== undefined && !grouped.requestedEmitted) {
+      return grouped;
+    }
+    if (grouped !== undefined && this.callBelongsToWave(grouped, ids.callId)) {
+      return grouped;
+    }
+    if (grouped !== undefined && grouped.requestedEmitted) {
+      return this.singletonWave(ids.parentCallId, ids.callId);
+    }
+    if (this.sealedWaveKeys.has(groupedKey)) {
+      return this.singletonWave(ids.parentCallId, ids.callId);
+    }
+    return this.ensureWave(groupedKey, {
+      modelCallId: ids.modelCallId,
+      parentCallId: ids.parentCallId,
+    });
+  }
+
+  /**
+   * Completes join a model-step wave only when that call already started
+   * there. A start-less complete on an open sibling batch would flush with
+   * `actions.requested` and then block `actions.completed` forever.
+   */
+  private waveForComplete(ids: {
+    parentCallId?: string;
+    modelCallId?: string;
+    callId: string;
+  }): ToolWave | undefined {
+    const groupedKey = waveKey(ids);
+    const grouped = this.waves.get(groupedKey);
+    if (grouped !== undefined && this.callBelongsToWave(grouped, ids.callId)) {
+      return grouped;
+    }
+    if (grouped !== undefined) {
+      return this.singletonWave(ids.parentCallId, ids.callId);
+    }
+    if (this.sealedWaveKeys.has(groupedKey)) {
+      return this.waves.get(waveKey({ parentCallId: ids.parentCallId, callId: ids.callId }));
+    }
+    return this.ensureWave(groupedKey, {
+      modelCallId: ids.modelCallId,
+      parentCallId: ids.parentCallId,
+    });
+  }
+
+  private adoptSingletonResults(
+    wave: ToolWave,
+    parentCallId: string | undefined,
+    callId: string,
+  ): void {
+    const singletonKey = waveKey({ parentCallId, callId });
+    if (singletonKey === wave.key) {
+      return;
+    }
+    const singleton = this.waves.get(singletonKey);
+    if (singleton === undefined) {
+      return;
+    }
+    for (const result of singleton.results) {
+      if (wave.results.every(existing => existing.callId !== result.callId)) {
+        wave.results.push(result);
+      }
+    }
+    this.waves.delete(singletonKey);
+  }
+
+  private ensureWave(key: string, ids: { modelCallId?: string; parentCallId?: string }): ToolWave {
+    let wave = this.waves.get(key);
+    if (wave === undefined) {
+      const expectedCalls = this.listedCounts.get(ids.parentCallId ?? "");
+      wave = {
+        key,
+        modelCallId: ids.modelCallId,
+        parentCallId: ids.parentCallId,
+        expectedCalls,
+        calls: [],
+        results: [],
+        requestedEmitted: false,
+        completedEmitted: false,
+      };
+      this.waves.set(key, wave);
+    }
+    return wave;
+  }
+
+  private noteRequestsListed(parentCallId: string | undefined, callCount: number): void {
+    const listed = Math.max(0, callCount);
+    if (listed === 0) {
+      this.sealOpenRequests({ parentCallId });
+      this.listedCounts.delete(parentCallId ?? "");
+      return;
+    }
+    this.listedCounts.set(parentCallId ?? "", listed);
+    for (const wave of this.waves.values()) {
+      if (wave.parentCallId !== parentCallId || wave.requestedEmitted) {
+        continue;
+      }
+      wave.expectedCalls = listed;
+      this.maybeSealListedWave(wave);
+    }
+  }
+
+  private maybeSealListedWave(wave: ToolWave): void {
+    const expected = wave.expectedCalls ?? this.listedCounts.get(wave.parentCallId ?? "");
+    if (expected !== undefined && wave.calls.length >= expected) {
+      this.sealWaveRequests(wave);
+    }
+  }
+
+  private sealOpenRequests(ids?: { parentCallId?: string; exceptModelCallId?: string }): void {
+    const parentCallId = ids?.parentCallId;
+    const exceptModelCallId = ids?.exceptModelCallId;
+    for (const wave of this.waves.values()) {
+      if (wave.parentCallId !== parentCallId) {
+        continue;
+      }
+      if (exceptModelCallId !== undefined && wave.modelCallId === exceptModelCallId) {
+        continue;
+      }
+      this.sealWaveRequests(wave);
+    }
+  }
+
+  private sealWaveRequests(wave: ToolWave): void {
+    if (wave.requestedEmitted || wave.calls.length === 0) {
+      return;
+    }
+    wave.requestedEmitted = true;
+    this.listedCounts.delete(wave.parentCallId ?? "");
+    this.emit({
+      type: "actions.requested",
+      data: {
+        calls: wave.calls,
+        parentCallId: wave.parentCallId,
+        modelCallId: wave.modelCallId,
+      },
+    });
+    for (const result of wave.results) {
+      this.emit({
+        type: "action.result",
+        data: result,
+      });
+    }
+    this.maybeEmitActionsCompleted(wave);
+  }
+
+  private maybeEmitActionsCompleted(wave: ToolWave): void {
+    if (
+      wave.completedEmitted ||
+      !wave.requestedEmitted ||
+      wave.calls.length === 0 ||
+      wave.results.length < wave.calls.length
+    ) {
+      return;
+    }
+    const callIds = new Set(wave.calls.map(call => call.callId));
+    if (!wave.results.every(result => callIds.has(result.callId))) {
+      return;
+    }
+    if (!wave.calls.every(call => wave.results.some(result => result.callId === call.callId))) {
+      return;
+    }
+    this.emitActionsCompleted(wave);
+  }
+
+  private emitActionsCompleted(wave: ToolWave): void {
+    wave.completedEmitted = true;
+    this.emit({
+      type: "actions.completed",
+      data: {
+        results: wave.results,
+        parentCallId: wave.parentCallId,
+        modelCallId: wave.modelCallId,
+      },
+    });
+    this.forgetWave(wave);
+  }
+
+  private forgetWave(wave: ToolWave): void {
+    this.waves.delete(wave.key);
+    this.sealedWaveKeys.add(wave.key);
+    for (const callId of new Set([
+      ...wave.calls.map(call => call.callId),
+      ...wave.results.map(result => result.callId),
+    ])) {
+      this.sealedWaveKeys.add(waveKey({ parentCallId: wave.parentCallId, callId }));
+    }
+    wave.calls = [];
+    wave.results = [];
+  }
+
+  private flushOpenResults(): void {
+    for (const wave of [...this.waves.values()]) {
+      if (wave.calls.length === 0 && wave.results.length > 0) {
+        wave.calls = wave.results.map(result => ({
+          callId: result.callId,
+          toolName: result.toolName,
+          parentCallId: result.parentCallId,
+          modelCallId: result.modelCallId,
+        }));
+      }
+      this.sealWaveRequests(wave);
+      this.maybeEmitActionsCompleted(wave);
+      if (!wave.completedEmitted) {
+        this.forgetWave(wave);
+      }
+    }
+  }
+
   private ensureNested(parentCallId: string): NestedAccumulators {
     let acc = this.nested.get(parentCallId);
     if (acc === undefined) {
@@ -415,10 +742,10 @@ export function describeToolCall(toolCall: ToolCall): ToolCallDescription {
         toolName: "task",
         args: {
           description: toolCall.args.description,
-          ...(subagentName === undefined ? {} : { subagentType: subagentName }),
+          subagentType: subagentName,
         },
         subagent: {
-          ...(subagentName === undefined ? {} : { name: subagentName }),
+          name: subagentName,
           description: toolCall.args.description,
         },
       };
@@ -462,6 +789,10 @@ export function describeToolResult(toolCall: ToolCall): ToolResultDescription {
   return { output: result.value, isError: false };
 }
 
+function waveKey(ids: { parentCallId?: string; modelCallId?: string; callId: string }): string {
+  return `${ids.parentCallId ?? ""}:${ids.modelCallId ?? `call:${ids.callId}`}`;
+}
+
 function addUsage(total: TurnUsage | undefined, usage: TurnUsage): TurnUsage {
   if (total === undefined) {
     return { ...usage };

package/src/internal/hosted-delivery.ts

@@ -615,7 +615,7 @@ export function registerHostedDeliveryRoute(input: {
     }
   };
 
-  // Hosted callers reach this only through AnyRun's signed pod-port URL.
+  // Hosted callers reach this only through Anyrun's signed pod-port URL.
   // The marker is a second, route-specific fence distinct from channel auth.
   const auth: AuthPolicy = request => {
     if (request.headers.get(HOSTED_DELIVERY_HEADER) !== "1") {