@cursor/july 0.1.107 → 0.1.108

package/src/internal/guest-network.ts

@@ -12,11 +12,9 @@
  * 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.
+ * Quiet guest Connect failures with a typed Connect/undici code are stalls,
+ * not dead NICs. Those become `guest_connect_stalled` so TAS retries the same
+ * pod. Untyped errors stay unknown rather than being classified from prose.
  */
 
 import { HOSTED_GUEST_RETRY_TRANSIENT } from "./hosted-delivery-protocol.js";
@@ -71,11 +69,16 @@ export class GuestNetworkUnavailableError extends Error {
   }
 }
 
+class GuestNetworkProbeFailedError extends Error {
+  constructor(cause: unknown) {
+    super("Guest network probe failed", { cause });
+    this.name = "GuestNetworkProbeFailedError";
+  }
+}
+
 /**
  * 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`.
+ * `AggregateError`) carries a known network-level code.
  */
 export function isTransientGuestNetworkError(error: unknown): boolean {
   return isTransientAtDepth(error, 0);
@@ -91,9 +94,8 @@ const QUIET_CONNECT_ERROR_CODES: ReadonlySet<string> = new Set([
   "UND_ERR_BODY_TIMEOUT",
   "UND_ERR_HEADERS_TIMEOUT",
 ]);
-
-const QUIET_CONNECT_MESSAGE =
-  /^(?:\[(?:unknown|canceled|unavailable)\])|connection stalled|this operation was aborted/i;
+// gRPC Canceled, Unknown, and Unavailable.
+const QUIET_CONNECT_CODES: ReadonlySet<number> = new Set([1, 2, 14]);
 
 export function hasGuestNetworkErrno(error: unknown): boolean {
   return hasCodeAtDepth(error, 0, TRANSIENT_NETWORK_ERROR_CODES);
@@ -115,16 +117,16 @@ export function isQuietGuestConnectStall(error: unknown): boolean {
   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 numericErrorCode(error: Error): number | undefined {
+  const code = (error as { code?: unknown }).code;
+  return typeof code === "number" ? code : undefined;
+}
+
 function hasCodeAtDepth(
   error: unknown,
   depth: number,
@@ -150,14 +152,15 @@ 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") {
+  if (error.name === "AbortError") {
     return true;
   }
-  const code = errorCode(error);
-  if (code !== undefined && QUIET_CONNECT_ERROR_CODES.has(code)) {
+  const numericCode = numericErrorCode(error);
+  if (numericCode !== undefined && QUIET_CONNECT_CODES.has(numericCode)) {
     return true;
   }
-  if (QUIET_CONNECT_MESSAGE.test(error.message)) {
+  const code = errorCode(error);
+  if (code !== undefined && QUIET_CONNECT_ERROR_CODES.has(code)) {
     return true;
   }
   if (
@@ -173,10 +176,17 @@ 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") {
+  if (error instanceof GuestNetworkUnavailableError) {
     return true;
   }
-  if (error instanceof GuestNetworkUnavailableError) {
+  if (error instanceof GuestNetworkProbeFailedError) {
+    return true;
+  }
+  if (error.name === "AbortError") {
+    return true;
+  }
+  const numericCode = numericErrorCode(error);
+  if (numericCode !== undefined && QUIET_CONNECT_CODES.has(numericCode)) {
     return true;
   }
   const code = errorCode(error);
@@ -249,13 +259,17 @@ 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();
+  try {
+    // 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();
+  } catch (error) {
+    throw new GuestNetworkProbeFailedError(error);
+  }
 }
 
 export type GuestNetworkWaitOutcome = "ready" | "skipped" | "unavailable";

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

@@ -19,6 +19,8 @@ export type HostedAdmissionAdapter = {
    */
   prepareArgs?(args: ChannelHandlerArgs): ChannelHandlerArgs;
   dispatch(input: {
+    /** Mounted channel id the delivery addressed (always set by hosted delivery). */
+    channelId?: string;
     eventType: string;
     payload: unknown;
     deliveryId: string;

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

@@ -0,0 +1,130 @@
+/**
+ * Catch ingress wire contract, July copy. The control plane keeps a
+ * byte-identical copy of these constants in
+ * `backend/packages/server-shared/src/agentServe/agentSdkCatch.ts`; a
+ * backend drift test compares the two as text. Neither package imports the
+ * other.
+ *
+ * A caught request is one hosted admission whose `eventType` is
+ * {@link AGENT_SDK_CATCH_EVENT_TYPE} and whose `payload` is a
+ * {@link CatchRequestEnvelope}: the HTTP request the control plane
+ * accepted on a manifest-declared route after verifying the deployment's
+ * secret. July replays it into the authored route handler; the control
+ * plane never runs channel code.
+ */
+
+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";
+export const AGENT_SDK_SESSION_EVENT_TYPE = "agentsdk.session";
+export const AGENT_SDK_HTTP_CHANNEL_ID = "http";
+export const AGENT_SDK_HTTP_CHANNEL_KIND = "http";
+export const AGENT_SDK_SESSION_RESUME_KEY_PREFIX = "cont:session:";
+export const AGENT_SDK_CATCH_MAX_BODY_BYTES: number = 256 * 1024;
+
+export const AGENT_SDK_CATCH_ROUTE_METHODS = [
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+] as const;
+export type CatchRouteMethod = (typeof AGENT_SDK_CATCH_ROUTE_METHODS)[number];
+
+export type CatchRequestEnvelope = {
+  v: 1;
+  method: CatchRouteMethod;
+  /** Channel-relative path, e.g. `/webhook`. */
+  path: string;
+  /** Raw query string without the leading `?`; empty when absent. */
+  query: string;
+  /** Lowercased header names. */
+  headers: Record<string, string>;
+  body: { encoding: "utf8" | "base64"; data: string } | null;
+  receivedAt: string;
+};
+
+/**
+ * Mailbox key the control plane stamps on an explicit `ses_…` resume. The
+ * suffix is the CP session id the hosted execution also names, so the
+ * engine can recognise the key as "this existing session" rather than a
+ * new continuation identity.
+ */
+export function hostedSessionResumeKey(sessionPublicId: string): string {
+  return `${AGENT_SDK_SESSION_RESUME_KEY_PREFIX}${sessionPublicId}`;
+}
+
+const ENVELOPE_KEYS = new Set([
+  "v",
+  "method",
+  "path",
+  "query",
+  "headers",
+  "body",
+  "receivedAt",
+]);
+const METHODS = new Set<string>(AGENT_SDK_CATCH_ROUTE_METHODS);
+const MAX_PATH_CHARS = 1024;
+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
+): CatchRequestEnvelope | undefined {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  if (
+    Object.keys(value).some((key) => !ENVELOPE_KEYS.has(key)) ||
+    value.v !== AGENT_SDK_CATCH_ENVELOPE_VERSION ||
+    typeof value.method !== "string" ||
+    !METHODS.has(value.method) ||
+    typeof value.path !== "string" ||
+    !value.path.startsWith("/") ||
+    value.path.length > MAX_PATH_CHARS ||
+    typeof value.query !== "string" ||
+    value.query.length > MAX_QUERY_CHARS ||
+    typeof value.receivedAt !== "string" ||
+    !isRecord(value.headers)
+  ) {
+    return undefined;
+  }
+  const entries = Object.entries(value.headers);
+  if (entries.length > MAX_HEADER_COUNT) {
+    return undefined;
+  }
+  let headerBytes = 0;
+  for (const [name, headerValue] of entries) {
+    if (typeof headerValue !== "string" || name !== name.toLowerCase()) {
+      return undefined;
+    }
+    headerBytes += name.length + headerValue.length;
+  }
+  if (headerBytes > MAX_HEADER_BYTES) {
+    return undefined;
+  }
+  if (value.body !== null) {
+    if (
+      !isRecord(value.body) ||
+      (value.body.encoding !== "utf8" && value.body.encoding !== "base64") ||
+      typeof value.body.data !== "string"
+    ) {
+      return undefined;
+    }
+  }
+  return value as CatchRequestEnvelope;
+}
+
+/** Raw request bytes from an envelope body; empty for a null body. */
+export function decodeCatchBody(body: CatchRequestEnvelope["body"]): Buffer {
+  if (body === null) {
+    return Buffer.alloc(0);
+  }
+  return Buffer.from(body.data, body.encoding);
+}

package/src/internal/hosted-catch.ts

@@ -0,0 +1,192 @@
+/**
+ * Hosted admission for caught HTTP requests.
+ *
+ * The control plane accepted a request on one of this channel's declared
+ * routes, verified the deployment's secret, and claim-checked the request
+ * as a {@link CatchRequestEnvelope}. Admission replays that request into
+ * the authored route handler exactly as the local router would have
+ * (same route table, same Zod schema gate), with the control plane as the
+ * authenticated principal. A captured `send()` becomes the pending send;
+ * a handler that answers without sending is a `skip`.
+ */
+
+import type {
+  AuthContext,
+  ChannelDefinition,
+  ChannelHandlerArgs,
+  ChannelRoute,
+} from "../types.js";
+import {
+  acknowledgeTurn,
+  dispatchOutcome,
+  skipped,
+  tagOutcome,
+} from "./channel-dispatch.js";
+import { invokeChannelRoute } from "./channel-route-dispatch.js";
+import { DeferredChannelSessionError } from "./deferred-channel-session.js";
+import { attachHostedAdmissionAdapter } from "./hosted-admission-adapter.js";
+import {
+  AGENT_SDK_CATCH_EVENT_TYPE,
+  AGENT_SDK_CUSTOM_CHANNEL_KIND,
+  type CatchRequestEnvelope,
+  decodeCatchBody,
+  parseCatchRequestEnvelope,
+} from "./hosted-catch-protocol.js";
+import { errorResponse } from "./http-channel.js";
+import { Router } from "./router.js";
+
+/** Header a replayed request carries so handlers can dedupe on delivery. */
+export const CATCH_DELIVERY_ID_HEADER = "x-agent-sdk-delivery-id";
+/** Placeholder origin for replayed requests; handlers see a well-formed URL. */
+const CATCH_REQUEST_ORIGIN = "http://agent-sdk.hosted";
+
+/**
+ * Principal for a replayed request. The deployment secret was checked by
+ * the control plane before compute existed; the channel's own auth chain
+ * does not run again in the VM.
+ */
+export const CATCH_AUTH_CONTEXT: AuthContext = {
+  authenticator: "control-plane-catch",
+  principalId: "agent-sdk:catch",
+  principalType: "runtime",
+};
+
+const BODYLESS_METHODS = new Set(["GET", "HEAD"]);
+
+export function catchRequestFromEnvelope(input: {
+  channelId: string;
+  deliveryId: string;
+  envelope: CatchRequestEnvelope;
+}): Request {
+  const { envelope } = input;
+  const url = `${CATCH_REQUEST_ORIGIN}/v1/channels/${input.channelId}${envelope.path}${
+    envelope.query === "" ? "" : `?${envelope.query}`
+  }`;
+  const headers = new Headers(envelope.headers);
+  headers.set(CATCH_DELIVERY_ID_HEADER, input.deliveryId);
+  const body = decodeCatchBody(envelope.body);
+  return new Request(url, {
+    method: envelope.method,
+    headers,
+    body:
+      body.length === 0 || BODYLESS_METHODS.has(envelope.method)
+        ? undefined
+        : new Uint8Array(body),
+  });
+}
+
+export async function replayCatchRequest(input: {
+  channelId: string;
+  deliveryId: string;
+  routes: readonly ChannelRoute[];
+  payload: unknown;
+  args: ChannelHandlerArgs;
+}): Promise<Response> {
+  const envelope = parseCatchRequestEnvelope(input.payload);
+  if (envelope === undefined) {
+    return errorResponse(
+      400,
+      "invalid_catch_envelope",
+      "Expected a supported Agent SDK catch request envelope."
+    );
+  }
+  const router = new Router();
+  for (const route of input.routes) {
+    router.add({
+      method: route.method,
+      pattern: route.path,
+      auth: "none",
+      handler: () => errorResponse(500, "unreachable", "unreachable"),
+    });
+  }
+  const matched = router.match(envelope.method, envelope.path);
+  const route = input.routes.find(
+    (candidate) =>
+      candidate.method === matched?.route.method &&
+      candidate.path === matched.route.pattern
+  );
+  if (matched === undefined || route === undefined) {
+    // The control plane routes from the same pinned manifest this VM was
+    // frozen from; a miss here is drift, not a caller error.
+    return errorResponse(
+      404,
+      "route_not_declared",
+      `No ${envelope.method} ${envelope.path} route is mounted on channel "${input.channelId}".`
+    );
+  }
+  const request = catchRequestFromEnvelope({
+    channelId: input.channelId,
+    deliveryId: input.deliveryId,
+    envelope,
+  });
+  let response: Response;
+  try {
+    response = await invokeChannelRoute({
+      route,
+      request,
+      handlerArgs: {
+        ...input.args,
+        params: matched.params,
+        auth: CATCH_AUTH_CONTEXT,
+      },
+    });
+  } catch (error) {
+    // `return Response.json({ sessionId: session.id })` after `send()` is
+    // the ordinary local webhook shape. Hosted, `send()` is captured and the
+    // handle is deferred, so reading `.id` throws — but nobody reads this
+    // handler's HTTP reply hosted; the captured send is the outcome.
+    if (error instanceof DeferredChannelSessionError) {
+      return acknowledgeTurn();
+    }
+    throw error;
+  }
+  // A 2xx the handler did not tag and in which nothing was captured means
+  // it handled the request itself (acknowledged, ignored, replied). There is
+  // nothing to execute: report skip instead of failing the delivery.
+  if (response.ok && dispatchOutcome(response) === undefined) {
+    return tagOutcome(response, "skip");
+  }
+  // A 4xx is the handler rejecting the sender (bad signature on a
+  // handler-verified `publicEndpoint()` route, schema mismatch, unknown
+  // event). The sender already has its 202; retrying the delivery cannot
+  // change the verdict, so report a cheap skip that lets the control plane
+  // discard the compute instead of failing and retrying the activity.
+  if (response.status >= 400 && response.status < 500) {
+    // Logged so a probed public route or a misconfigured provider secret is
+    // distinguishable from a benign "nothing to do" skip in the guest logs;
+    // the wire outcome to the control plane is still `skip`.
+    console.info(
+      `[agent-sdk] catch replay rejected by handler deliveryId=${input.deliveryId} channelId=${input.channelId} route=${envelope.method} ${route.path} status=${String(response.status)}`
+    );
+    return skipped(`handler rejected the request (${response.status})`, {
+      status: response.status,
+    });
+  }
+  return response;
+}
+
+/**
+ * Attach catch admission to an authored channel. Provider packs attach
+ * their own adapter afterwards and replace this one; the control plane
+ * never sends `http.request` to a pack kind in any case.
+ */
+export function attachCatchAdmission(
+  definition: ChannelDefinition<unknown>,
+  routes: readonly ChannelRoute[]
+): void {
+  attachHostedAdmissionAdapter(definition, {
+    kind: definition.meta?.kind ?? AGENT_SDK_CUSTOM_CHANNEL_KIND,
+    dispatch: ({ channelId, eventType, payload, deliveryId, args }) => {
+      if (eventType !== AGENT_SDK_CATCH_EVENT_TYPE) {
+        return Promise.resolve(skipped("not a caught http request"));
+      }
+      return replayCatchRequest({
+        channelId: channelId ?? "channel",
+        deliveryId,
+        routes,
+        payload,
+        args,
+      });
+    },
+  });
+}