@cursor/july 0.1.107 → 0.1.109

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,
+      });
+    },
+  });
+}

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

@@ -9,10 +9,144 @@ export type HostedGuestRetryDisposition =
   | typeof HOSTED_GUEST_RETRY_TRANSIENT
   | typeof HOSTED_GUEST_RETRY_TERMINAL;
 
+export const HOSTED_FAILURE_CLASSIFICATION_VERSION = 1;
+
+export type HostedFailureDomain =
+  | "configuration"
+  | "protocol"
+  | "platform"
+  | "agent"
+  | "dependency"
+  | "cancellation"
+  | "unknown";
+
+export type HostedFailureSource =
+  | "tas"
+  | "factory"
+  | "anyrun"
+  | "engine"
+  | "agent";
+
+export type HostedFailureClassification = {
+  v: typeof HOSTED_FAILURE_CLASSIFICATION_VERSION;
+  domain: HostedFailureDomain;
+  source: HostedFailureSource;
+};
+
+const HOSTED_FAILURE_DOMAINS = new Set<HostedFailureDomain>([
+  "configuration",
+  "protocol",
+  "platform",
+  "agent",
+  "dependency",
+  "cancellation",
+  "unknown",
+]);
+const HOSTED_FAILURE_SOURCES = new Set<HostedFailureSource>([
+  "tas",
+  "factory",
+  "anyrun",
+  "engine",
+  "agent",
+]);
+
+export type HostedFailureCode =
+  | "agent_admission_threw"
+  | "agent_dependency_failed"
+  | "background_dispatch_failed"
+  | "bound_secrets_not_consumed"
+  | "channel_dispatch_failed"
+  | "channel_kind_mismatch"
+  | "channel_not_found"
+  | "channel_outcome_missing"
+  | "forbidden"
+  | "guest_connect_stalled"
+  | "guest_network_unavailable"
+  | "hosted_admission_session_mismatch"
+  | "hosted_admission_unavailable"
+  | "hosted_deferred_session_unusable"
+  | "hosted_local_send_rejected"
+  | "hosted_send_limit_exceeded"
+  | "internal_error"
+  | "invalid_hosted_admission"
+  | "invalid_hosted_execution"
+  | "invalid_request"
+  | "method_not_allowed"
+  | "not_found"
+  | "session_busy"
+  | "turn_cancelled"
+  | "turn_failed"
+  | "unauthorized"
+  | "v2_identity_conflict";
+
+export const HOSTED_FAILURE_CLASSIFICATIONS: Record<
+  HostedFailureCode,
+  Omit<HostedFailureClassification, "v">
+> = {
+  agent_admission_threw: { domain: "agent", source: "agent" },
+  agent_dependency_failed: { domain: "dependency", source: "factory" },
+  background_dispatch_failed: { domain: "agent", source: "agent" },
+  bound_secrets_not_consumed: { domain: "platform", source: "engine" },
+  channel_dispatch_failed: { domain: "agent", source: "agent" },
+  channel_kind_mismatch: { domain: "configuration", source: "engine" },
+  channel_not_found: { domain: "configuration", source: "engine" },
+  channel_outcome_missing: { domain: "protocol", source: "agent" },
+  forbidden: { domain: "configuration", source: "engine" },
+  guest_connect_stalled: { domain: "platform", source: "engine" },
+  guest_network_unavailable: { domain: "platform", source: "anyrun" },
+  hosted_admission_session_mismatch: { domain: "protocol", source: "engine" },
+  hosted_admission_unavailable: { domain: "platform", source: "engine" },
+  hosted_deferred_session_unusable: { domain: "agent", source: "agent" },
+  hosted_local_send_rejected: { domain: "agent", source: "agent" },
+  hosted_send_limit_exceeded: { domain: "agent", source: "agent" },
+  internal_error: { domain: "unknown", source: "engine" },
+  invalid_hosted_admission: { domain: "protocol", source: "engine" },
+  invalid_hosted_execution: { domain: "protocol", source: "engine" },
+  invalid_request: { domain: "protocol", source: "engine" },
+  method_not_allowed: { domain: "protocol", source: "engine" },
+  not_found: { domain: "protocol", source: "engine" },
+  session_busy: { domain: "platform", source: "engine" },
+  turn_cancelled: { domain: "cancellation", source: "agent" },
+  turn_failed: { domain: "agent", source: "agent" },
+  unauthorized: { domain: "configuration", source: "engine" },
+  v2_identity_conflict: { domain: "protocol", source: "engine" },
+};
+
+export function hostedFailureClassification(
+  code: string
+): HostedFailureClassification {
+  const known = HOSTED_FAILURE_CLASSIFICATIONS[code as HostedFailureCode];
+  return {
+    v: HOSTED_FAILURE_CLASSIFICATION_VERSION,
+    domain: known?.domain ?? "unknown",
+    source: known?.source ?? "engine",
+  };
+}
+
+export function parseHostedFailureClassification(
+  value: unknown
+): HostedFailureClassification | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const body = value as Record<string, unknown>;
+  if (
+    body.v !== HOSTED_FAILURE_CLASSIFICATION_VERSION ||
+    typeof body.domain !== "string" ||
+    !HOSTED_FAILURE_DOMAINS.has(body.domain as HostedFailureDomain) ||
+    typeof body.source !== "string" ||
+    !HOSTED_FAILURE_SOURCES.has(body.source as HostedFailureSource)
+  ) {
+    return undefined;
+  }
+  return body as HostedFailureClassification;
+}
+
 export type HostedGuestError = {
   ok: false;
   error: string;
   retry: HostedGuestRetryDisposition;
+  classification: HostedFailureClassification;
   message?: string;
   turnStatus?: string;
 };
@@ -33,6 +167,7 @@ export function hostedGuestErrorResponse(input: {
     ok: false,
     error: input.error,
     retry: input.retry,
+    classification: hostedFailureClassification(input.error),
     message: input.message,
     turnStatus: input.turnStatus,
   };
@@ -66,6 +201,30 @@ export type HostedReminderFirePayload = {
   fireCount: number;
 };
 
+/** Protocol v1 immutable fire descriptor (architecture v2 CP path). */
+export type HostedReminderFireDescriptorPayload = {
+  protocolVersion: 1;
+  id: string;
+  fireCount: number;
+  generation: number;
+  purpose: string;
+  channelId: string;
+  continuationToken: string;
+  target?: Record<string, unknown>;
+  scheduleKind: "every" | "cron" | "delay" | "at";
+  scheduleValue: string;
+  intervalMs?: number;
+  prompt?: string;
+  handler?: string;
+  args?: Record<string, unknown>;
+  hasRunHandler: boolean;
+  hasUntilFn: boolean;
+  untilPrompt?: string;
+  busyPolicy: "skipIfBusy" | "queueBehindTurn";
+  nextFireAtMs: number;
+  claimedAtMs: number;
+};
+
 export type HostedAdmissionManagedAutomation = {
   automationUuid: string;
   mcpServerNames: string[];
@@ -267,6 +426,234 @@ export function parseHostedReminderFirePayload(
   };
 }
 
+const HOSTED_REMINDER_FIRE_DESCRIPTOR_KEYS = new Set([
+  "protocolVersion",
+  "id",
+  "fireCount",
+  "generation",
+  "purpose",
+  "channelId",
+  "continuationToken",
+  "target",
+  "scheduleKind",
+  "scheduleValue",
+  "intervalMs",
+  "prompt",
+  "handler",
+  "args",
+  "hasRunHandler",
+  "hasUntilFn",
+  "untilPrompt",
+  "busyPolicy",
+  "nextFireAtMs",
+  "claimedAtMs",
+]);
+
+const HOSTED_REMINDER_SCHEDULE_KINDS = new Set([
+  "every",
+  "cron",
+  "delay",
+  "at",
+]);
+const HOSTED_REMINDER_BUSY_POLICIES = new Set([
+  "skipIfBusy",
+  "queueBehindTurn",
+]);
+
+const HOSTED_REMINDER_JSON_MAX_DEPTH = 8;
+
+/** Reject non-JSON values (NaN/Infinity/undefined/bigint/function/symbol). */
+function isJsonSafeValue(value: unknown, depth: number): boolean {
+  if (depth > HOSTED_REMINDER_JSON_MAX_DEPTH) {
+    return false;
+  }
+  if (value === null) {
+    return true;
+  }
+  const type = typeof value;
+  if (type === "string" || type === "boolean") {
+    return true;
+  }
+  if (type === "number") {
+    return Number.isFinite(value);
+  }
+  if (type !== "object") {
+    return false;
+  }
+  if (Array.isArray(value)) {
+    return value.every((entry) => isJsonSafeValue(entry, depth + 1));
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) {
+    return false;
+  }
+  for (const entry of Object.values(value as Record<string, unknown>)) {
+    if (!isJsonSafeValue(entry, depth + 1)) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function parseOptionalJsonObjectField(
+  value: unknown,
+  maxBytes: number
+): Record<string, unknown> | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  if (!isJsonSafeValue(value, 0)) {
+    return undefined;
+  }
+  try {
+    const encoded = JSON.stringify(value);
+    if (
+      encoded === undefined ||
+      Buffer.byteLength(encoded, "utf8") > maxBytes
+    ) {
+      return undefined;
+    }
+    const roundTrip = JSON.parse(encoded) as unknown;
+    if (
+      typeof roundTrip !== "object" ||
+      roundTrip === null ||
+      Array.isArray(roundTrip)
+    ) {
+      return undefined;
+    }
+    return roundTrip as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Parse the immutable CP fire descriptor. Rejects unknown keys, non-enum
+ * schedule/busy values, and non-JSON-safe optional object fields.
+ */
+export function parseHostedReminderFireDescriptorPayload(
+  value: unknown
+): HostedReminderFireDescriptorPayload | 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_REMINDER_FIRE_DESCRIPTOR_KEYS.has(key)
+    )
+  ) {
+    return undefined;
+  }
+  if (
+    body.protocolVersion !== 1 ||
+    typeof body.id !== "string" ||
+    body.id.length === 0 ||
+    body.id.length > 128 ||
+    typeof body.fireCount !== "number" ||
+    !Number.isInteger(body.fireCount) ||
+    body.fireCount < 0 ||
+    typeof body.generation !== "number" ||
+    !Number.isInteger(body.generation) ||
+    body.generation < 0 ||
+    typeof body.purpose !== "string" ||
+    body.purpose.length === 0 ||
+    body.purpose.length > 512 ||
+    typeof body.channelId !== "string" ||
+    body.channelId.length === 0 ||
+    body.channelId.length > 128 ||
+    typeof body.continuationToken !== "string" ||
+    body.continuationToken.length === 0 ||
+    body.continuationToken.length > 512 ||
+    typeof body.scheduleKind !== "string" ||
+    !HOSTED_REMINDER_SCHEDULE_KINDS.has(body.scheduleKind) ||
+    typeof body.scheduleValue !== "string" ||
+    body.scheduleValue.length === 0 ||
+    body.scheduleValue.length > 512 ||
+    typeof body.hasRunHandler !== "boolean" ||
+    typeof body.hasUntilFn !== "boolean" ||
+    typeof body.busyPolicy !== "string" ||
+    !HOSTED_REMINDER_BUSY_POLICIES.has(body.busyPolicy) ||
+    typeof body.nextFireAtMs !== "number" ||
+    !Number.isFinite(body.nextFireAtMs) ||
+    typeof body.claimedAtMs !== "number" ||
+    !Number.isFinite(body.claimedAtMs) ||
+    !Number.isInteger(body.claimedAtMs) ||
+    body.claimedAtMs < 0
+  ) {
+    return undefined;
+  }
+  if (body.intervalMs !== undefined) {
+    if (
+      typeof body.intervalMs !== "number" ||
+      !Number.isFinite(body.intervalMs) ||
+      !Number.isInteger(body.intervalMs) ||
+      body.intervalMs <= 0
+    ) {
+      return undefined;
+    }
+  }
+  if (body.prompt !== undefined) {
+    if (typeof body.prompt !== "string" || body.prompt.length > 8192) {
+      return undefined;
+    }
+  }
+  if (body.handler !== undefined) {
+    if (
+      typeof body.handler !== "string" ||
+      body.handler.length === 0 ||
+      body.handler.length > 128
+    ) {
+      return undefined;
+    }
+  }
+  if (body.untilPrompt !== undefined) {
+    if (
+      typeof body.untilPrompt !== "string" ||
+      body.untilPrompt.length > 8192
+    ) {
+      return undefined;
+    }
+  }
+  const target = parseOptionalJsonObjectField(body.target, 16 * 1024);
+  if (body.target !== undefined && target === undefined) {
+    return undefined;
+  }
+  const args = parseOptionalJsonObjectField(body.args, 32 * 1024);
+  if (body.args !== undefined && args === undefined) {
+    return undefined;
+  }
+  return {
+    protocolVersion: 1,
+    id: body.id,
+    fireCount: body.fireCount,
+    generation: body.generation,
+    purpose: body.purpose,
+    channelId: body.channelId,
+    continuationToken: body.continuationToken,
+    ...(target === undefined ? {} : { target }),
+    scheduleKind:
+      body.scheduleKind as HostedReminderFireDescriptorPayload["scheduleKind"],
+    scheduleValue: body.scheduleValue,
+    ...(body.intervalMs === undefined ? {} : { intervalMs: body.intervalMs }),
+    ...(body.prompt === undefined ? {} : { prompt: body.prompt }),
+    ...(body.handler === undefined ? {} : { handler: body.handler }),
+    ...(args === undefined ? {} : { args }),
+    hasRunHandler: body.hasRunHandler,
+    hasUntilFn: body.hasUntilFn,
+    ...(body.untilPrompt === undefined
+      ? {}
+      : { untilPrompt: body.untilPrompt }),
+    busyPolicy:
+      body.busyPolicy as HostedReminderFireDescriptorPayload["busyPolicy"],
+    nextFireAtMs: body.nextFireAtMs,
+    claimedAtMs: body.claimedAtMs,
+  };
+}
+
 export function parseHostedAdmissionOutcome(
   value: unknown
 ): HostedAdmissionOutcome | undefined {