@cursor/july 0.1.105 → 0.1.108

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

@@ -2,6 +2,178 @@ export const HOSTED_DELIVERY_PROTOCOL_VERSION = 2;
 export const HOSTED_DELIVERY_HEADER = "x-agent-sdk-hosted-delivery";
 export const HOSTED_ADMISSION_PATH = "/v1/internal/hosted-admission";
 export const HOSTED_EXECUTION_PATH = "/v1/internal/hosted-execution";
+export const HOSTED_GUEST_RETRY_TRANSIENT = "transient";
+export const HOSTED_GUEST_RETRY_TERMINAL = "terminal";
+
+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;
+};
+
+/**
+ * Hosted delivery is the only HTTP surface whose failures drive Temporal
+ * retries. Keep its retry disposition explicit instead of making the shared
+ * HTTP error helper guess from a status code.
+ */
+export function hostedGuestErrorResponse(input: {
+  status: number;
+  error: string;
+  retry: HostedGuestRetryDisposition;
+  message?: string;
+  turnStatus?: string;
+}): Response {
+  const body: HostedGuestError = {
+    ok: false,
+    error: input.error,
+    retry: input.retry,
+    classification: hostedFailureClassification(input.error),
+    message: input.message,
+    turnStatus: input.turnStatus,
+  };
+  return Response.json(body, { status: input.status });
+}
+
 /**
  * Filename under the serve `--state-root` (not the per-slug SessionEngine
  * dir). Hosted freeze uses `/workspace/.agent-serve`; the Temporal host
@@ -10,6 +182,49 @@ export const HOSTED_EXECUTION_PATH = "/v1/internal/hosted-execution";
  */
 export const HOSTED_EXECUTION_DIAG_FILENAME = "hosted-execution.json";
 
+/**
+ * Reserved hosted-admission `channelKind` for durable reminder fires.
+ * Bypasses authored channel admission and invokes ReminderRunner.dispatch.
+ * Backend builds envelopes with this constant + {@link HOSTED_REMINDER_EVENT_TYPE}.
+ */
+export const HOSTED_REMINDER_CHANNEL_KIND = "agent-sdk:reminder";
+
+/**
+ * Reserved hosted-admission `eventType` for durable reminder fires.
+ * Payload is {@link HostedReminderFirePayload}.
+ */
+export const HOSTED_REMINDER_EVENT_TYPE = "agent-sdk.reminder/fire";
+
+/** Compact reminder-fire payload on the reserved hosted-admission path. */
+export type HostedReminderFirePayload = {
+  reminderId: string;
+  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[];
@@ -171,6 +386,274 @@ export function parseHostedExecution(
   return body as HostedExecution;
 }
 
+/**
+ * True when the admission envelope is the reserved internal reminder fire
+ * path (not an authored channel event).
+ */
+export function isHostedReminderAdmission(delivery: HostedAdmission): boolean {
+  return (
+    delivery.channelKind === HOSTED_REMINDER_CHANNEL_KIND &&
+    delivery.eventType === HOSTED_REMINDER_EVENT_TYPE
+  );
+}
+
+/**
+ * Parse `{ reminderId, fireCount }` from a reserved reminder admission
+ * payload. Rejects unknown keys and non-integer fireCount.
+ */
+export function parseHostedReminderFirePayload(
+  value: unknown
+): HostedReminderFirePayload | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+  const body = value as Record<string, unknown>;
+  const keys = Object.keys(body);
+  if (
+    keys.length !== 2 ||
+    !Object.hasOwn(body, "reminderId") ||
+    !Object.hasOwn(body, "fireCount") ||
+    !boundedString(body.reminderId, 128) ||
+    typeof body.fireCount !== "number" ||
+    !Number.isInteger(body.fireCount) ||
+    body.fireCount < 0
+  ) {
+    return undefined;
+  }
+  return {
+    reminderId: body.reminderId,
+    fireCount: body.fireCount,
+  };
+}
+
+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 {