@cursor/july 0.1.107 → 0.1.109

package/dist/internal/framework-file-storage.js

@@ -21,9 +21,8 @@
  * `continuation` go to the framework file store (file-shaped; the store
  * accepts values up to 64 MiB per
  * object without chunking, versus the KV proxy's 1 MiB row cap), while
- * author `kv`, eval runs, A/B samples, and conditional writes stay on the
- * control-plane KV proxy (the dashboard reads them there, and CAS needs a
- * database).
+ * author `kv`, eval runs, and conditional writes stay on the control-plane
+ * KV proxy (the dashboard reads them there, and CAS needs a database).
  *
  * v2 only, by construction: the composite is selected in
  * framework-storage-selection.ts, which v1 never reaches with a
@@ -188,8 +187,8 @@ function decodeDocument(key, bytes) {
 /**
  * Split one storage core by key kind: framework session state to `files`,
  * everything else to `kv`. Spread over the KV backend when building the
- * full definition so its `evals` / `abs` groups (and the cursor-hosted
- * marker) ride along untouched; wrap the KV `cas` group with
+ * full definition so its `evals` group (and the cursor-hosted marker)
+ * rides along untouched; wrap the KV `cas` group with
  * {@link frameworkGuardedCas} rather than spreading it as-is.
  */
 export function composeFrameworkStorage(input) {

package/dist/internal/framework-storage-selection.d.ts

@@ -24,8 +24,8 @@
  *   (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`, bound at task time) holds
  *   session records, event transcripts, and the continuation index —
  *   file-shaped state on file storage, apart from the author-facing user
- *   store. Author `host.kv`, eval runs, A/B samples, and conditional writes
- *   ride the AgentSDK v2 KV proxy (cursor-hosted-v2.ts), which resolves the
+ *   store. Author `host.kv`, eval runs, and conditional writes ride the
+ *   AgentSDK v2 KV proxy (cursor-hosted-v2.ts), which resolves the
  *   pod service account to the factorydb deployment row (the v1 Bugbot
  *   proxy cannot resolve v2 pods at all). Framework session state never
  *   routes to the KV proxy — the composite splits by key kind — so

package/dist/internal/framework-storage-selection.js

@@ -24,8 +24,8 @@
  *   (`AGENT_SERVE_FRAMEWORK_STORE_SOURCE_ID`, bound at task time) holds
  *   session records, event transcripts, and the continuation index —
  *   file-shaped state on file storage, apart from the author-facing user
- *   store. Author `host.kv`, eval runs, A/B samples, and conditional writes
- *   ride the AgentSDK v2 KV proxy (cursor-hosted-v2.ts), which resolves the
+ *   store. Author `host.kv`, eval runs, and conditional writes ride the
+ *   AgentSDK v2 KV proxy (cursor-hosted-v2.ts), which resolves the
  *   pod service account to the factorydb deployment row (the v1 Bugbot
  *   proxy cannot resolve v2 pods at all). Framework session state never
  *   routes to the KV proxy — the composite splits by key kind — so

package/dist/internal/guest-network.d.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.
  */
 export declare const GUEST_NETWORK_UNAVAILABLE = "guest_network_unavailable";
 export declare const GUEST_CONNECT_STALLED = "guest_connect_stalled";
@@ -39,9 +37,7 @@ export declare class GuestNetworkUnavailableError extends Error {
 }
 /**
  * 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 declare function isTransientGuestNetworkError(error: unknown): boolean;
 export declare function hasGuestNetworkErrno(error: unknown): boolean;
@@ -52,8 +48,6 @@ export declare function hasGuestNetworkErrno(error: unknown): boolean;
  * mapper can return `guest_connect_stalled` instead of a mystery 503.
  */
 export declare function isQuietGuestConnectStall(error: unknown): boolean;
-/** Message-only form for `waitForCompletion` outcomes that do not throw. */
-export declare function isQuietGuestConnectStallMessage(message: string): boolean;
 /** Last-line wait inside an already-open hosted POST. */
 export declare const DEFAULT_WAIT_TIMEOUT_MS = 8000;
 export type GuestNetworkWaitOptions = {

package/dist/internal/guest-network.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guest-network.d.ts","sourceRoot":"","sources":["../../src/internal/guest-network.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AACrE,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D,sEAAsE;AACtE,eAAO,MAAM,kBAAkB,sBAAsB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,mCAAmC,QAAS,CAAC;AAuB1D,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,IAAI,EAAE,OAAO,yBAAyB,CAA6B;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,YACE,OAAO,SAAsD,EAC7D,MAAM,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAO,EAMzD;CACF;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpE;AAgBD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQhE;AAED,4EAA4E;AAC5E,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAExE;AA+ED,yDAAyD;AACzD,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAG7C,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC,CAAC;AA2CF,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,SAAS,GAAG,aAAa,CAAC;AAE1E,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,OAAO,CAAC,uBAAuB,EAAE,aAAa,CAAC,CAAC;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,qBAAqB,GAC3B,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAkDjC;AAED;;;;;GAKG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,QAAQ,CAAC,CAuCnB"}
+{"version":3,"file":"guest-network.d.ts","sourceRoot":"","sources":["../../src/internal/guest-network.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,eAAO,MAAM,yBAAyB,8BAA8B,CAAC;AACrE,eAAO,MAAM,qBAAqB,0BAA0B,CAAC;AAE7D,sEAAsE;AACtE,eAAO,MAAM,kBAAkB,sBAAsB,CAAC;AAEtD;;;;GAIG;AACH,eAAO,MAAM,mCAAmC,QAAS,CAAC;AAuB1D,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,IAAI,EAAE,OAAO,yBAAyB,CAA6B;IAC5E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,YACE,OAAO,SAAsD,EAC7D,MAAM,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,aAAa,CAAC,EAAE,MAAM,CAAA;KAAO,EAMzD;CACF;AASD;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpE;AAeD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAQhE;AA4FD,yDAAyD;AACzD,eAAO,MAAM,uBAAuB,OAAQ,CAAC;AAG7C,MAAM,MAAM,uBAAuB,GAAG;IACpC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC,CAAC;AA+CF,MAAM,MAAM,uBAAuB,GAAG,OAAO,GAAG,SAAS,GAAG,aAAa,CAAC;AAE1E,MAAM,MAAM,sBAAsB,GAAG;IACnC,OAAO,EAAE,OAAO,CAAC,uBAAuB,EAAE,aAAa,CAAC,CAAC;IACzD,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC,OAAO,EAAE,uBAAuB,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,qBAAqB,GAC3B,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,sBAAsB,CAAC,CAkDjC;AAED;;;;;GAKG;AACH,wBAAsB,6BAA6B,CACjD,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,QAAQ,CAAC,CAuCnB"}

package/dist/internal/guest-network.js

@@ -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.
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -67,11 +65,15 @@ export class GuestNetworkUnavailableError extends Error {
         this.probeAttempts = (_b = extras.probeAttempts) !== null && _b !== void 0 ? _b : 0;
     }
 }
+class GuestNetworkProbeFailedError extends Error {
+    constructor(cause) {
+        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) {
     return isTransientAtDepth(error, 0);
@@ -86,7 +88,8 @@ const QUIET_CONNECT_ERROR_CODES = 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 = new Set([1, 2, 14]);
 export function hasGuestNetworkErrno(error) {
     return hasCodeAtDepth(error, 0, TRANSIENT_NETWORK_ERROR_CODES);
 }
@@ -105,14 +108,14 @@ export function isQuietGuestConnectStall(error) {
     }
     return isQuietSignatureAtDepth(error, 0);
 }
-/** Message-only form for `waitForCompletion` outcomes that do not throw. */
-export function isQuietGuestConnectStallMessage(message) {
-    return QUIET_CONNECT_MESSAGE.test(message);
-}
 function errorCode(error) {
     const code = error.code;
     return typeof code === "string" && code.length > 0 ? code : undefined;
 }
+function numericErrorCode(error) {
+    const code = error.code;
+    return typeof code === "number" ? code : undefined;
+}
 function hasCodeAtDepth(error, depth, codes) {
     if (depth >= MAX_CAUSE_DEPTH || !(error instanceof Error)) {
         return false;
@@ -131,14 +134,15 @@ function isQuietSignatureAtDepth(error, depth) {
     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 (error instanceof AggregateError &&
@@ -151,10 +155,17 @@ function isTransientAtDepth(error, depth) {
     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 GuestNetworkProbeFailedError) {
         return true;
     }
-    if (error instanceof GuestNetworkUnavailableError) {
+    if (error.name === "AbortError") {
+        return true;
+    }
+    const numericCode = numericErrorCode(error);
+    if (numericCode !== undefined && QUIET_CONNECT_CODES.has(numericCode)) {
         return true;
     }
     const code = errorCode(error);
@@ -199,13 +210,18 @@ function waitEnabled(options) {
 function defaultProbe(probeUrl, probeTimeoutMs) {
     return __awaiter(this, void 0, void 0, function* () {
         var _a;
-        // Any HTTP response means egress and DNS work. 401/404 are ready.
-        const response = yield fetch(probeUrl, {
-            method: "GET",
-            redirect: "manual",
-            signal: AbortSignal.timeout(probeTimeoutMs),
-        });
-        void ((_a = response.body) === null || _a === void 0 ? void 0 : _a.cancel());
+        try {
+            // Any HTTP response means egress and DNS work. 401/404 are ready.
+            const response = yield fetch(probeUrl, {
+                method: "GET",
+                redirect: "manual",
+                signal: AbortSignal.timeout(probeTimeoutMs),
+            });
+            void ((_a = response.body) === null || _a === void 0 ? void 0 : _a.cancel());
+        }
+        catch (error) {
+            throw new GuestNetworkProbeFailedError(error);
+        }
     });
 }
 /**

package/dist/internal/hosted-admission-adapter.d.ts

@@ -18,6 +18,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/dist/internal/hosted-admission-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hosted-admission-adapter.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-admission-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD;;;;;;;;;GASG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,WAAW,CAAC,CAAC,IAAI,EAAE,kBAAkB,GAAG,kBAAkB,CAAC;IAC3D,QAAQ,CAAC,KAAK,EAAE;QACd,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,OAAO,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE,kBAAkB,CAAC;KAC1B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACvB,CAAC;AAIF,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CAEN;AAED,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,GACjB,sBAAsB,GAAG,SAAS,CAEpC"}
+{"version":3,"file":"hosted-admission-adapter.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-admission-adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD;;;;;;;;;GASG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,WAAW,CAAC,CAAC,IAAI,EAAE,kBAAkB,GAAG,kBAAkB,CAAC;IAC3D,QAAQ,CAAC,KAAK,EAAE;QACd,iFAAiF;QACjF,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,EAAE,MAAM,CAAC;QAClB,OAAO,EAAE,OAAO,CAAC;QACjB,UAAU,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE,kBAAkB,CAAC;KAC1B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACvB,CAAC;AAIF,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,sBAAsB,GAC9B,IAAI,CAEN;AAED,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,GACjB,sBAAsB,GAAG,SAAS,CAEpC"}

package/dist/internal/hosted-catch-protocol.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 declare const AGENT_SDK_CATCH_ENVELOPE_VERSION = 1;
+export declare const AGENT_SDK_CATCH_EVENT_TYPE = "http.request";
+export declare const AGENT_SDK_CUSTOM_CHANNEL_KIND = "custom";
+export declare const AGENT_SDK_SESSION_EVENT_TYPE = "agentsdk.session";
+export declare const AGENT_SDK_HTTP_CHANNEL_ID = "http";
+export declare const AGENT_SDK_HTTP_CHANNEL_KIND = "http";
+export declare const AGENT_SDK_SESSION_RESUME_KEY_PREFIX = "cont:session:";
+export declare const AGENT_SDK_CATCH_MAX_BODY_BYTES: number;
+export declare const AGENT_SDK_CATCH_ROUTE_METHODS: readonly ["GET", "POST", "PUT", "PATCH", "DELETE"];
+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 declare function hostedSessionResumeKey(sessionPublicId: string): string;
+/** Strict parse of a claim-checked catch envelope; anything else is undefined. */
+export declare function parseCatchRequestEnvelope(value: unknown): CatchRequestEnvelope | undefined;
+/** Raw request bytes from an envelope body; empty for a null body. */
+export declare function decodeCatchBody(body: CatchRequestEnvelope["body"]): Buffer;
+//# sourceMappingURL=hosted-catch-protocol.d.ts.map

package/dist/internal/hosted-catch-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-catch-protocol.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-catch-protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,eAAO,MAAM,gCAAgC,IAAI,CAAC;AAClD,eAAO,MAAM,0BAA0B,iBAAiB,CAAC;AACzD,eAAO,MAAM,6BAA6B,WAAW,CAAC;AACtD,eAAO,MAAM,4BAA4B,qBAAqB,CAAC;AAC/D,eAAO,MAAM,yBAAyB,SAAS,CAAC;AAChD,eAAO,MAAM,2BAA2B,SAAS,CAAC;AAClD,eAAO,MAAM,mCAAmC,kBAAkB,CAAC;AACnE,eAAO,MAAM,8BAA8B,EAAE,MAAmB,CAAC;AAEjE,eAAO,MAAM,6BAA6B,YACxC,KAAK,EACL,MAAM,EACN,KAAK,EACL,OAAO,EACP,QAAQ,CACA,CAAC;AACX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9E,MAAM,MAAM,oBAAoB,GAAG;IACjC,CAAC,EAAE,CAAC,CAAC;IACL,MAAM,EAAE,gBAAgB,CAAC;IACzB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE;QAAE,QAAQ,EAAE,MAAM,GAAG,QAAQ,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC3D,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAEtE;AAqBD,kFAAkF;AAClF,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,OAAO,GACb,oBAAoB,GAAG,SAAS,CA2ClC;AAED,sEAAsE;AACtE,wBAAgB,eAAe,CAAC,IAAI,EAAE,oBAAoB,CAAC,MAAM,CAAC,GAAG,MAAM,CAK1E"}

package/dist/internal/hosted-catch-protocol.js

@@ -0,0 +1,103 @@
+/**
+ * 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 = 256 * 1024;
+export const AGENT_SDK_CATCH_ROUTE_METHODS = [
+    "GET",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+];
+/**
+ * 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) {
+    return `${AGENT_SDK_SESSION_RESUME_KEY_PREFIX}${sessionPublicId}`;
+}
+const ENVELOPE_KEYS = new Set([
+    "v",
+    "method",
+    "path",
+    "query",
+    "headers",
+    "body",
+    "receivedAt",
+]);
+const METHODS = new Set(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) {
+    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) {
+    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;
+}
+/** Raw request bytes from an envelope body; empty for a null body. */
+export function decodeCatchBody(body) {
+    if (body === null) {
+        return Buffer.alloc(0);
+    }
+    return Buffer.from(body.data, body.encoding);
+}

package/dist/internal/hosted-catch.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 { type CatchRequestEnvelope } from "./hosted-catch-protocol.js";
+/** Header a replayed request carries so handlers can dedupe on delivery. */
+export declare const CATCH_DELIVERY_ID_HEADER = "x-agent-sdk-delivery-id";
+/**
+ * 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 declare const CATCH_AUTH_CONTEXT: AuthContext;
+export declare function catchRequestFromEnvelope(input: {
+    channelId: string;
+    deliveryId: string;
+    envelope: CatchRequestEnvelope;
+}): Request;
+export declare function replayCatchRequest(input: {
+    channelId: string;
+    deliveryId: string;
+    routes: readonly ChannelRoute[];
+    payload: unknown;
+    args: ChannelHandlerArgs;
+}): Promise<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 declare function attachCatchAdmission(definition: ChannelDefinition<unknown>, routes: readonly ChannelRoute[]): void;
+//# sourceMappingURL=hosted-catch.d.ts.map

package/dist/internal/hosted-catch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-catch.d.ts","sourceRoot":"","sources":["../../src/internal/hosted-catch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,YAAY,EACb,MAAM,aAAa,CAAC;AAUrB,OAAO,EAGL,KAAK,oBAAoB,EAG1B,MAAM,4BAA4B,CAAC;AAIpC,4EAA4E;AAC5E,eAAO,MAAM,wBAAwB,4BAA4B,CAAC;AAIlE;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAIhC,CAAC;AAIF,wBAAgB,wBAAwB,CAAC,KAAK,EAAE;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,oBAAoB,CAAC;CAChC,GAAG,OAAO,CAgBV;AAED,wBAAsB,kBAAkB,CAAC,KAAK,EAAE;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IAChC,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,kBAAkB,CAAC;CAC1B,GAAG,OAAO,CAAC,QAAQ,CAAC,CAkFpB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,UAAU,EAAE,iBAAiB,CAAC,OAAO,CAAC,EACtC,MAAM,EAAE,SAAS,YAAY,EAAE,GAC9B,IAAI,CAgBN"}

package/dist/internal/hosted-catch.js

@@ -0,0 +1,149 @@
+/**
+ * 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`.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+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, 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 = {
+    authenticator: "control-plane-catch",
+    principalId: "agent-sdk:catch",
+    principalType: "runtime",
+};
+const BODYLESS_METHODS = new Set(["GET", "HEAD"]);
+export function catchRequestFromEnvelope(input) {
+    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 function replayCatchRequest(input) {
+    return __awaiter(this, void 0, void 0, function* () {
+        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 === null || matched === void 0 ? void 0 : 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;
+        try {
+            response = yield invokeChannelRoute({
+                route,
+                request,
+                handlerArgs: Object.assign(Object.assign({}, 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, routes) {
+    var _a;
+    var _b;
+    attachHostedAdmissionAdapter(definition, {
+        kind: (_b = (_a = definition.meta) === null || _a === void 0 ? void 0 : _a.kind) !== null && _b !== void 0 ? _b : 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 !== null && channelId !== void 0 ? channelId : "channel",
+                deliveryId,
+                routes,
+                payload,
+                args,
+            });
+        },
+    });
+}