@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/github-fanout.ts

@@ -1,144 +0,0 @@
-/**
- * Local fan-out proxy for `agent-sdk github forward`.
- *
- * `gh webhook forward` can only target a single URL, and GitHub allows just one
- * forwarder per repo/org. To feed several GitHub channels at once, we run one
- * forwarder into this loopback proxy, which re-posts each delivery — raw body
- * and signature headers intact, so per-channel `X-Hub-Signature-256` checks
- * still pass — to every channel whose declared event set matches the
- * delivery's `x-github-event`.
- */
-
-import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
-import type { AddressInfo } from "node:net";
-import { type GitHubForwardTarget, targetLabel } from "../channels/github/forward.js";
-
-/** Request headers copied verbatim from gh onto each fanned-out delivery. */
-export const FANOUT_FORWARD_HEADERS: readonly string[] = [
-  "content-type",
-  "x-github-event",
-  "x-github-delivery",
-  "x-github-hook-id",
-  "x-hub-signature",
-  "x-hub-signature-256",
-  "user-agent",
-  "accept",
-];
-
-export interface FanoutServer {
-  /** Loopback URL to point `gh webhook forward --url` at. */
-  url: string;
-  close(): void;
-}
-
-export interface FanoutOptions {
-  /** Sink for per-delivery failures. Defaults to `process.stderr`. */
-  logger?: (line: string) => void;
-}
-
-/** Start a loopback proxy that fans deliveries out to {@link targets}. */
-export async function startFanoutServer(
-  targets: readonly GitHubForwardTarget[],
-  options: FanoutOptions = {},
-): Promise<FanoutServer> {
-  const server = createServer((req, res) => {
-    handleFanoutRequest(req, res, targets, options);
-  });
-  await new Promise<void>((resolve, reject) => {
-    server.once("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      resolve();
-    });
-  });
-  const address = server.address() as AddressInfo;
-  return {
-    url: `http://127.0.0.1:${address.port}`,
-    close: () => {
-      server.close();
-    },
-  };
-}
-
-function handleFanoutRequest(
-  req: IncomingMessage,
-  res: ServerResponse,
-  targets: readonly GitHubForwardTarget[],
-  options: FanoutOptions,
-): void {
-  const chunks: Buffer[] = [];
-  req.on("data", (chunk: Buffer) => {
-    chunks.push(chunk);
-  });
-  req.on("end", () => {
-    void fanoutDelivery(Buffer.concat(chunks), req.headers, targets, options)
-      .then(delivered => {
-        res.writeHead(200, { "content-type": "application/json" });
-        res.end(JSON.stringify({ ok: true, delivered }));
-      })
-      .catch((error: unknown) => {
-        res.writeHead(502, { "content-type": "application/json" });
-        res.end(
-          JSON.stringify({
-            ok: false,
-            error: error instanceof Error ? error.message : String(error),
-          }),
-        );
-      });
-  });
-}
-
-/**
- * Re-post a single delivery to the matching targets, returning the labels that
- * accepted it. Only targets whose event set includes the delivery's
- * `x-github-event` receive it (all of them when the header is absent).
- */
-export async function fanoutDelivery(
-  body: Buffer,
-  headers: IncomingMessage["headers"],
-  targets: readonly GitHubForwardTarget[],
-  options: FanoutOptions = {},
-): Promise<string[]> {
-  const log = options.logger ?? (line => process.stderr.write(line));
-  const event =
-    typeof headers["x-github-event"] === "string" ? headers["x-github-event"] : undefined;
-  const outbound: Record<string, string> = {};
-  for (const name of FANOUT_FORWARD_HEADERS) {
-    const value = headers[name];
-    if (typeof value === "string") {
-      outbound[name] = value;
-    }
-  }
-  const recipients = targets.filter(target => event === undefined || target.events.includes(event));
-  // Reuse one Uint8Array view across recipients (Buffer isn't a BodyInit).
-  const payload = new Uint8Array(body);
-  const delivered: string[] = [];
-  // Bounded by the number of GitHub channels in the project (a handful), so
-  // unbounded-concurrency concerns do not apply here.
-  await Promise.all(
-    recipients.map(async target => {
-      const label = targetLabel(target);
-      try {
-        const response = await fetch(target.url, {
-          method: "POST",
-          headers: outbound,
-          body: payload,
-        });
-        if (!response.ok) {
-          log(`[agent-sdk] delivery to ${label} failed: HTTP ${response.status}\n`);
-          return;
-        }
-        delivered.push(label);
-      } catch (error) {
-        log(
-          `[agent-sdk] delivery to ${label} failed: ${
-            error instanceof Error ? error.message : String(error)
-          }\n`,
-        );
-      }
-    }),
-  );
-  if (recipients.length > 0 && delivered.length === 0) {
-    throw new Error(`fan-out delivery failed for all ${recipients.length} matching channel(s)`);
-  }
-  return delivered;
-}

package/src/internal/guest-network.ts

@@ -1,391 +0,0 @@
-/**
- * Guest egress readiness for hosted v2.
- *
- * `waitForEngineReady` only polls July `/v1/health` (process listening). After
- * a freeze restore the guest network (DNS, egress programming, dead sockets)
- * often comes up later. Authored admission/execution that `fetch`es in that
- * window throws undici `TypeError: fetch failed`, which used to become a
- * redacted HTTP 500 `internal_error` and a minutes-long Temporal retry.
- *
- * TAS waits on GET `/v1/guest-network` (90s, Sand's resume bar) before
- * opening the hosted POST. The in-POST wait stays a short last-line check
- * so leftover races still return 503 `guest_network_unavailable` instead of
- * a redacted 500.
- *
- * 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";
-
-export const GUEST_NETWORK_UNAVAILABLE = "guest_network_unavailable";
-export const GUEST_CONNECT_STALLED = "guest_connect_stalled";
-
-/** Control-plane readiness probe. Auth none, same as `/v1/health`. */
-export const GUEST_NETWORK_PATH = "/v1/guest-network";
-
-/**
- * Sand `READY_TIMEOUT_MS` / resume reachability bar. The in-POST wait stays
- * at {@link DEFAULT_WAIT_TIMEOUT_MS}; this budget is for GET `/v1/guest-network`
- * so TAS does not open a hosted turn on a dead NIC.
- */
-export const GUEST_NETWORK_READY_WAIT_TIMEOUT_MS = 90_000;
-
-/**
- * Node/undici codes that mean the request never produced an HTTP response.
- * `ENOTFOUND`/`EAI_AGAIN` cover restored-pod DNS races.
- */
-const TRANSIENT_NETWORK_ERROR_CODES: ReadonlySet<string> = new Set([
-  "ECONNREFUSED",
-  "ECONNRESET",
-  "EAI_AGAIN",
-  "EHOSTUNREACH",
-  "ENETDOWN",
-  "ENETUNREACH",
-  "ENOTFOUND",
-  "EPIPE",
-  "ETIMEDOUT",
-  "UND_ERR_CONNECT_TIMEOUT",
-  "UND_ERR_SOCKET",
-  "UND_ERR_CLOSED",
-]);
-
-const MAX_CAUSE_DEPTH = 8;
-
-export class GuestNetworkUnavailableError extends Error {
-  readonly code: typeof GUEST_NETWORK_UNAVAILABLE = GUEST_NETWORK_UNAVAILABLE;
-  readonly waitMs: number;
-  readonly probeAttempts: number;
-
-  constructor(
-    message = "Guest network is not ready for outbound requests.",
-    extras: { waitMs?: number; probeAttempts?: number } = {},
-  ) {
-    super(message);
-    this.name = "GuestNetworkUnavailableError";
-    this.waitMs = extras.waitMs ?? 0;
-    this.probeAttempts = extras.probeAttempts ?? 0;
-  }
-}
-
-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`) carries a known network-level code.
- */
-export function isTransientGuestNetworkError(error: unknown): boolean {
-  return isTransientAtDepth(error, 0);
-}
-
-/**
- * Connect/undici codes that mean the socket was up but the RPC went quiet
- * (headers never arrived, body stalled, caller aborted). Not a DNS/egress
- * miss — those live in the network errno set.
- */
-const QUIET_CONNECT_ERROR_CODES: ReadonlySet<string> = new Set([
-  "ABORT_ERR",
-  "UND_ERR_BODY_TIMEOUT",
-  "UND_ERR_HEADERS_TIMEOUT",
-]);
-// 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);
-}
-
-/**
- * Quiet guest Connect: the request left the guest but never produced a
- * useful RPC outcome. Distinct from {@link isTransientGuestNetworkError}
- * so the in-POST wait still retries bare `fetch failed`, while the HTTP
- * mapper can return `guest_connect_stalled` instead of a mystery 503.
- */
-export function isQuietGuestConnectStall(error: unknown): boolean {
-  if (error instanceof GuestNetworkUnavailableError) {
-    return false;
-  }
-  if (hasGuestNetworkErrno(error)) {
-    return false;
-  }
-  return isQuietSignatureAtDepth(error, 0);
-}
-
-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, codes: ReadonlySet<string>): boolean {
-  if (depth >= MAX_CAUSE_DEPTH || !(error instanceof Error)) {
-    return false;
-  }
-  const code = errorCode(error);
-  if (code !== undefined && codes.has(code)) {
-    return true;
-  }
-  if (
-    error instanceof AggregateError &&
-    error.errors.some(inner => hasCodeAtDepth(inner, depth + 1, codes))
-  ) {
-    return true;
-  }
-  return hasCodeAtDepth(error.cause, depth + 1, codes);
-}
-
-function isQuietSignatureAtDepth(error: unknown, depth: number): boolean {
-  if (depth >= MAX_CAUSE_DEPTH || !(error instanceof Error)) {
-    return false;
-  }
-  if (error.name === "AbortError") {
-    return true;
-  }
-  const numericCode = numericErrorCode(error);
-  if (numericCode !== undefined && QUIET_CONNECT_CODES.has(numericCode)) {
-    return true;
-  }
-  const code = errorCode(error);
-  if (code !== undefined && QUIET_CONNECT_ERROR_CODES.has(code)) {
-    return true;
-  }
-  if (
-    error instanceof AggregateError &&
-    error.errors.some(inner => isQuietSignatureAtDepth(inner, depth + 1))
-  ) {
-    return true;
-  }
-  return isQuietSignatureAtDepth(error.cause, depth + 1);
-}
-
-function isTransientAtDepth(error: unknown, depth: number): boolean {
-  if (depth >= MAX_CAUSE_DEPTH || !(error instanceof Error)) {
-    return false;
-  }
-  if (error instanceof GuestNetworkUnavailableError) {
-    return true;
-  }
-  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);
-  if (
-    code !== undefined &&
-    (TRANSIENT_NETWORK_ERROR_CODES.has(code) || QUIET_CONNECT_ERROR_CODES.has(code))
-  ) {
-    return true;
-  }
-  if (
-    error instanceof AggregateError &&
-    error.errors.some(inner => isTransientAtDepth(inner, depth + 1))
-  ) {
-    return true;
-  }
-  return isTransientAtDepth(error.cause, depth + 1);
-}
-
-const DEFAULT_PROBE_TIMEOUT_MS = 2_000;
-/** Last-line wait inside an already-open hosted POST. */
-export const DEFAULT_WAIT_TIMEOUT_MS = 8_000;
-const DEFAULT_POLL_MS = 250;
-
-export type GuestNetworkWaitOptions = {
-  /**
-   * When omitted, wait is enabled only on hosted engines (probe URL set and
-   * not running under Vitest). Tests pass `true` plus a mock `probe`.
-   */
-  enabled?: boolean;
-  /** Override the allowlisted probe URL. */
-  probeUrl?: string;
-  waitTimeoutMs?: number;
-  pollMs?: number;
-  probeTimeoutMs?: number;
-  probe?: () => Promise<void>;
-  now?: () => number;
-  sleep?: (ms: number) => Promise<void>;
-};
-
-function defaultSleep(ms: number): Promise<void> {
-  return new Promise(resolve => {
-    setTimeout(resolve, ms);
-  });
-}
-
-function resolveProbeUrl(explicit?: string): string | undefined {
-  const raw =
-    explicit ??
-    process.env.AGENT_SERVE_EGRESS_PROBE_URL ??
-    process.env.AGENT_SERVE_CURSOR_BACKEND_URL;
-  const trimmed = raw?.trim() ?? "";
-  return trimmed.length > 0 ? trimmed : undefined;
-}
-
-function waitEnabled(options: GuestNetworkWaitOptions): boolean {
-  if (options.enabled !== undefined) {
-    return options.enabled;
-  }
-  if (process.env.VITEST === "true") {
-    return false;
-  }
-  if (process.env.AGENT_SERVE_SKIP_GUEST_NETWORK_WAIT === "1") {
-    return false;
-  }
-  return resolveProbeUrl(options.probeUrl) !== undefined;
-}
-
-async function defaultProbe(probeUrl: string, probeTimeoutMs: number): Promise<void> {
-  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";
-
-export type GuestNetworkWaitResult = {
-  outcome: Exclude<GuestNetworkWaitOutcome, "unavailable">;
-  waitMs: number;
-  probeAttempts: number;
-};
-
-export type GuestNetworkWaitStats = {
-  outcome: GuestNetworkWaitOutcome;
-  waitMs: number;
-  probeAttempts: number;
-};
-
-/**
- * `Server-Timing` metric the control plane scrapes for Datadog
- * `hosted_*.guest_network_wait_ms`. Any HTTP response (ok or 503) can
- * carry it so restore time-to-egress is visible on both paths.
- */
-export function formatGuestNetworkServerTiming(stats: GuestNetworkWaitStats): string {
-  return `guest_net;desc="${stats.outcome}";dur=${Math.max(0, stats.waitMs).toFixed(1)};probes=${String(stats.probeAttempts)}`;
-}
-
-/**
- * Poll until a cheap allowlisted GET succeeds or the wait budget expires.
- * Throws {@link GuestNetworkUnavailableError} on timeout so hosted routes
- * can return 503 without running authored code.
- */
-export async function waitForGuestNetworkReady(
-  options: GuestNetworkWaitOptions = {},
-): Promise<GuestNetworkWaitResult> {
-  if (!waitEnabled(options)) {
-    return { outcome: "skipped", waitMs: 0, probeAttempts: 0 };
-  }
-  const probeUrl = resolveProbeUrl(options.probeUrl);
-  const probe =
-    options.probe ??
-    (probeUrl === undefined
-      ? undefined
-      : () => defaultProbe(probeUrl, options.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS));
-  if (probe === undefined) {
-    return { outcome: "skipped", waitMs: 0, probeAttempts: 0 };
-  }
-  const waitTimeoutMs = options.waitTimeoutMs ?? DEFAULT_WAIT_TIMEOUT_MS;
-  const pollMs = options.pollMs ?? DEFAULT_POLL_MS;
-  const now = options.now ?? Date.now;
-  const sleep = options.sleep ?? defaultSleep;
-  const startedAt = now();
-  let lastError: unknown;
-  let probeAttempts = 0;
-  for (;;) {
-    probeAttempts += 1;
-    try {
-      await probe();
-      return {
-        outcome: "ready",
-        waitMs: Math.max(0, now() - startedAt),
-        probeAttempts,
-      };
-    } catch (error) {
-      lastError = error;
-      if (!isTransientGuestNetworkError(error)) {
-        throw error;
-      }
-    }
-    const elapsedMs = now() - startedAt;
-    if (elapsedMs >= waitTimeoutMs) {
-      const detail = lastError instanceof Error ? lastError.message : String(lastError);
-      throw new GuestNetworkUnavailableError(
-        `Guest network did not become ready within ${String(waitTimeoutMs)}ms (${detail}).`,
-        { waitMs: Math.max(0, elapsedMs), probeAttempts },
-      );
-    }
-    await sleep(pollMs);
-  }
-}
-
-/**
- * GET `/v1/guest-network`: wait up to
- * {@link GUEST_NETWORK_READY_WAIT_TIMEOUT_MS} and return 200 (ready/skipped)
- * or 503 `guest_network_unavailable`. Server-Timing matches the hosted POST
- * so TAS can scrape the same `guest_net` metric before `postHosted`.
- */
-export async function guestNetworkReadinessResponse(
-  options: GuestNetworkWaitOptions = {},
-): Promise<Response> {
-  try {
-    const result = await waitForGuestNetworkReady({
-      waitTimeoutMs: GUEST_NETWORK_READY_WAIT_TIMEOUT_MS,
-      ...options,
-    });
-    return new Response(JSON.stringify({ ok: true, ...result }), {
-      status: 200,
-      headers: {
-        "content-type": "application/json; charset=utf-8",
-        "server-timing": formatGuestNetworkServerTiming(result),
-      },
-    });
-  } catch (error) {
-    if (!(error instanceof GuestNetworkUnavailableError)) {
-      throw error;
-    }
-    return new Response(
-      JSON.stringify({
-        ok: false,
-        error: GUEST_NETWORK_UNAVAILABLE,
-        retry: HOSTED_GUEST_RETRY_TRANSIENT,
-        message: error.message,
-        waitMs: error.waitMs,
-        probeAttempts: error.probeAttempts,
-      }),
-      {
-        status: 503,
-        headers: {
-          "content-type": "application/json; charset=utf-8",
-          "server-timing": formatGuestNetworkServerTiming({
-            outcome: "unavailable",
-            waitMs: error.waitMs,
-            probeAttempts: error.probeAttempts,
-          }),
-        },
-      },
-    );
-  }
-}