@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/cursor/bound-secret-file.ts

@@ -1,101 +0,0 @@
-/**
- * Destroying a hosted v2 task-bind secret file after its value is in
- * `process.env`.
- *
- * The bind files under `/run/cursor/secrets/` are an IPC channel, not a
- * credential store: the control plane cannot set another process's
- * environment, so it drops the value on tmpfs and July copies it into
- * `process.env` before anything authored runs. Once that copy succeeds the
- * on-disk value is pure liability — authored agent code runs in this pod and
- * can read any world-readable path.
- *
- * Unlink is preferred. It is not always available: pod-daemon writes the
- * files as root, and removing a directory entry needs write permission on
- * `/run/cursor/secrets`, which is root-owned. Making that directory writable
- * by the guest is not the fix — untrusted guest code could then plant a
- * symlink that the next root-side bind write would follow. The binder instead
- * relaxes the two secret files themselves so the guest can truncate them, and
- * this module falls back to a zero-length overwrite. Both readers treat an
- * empty bind file as unsigned.
- */
-
-import { closeSync, fsyncSync, ftruncateSync, openSync, readFileSync, unlinkSync } from "node:fs";
-
-/**
- * What happened to a bind file. Only `readable` is a failure: the secret
- * survived the consume and callers must not run authored code.
- */
-export type BoundSecretFileDisposal =
-  /** Nothing recoverable was there — missing, empty, or unreadable already. */
-  | { state: "absent" }
-  /** Directory entry removed. */
-  | { state: "unlinked" }
-  /** Truncated to zero length and fsynced; an empty file remains. */
-  | { state: "wiped" }
-  /** Still recoverable by a later `readFile`. */
-  | { state: "readable"; reason: string };
-
-/**
- * Whether a later `readFile` of this path could still recover a secret.
- * A read failure counts as unrecoverable: this process just read the file
- * during hydrate, so losing access to it means the content is gone.
- */
-export function boundSecretFileIsReadable(path: string): boolean {
-  try {
-    return readFileSync(path, "utf8").trim() !== "";
-  } catch {
-    return false;
-  }
-}
-
-function errorReason(error: unknown): string {
-  const code = (error as { code?: unknown } | undefined)?.code;
-  return typeof code === "string" ? code : "unknown";
-}
-
-/**
- * Remove a bind file's contents from disk, preferring unlink over an empty
- * leftover. Callers must have already copied the value into `process.env`:
- * this is destructive and there is no second bind until the control plane
- * rewrites the file before the next hosted request.
- */
-export function destroyBoundSecretFile(path: string): BoundSecretFileDisposal {
-  if (!boundSecretFileIsReadable(path)) {
-    // Nothing recoverable, so nothing to fail over. Still try to clear the
-    // empty leftover: whether that succeeds does not change the disposal,
-    // because there is no secret here either way.
-    try {
-      unlinkSync(path);
-    } catch {
-      // Already gone, or a directory the guest cannot write. Both are fine.
-    }
-    return { state: "absent" };
-  }
-  let unlinkReason: string | undefined;
-  try {
-    unlinkSync(path);
-    if (!boundSecretFileIsReadable(path)) {
-      return { state: "unlinked" };
-    }
-    unlinkReason = "recreated";
-  } catch (error) {
-    unlinkReason = errorReason(error);
-  }
-  try {
-    const fd = openSync(path, "r+");
-    try {
-      ftruncateSync(fd, 0);
-      fsyncSync(fd);
-    } finally {
-      closeSync(fd);
-    }
-  } catch (error) {
-    return {
-      state: "readable",
-      reason: `unlink ${unlinkReason}, truncate ${errorReason(error)}`,
-    };
-  }
-  return boundSecretFileIsReadable(path)
-    ? { state: "readable", reason: `unlink ${unlinkReason}, truncate no-op` }
-    : { state: "wiped" };
-}

package/src/internal/cursor/credentials.ts

@@ -1,560 +0,0 @@
-/**
- * Cursor account credentials for the agent-serve host.
- *
- * Exactly one kind of secret exists at runtime: a **personal Cursor user API
- * key**. Two ways to obtain it, one code path after that:
- *
- * - `agent-sdk login` runs the same PKCE browser flow as `cursor-agent`
- *   and Sand, then uses the short-lived session once to mint a named,
- *   dashboard-revocable user API key — only the key is stored.
- * - `CURSOR_API_KEY` (or `serve({ apiKey })`) wins over the stored key, so
- *   CI and hosted deployments stay env-driven.
- * - `CURSOR_API_KEY_FILE` (or the hosted default path) is next: freeze bind
- *   drops the key at task time without restarting July. On the hosted path
- *   that file is consumed into `CURSOR_API_KEY` and destroyed before
- *   anything authored runs, so this fallback is there for local,
- *   self-hosted, and the unsigned window before the first bind.
- * - Stored `july login` is last. Same order for hosted and self-hosted:
- *   option → env → file → login.
- *
- * There is deliberately no session-token storage, refresh-token rotation, or
- * cross-tool credential sharing here: short-lived access tokens are minted
- * on demand from the API key (see `backend-client.ts`).
- */
-
-import { createHash, randomBytes, randomUUID } from "node:crypto";
-import { readFileSync } from "node:fs";
-import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import { z } from "zod";
-import { CLI_COMMAND_NAME } from "../distribution.js";
-import { type BoundSecretFileDisposal, destroyBoundSecretFile } from "./bound-secret-file.js";
-
-export const DEFAULT_CURSOR_BACKEND_URL = "https://api2.cursor.sh";
-export const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
-const DEFAULT_CURSOR_WEBSITE_URL = "https://cursor.com";
-
-/**
- * Base URL for main-backend-only routes (key exchange, DashboardService —
- * these 404 on api.cursor.com). Hosted pods pin `CURSOR_API_BASE_URL` to the
- * external API, so `AGENT_SERVE_CURSOR_BACKEND_URL` re-pins this family
- * there. Deliberately namespaced: pod env propagates to the SDK harness,
- * which reads the generic `CURSOR_BACKEND_URL` for its own hosts.
- */
-export function cursorBackendUrl(): string {
-  return trimTrailingSlash(
-    process.env.AGENT_SERVE_CURSOR_BACKEND_URL ??
-      process.env.CURSOR_API_BASE_URL ??
-      DEFAULT_CURSOR_BACKEND_URL,
-  );
-}
-
-/**
- * External API base URL for routes served only by the external-api
- * microlith (`/internal/agent-serve/*`, `/v0/grokbot/*`, engine aliases).
- * In production these are mounted on api.cursor.com and 404 on
- * api2.cursor.sh, so the deploy surface needs its own default.
- * `CURSOR_API_BASE_URL` still overrides everything for local dev, where
- * one server mounts all routes.
- */
-export function cursorExternalApiUrl(): string {
-  return trimTrailingSlash(process.env.CURSOR_API_BASE_URL ?? DEFAULT_CURSOR_EXTERNAL_API_URL);
-}
-
-/** Website base URL for the login deep link (`CURSOR_WEBSITE_URL` override). */
-export function cursorWebsiteUrl(): string {
-  return trimTrailingSlash(process.env.CURSOR_WEBSITE_URL ?? DEFAULT_CURSOR_WEBSITE_URL);
-}
-
-function trimTrailingSlash(url: string): string {
-  return url.endsWith("/") ? url.slice(0, -1) : url;
-}
-
-// ============================================================================
-// Stored credential (one file, one secret)
-// ============================================================================
-
-const storedCredentialsSchema: z.ZodObject<
-  { backendUrl: z.ZodString; apiKey: z.ZodString },
-  "strip"
-> = z.object({
-  /** Backend the key was minted against; keys never cross backends. */
-  backendUrl: z.string(),
-  apiKey: z.string().min(1),
-});
-
-export type StoredCredentials = z.infer<typeof storedCredentialsSchema>;
-
-/**
- * `~/.config/agent-serve/` (honoring `XDG_CONFIG_HOME`), the host-level
- * config directory for credentials and the update-check cache.
- * `AGENT_SERVE_CONFIG_DIR` pins the directory outright (tests, containers).
- */
-export function configDirPath(): string {
-  return (
-    process.env.AGENT_SERVE_CONFIG_DIR ??
-    join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "agent-serve")
-  );
-}
-
-/** `<configDir>/credentials.json` (0600). */
-export function credentialsFilePath(): string {
-  return join(configDirPath(), "credentials.json");
-}
-
-function parseStoredCredentialsJson(raw: string): StoredCredentials | undefined {
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(raw) as unknown;
-  } catch {
-    return undefined;
-  }
-  const credentials = storedCredentialsSchema.safeParse(parsed);
-  if (!credentials.success) {
-    return undefined;
-  }
-  return {
-    backendUrl: trimTrailingSlash(credentials.data.backendUrl),
-    apiKey: credentials.data.apiKey,
-  };
-}
-
-export function readStoredCredentialsSync(): StoredCredentials | undefined {
-  let raw: string;
-  try {
-    raw = readFileSync(credentialsFilePath(), "utf8");
-  } catch {
-    return undefined;
-  }
-  return parseStoredCredentialsJson(raw);
-}
-
-export async function readStoredCredentials(): Promise<StoredCredentials | undefined> {
-  let raw: string;
-  try {
-    raw = await readFile(credentialsFilePath(), "utf8");
-  } catch {
-    return undefined;
-  }
-  return parseStoredCredentialsJson(raw);
-}
-
-export async function writeStoredCredentials(credentials: StoredCredentials): Promise<void> {
-  const path = credentialsFilePath();
-  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-  await writeFile(path, `${JSON.stringify(credentials, null, 2)}\n`, {
-    mode: 0o600,
-  });
-  // writeFile mode only applies on create; clamp pre-existing files too.
-  await chmod(path, 0o600);
-}
-
-export async function clearStoredCredentials(): Promise<boolean> {
-  try {
-    await rm(credentialsFilePath());
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// ============================================================================
-// Resolution (option > env > file > service account > stored login)
-// ============================================================================
-
-export type ApiKeySource = "option" | "env" | "file" | "service-account" | "login";
-
-export interface ResolvedApiKey {
-  apiKey: string;
-  source: ApiKeySource;
-  backendUrl: string;
-}
-
-/**
- * Hosted task-bind path. Not a secret: the snapshot may name this path.
- * The binder writes the key here after restore, and hosted admission /
- * execution consume it into `process.env.CURSOR_API_KEY` and destroy the
- * file before authored work — this is an IPC handoff, not a credential
- * source July keeps reading. Override with `CURSOR_API_KEY_FILE`. A missing
- * file is unsigned — self-hosted then uses `CURSOR_API_KEY` or stored login.
- */
-export const DEFAULT_CURSOR_API_KEY_FILE: string = "/run/cursor/secrets/CURSOR_API_KEY";
-
-/**
- * Read `CURSOR_API_KEY_FILE` (or {@link DEFAULT_CURSOR_API_KEY_FILE} when
- * unset). Missing/empty files are unsigned, not an error — freeze bake
- * listens before the binder drops the key; self-hosted falls through to
- * env or login.
- */
-export function resolveCursorApiKeyFilePath(
-  filePath?: string,
-  env: NodeJS.ProcessEnv = process.env,
-): string {
-  const configured = filePath ?? env.CURSOR_API_KEY_FILE;
-  return configured !== undefined && configured.trim() !== ""
-    ? configured.trim()
-    : DEFAULT_CURSOR_API_KEY_FILE;
-}
-
-export function readApiKeyFromFile(filePath?: string): string | undefined {
-  const path = resolveCursorApiKeyFilePath(filePath);
-  try {
-    const raw = readFileSync(path, "utf8").trim();
-    return raw === "" ? undefined : raw;
-  } catch {
-    return undefined;
-  }
-}
-
-export type BoundCursorApiKeyConsumeResult = {
-  /** The file supplied `CURSOR_API_KEY` on this call. */
-  applied: boolean;
-  disposal: BoundSecretFileDisposal;
-};
-
-/**
- * Copy the task-bind key file into `process.env.CURSOR_API_KEY`, then destroy
- * the file.
- *
- * Hosted v2 cannot set another process's environment from the binder, so it
- * drops a tmpfs file. Teaching every reader to open that file misses authored
- * `process.env.CURSOR_API_KEY` and leaves a secret on disk. Hosted admission /
- * execution call this once per request, next to the deployment-secrets
- * consume: after it returns, env-only readers work and the key is no longer
- * recoverable from disk. The control plane re-binds before the next request.
- *
- * The env write always happens before the destroy, never the other way round.
- * An already-set `CURSOR_API_KEY` is not overwritten, but the file is still
- * destroyed — env is the source, the file is only the handoff.
- *
- * A `readable` disposal means the secret survived; callers on the hosted path
- * must fail the request rather than run authored code.
- */
-export function consumeBoundCursorApiKey(options?: {
-  filePath?: string;
-  env?: NodeJS.ProcessEnv;
-}): BoundCursorApiKeyConsumeResult {
-  const env = options?.env ?? process.env;
-  const path = resolveCursorApiKeyFilePath(options?.filePath, env);
-  const envKeyAlreadySet = env.CURSOR_API_KEY !== undefined && env.CURSOR_API_KEY.trim() !== "";
-  let raw = "";
-  try {
-    raw = readFileSync(path, "utf8").trim();
-  } catch {
-    return { applied: false, disposal: { state: "absent" } };
-  }
-  if (raw === "") {
-    return { applied: false, disposal: destroyBoundSecretFile(path) };
-  }
-  if (!envKeyAlreadySet) {
-    env.CURSOR_API_KEY = raw;
-  }
-  return {
-    applied: !envKeyAlreadySet,
-    disposal: destroyBoundSecretFile(path),
-  };
-}
-
-function presentEnvKey(name: string): string | undefined {
-  const value = process.env[name];
-  if (value === undefined) {
-    return undefined;
-  }
-  const trimmed = value.trim();
-  return trimmed === "" ? undefined : trimmed;
-}
-
-/**
- * First present source wins. We define the order; operators do not.
- * `--api-key` / `serve({ apiKey })` → `CURSOR_API_KEY` → `CURSOR_API_KEY_FILE`
- * (hosted default path if unset) → `CURSOR_SERVICE_ACCOUNT_KEY` → stored
- * `july login`.
- *
- * A cloud-agent VM often has the service-account key and no user API key.
- * The explicit key and the hosted bind file still win, so a task credential
- * is not replaced by the ambient service-account key. The service-account
- * key wins over a leftover personal login.
- */
-export function resolveApiKeySync(options?: {
-  apiKey?: string;
-  backendUrl?: string;
-}): ResolvedApiKey | undefined {
-  const backendUrl = options?.backendUrl ?? cursorBackendUrl();
-  if (options?.apiKey !== undefined && options.apiKey.trim() !== "") {
-    return { apiKey: options.apiKey.trim(), source: "option", backendUrl };
-  }
-  const envKey = presentEnvKey("CURSOR_API_KEY");
-  if (envKey !== undefined) {
-    return { apiKey: envKey, source: "env", backendUrl };
-  }
-  const fileKey = readApiKeyFromFile();
-  if (fileKey !== undefined) {
-    return { apiKey: fileKey, source: "file", backendUrl };
-  }
-  const serviceAccountKey = presentEnvKey("CURSOR_SERVICE_ACCOUNT_KEY");
-  if (serviceAccountKey !== undefined) {
-    return {
-      apiKey: serviceAccountKey,
-      source: "service-account",
-      backendUrl,
-    };
-  }
-  const stored = readStoredCredentialsSync();
-  if (stored !== undefined && stored.backendUrl === backendUrl) {
-    return { apiKey: stored.apiKey, source: "login", backendUrl };
-  }
-  return undefined;
-}
-
-/**
- * {@link resolveApiKeySync} as a Promise for call sites that already await.
- */
-export async function resolveApiKey(options?: {
-  apiKey?: string;
-  backendUrl?: string;
-}): Promise<ResolvedApiKey | undefined> {
-  return resolveApiKeySync(options);
-}
-
-/** One-line hint for "no credentials" errors, shared across surfaces. */
-export const SIGN_IN_HINT: string = `Run \`${CLI_COMMAND_NAME} login\` (or set CURSOR_API_KEY / CURSOR_API_KEY_FILE / CURSOR_SERVICE_ACCOUNT_KEY / pass serve({ apiKey })).`;
-
-// ============================================================================
-// PKCE browser login (mirrors cursor-agent / Sand)
-// ============================================================================
-
-const loginPollResponseSchema = z.object({ accessToken: z.string() });
-
-export interface LoginStart {
-  /** URL the user opens in a browser to approve the login. */
-  loginUrl: string;
-  uuid: string;
-  verifier: string;
-}
-
-/**
- * Build the `/loginDeepControl` deep link and its PKCE material. The portal
- * completes the login and the backend holds the resulting session until
- * {@link pollForLoginTokens} picks it up with the verifier.
- */
-export function startBrowserLogin(): LoginStart {
-  const verifier = randomBytes(32).toString("base64url");
-  const challenge = createHash("sha256").update(verifier).digest("base64url");
-  const uuid = randomUUID();
-  const url = new URL("/loginDeepControl", `${cursorWebsiteUrl()}/`);
-  url.searchParams.set("challenge", challenge);
-  url.searchParams.set("uuid", uuid);
-  url.searchParams.set("mode", "login");
-  url.searchParams.set("redirectTarget", "cli");
-  return { loginUrl: url.toString(), uuid, verifier };
-}
-
-/** Backend pending-login 404 body from `respondToPollLogin` ("still waiting"). */
-const POLL_PENDING_BODY = "Not found";
-
-/**
- * Why the poll stopped. Distinct cases because collapsing them into
- * "timed out or was cancelled" turned an unsupported-verb 404 into an
- * unfalsifiable "login is slow" report.
- */
-export type LoginPollResult =
-  | { status: "signed_in"; accessToken: string }
-  | { status: "cancelled" }
-  | { status: "timed_out" }
-  | { status: "failed"; message: string };
-
-/**
- * Poll `/auth/poll` until the browser login completes.
- *
- * **POST, with the verifier in the JSON body.** The verifier is redeemable:
- * anyone holding it (plus the uuid) can complete the login and mint a durable
- * user API key, so it must not reach a URL — not the backend's access log, not
- * a proxy's request log, not a terminal. `POST /auth/poll` exists for exactly
- * this reason.
- *
- * A backend that predates that route answers POST with a route-not-found 404.
- * Those get one sticky fallback to `GET /auth/poll?uuid=…&verifier=…` — the
- * shape the vscode client and Sand already use — so the login still works
- * while the backend catches up. The fallback puts the verifier in the query
- * string, which is the exposure POST was added to remove, so it warns; it
- * disappears on its own once the backend serves POST.
- */
-export async function pollForLoginTokens(args: {
-  uuid: string;
-  verifier: string;
-  backendUrl?: string;
-  signal?: AbortSignal;
-  /** Notified once if the backend forces the GET fallback. */
-  logger?: (line: string) => void;
-  /** Test seam; defaults to global fetch. */
-  fetchImpl?: typeof fetch;
-  /** Test seam; defaults to 150 (~24 minutes with the backoff below). */
-  maxAttempts?: number;
-}): Promise<LoginPollResult> {
-  const backendUrl = trimTrailingSlash(args.backendUrl ?? cursorBackendUrl());
-  const fetchImpl = args.fetchImpl ?? fetch;
-  const redact = (text: string): string => truncate(redactVerifier(text, args.verifier));
-
-  const postUrl = `${backendUrl}/auth/poll`;
-  // Only built if the backend leaves us no choice (see the doc comment).
-  const getUrl = (): string => {
-    const url = new URL("/auth/poll", `${backendUrl}/`);
-    url.searchParams.set("uuid", args.uuid);
-    url.searchParams.set("verifier", args.verifier);
-    return url.toString();
-  };
-
-  const maxAttempts = args.maxAttempts ?? 150;
-  let useGet = false;
-  let consecutiveErrors = 0;
-  for (let attempt = 0; attempt < maxAttempts; attempt++) {
-    if (isAborted(args.signal)) {
-      return { status: "cancelled" };
-    }
-    try {
-      const response = useGet
-        ? await fetchImpl(getUrl(), {
-            method: "GET",
-            headers: { accept: "application/json" },
-            ...(args.signal === undefined ? {} : { signal: args.signal }),
-          })
-        : await fetchImpl(postUrl, {
-            method: "POST",
-            headers: {
-              accept: "application/json",
-              "content-type": "application/json",
-            },
-            body: JSON.stringify({ uuid: args.uuid, verifier: args.verifier }),
-            ...(args.signal === undefined ? {} : { signal: args.signal }),
-          });
-
-      if (response.status === 404) {
-        const body = (await response.text()).trim();
-        if (!useGet && body !== POLL_PENDING_BODY) {
-          // Any 404 on POST that is not the pending marker means this backend
-          // has no POST route. Retry the same attempt over GET rather than
-          // guessing at body shapes; GET's handling below is deliberately
-          // lenient, so an unrecognized body cannot strand the login.
-          useGet = true;
-          args.logger?.(
-            `${backendUrl} has no POST /auth/poll; falling back to GET, which puts the single-use login verifier in the request URL (and the backend's access log). It will use POST once the backend deploys that route.`,
-          );
-          continue;
-        }
-        if (useGet && isRouteNotFoundBody(body)) {
-          // Neither verb is served — polling harder cannot fix that.
-          return {
-            status: "failed",
-            message: `${backendUrl} serves neither POST nor GET /auth/poll (404: ${redact(body)})`,
-          };
-        }
-        // Pending: the browser sign-in has not landed yet. On GET this is
-        // deliberately lenient — treating an unrecognized 404 body as fatal is
-        // what made an earlier poll die on its first attempt and call it a
-        // timeout.
-        consecutiveErrors = 0;
-      } else if (!response.ok) {
-        consecutiveErrors++;
-        if (consecutiveErrors >= 3) {
-          return {
-            status: "failed",
-            message: `${backendUrl}/auth/poll kept failing (${response.status}: ${redact((await response.text()).trim())})`,
-          };
-        }
-      } else {
-        const body = loginPollResponseSchema.safeParse(await response.json());
-        if (body.success && body.data.accessToken !== "") {
-          return { status: "signed_in", accessToken: body.data.accessToken };
-        }
-        return {
-          status: "failed",
-          message: `${backendUrl}/auth/poll returned 200 without an accessToken`,
-        };
-      }
-    } catch (error) {
-      if (isAborted(args.signal)) {
-        return { status: "cancelled" };
-      }
-      consecutiveErrors++;
-      if (consecutiveErrors >= 3) {
-        return {
-          status: "failed",
-          message: `could not reach ${backendUrl}/auth/poll (${redact(
-            error instanceof Error ? error.message : String(error),
-          )})`,
-        };
-      }
-    }
-    await sleep(Math.min(1000 * 1.2 ** attempt, 10_000), args.signal);
-  }
-  return { status: "timed_out" };
-}
-
-/**
- * Fastify's route-not-found envelope: `{"message":"Route GET:/auth/poll not
- * found",…}`. Distinct from the backend's pending marker ({@link
- * POLL_PENDING_BODY}), and the only 404 shape on the GET path that is fatal.
- */
-function isRouteNotFoundBody(body: string): boolean {
-  if (!body.startsWith("{")) {
-    return false;
-  }
-  try {
-    const parsed = JSON.parse(body) as { message?: unknown };
-    return (
-      typeof parsed.message === "string" &&
-      /^Route \w+:/.test(parsed.message) &&
-      parsed.message.includes("not found")
-    );
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Keep the verifier out of anything user-visible. Fastify's 404 body echoes the
- * whole request URL — `Route GET:/auth/poll?uuid=…&verifier=… not found` — so
- * echoing a poll response verbatim would print a redeemable secret into the
- * terminal, CI logs, and pasted bug reports.
- */
-function redactVerifier(text: string, verifier: string): string {
-  if (verifier === "") {
-    return text;
-  }
-  let redacted = text.split(verifier).join("[verifier redacted]");
-  const encoded = encodeURIComponent(verifier);
-  if (encoded !== verifier) {
-    redacted = redacted.split(encoded).join("[verifier redacted]");
-  }
-  return redacted;
-}
-
-function truncate(value: string, max = 200): string {
-  return value.length <= max ? value : `${value.slice(0, max)}…`;
-}
-
-// Reads the abort flag through a call boundary so repeated checks across an
-// `await` aren't collapsed by control-flow narrowing (the signal is mutated
-// by another task, so `aborted` really can flip mid-loop).
-function isAborted(signal?: AbortSignal): boolean {
-  return signal?.aborted === true;
-}
-
-function sleep(ms: number, signal?: AbortSignal): Promise<void> {
-  return new Promise(resolve => {
-    if (signal?.aborted === true) {
-      resolve();
-      return;
-    }
-    const timer = setTimeout(() => {
-      signal?.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    const onAbort = (): void => {
-      clearTimeout(timer);
-      resolve();
-    };
-    signal?.addEventListener("abort", onAbort, { once: true });
-  });
-}