@cursor/july 0.1.102 → 0.1.104

package/src/internal/guest-network.ts

@@ -0,0 +1,389 @@
+/**
+ * Guest egress readiness for hosted v2.
+ *
+ * `waitForEngineReady` only polls July `/v1/health` (process listening). After
+ * a freeze restore the guest network (DNS, egress programming, dead sockets)
+ * often comes up later. Authored admission/execution that `fetch`es in that
+ * window throws undici `TypeError: fetch failed`, which used to become a
+ * redacted HTTP 500 `internal_error` and a minutes-long Temporal retry.
+ *
+ * TAS waits on GET `/v1/guest-network` (90s, Sand's resume bar) before
+ * opening the hosted POST. The in-POST wait stays a short last-line check
+ * so leftover races still return 503 `guest_network_unavailable` instead of
+ * a redacted 500.
+ *
+ * Quiet guest Connect (`TypeError: fetch failed` with no errno, Connect
+ * `[unknown]`/`[canceled]`/`[unavailable]`, headers/body timeout) is a
+ * stall, not a dead NIC. Those become `guest_connect_stalled` so TAS
+ * retries the same pod — including when `waitForCompletion` resolves
+ * with that message instead of throwing.
+ */
+
+export const GUEST_NETWORK_UNAVAILABLE = "guest_network_unavailable";
+export const GUEST_CONNECT_STALLED = "guest_connect_stalled";
+
+/** Control-plane readiness probe. Auth none, same as `/v1/health`. */
+export const GUEST_NETWORK_PATH = "/v1/guest-network";
+
+/**
+ * Sand `READY_TIMEOUT_MS` / resume reachability bar. The in-POST wait stays
+ * at {@link DEFAULT_WAIT_TIMEOUT_MS}; this budget is for GET `/v1/guest-network`
+ * so TAS does not open a hosted turn on a dead NIC.
+ */
+export const GUEST_NETWORK_READY_WAIT_TIMEOUT_MS = 90_000;
+
+/**
+ * Node/undici codes that mean the request never produced an HTTP response.
+ * `ENOTFOUND`/`EAI_AGAIN` cover restored-pod DNS races.
+ */
+const TRANSIENT_NETWORK_ERROR_CODES: ReadonlySet<string> = new Set([
+  "ECONNREFUSED",
+  "ECONNRESET",
+  "EAI_AGAIN",
+  "EHOSTUNREACH",
+  "ENETDOWN",
+  "ENETUNREACH",
+  "ENOTFOUND",
+  "EPIPE",
+  "ETIMEDOUT",
+  "UND_ERR_CONNECT_TIMEOUT",
+  "UND_ERR_SOCKET",
+  "UND_ERR_CLOSED",
+]);
+
+const MAX_CAUSE_DEPTH = 8;
+
+export class GuestNetworkUnavailableError extends Error {
+  readonly code: typeof GUEST_NETWORK_UNAVAILABLE = GUEST_NETWORK_UNAVAILABLE;
+  readonly waitMs: number;
+  readonly probeAttempts: number;
+
+  constructor(
+    message = "Guest network is not ready for outbound requests.",
+    extras: { waitMs?: number; probeAttempts?: number } = {}
+  ) {
+    super(message);
+    this.name = "GuestNetworkUnavailableError";
+    this.waitMs = extras.waitMs ?? 0;
+    this.probeAttempts = extras.probeAttempts ?? 0;
+  }
+}
+
+/**
+ * True when the error (or anything on its `cause` chain, or inside an
+ * `AggregateError`) is a network-level fetch failure. Connect-web wraps
+ * undici's `TypeError: fetch failed` as `ConnectError` and keeps the
+ * original on `cause`.
+ */
+export function isTransientGuestNetworkError(error: unknown): boolean {
+  return isTransientAtDepth(error, 0);
+}
+
+/**
+ * Connect/undici codes that mean the socket was up but the RPC went quiet
+ * (headers never arrived, body stalled, caller aborted). Not a DNS/egress
+ * miss — those live in the network errno set.
+ */
+const QUIET_CONNECT_ERROR_CODES: ReadonlySet<string> = new Set([
+  "ABORT_ERR",
+  "UND_ERR_BODY_TIMEOUT",
+  "UND_ERR_HEADERS_TIMEOUT",
+]);
+
+const QUIET_CONNECT_MESSAGE =
+  /^(?:\[(?:unknown|canceled|unavailable)\])|connection stalled|this operation was aborted/i;
+
+export function hasGuestNetworkErrno(error: unknown): boolean {
+  return hasCodeAtDepth(error, 0, TRANSIENT_NETWORK_ERROR_CODES);
+}
+
+/**
+ * Quiet guest Connect: the request left the guest but never produced a
+ * useful RPC outcome. Distinct from {@link isTransientGuestNetworkError}
+ * so the in-POST wait still retries bare `fetch failed`, while the HTTP
+ * mapper can return `guest_connect_stalled` instead of a mystery 503.
+ */
+export function isQuietGuestConnectStall(error: unknown): boolean {
+  if (error instanceof GuestNetworkUnavailableError) {
+    return false;
+  }
+  if (hasGuestNetworkErrno(error)) {
+    return false;
+  }
+  return isQuietSignatureAtDepth(error, 0);
+}
+
+/** Message-only form for `waitForCompletion` outcomes that do not throw. */
+export function isQuietGuestConnectStallMessage(message: string): boolean {
+  return QUIET_CONNECT_MESSAGE.test(message);
+}
+
+function errorCode(error: Error): string | undefined {
+  const code = (error as NodeJS.ErrnoException).code;
+  return typeof code === "string" && code.length > 0 ? code : undefined;
+}
+
+function hasCodeAtDepth(
+  error: unknown,
+  depth: number,
+  codes: ReadonlySet<string>
+): boolean {
+  if (depth >= MAX_CAUSE_DEPTH || !(error instanceof Error)) {
+    return false;
+  }
+  const code = errorCode(error);
+  if (code !== undefined && codes.has(code)) {
+    return true;
+  }
+  if (
+    error instanceof AggregateError &&
+    error.errors.some((inner) => hasCodeAtDepth(inner, depth + 1, codes))
+  ) {
+    return true;
+  }
+  return hasCodeAtDepth(error.cause, depth + 1, codes);
+}
+
+function isQuietSignatureAtDepth(error: unknown, depth: number): boolean {
+  if (depth >= MAX_CAUSE_DEPTH || !(error instanceof Error)) {
+    return false;
+  }
+  if (error instanceof TypeError && error.message === "fetch failed") {
+    return true;
+  }
+  const code = errorCode(error);
+  if (code !== undefined && QUIET_CONNECT_ERROR_CODES.has(code)) {
+    return true;
+  }
+  if (QUIET_CONNECT_MESSAGE.test(error.message)) {
+    return true;
+  }
+  if (
+    error instanceof AggregateError &&
+    error.errors.some((inner) => isQuietSignatureAtDepth(inner, depth + 1))
+  ) {
+    return true;
+  }
+  return isQuietSignatureAtDepth(error.cause, depth + 1);
+}
+
+function isTransientAtDepth(error: unknown, depth: number): boolean {
+  if (depth >= MAX_CAUSE_DEPTH || !(error instanceof Error)) {
+    return false;
+  }
+  if (error instanceof TypeError && error.message === "fetch failed") {
+    return true;
+  }
+  if (error instanceof GuestNetworkUnavailableError) {
+    return true;
+  }
+  const code = errorCode(error);
+  if (
+    code !== undefined &&
+    (TRANSIENT_NETWORK_ERROR_CODES.has(code) ||
+      QUIET_CONNECT_ERROR_CODES.has(code))
+  ) {
+    return true;
+  }
+  if (
+    error instanceof AggregateError &&
+    error.errors.some((inner) => isTransientAtDepth(inner, depth + 1))
+  ) {
+    return true;
+  }
+  return isTransientAtDepth(error.cause, depth + 1);
+}
+
+const DEFAULT_PROBE_TIMEOUT_MS = 2_000;
+/** Last-line wait inside an already-open hosted POST. */
+export const DEFAULT_WAIT_TIMEOUT_MS = 8_000;
+const DEFAULT_POLL_MS = 250;
+
+export type GuestNetworkWaitOptions = {
+  /**
+   * When omitted, wait is enabled only on hosted engines (probe URL set and
+   * not running under Vitest). Tests pass `true` plus a mock `probe`.
+   */
+  enabled?: boolean;
+  /** Override the allowlisted probe URL. */
+  probeUrl?: string;
+  waitTimeoutMs?: number;
+  pollMs?: number;
+  probeTimeoutMs?: number;
+  probe?: () => Promise<void>;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+};
+
+function defaultSleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+function resolveProbeUrl(explicit?: string): string | undefined {
+  const raw =
+    explicit ??
+    process.env.AGENT_SERVE_EGRESS_PROBE_URL ??
+    process.env.AGENT_SERVE_CURSOR_BACKEND_URL;
+  const trimmed = raw?.trim() ?? "";
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+function waitEnabled(options: GuestNetworkWaitOptions): boolean {
+  if (options.enabled !== undefined) {
+    return options.enabled;
+  }
+  if (process.env.VITEST === "true") {
+    return false;
+  }
+  if (process.env.AGENT_SERVE_SKIP_GUEST_NETWORK_WAIT === "1") {
+    return false;
+  }
+  return resolveProbeUrl(options.probeUrl) !== undefined;
+}
+
+async function defaultProbe(
+  probeUrl: string,
+  probeTimeoutMs: number
+): Promise<void> {
+  // Any HTTP response means egress and DNS work. 401/404 are ready.
+  const response = await fetch(probeUrl, {
+    method: "GET",
+    redirect: "manual",
+    signal: AbortSignal.timeout(probeTimeoutMs),
+  });
+  void response.body?.cancel();
+}
+
+export type GuestNetworkWaitOutcome = "ready" | "skipped" | "unavailable";
+
+export type GuestNetworkWaitResult = {
+  outcome: Exclude<GuestNetworkWaitOutcome, "unavailable">;
+  waitMs: number;
+  probeAttempts: number;
+};
+
+export type GuestNetworkWaitStats = {
+  outcome: GuestNetworkWaitOutcome;
+  waitMs: number;
+  probeAttempts: number;
+};
+
+/**
+ * `Server-Timing` metric the control plane scrapes for Datadog
+ * `hosted_*.guest_network_wait_ms`. Any HTTP response (ok or 503) can
+ * carry it so restore time-to-egress is visible on both paths.
+ */
+export function formatGuestNetworkServerTiming(
+  stats: GuestNetworkWaitStats
+): string {
+  return `guest_net;desc="${stats.outcome}";dur=${Math.max(0, stats.waitMs).toFixed(1)};probes=${String(stats.probeAttempts)}`;
+}
+
+/**
+ * Poll until a cheap allowlisted GET succeeds or the wait budget expires.
+ * Throws {@link GuestNetworkUnavailableError} on timeout so hosted routes
+ * can return 503 without running authored code.
+ */
+export async function waitForGuestNetworkReady(
+  options: GuestNetworkWaitOptions = {}
+): Promise<GuestNetworkWaitResult> {
+  if (!waitEnabled(options)) {
+    return { outcome: "skipped", waitMs: 0, probeAttempts: 0 };
+  }
+  const probeUrl = resolveProbeUrl(options.probeUrl);
+  const probe =
+    options.probe ??
+    (probeUrl === undefined
+      ? undefined
+      : () =>
+          defaultProbe(
+            probeUrl,
+            options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS
+          ));
+  if (probe === undefined) {
+    return { outcome: "skipped", waitMs: 0, probeAttempts: 0 };
+  }
+  const waitTimeoutMs = options.waitTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
+  const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? defaultSleep;
+  const startedAt = now();
+  let lastError: unknown;
+  let probeAttempts = 0;
+  for (;;) {
+    probeAttempts += 1;
+    try {
+      await probe();
+      return {
+        outcome: "ready",
+        waitMs: Math.max(0, now() - startedAt),
+        probeAttempts,
+      };
+    } catch (error) {
+      lastError = error;
+      if (!isTransientGuestNetworkError(error)) {
+        throw error;
+      }
+    }
+    const elapsedMs = now() - startedAt;
+    if (elapsedMs >= waitTimeoutMs) {
+      const detail =
+        lastError instanceof Error ? lastError.message : String(lastError);
+      throw new GuestNetworkUnavailableError(
+        `Guest network did not become ready within ${String(waitTimeoutMs)}ms (${detail}).`,
+        { waitMs: Math.max(0, elapsedMs), probeAttempts }
+      );
+    }
+    await sleep(pollMs);
+  }
+}
+
+/**
+ * GET `/v1/guest-network`: wait up to
+ * {@link GUEST_NETWORK_READY_WAIT_TIMEOUT_MS} and return 200 (ready/skipped)
+ * or 503 `guest_network_unavailable`. Server-Timing matches the hosted POST
+ * so TAS can scrape the same `guest_net` metric before `postHosted`.
+ */
+export async function guestNetworkReadinessResponse(
+  options: GuestNetworkWaitOptions = {}
+): Promise<Response> {
+  try {
+    const result = await waitForGuestNetworkReady({
+      waitTimeoutMs: GUEST_NETWORK_READY_WAIT_TIMEOUT_MS,
+      ...options,
+    });
+    return new Response(JSON.stringify({ ok: true, ...result }), {
+      status: 200,
+      headers: {
+        "content-type": "application/json; charset=utf-8",
+        "server-timing": formatGuestNetworkServerTiming(result),
+      },
+    });
+  } catch (error) {
+    if (!(error instanceof GuestNetworkUnavailableError)) {
+      throw error;
+    }
+    return new Response(
+      JSON.stringify({
+        ok: false,
+        error: GUEST_NETWORK_UNAVAILABLE,
+        message: error.message,
+        waitMs: error.waitMs,
+        probeAttempts: error.probeAttempts,
+      }),
+      {
+        status: 503,
+        headers: {
+          "content-type": "application/json; charset=utf-8",
+          "server-timing": formatGuestNetworkServerTiming({
+            outcome: "unavailable",
+            waitMs: error.waitMs,
+            probeAttempts: error.probeAttempts,
+          }),
+        },
+      }
+    );
+  }
+}

package/src/internal/host-otel.ts

@@ -2,9 +2,9 @@
  * Author-facing OpenTelemetry surface for {@link HostContext.otel}.
  *
  * Always present on `ctx.host`. Counters and histograms no-op when no meter
- * is running. `setAttributes` still tags the open session when a collector
- * is attached. `forSession` is engine-only so a tool cannot retarget another
- * conversation's tags.
+ * is running. `setAttributes` still tags open turn/tool spans when a
+ * collector is attached. `forSession` is engine-only so a tool cannot
+ * retarget another conversation's tags.
  */
 
 import type { Counter, Histogram, Meter } from "@opentelemetry/api";
@@ -27,6 +27,7 @@ const RESERVED_METRICS = new Set([
 
 const RESERVED_ATTRIBUTES = new Set([
   "cursor.conversation.id",
+  "agent_sdk.session_id",
   "agent_sdk.agent",
   "agent_sdk.turn_id",
   "agent_sdk.framework",
@@ -157,7 +158,10 @@ function emitAttributes(
     "agent_sdk.agent": state.shared.agentName,
     ...(state.sessionId === undefined
       ? {}
-      : { "cursor.conversation.id": state.sessionId }),
+      : {
+          "cursor.conversation.id": state.sessionId,
+          "agent_sdk.session_id": state.sessionId,
+        }),
   });
 }
 

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

@@ -4,17 +4,18 @@ import type { ChannelHandlerArgs } from "../types.js";
  * Hosted-admission hook a channel pack attaches to its definition.
  *
  * Hosted delivery looks this up from the mounted definition — it does not
- * switch on `channelKind`. A new forge implements `dispatch` / `getOutcome`
- * next to its webhook handler and calls {@link attachHostedAdmissionAdapter}
- * from the channel constructor.
+ * switch on `channelKind`. A new forge implements `dispatch` next to its
+ * webhook handler and calls {@link attachHostedAdmissionAdapter} from the
+ * channel constructor. Every 2xx from `dispatch` must carry a tag from
+ * `internal/channel-dispatch`; an untagged one is answered with 502
+ * `channel_outcome_missing`.
  */
-export type HostedAdmissionDispatchOutcome = "skip" | "task";
-
 export type HostedAdmissionAdapter = {
   kind: string;
   /**
-   * Optional wrap of the capturing `send` / `waitUntil` args (GitHub uses
-   * this to propagate background-task errors). Identity when omitted.
+   * Optional wrap of the capturing `send` / `waitUntil` args (the PR
+   * channels use this to propagate background-task errors). Identity when
+   * omitted.
    */
   prepareArgs?(args: ChannelHandlerArgs): ChannelHandlerArgs;
   dispatch(input: {
@@ -23,7 +24,6 @@ export type HostedAdmissionAdapter = {
     deliveryId: string;
     args: ChannelHandlerArgs;
   }): Promise<Response>;
-  getOutcome(response: Response): HostedAdmissionDispatchOutcome | undefined;
 };
 
 const adapters = new WeakMap<object, HostedAdmissionAdapter>();

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

@@ -13,6 +13,12 @@ export const HOSTED_EXECUTION_DIAG_FILENAME = "hosted-execution.json";
 export type HostedAdmissionManagedAutomation = {
   automationUuid: string;
   mcpServerNames: string[];
+  /**
+   * Slack channel ids the automation's "Send to Slack" action targets,
+   * posted through the control-plane Slack relay. Omitted when the action
+   * is toggled off (never empty).
+   */
+  slackChannels?: string[];
 };
 
 export type HostedAdmission = {
@@ -59,9 +65,15 @@ const DELIVERY_KEYS = new Set([
   "payload",
   "managedAutomation",
 ]);
-const MANAGED_AUTOMATION_KEYS = new Set(["automationUuid", "mcpServerNames"]);
+const MANAGED_AUTOMATION_KEYS = new Set([
+  "automationUuid",
+  "mcpServerNames",
+  "slackChannels",
+]);
 /** 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"]);
 
 function boundedString(value: unknown, max: number): value is string {
@@ -92,10 +104,23 @@ function parseManagedAutomation(
   ) {
     return undefined;
   }
+  if (body.slackChannels !== undefined) {
+    if (
+      !Array.isArray(body.slackChannels) ||
+      body.slackChannels.length === 0 ||
+      body.slackChannels.length > MANAGED_AUTOMATION_MAX_SLACK_CHANNELS ||
+      !body.slackChannels.every((channel) => boundedString(channel, 64))
+    ) {
+      return undefined;
+    }
+  }
   return {
     managedAutomation: {
       automationUuid: body.automationUuid,
       mcpServerNames: body.mcpServerNames,
+      ...(body.slackChannels === undefined
+        ? {}
+        : { slackChannels: body.slackChannels as string[] }),
     },
   };
 }