@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/hosted-catch.ts

@@ -1,179 +0,0 @@
-/**
- * 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,
-      });
-    },
-  });
-}