@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/cursor-relay-core.ts

@@ -1,563 +0,0 @@
-/**
- * Shared engine for the Cursor pull relays (`--cursor-events` for GitHub SCM
- * events, and the automatic Slack relay for `cursorAccount` channels). Both
- * long-poll a per-principal Cursor backend stream with a durable client-owned
- * offset and a heartbeat registration; only the subscribe/poll paths, the
- * registration body/response, and the per-event dispatch differ. Those vary
- * as data or closures on a {@link RelayAdapter}, so this engine is written
- * once and tested through each provider's relay.
- */
-
-import { randomUUID } from "node:crypto";
-import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-
-import { LOG_PREFIX } from "./distribution.js";
-
-const OFFSET_SNAPSHOT_VERSION = 1 as const;
-const DEFAULT_POLL_WAIT_MS = 25_000;
-const DEFAULT_POLL_LIMIT = 100;
-const DEFAULT_REGISTER_INTERVAL_MS = 5 * 60 * 1000;
-const CONSUMER_ID_PATTERN = /^[a-zA-Z0-9_-]{1,64}$/;
-const DEFAULT_IDLE_POLL_DELAY_MS = 250;
-const MIN_BACKOFF_MS = 1_000;
-const MAX_BACKOFF_MS = 30_000;
-const AUTH_FAILURE_BACKOFF_MS = 60_000;
-/** Attempts per event before the offset advances past it. */
-const DISPATCH_ATTEMPTS = 3;
-const DISPATCH_RETRY_DELAYS_MS = [250, 1_000];
-/** Budget for the best-effort deregistration PUT during stop(). */
-const DEREGISTER_TIMEOUT_MS = 1_500;
-
-interface OffsetSnapshot {
-  version: typeof OFFSET_SNAPSHOT_VERSION;
-  offset: string;
-  updatedAt: string;
-}
-
-/** Durable offset snapshot under `<stateDir>/offset.json`. */
-export class RelayOffsetStore {
-  constructor(private readonly stateDir: string) {}
-
-  private get filePath(): string {
-    return join(this.stateDir, "offset.json");
-  }
-
-  async load(): Promise<string | undefined> {
-    try {
-      const raw = await readFile(this.filePath, "utf8");
-      const parsed = JSON.parse(raw) as Partial<OffsetSnapshot>;
-      if (parsed.version === OFFSET_SNAPSHOT_VERSION && typeof parsed.offset === "string") {
-        return parsed.offset;
-      }
-      return undefined;
-    } catch {
-      return undefined;
-    }
-  }
-
-  async save(offset: string): Promise<void> {
-    await mkdir(this.stateDir, { recursive: true });
-    const snapshot: OffsetSnapshot = {
-      version: OFFSET_SNAPSHOT_VERSION,
-      offset,
-      updatedAt: new Date().toISOString(),
-    };
-    // Write-then-rename so a crash mid-write never corrupts the snapshot.
-    const tmpPath = `${this.filePath}.tmp`;
-    await writeFile(tmpPath, JSON.stringify(snapshot, null, 2), "utf8");
-    await rename(tmpPath, this.filePath);
-  }
-}
-
-/** Compare stream offsets (`<ms>-<seq>`). */
-export function compareStreamOffsets(a: string, b: string): number {
-  const [aMs, aSeq] = splitOffset(a);
-  const [bMs, bSeq] = splitOffset(b);
-  if (aMs !== bMs) return aMs < bMs ? -1 : 1;
-  if (aSeq !== bSeq) return aSeq < bSeq ? -1 : 1;
-  return 0;
-}
-
-function splitOffset(offset: string): [number, number] {
-  const dash = offset.indexOf("-");
-  const ms = Number(dash === -1 ? offset : offset.slice(0, dash));
-  const seq = dash === -1 ? 0 : Number(offset.slice(dash + 1));
-  return [Number.isFinite(ms) ? ms : 0, Number.isFinite(seq) ? seq : 0];
-}
-
-export function describeRelayError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
-interface PollResponse<TEvent> {
-  events: TEvent[];
-  nextOffset: string;
-  gapDetected: boolean;
-}
-
-/**
- * Provider-specific behavior for {@link CursorRelayCore}. Everything else —
- * consumer-id persistence, registration-gated lifecycle, heartbeat, the
- * anchor/poll/dedupe/offset loop, and backoff — is shared.
- */
-export interface RelayAdapter<TEvent extends { offset: string }> {
-  /** Log fragment, e.g. `cursor-events` → `[agent-sdk] cursor-events: …`. */
-  readonly logPrefix: string;
-  /** Subscription registration path, e.g. `/v0/scm-events/subscriptions`. */
-  readonly subscribePath: string;
-  /** Base long-poll path, e.g. `/v0/scm-events`. */
-  readonly pollPath: string;
-  /** The registration request body for this consumer id. */
-  buildRegistrationBody(consumerId: string): unknown;
-  /**
-   * The empty-scope registration body used to deregister this consumer on a
-   * clean stop. When present, `stop()` best-effort PUTs it so the consumer's
-   * registration does not linger as a ghost until its server-side TTL (a
-   * ghost with this host's agent names makes name routing ambiguous for a
-   * redeployed sibling until it expires).
-   */
-  buildDeregistrationBody?(consumerId: string): unknown;
-  /**
-   * Apply the (ok) registration response: update the accepted-scope filter
-   * and return the human-readable outcome lines to log. The core logs them
-   * only when they change, so returning stable lines keeps the heartbeat
-   * quiet.
-   */
-  applyRegistrationResponse(json: unknown): string[];
-  /**
-   * Whether an event from the shared principal stream belongs to THIS
-   * consumer (repo/agent + kind filter). Non-matching events still advance
-   * the offset but are not dispatched.
-   */
-  shouldDispatch(event: TEvent): boolean;
-  /**
-   * Handle one matching event. Failures retry a bounded number of times
-   * ({@link DISPATCH_ATTEMPTS}), then log and skip.
-   */
-  dispatch(event: TEvent): Promise<void>;
-}
-
-export interface CursorRelayCoreOptions<TEvent extends { offset: string }> {
-  baseUrl: string;
-  apiKey: string;
-  stateDir: string;
-  adapter: RelayAdapter<TEvent>;
-  logger: (line: string) => void;
-  /** Test seam. Defaults to global fetch. */
-  fetchImpl?: typeof fetch;
-  /** Test seam: override long-poll wait (default 25s). */
-  pollWaitMs?: number;
-  /**
-   * Desired-revision generation for hosted engines. Sent as
-   * `x-agent-serve-generation` so the control plane can fence zombies after
-   * a redeploy. Defaults to `process.env.AGENT_SERVE_GENERATION` when set.
-   */
-  deploymentGeneration?: number;
-}
-
-/** Must match server-shared `AGENT_SERVE_GENERATION_HEADER`. */
-export const AGENT_SERVE_GENERATION_HEADER = "x-agent-serve-generation";
-
-/** Must match server-shared `AGENT_SERVE_GENERATION_ENV_VAR`. */
-export const AGENT_SERVE_GENERATION_ENV_VAR = "AGENT_SERVE_GENERATION";
-
-export function resolveAgentServeDeploymentGeneration(explicit?: number): number | undefined {
-  if (explicit !== undefined && Number.isSafeInteger(explicit) && explicit > 0) {
-    return explicit;
-  }
-  const raw = process.env[AGENT_SERVE_GENERATION_ENV_VAR]?.trim();
-  if (raw === undefined || raw.length === 0) {
-    return undefined;
-  }
-  if (!/^\d+$/.test(raw)) {
-    return undefined;
-  }
-  const parsed = Number(raw);
-  if (!Number.isSafeInteger(parsed) || parsed <= 0) {
-    return undefined;
-  }
-  return parsed;
-}
-
-export class CursorRelayCore<TEvent extends { offset: string }> {
-  private running = false;
-  private abort: AbortController | undefined;
-  private registerTimer: NodeJS.Timeout | undefined;
-  private consumePromise: Promise<void> | undefined;
-  private readonly offsetStore: RelayOffsetStore;
-  private readonly fetchImpl: typeof fetch;
-  private readonly deploymentGeneration: number | undefined;
-  private consumerId = "";
-  /** undefined until the first registration, so a clean first success logs. */
-  private lastRegistrationLog: string | undefined;
-  /** Whether any registration succeeded (gates the stop-time deregister). */
-  private registeredOnce = false;
-  /**
-   * The in-flight heartbeat re-registration, if any. `stop()` awaits it
-   * before deregistering so a just-sent heartbeat cannot land after the
-   * deregistration PUT and resurrect the registration for a full TTL.
-   */
-  private heartbeatPromise: Promise<boolean> | undefined;
-
-  constructor(private readonly options: CursorRelayCoreOptions<TEvent>) {
-    this.offsetStore = new RelayOffsetStore(options.stateDir);
-    this.fetchImpl = options.fetchImpl ?? fetch;
-    this.deploymentGeneration = resolveAgentServeDeploymentGeneration(options.deploymentGeneration);
-  }
-
-  start(): void {
-    if (this.running) return;
-    this.running = true;
-    this.abort = new AbortController();
-    this.consumePromise = this.run();
-  }
-
-  /**
-   * Registration-gated lifecycle: no anchor and no consumption until one
-   * registration succeeded — anchoring "now" while unsubscribed would
-   * silently miss every delivery in between.
-   */
-  private async run(): Promise<void> {
-    await this.resolveConsumerId();
-    const registered = await this.registerUntilSuccess();
-    if (!registered) return;
-    this.registerTimer = setInterval(() => {
-      this.heartbeatPromise = this.registerOnce();
-    }, DEFAULT_REGISTER_INTERVAL_MS);
-    this.registerTimer.unref?.();
-    await this.consumeLoop();
-  }
-
-  /**
-   * Durable consumer identity for this state root (memoized), so this host's
-   * registrations never clobber a sibling consumer's on the same key and
-   * survive restarts. Public so callers can bind transports with it before
-   * `start()` (the Slack relay proxies outbound calls under this id).
-   */
-  async resolveConsumerId(): Promise<string> {
-    if (this.consumerId !== "") {
-      return this.consumerId;
-    }
-    const filePath = join(this.options.stateDir, "consumer-id");
-    try {
-      const existing = (await readFile(filePath, "utf8")).trim();
-      if (CONSUMER_ID_PATTERN.test(existing)) {
-        this.consumerId = existing;
-        return existing;
-      }
-    } catch {
-      // Missing or unreadable: mint below.
-    }
-    const minted = randomUUID();
-    try {
-      await mkdir(this.options.stateDir, { recursive: true });
-      const tmpPath = `${filePath}.tmp`;
-      await writeFile(tmpPath, `${minted}\n`, "utf8");
-      await rename(tmpPath, filePath);
-    } catch (error) {
-      this.log(
-        `could not persist consumer id (${describeRelayError(error)}); using an ephemeral one for this run`,
-      );
-    }
-    this.consumerId = minted;
-    return minted;
-  }
-
-  async stop(): Promise<void> {
-    if (!this.running) return;
-    this.running = false;
-    if (this.registerTimer !== undefined) {
-      clearInterval(this.registerTimer);
-      this.registerTimer = undefined;
-    }
-    this.abort?.abort();
-    // Bounded wait: server close must never hang on a poll that ignores the
-    // abort (offsets are saved as events are processed, so cutting the loop
-    // loose loses nothing).
-    await Promise.race([
-      this.consumePromise?.catch(() => {}),
-      new Promise<void>(resolve => {
-        const timer = setTimeout(resolve, 2_000);
-        timer.unref?.();
-      }),
-    ]);
-    // A heartbeat re-registration may be in flight (its fetch was just
-    // aborted); let it settle so it cannot land after the deregistration.
-    await this.heartbeatPromise?.catch(() => {});
-    await this.deregister();
-  }
-
-  /**
-   * Best-effort empty-scope PUT on clean stop, so this consumer's
-   * registration is dropped immediately instead of lingering until its
-   * server-side TTL. A ghost registration keeps this host's agent names
-   * live and makes name routing ambiguous for a redeployed sibling with a
-   * fresh consumer id. Failures only log — the TTL still cleans up.
-   */
-  private async deregister(): Promise<void> {
-    const adapter = this.options.adapter;
-    if (
-      adapter.buildDeregistrationBody === undefined ||
-      !this.registeredOnce ||
-      this.consumerId === ""
-    ) {
-      return;
-    }
-    const url = `${this.options.baseUrl.replace(/\/+$/, "")}${adapter.subscribePath}`;
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), DEREGISTER_TIMEOUT_MS);
-    timer.unref?.();
-    try {
-      const response = await this.fetchImpl(url, {
-        method: "PUT",
-        headers: {
-          authorization: `Bearer ${this.options.apiKey}`,
-          "content-type": "application/json",
-          ...(this.deploymentGeneration === undefined
-            ? {}
-            : {
-                [AGENT_SERVE_GENERATION_HEADER]: String(this.deploymentGeneration),
-              }),
-        },
-        body: JSON.stringify(adapter.buildDeregistrationBody(this.consumerId)),
-        signal: controller.signal,
-      });
-      if (response.ok) {
-        this.log("deregistered on shutdown");
-      } else {
-        this.log(`deregistration failed: ${response.status} (registration lapses by TTL)`);
-      }
-    } catch (error) {
-      this.log(`deregistration failed: ${describeRelayError(error)} (registration lapses by TTL)`);
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-
-  private log(line: string): void {
-    this.options.logger(`${LOG_PREFIX} ${this.options.adapter.logPrefix}: ${line}`);
-  }
-
-  private async request(method: string, path: string, body?: unknown): Promise<Response> {
-    const url = `${this.options.baseUrl.replace(/\/+$/, "")}${path}`;
-    return this.fetchImpl(url, {
-      method,
-      headers: {
-        authorization: `Bearer ${this.options.apiKey}`,
-        ...(body === undefined ? {} : { "content-type": "application/json" }),
-        ...(this.deploymentGeneration === undefined
-          ? {}
-          : {
-              [AGENT_SERVE_GENERATION_HEADER]: String(this.deploymentGeneration),
-            }),
-      },
-      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
-      ...(this.abort === undefined ? {} : { signal: this.abort.signal }),
-    });
-  }
-
-  /** Retry registration with backoff until it succeeds or the relay stops. */
-  private async registerUntilSuccess(): Promise<boolean> {
-    let backoffMs = MIN_BACKOFF_MS;
-    while (this.running) {
-      if (await this.registerOnce()) {
-        return true;
-      }
-      await this.sleep(backoffMs);
-      backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
-    }
-    return false;
-  }
-
-  /**
-   * Register (or refresh) via the adapter. Returns true when the server
-   * accepted the registration (individual scopes may still have failed
-   * validation — the adapter logs those).
-   */
-  private async registerOnce(): Promise<boolean> {
-    if (!this.running) return false;
-    try {
-      const response = await this.request(
-        "PUT",
-        this.options.adapter.subscribePath,
-        this.options.adapter.buildRegistrationBody(this.consumerId),
-      );
-      if (!response.ok) {
-        const text = await response.text().catch(() => "");
-        this.logRegistrationOutcome([
-          `registration failed: ${response.status} ${text.slice(0, 300)}`,
-        ]);
-        return false;
-      }
-      const json = (await response.json()) as unknown;
-      this.logRegistrationOutcome(this.options.adapter.applyRegistrationResponse(json));
-      this.registeredOnce = true;
-      return true;
-    } catch (error) {
-      if (this.isAbort(error)) return false;
-      this.logRegistrationOutcome([`registration error: ${describeRelayError(error)}`]);
-      return false;
-    }
-  }
-
-  /** Log registration outcome lines only when they change (heartbeat-quiet). */
-  private logRegistrationOutcome(lines: string[]): void {
-    const key = lines.join("\n");
-    if (key === this.lastRegistrationLog) return;
-    this.lastRegistrationLog = key;
-    for (const line of lines) {
-      this.log(line);
-    }
-  }
-
-  private async consumeLoop(): Promise<void> {
-    let backoffMs = MIN_BACKOFF_MS;
-    let offset = await this.offsetStore.load();
-    let announcedGap = false;
-
-    while (this.running) {
-      try {
-        if (offset === undefined) {
-          // First run: anchor at "now" so the agent does not replay (and
-          // react to) the retained backlog of old events.
-          const anchorResponse = await this.request(
-            "GET",
-            `${this.options.adapter.pollPath}?after=%24&limit=1`,
-          );
-          if (!anchorResponse.ok) {
-            backoffMs = await this.backoffAfterHttpFailure(anchorResponse, backoffMs);
-            continue;
-          }
-          const anchor = (await anchorResponse.json()) as PollResponse<TEvent>;
-          offset = anchor.nextOffset;
-          await this.offsetStore.save(offset);
-          this.log(`anchored at offset "${offset}"`);
-          backoffMs = MIN_BACKOFF_MS;
-          continue;
-        }
-
-        const query = new URLSearchParams({
-          after: offset,
-          limit: String(DEFAULT_POLL_LIMIT),
-          waitMs: String(this.options.pollWaitMs ?? DEFAULT_POLL_WAIT_MS),
-        });
-        const response = await this.request(
-          "GET",
-          `${this.options.adapter.pollPath}?${query.toString()}`,
-        );
-        if (!response.ok) {
-          backoffMs = await this.backoffAfterHttpFailure(response, backoffMs);
-          continue;
-        }
-        const poll = (await response.json()) as PollResponse<TEvent>;
-        backoffMs = MIN_BACKOFF_MS;
-
-        if (poll.gapDetected && !announcedGap) {
-          announcedGap = true;
-          this.log(
-            "gap detected: events may have been trimmed while this host was offline; resuming from the oldest retained event",
-          );
-        }
-        if (poll.events.length > 0) {
-          announcedGap = false;
-        }
-
-        for (const event of poll.events) {
-          if (!this.running) break;
-          // At-least-once dedupe: never re-dispatch at or before the last
-          // processed offset (reads are exclusive-after, so this only fires
-          // on replay after a crash between dispatch and save).
-          if (compareStreamOffsets(event.offset, offset) <= 0) continue;
-          if (this.options.adapter.shouldDispatch(event)) {
-            await this.dispatchWithRetry(event);
-          }
-          offset = event.offset;
-        }
-        if (poll.nextOffset !== "" && compareStreamOffsets(poll.nextOffset, offset) > 0) {
-          offset = poll.nextOffset;
-        }
-        if (poll.events.length > 0) {
-          await this.offsetStore.save(offset);
-        } else {
-          await this.sleep(DEFAULT_IDLE_POLL_DELAY_MS);
-        }
-      } catch (error) {
-        if (this.isAbort(error)) return;
-        this.log(`poll error: ${describeRelayError(error)}`);
-        await this.sleep(backoffMs);
-        backoffMs = Math.min(backoffMs * 2, MAX_BACKOFF_MS);
-      }
-    }
-  }
-
-  /**
-   * Dispatch one event with a small bounded retry before the offset advances
-   * past it. Transient local failures (e.g. a connection reset while POSTing
-   * to the channel) used to drop the event outright; a poison event still
-   * only costs {@link DISPATCH_ATTEMPTS} tries and is then skipped, keeping
-   * at-least-once semantics without a retry loop.
-   */
-  private async dispatchWithRetry(event: TEvent): Promise<void> {
-    for (let attempt = 1; attempt <= DISPATCH_ATTEMPTS; attempt++) {
-      if (attempt > 1 && !this.running) {
-        this.log(`dispatch abandoned at offset ${event.offset}: relay stopping`);
-        return;
-      }
-      try {
-        await this.options.adapter.dispatch(event);
-        return;
-      } catch (error) {
-        if (attempt === DISPATCH_ATTEMPTS) {
-          this.log(
-            `dispatch failed at offset ${event.offset} after ${attempt} attempts: ${describeRelayError(error)}`,
-          );
-          return;
-        }
-        this.log(
-          `dispatch attempt ${attempt} failed at offset ${event.offset}: ${describeRelayError(error)}; retrying`,
-        );
-        await this.sleep(
-          DISPATCH_RETRY_DELAYS_MS[Math.min(attempt - 1, DISPATCH_RETRY_DELAYS_MS.length - 1)],
-        );
-      }
-    }
-  }
-
-  /** Log the failure, sleep, and return the backoff for the NEXT failure. */
-  private async backoffAfterHttpFailure(response: Response, backoffMs: number): Promise<number> {
-    // 409 = generation fence (stale resident after redeploy). Same long
-    // backoff as auth: retrying every second cannot heal a wrong generation.
-    const isAuthOrFenceFailure =
-      response.status === 401 || response.status === 403 || response.status === 409;
-    const sleepMs = isAuthOrFenceFailure ? AUTH_FAILURE_BACKOFF_MS : backoffMs;
-    const text = await response.text().catch(() => "");
-    this.log(
-      `poll failed: ${response.status} ${text.slice(0, 300)} (retrying in ${Math.round(sleepMs / 1000)}s)`,
-    );
-    await this.sleep(sleepMs);
-    return isAuthOrFenceFailure ? AUTH_FAILURE_BACKOFF_MS : Math.min(backoffMs * 2, MAX_BACKOFF_MS);
-  }
-
-  private sleep(ms: number): Promise<void> {
-    return new Promise(resolve => {
-      const signal = this.abort?.signal;
-      if (signal?.aborted === true) {
-        resolve();
-        return;
-      }
-      const finish = (): void => {
-        clearTimeout(timer);
-        signal?.removeEventListener("abort", finish);
-        resolve();
-      };
-      const timer = setTimeout(finish, ms);
-      timer.unref?.();
-      signal?.addEventListener("abort", finish, { once: true });
-    });
-  }
-
-  private isAbort(error: unknown): boolean {
-    return !this.running || (error instanceof Error && error.name === "AbortError");
-  }
-}

package/src/internal/deferred-channel-session.ts

@@ -1,61 +0,0 @@
-import type { ChannelSession } from "../types.js";
-
-const deferredSessions = new WeakSet<ChannelSession>();
-
-/**
- * Authored code touched a member of the deferred handle that needs the live
- * session. This is deterministic (the session never exists during admission),
- * so the admission route surfaces it as a non-retryable 422 rather than a
- * retryable failure.
- */
-export class DeferredChannelSessionError extends Error {
-  constructor(member: string) {
-    super(
-      `ChannelSession.${member} is not available on a send() captured ` +
-        "during hosted admission: the control plane allocates the session " +
-        "(and runs the turn) only after this delivery is acknowledged, so " +
-        "the handle cannot observe it yet. Move work that needs the live " +
-        "session into the session turn instead.",
-    );
-  }
-}
-
-function unavailable(member: string): never {
-  throw new DeferredChannelSessionError(member);
-}
-
-/**
- * Inert `ChannelSession` returned by the hosted-admission `send` stub: every
- * member fails loudly via {@link DeferredChannelSessionError}. Caveat: new
- * OPTIONAL members added to `ChannelSession` slip through this factory
- * silently (reads return `undefined`) until a throwing getter is added here.
- */
-export function createDeferredChannelSession(): ChannelSession {
-  const session: ChannelSession = {
-    get id(): string {
-      return unavailable("id");
-    },
-    get continuationToken(): string | null {
-      return unavailable("continuationToken");
-    },
-    get isNew(): boolean {
-      return unavailable("isNew");
-    },
-    get coalesced(): boolean | undefined {
-      return unavailable("coalesced");
-    },
-    get info(): ChannelSession["info"] {
-      return unavailable("info");
-    },
-    getEventStream: async () => unavailable("getEventStream()"),
-    waitForCompletion: async () => unavailable("waitForCompletion()"),
-    setContinuationToken: async () => unavailable("setContinuationToken()"),
-  };
-  deferredSessions.add(session);
-  return session;
-}
-
-/** True when `send()` returned a hosted-admission capture handle. */
-export function isDeferredChannelSession(session: ChannelSession): boolean {
-  return deferredSessions.has(session);
-}