@cursor/july 0.1.109 → 0.1.112

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

@@ -67,10 +67,15 @@ export function isFrameworkFileKey(key: string): boolean {
   return FRAMEWORK_FILE_KINDS.has(kind);
 }
 
-/** The KV core over a {@link FileSink}: one JSON document per key. */
+/**
+ * The KV core over a {@link FileSink}: one JSON document per key.
+ * `putMany` stays optional — the KV-proxy core has no batch write, and the
+ * composite falls back to sequential puts on a side without one.
+ */
 export type FileSinkStorageCore = Required<
   Pick<StorageConfig, "put" | "get" | "delete" | "list">
->;
+> &
+  Pick<StorageConfig, "putMany">;
 
 /** Parallel per-key reads backing `list` (each is presign + object GET). */
 const LIST_READ_CONCURRENCY = 8;
@@ -85,7 +90,7 @@ const LIST_READ_CONCURRENCY = 8;
 function isUnrepresentableFileKey(key: string): boolean {
   return key
     .split("/")
-    .some((segment) => segment === "" || segment === "." || segment === "..");
+    .some(segment => segment === "" || segment === "." || segment === "..");
 }
 
 /**
@@ -109,6 +114,63 @@ export function fileSinkStorageCore(sink: FileSink): FileSinkStorageCore {
       }
       await sink.put(key, encodeDocument(key, value));
     },
+    async putMany(entries): Promise<Array<{ key: string; error?: unknown }>> {
+      const results: Array<{ key: string; error?: unknown }> = entries.map(
+        entry => ({ key: entry.key })
+      );
+      const writable: Array<{ index: number; key: string; body: Uint8Array }> =
+        [];
+      for (let index = 0; index < entries.length; index += 1) {
+        const entry = entries[index];
+        if (entry === undefined) {
+          continue;
+        }
+        if (isUnrepresentableFileKey(entry.key)) {
+          results[index] = {
+            key: entry.key,
+            error: new Error(
+              `framework file storage: key "${entry.key}" has a path segment the store cannot represent`
+            ),
+          };
+          continue;
+        }
+        writable.push({
+          index,
+          key: entry.key,
+          body: encodeDocument(entry.key, entry.value),
+        });
+      }
+      if (writable.length === 0) {
+        return results;
+      }
+      if (sink.putMany !== undefined) {
+        // The point of the batch: one backend round trip for the flush.
+        const settled = await sink.putMany(
+          writable.map(({ key, body }) => ({ key, body }))
+        );
+        for (let i = 0; i < writable.length; i += 1) {
+          const target = writable[i];
+          const outcome = settled[i];
+          if (target === undefined) {
+            continue;
+          }
+          if (outcome?.status === "rejected") {
+            results[target.index] = { key: target.key, error: outcome.reason };
+          }
+        }
+        return results;
+      }
+      // No batch support: sequential puts, preserving the sink's strict
+      // one-at-a-time ordering contract.
+      for (const target of writable) {
+        try {
+          await sink.put(target.key, target.body);
+        } catch (error) {
+          results[target.index] = { key: target.key, error };
+        }
+      }
+      return results;
+    },
     async get(key): Promise<JsonValue | undefined> {
       if (isUnrepresentableFileKey(key)) {
         return undefined;
@@ -129,7 +191,7 @@ export function fileSinkStorageCore(sink: FileSink): FileSinkStorageCore {
       const entries = await sink.list(prefix);
       // FileSink.list returns metadata only, so each value is its own
       // read; bound the fan-out — a bulk read here sits on restore paths.
-      const bodies = await mapBounded(entries, LIST_READ_CONCURRENCY, (entry) =>
+      const bodies = await mapBounded(entries, LIST_READ_CONCURRENCY, entry =>
         sink.get(entry.key)
       );
       const out: StorageEntry[] = [];
@@ -213,6 +275,44 @@ export function composeFrameworkStorage(input: {
     isFrameworkFileKey(key) ? input.files : input.kv;
   return {
     put: (key, value, ctx) => route(key).put(key, value, ctx),
+    async putMany(entries, ctx) {
+      // Partition by destination store, batch each side, and reassemble
+      // per-entry outcomes in input order.
+      const indexed = entries.map((entry, index) => ({ entry, index }));
+      const results: Array<{ key: string; error?: unknown }> = entries.map(
+        entry => ({ key: entry.key })
+      );
+      for (const core of [input.files, input.kv]) {
+        const side = indexed.filter(({ entry }) => route(entry.key) === core);
+        if (side.length === 0) {
+          continue;
+        }
+        if (core.putMany === undefined) {
+          // No batch write on this side (the KV proxy): sequential puts,
+          // preserving the strict one-at-a-time ordering it promises.
+          for (const { entry, index } of side) {
+            try {
+              await core.put(entry.key, entry.value, ctx);
+            } catch (error) {
+              results[index] = { key: entry.key, error };
+            }
+          }
+          continue;
+        }
+        const settled = await core.putMany(
+          side.map(({ entry }) => entry),
+          ctx
+        );
+        for (let i = 0; i < side.length; i += 1) {
+          const target = side[i];
+          const outcome = settled[i];
+          if (target !== undefined && outcome !== undefined) {
+            results[target.index] = outcome;
+          }
+        }
+      }
+      return results;
+    },
     get: (key, ctx) => route(key).get(key, ctx),
     delete: (key, ctx) => route(key).delete(key, ctx),
     list: (prefix, ctx) => route(prefix).list(prefix, ctx),

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

@@ -63,13 +63,6 @@ import {
 } from "./framework-file-storage.js";
 import { resolveAgentV2Hosting } from "./v2-hosting.js";
 
-/**
- * Hosted v2 event-chunk flush debounce. Matches the session view's live poll
- * cadence; a streaming turn still caps each chunk at the coordinator's batch
- * limit, so a long turn writes a few dozen chunks rather than one per event.
- */
-export const HOSTED_V2_EVENT_FLUSH_DEBOUNCE_MS = 2_000;
-
 export interface FrameworkStorageSelectionInput {
   /** `agent/storage.ts`, when the author wrote one (v1 only: discovery rejects it on v2). */
   readonly authored: StorageDefinition | undefined;
@@ -127,13 +120,10 @@ export function selectFrameworkStorageDefinition(
   // comes up). Follow-ups restore lazily by continuation or session id;
   // GET /v1/sessions lists from the sink either way.
   //
-  // Events flush on a quiet-period debounce rather than only at turn end so
-  // the read-only session view and dashboard trace (which have no resident
-  // engine to ask) see steps mid-turn. The turn-end record still lands
-  // before the execution reply: drainSessionDurability forces the flush.
+  // Events flush at turn end. drainSessionDurability still forces the
+  // record onto the sink before the execution reply.
   const policy = {
     restore: "off",
-    debounceMs: HOSTED_V2_EVENT_FLUSH_DEBOUNCE_MS,
   } as const;
   // Full chain (env → bind file → stored login): frozen engines listen
   // unsigned and bind store ids + CURSOR_API_KEY at task time, after this

package/src/internal/github-fanout.ts

@@ -78,7 +78,7 @@ function handleFanoutRequest(
   });
   req.on("end", () => {
     void fanoutDelivery(Buffer.concat(chunks), req.headers, targets, options)
-      .then((delivered) => {
+      .then(delivered => {
         res.writeHead(200, { "content-type": "application/json" });
         res.end(JSON.stringify({ ok: true, delivered }));
       })
@@ -105,7 +105,7 @@ export async function fanoutDelivery(
   targets: readonly GitHubForwardTarget[],
   options: FanoutOptions = {}
 ): Promise<string[]> {
-  const log = options.logger ?? ((line) => process.stderr.write(line));
+  const log = options.logger ?? (line => process.stderr.write(line));
   const event =
     typeof headers["x-github-event"] === "string"
       ? headers["x-github-event"]
@@ -118,7 +118,7 @@ export async function fanoutDelivery(
     }
   }
   const recipients = targets.filter(
-    (target) => event === undefined || target.events.includes(event)
+    target => event === undefined || target.events.includes(event)
   );
   // Reuse one Uint8Array view across recipients (Buffer isn't a BodyInit).
   const payload = new Uint8Array(body);
@@ -126,7 +126,7 @@ export async function fanoutDelivery(
   // Bounded by the number of GitHub channels in the project (a handful), so
   // unbounded-concurrency concerns do not apply here.
   await Promise.all(
-    recipients.map(async (target) => {
+    recipients.map(async target => {
       const label = targetLabel(target);
       try {
         const response = await fetch(target.url, {

package/src/internal/guest-network.ts

@@ -141,7 +141,7 @@ function hasCodeAtDepth(
   }
   if (
     error instanceof AggregateError &&
-    error.errors.some((inner) => hasCodeAtDepth(inner, depth + 1, codes))
+    error.errors.some(inner => hasCodeAtDepth(inner, depth + 1, codes))
   ) {
     return true;
   }
@@ -165,7 +165,7 @@ function isQuietSignatureAtDepth(error: unknown, depth: number): boolean {
   }
   if (
     error instanceof AggregateError &&
-    error.errors.some((inner) => isQuietSignatureAtDepth(inner, depth + 1))
+    error.errors.some(inner => isQuietSignatureAtDepth(inner, depth + 1))
   ) {
     return true;
   }
@@ -199,7 +199,7 @@ function isTransientAtDepth(error: unknown, depth: number): boolean {
   }
   if (
     error instanceof AggregateError &&
-    error.errors.some((inner) => isTransientAtDepth(inner, depth + 1))
+    error.errors.some(inner => isTransientAtDepth(inner, depth + 1))
   ) {
     return true;
   }
@@ -228,7 +228,7 @@ export type GuestNetworkWaitOptions = {
 };
 
 function defaultSleep(ms: number): Promise<void> {
-  return new Promise((resolve) => {
+  return new Promise(resolve => {
     setTimeout(resolve, ms);
   });
 }

package/src/internal/host-files.ts

@@ -217,7 +217,7 @@ async function statKey(
     return await sink.stat(key);
   }
   const entries = await sink.list(key);
-  return entries.find((entry) => entry.key === key);
+  return entries.find(entry => entry.key === key);
 }
 
 // ============================================================================

package/src/internal/host-kv.ts

@@ -28,9 +28,9 @@ export function createHostKvApi(options: CreateHostKvApiOptions): HostKvApi {
   const storage = options.storage;
   if (storage?.supportsAuthorKv === true) {
     return {
-      get: (key) => storage.kvGet(normalizeAuthorKey(key)),
+      get: key => storage.kvGet(normalizeAuthorKey(key)),
       put: (key, value) => storage.kvPut(normalizeAuthorKey(key), value),
-      delete: (key) => storage.kvDelete(normalizeAuthorKey(key)),
+      delete: key => storage.kvDelete(normalizeAuthorKey(key)),
     };
   }
   return createFilesystemKvApi({

package/src/internal/hosted-admission-adapter.ts

@@ -1,4 +1,5 @@
 import type { ChannelHandlerArgs } from "../types.js";
+import type { HostedAdmissionPlatformHandoff } from "./hosted-delivery-protocol.js";
 
 /**
  * Hosted-admission hook a channel pack attaches to its definition.
@@ -25,6 +26,10 @@ export type HostedAdmissionAdapter = {
     payload: unknown;
     deliveryId: string;
     args: ChannelHandlerArgs;
+    /** Mailbox key the control plane already allocated for this admission. */
+    mailboxContinuationKey?: string;
+    /** Trusted control-plane handoff (Slack placeholder ts, …). */
+    platformHandoff?: HostedAdmissionPlatformHandoff;
   }): Promise<Response>;
 };
 

package/src/internal/hosted-catch-protocol.ts

@@ -13,6 +13,8 @@
  * plane never runs channel code.
  */
 
+import { isRecord } from "./is-record.js";
+
 export const AGENT_SDK_CATCH_ENVELOPE_VERSION = 1;
 export const AGENT_SDK_CATCH_EVENT_TYPE = "http.request";
 export const AGENT_SDK_CUSTOM_CHANNEL_KIND = "custom";
@@ -69,10 +71,6 @@ const MAX_QUERY_CHARS = 4096;
 const MAX_HEADER_COUNT = 64;
 const MAX_HEADER_BYTES = 16 * 1024;
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 /** Strict parse of a claim-checked catch envelope; anything else is undefined. */
 export function parseCatchRequestEnvelope(
   value: unknown
@@ -81,7 +79,7 @@ export function parseCatchRequestEnvelope(
     return undefined;
   }
   if (
-    Object.keys(value).some((key) => !ENVELOPE_KEYS.has(key)) ||
+    Object.keys(value).some(key => !ENVELOPE_KEYS.has(key)) ||
     value.v !== AGENT_SDK_CATCH_ENVELOPE_VERSION ||
     typeof value.method !== "string" ||
     !METHODS.has(value.method) ||

package/src/internal/hosted-catch.ts

@@ -101,7 +101,7 @@ export async function replayCatchRequest(input: {
   }
   const matched = router.match(envelope.method, envelope.path);
   const route = input.routes.find(
-    (candidate) =>
+    candidate =>
       candidate.method === matched?.route.method &&
       candidate.path === matched.route.pattern
   );

package/src/internal/hosted-delivery-protocol.ts

@@ -236,6 +236,20 @@ export type HostedAdmissionManagedAutomation = {
   slackChannels?: string[];
 };
 
+/**
+ * Trusted control-plane handoff for a Slack placeholder posted at ingress
+ * before the Temporal signal. Omitted when no placeholder was posted.
+ */
+export type HostedAdmissionPlatformHandoff = {
+  v: 1;
+  slackPlaceholder: {
+    messageTs: string;
+    channelId: string;
+    threadTs: string;
+    streamed: false;
+  };
+};
+
 export type HostedAdmission = {
   v: 2;
   channelId: string;
@@ -251,23 +265,50 @@ export type HostedAdmission = {
   mailboxContinuationKey: string;
   payload: unknown;
   managedAutomation?: HostedAdmissionManagedAutomation;
+  /** Present only when control-plane Slack fast-act posted a placeholder. */
+  platformHandoff?: HostedAdmissionPlatformHandoff;
 };
 
 export type HostedAdmissionOutcome =
   | { ok: true; v: 2; outcome: "skip" | "task" }
   | { ok: true; v: 2; outcome: "send"; admissionToken: string };
 
+/**
+ * Cap on delivery IDs an owner execute may report as consumed (primary +
+ * accepted active-guest enqueues). Enqueue requests beyond this return
+ * `not_active`.
+ */
+export const HOSTED_MAX_CONSUMED_DELIVERY_IDS = 16;
+
+/** Hosted-execution run mode. Omitted/`execute` is the legacy wait path. */
+export type HostedExecutionMode = "execute" | "enqueue";
+
 export type HostedExecution = {
   v: 2;
   admissionToken: string;
   sessionPublicId: string;
+  /**
+   * `execute` (default when omitted) runs the owner send and waits for the
+   * coalesce chain. `enqueue` injects into an accepting owner or returns
+   * `not_active`.
+   */
+  mode?: HostedExecutionMode;
 };
 
-export type HostedExecutionOutcome = {
-  ok: true;
-  v: 2;
-  outcome: "send";
-};
+export type HostedExecutionOutcome =
+  | {
+      ok: true;
+      v: 2;
+      outcome: "send";
+      /**
+       * Primary delivery id then accepted enqueue ids; length 1..16.
+       * Optional for old-guest compatibility; callers must normalize absent
+       * lists to `[primaryDeliveryId]`.
+       */
+      consumedDeliveryIds?: string[];
+    }
+  | { ok: true; v: 2; outcome: "enqueued" }
+  | { ok: true; v: 2; outcome: "not_active" };
 
 const DELIVERY_KEYS = new Set([
   "v",
@@ -279,17 +320,29 @@ const DELIVERY_KEYS = new Set([
   "mailboxContinuationKey",
   "payload",
   "managedAutomation",
+  "platformHandoff",
 ]);
 const MANAGED_AUTOMATION_KEYS = new Set([
   "automationUuid",
   "mcpServerNames",
   "slackChannels",
 ]);
+export const HOSTED_PLATFORM_HANDOFF_KEYS: ReadonlySet<string> = new Set([
+  "v",
+  "slackPlaceholder",
+]);
+export const HOSTED_SLACK_PLACEHOLDER_HANDOFF_KEYS: ReadonlySet<string> =
+  new Set(["messageTs", "channelId", "threadTs", "streamed"]);
 /** More names than any real automation configures is a malformed envelope. */
 const MANAGED_AUTOMATION_MAX_SERVERS = 64;
 /** More channels than the dashboard picker allows is a malformed envelope. */
 const MANAGED_AUTOMATION_MAX_SLACK_CHANNELS = 64;
-const EXECUTION_KEYS = new Set(["v", "admissionToken", "sessionPublicId"]);
+const EXECUTION_KEYS = new Set([
+  "v",
+  "admissionToken",
+  "sessionPublicId",
+  "mode",
+]);
 
 function boundedString(value: unknown, max: number): value is string {
   return typeof value === "string" && value.length > 0 && value.length <= max;
@@ -311,11 +364,11 @@ function parseManagedAutomation(
   }
   const body = value as Record<string, unknown>;
   if (
-    Object.keys(body).some((key) => !MANAGED_AUTOMATION_KEYS.has(key)) ||
+    Object.keys(body).some(key => !MANAGED_AUTOMATION_KEYS.has(key)) ||
     !boundedString(body.automationUuid, 128) ||
     !Array.isArray(body.mcpServerNames) ||
     body.mcpServerNames.length > MANAGED_AUTOMATION_MAX_SERVERS ||
-    !body.mcpServerNames.every((name) => boundedString(name, 256))
+    !body.mcpServerNames.every(name => boundedString(name, 256))
   ) {
     return undefined;
   }
@@ -324,7 +377,7 @@ function parseManagedAutomation(
       !Array.isArray(body.slackChannels) ||
       body.slackChannels.length === 0 ||
       body.slackChannels.length > MANAGED_AUTOMATION_MAX_SLACK_CHANNELS ||
-      !body.slackChannels.every((channel) => boundedString(channel, 64))
+      !body.slackChannels.every(channel => boundedString(channel, 64))
     ) {
       return undefined;
     }
@@ -340,6 +393,59 @@ function parseManagedAutomation(
   };
 }
 
+/**
+ * Parse optional control-plane Slack placeholder handoff. Absent → valid;
+ * present-but-malformed → invalid (fail closed like managedAutomation).
+ */
+function parsePlatformHandoff(
+  value: unknown
+): { platformHandoff?: HostedAdmissionPlatformHandoff } | undefined {
+  if (value === undefined) {
+    return {};
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const body = value as Record<string, unknown>;
+  if (
+    Object.keys(body).some(key => !HOSTED_PLATFORM_HANDOFF_KEYS.has(key)) ||
+    body.v !== 1
+  ) {
+    return undefined;
+  }
+  const placeholder = body.slackPlaceholder;
+  if (
+    typeof placeholder !== "object" ||
+    placeholder === null ||
+    Array.isArray(placeholder)
+  ) {
+    return undefined;
+  }
+  const slot = placeholder as Record<string, unknown>;
+  if (
+    Object.keys(slot).some(
+      key => !HOSTED_SLACK_PLACEHOLDER_HANDOFF_KEYS.has(key)
+    ) ||
+    !boundedString(slot.messageTs, 64) ||
+    !boundedString(slot.channelId, 64) ||
+    !boundedString(slot.threadTs, 64) ||
+    slot.streamed !== false
+  ) {
+    return undefined;
+  }
+  return {
+    platformHandoff: {
+      v: 1,
+      slackPlaceholder: {
+        messageTs: slot.messageTs,
+        channelId: slot.channelId,
+        threadTs: slot.threadTs,
+        streamed: slot.streamed,
+      },
+    },
+  };
+}
+
 export function parseHostedAdmission(
   value: unknown
 ): HostedAdmission | undefined {
@@ -348,7 +454,7 @@ export function parseHostedAdmission(
   }
   const body = value as Record<string, unknown>;
   if (
-    Object.keys(body).some((key) => !DELIVERY_KEYS.has(key)) ||
+    Object.keys(body).some(key => !DELIVERY_KEYS.has(key)) ||
     !Object.hasOwn(body, "payload") ||
     body.v !== HOSTED_DELIVERY_PROTOCOL_VERSION ||
     !boundedString(body.channelId, 128) ||
@@ -357,7 +463,8 @@ export function parseHostedAdmission(
     !boundedString(body.deliveryId, 256) ||
     (body.sessionMode !== "event" && body.sessionMode !== "continuation") ||
     !boundedString(body.mailboxContinuationKey, 512) ||
-    parseManagedAutomation(body.managedAutomation) === undefined
+    parseManagedAutomation(body.managedAutomation) === undefined ||
+    parsePlatformHandoff(body.platformHandoff) === undefined
   ) {
     return undefined;
   }
@@ -375,7 +482,7 @@ export function parseHostedExecution(
   }
   const body = value as Record<string, unknown>;
   if (
-    Object.keys(body).some((key) => !EXECUTION_KEYS.has(key)) ||
+    Object.keys(body).some(key => !EXECUTION_KEYS.has(key)) ||
     body.v !== HOSTED_DELIVERY_PROTOCOL_VERSION ||
     !boundedString(body.admissionToken, 128) ||
     typeof body.sessionPublicId !== "string" ||
@@ -383,9 +490,77 @@ export function parseHostedExecution(
   ) {
     return undefined;
   }
+  if (
+    body.mode !== undefined &&
+    body.mode !== "execute" &&
+    body.mode !== "enqueue"
+  ) {
+    return undefined;
+  }
   return body as HostedExecution;
 }
 
+const HOSTED_EXECUTION_OUTCOME_KEYS = new Set([
+  "ok",
+  "v",
+  "outcome",
+  "consumedDeliveryIds",
+]);
+
+function parseConsumedDeliveryIds(value: unknown): string[] | undefined {
+  if (!Array.isArray(value) || value.length === 0) {
+    return undefined;
+  }
+  if (value.length > HOSTED_MAX_CONSUMED_DELIVERY_IDS) {
+    return undefined;
+  }
+  if (!value.every(id => boundedString(id, 256))) {
+    return undefined;
+  }
+  return value as string[];
+}
+
+export function parseHostedExecutionOutcome(
+  value: unknown
+): HostedExecutionOutcome | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const body = value as Record<string, unknown>;
+  if (
+    Object.keys(body).some(key => !HOSTED_EXECUTION_OUTCOME_KEYS.has(key)) ||
+    body.ok !== true ||
+    body.v !== HOSTED_DELIVERY_PROTOCOL_VERSION
+  ) {
+    return undefined;
+  }
+  if (body.outcome === "enqueued" || body.outcome === "not_active") {
+    if (body.consumedDeliveryIds !== undefined) {
+      return undefined;
+    }
+    return body as HostedExecutionOutcome;
+  }
+  if (body.outcome !== "send") {
+    return undefined;
+  }
+  // Old guests omit consumedDeliveryIds; accept and let callers normalize.
+  if (body.consumedDeliveryIds === undefined) {
+    return { ok: true, v: 2, outcome: "send" };
+  }
+  const consumedDeliveryIds = parseConsumedDeliveryIds(
+    body.consumedDeliveryIds
+  );
+  if (consumedDeliveryIds === undefined) {
+    return undefined;
+  }
+  return {
+    ok: true,
+    v: 2,
+    outcome: "send",
+    consumedDeliveryIds,
+  };
+}
+
 /**
  * True when the admission envelope is the reserved internal reminder fire
  * path (not an authored channel event).
@@ -481,7 +656,7 @@ function isJsonSafeValue(value: unknown, depth: number): boolean {
     return false;
   }
   if (Array.isArray(value)) {
-    return value.every((entry) => isJsonSafeValue(entry, depth + 1));
+    return value.every(entry => isJsonSafeValue(entry, depth + 1));
   }
   const proto = Object.getPrototypeOf(value);
   if (proto !== Object.prototype && proto !== null) {
@@ -543,7 +718,7 @@ export function parseHostedReminderFireDescriptorPayload(
   const body = value as Record<string, unknown>;
   if (
     Object.keys(body).some(
-      (key) => !HOSTED_REMINDER_FIRE_DESCRIPTOR_KEYS.has(key)
+      key => !HOSTED_REMINDER_FIRE_DESCRIPTOR_KEYS.has(key)
     )
   ) {
     return undefined;