@cursor/bdk 0.2.3 → 0.2.5

package/src/internal/distribution.ts

@@ -1,126 +0,0 @@
-/**
- * Distribution facts for the running copy of the framework.
- *
- * The package publishes to npm as `@cursor/bdk`. `bdk` is the primary bin.
- * `agent-sdk` loads the same CLI from a second file so package managers
- * select `bdk` for `npx @cursor/bdk`.
- * In-repo agents still import `@cursor/july`; alias hooks pin both names
- * to this copy.
- */
-
-import { readFileSync } from "node:fs";
-import { join } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-
-/** Published npm package name. */
-export const PACKAGE_NAME = "@cursor/bdk";
-/** Previous published name. In-repo agents still import it. */
-export const FORMER_PACKAGE_NAME = "@cursor/july";
-const HOSTED_WORKTREE_SHA_FILENAME = ".cursor-hosted-worktree-sha";
-const GIT_COMMIT_SHA_RE = /^[0-9a-f]{40,64}$/;
-
-/**
- * Bracketed product tag for stderr / ServeOptions.logger lines
- * (`[agent-sdk] …`, `[agent-sdk/slack] …`).
- */
-export const LOG_PRODUCT = "agent-sdk";
-export const LOG_PREFIX: string = `[${LOG_PRODUCT}]`;
-export const SLACK_LOG_PREFIX: string = `[${LOG_PRODUCT}/slack]`;
-
-/** The bin name, for help text and copy-pasteable hints. */
-export const CLI_COMMAND_NAME = "bdk";
-
-/**
- * True when this module runs from compiled `dist/` output (a published
- * install, or `node dist/bin/agent-serve.js`). False when running from
- * TypeScript source under a host loader (`tsx src/bin/agent-serve.ts`),
- * where tsconfig paths already resolve the framework's import names.
- */
-export function isCompiledDistribution(): boolean {
-  const url = import.meta.url;
-  return !(url.endsWith(".ts") || url.endsWith(".mts"));
-}
-
-/**
- * Package root of the running copy: `src|dist/internal/distribution.*` is
- * always two directories below it.
- */
-export function packageRootDir(): string {
-  return fileURLToPath(new URL("../..", import.meta.url));
-}
-
-interface PackageManifest {
-  version: string;
-  exports: Record<string, { import: string }>;
-}
-
-function packageManifest(): PackageManifest {
-  const raw = readFileSync(join(packageRootDir(), "package.json"), "utf8");
-  return JSON.parse(raw) as PackageManifest;
-}
-
-/** Version of the running package (from its own package.json). */
-export function packageVersion(): string {
-  return packageManifest().version;
-}
-
-/**
- * Git commit of a checkout-built framework distribution. Published npm
- * packages do not carry this marker and return undefined.
- */
-export function packageGitSha(): string | undefined {
-  try {
-    const sha = readFileSync(join(packageRootDir(), "dist", HOSTED_WORKTREE_SHA_FILENAME), "utf8")
-      .trim()
-      .toLowerCase();
-    return GIT_COMMIT_SHA_RE.test(sha) ? sha : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-/** Facts `agent-sdk version` / `--version` print. */
-export interface CliVersionInfo {
-  /** Published npm name (`@cursor/bdk`). */
-  name: string;
-  /** `package.json` version of this install. */
-  version: string;
-}
-
-export function cliVersionInfo(): CliVersionInfo {
-  return {
-    name: PACKAGE_NAME,
-    version: packageVersion(),
-  };
-}
-
-/**
- * Text or JSON for `version` / `--version` / `-V`.
- * Text is the bare `package.json` version (npm-style). `--json` is the
- * complete `{ name, version, cli }` payload.
- */
-export function formatCliVersion(options?: { json?: boolean }): string {
-  const info = cliVersionInfo();
-  if (options?.json === true) {
-    return `${JSON.stringify(info, null, 2)}\n`;
-  }
-  return `${info.version}\n`;
-}
-
-/**
- * `@cursor/bdk[/subpath]` and `@cursor/july[/subpath]` → `file:` URL of this
- * copy's `import` target, for every subpath in the package `exports` map.
- * The published manifest points at `dist/`; Bazel's staged copy points at
- * the in-place `src/` emit, and the aliases follow whichever the manifest says.
- */
-export function frameworkAliases(): Record<string, string> {
-  const root = packageRootDir();
-  const entries: Array<[string, string]> = [];
-  for (const [exportPath, { import: file }] of Object.entries(packageManifest().exports)) {
-    const href = pathToFileURL(join(root, file)).href;
-    const suffix = exportPath === "." ? "" : `/${exportPath.slice(2)}`;
-    entries.push([`${PACKAGE_NAME}${suffix}`, href]);
-    entries.push([`${FORMER_PACKAGE_NAME}${suffix}`, href]);
-  }
-  return Object.fromEntries(entries);
-}

package/src/internal/docs-site.ts

@@ -1,248 +0,0 @@
-/**
- * Serves the built VitePress documentation site at `/docs`.
- *
- * The site is built from the package's `docs/` markdown into `dist/docs/`
- * (`pnpm run docs:build`; VitePress `base` is `/docs/`, so asset URLs
- * resolve under the mount). `serve` auto-builds it when the local
- * vitepress toolchain is present (source checkouts); published installs
- * ship the prebuilt site inside `dist/**`.
- *
- * Set `AGENT_SERVE_DOCS_DIST` to an overlay directory that contains a built
- * site (`index.html`). When that path exists, `/docs` is served from it so a
- * long-lived host (corp ECS) can pick up the published `@cursor/bdk` docs
- * without rebuilding the process image. Requests re-read the path, so an
- * atomic symlink swap is visible without a restart.
- */
-
-import { spawn } from "node:child_process";
-import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { createRequire } from "node:module";
-import { dirname, extname, join, normalize, sep } from "node:path";
-import { fileURLToPath } from "node:url";
-
-import { STATIC_CONTENT_TYPES } from "./playground/static.js";
-
-// src|dist/internal/docs-site.ts → packages/agent-serve/dist/docs/.
-const DOCS_DIST_DIR = fileURLToPath(new URL("../../dist/docs/", import.meta.url));
-
-const DOCS_OVERLAY_ENV = "AGENT_SERVE_DOCS_DIST";
-
-function realDir(dir: string): string | undefined {
-  try {
-    return realpathSync(dir);
-  } catch {
-    return undefined;
-  }
-}
-
-function isInsideRoot(fileReal: string, rootReal: string): boolean {
-  const prefix = rootReal.endsWith(sep) ? rootReal : `${rootReal}${sep}`;
-  return fileReal === rootReal || fileReal.startsWith(prefix);
-}
-
-/**
- * Resolve `candidate` to a regular file whose real path stays under
- * `rootReal`. Follows overlay / site-root symlinks, but refuses a planted
- * symlink (or hard-linked path) that escapes the docs tree.
- */
-function containedFile(candidate: string, rootReal: string): string | undefined {
-  try {
-    const real = realpathSync(candidate);
-    if (!isInsideRoot(real, rootReal) || !statSync(real).isFile()) {
-      return undefined;
-    }
-    return real;
-  } catch {
-    return undefined;
-  }
-}
-
-function hasDocsIndex(distDir: string): boolean {
-  const root = realDir(distDir);
-  if (root === undefined) {
-    return false;
-  }
-  return containedFile(join(distDir, "index.html"), root) !== undefined;
-}
-
-/** Absolute path of the VitePress site shipped in this install (ignores overlay). */
-export function shippedDocsDistDir(): string {
-  return DOCS_DIST_DIR;
-}
-
-/**
- * Directory `/docs` is served from. Prefers `AGENT_SERVE_DOCS_DIST` when that
- * overlay has a built site; otherwise the install's `dist/docs/`.
- */
-export function docsDistDir(): string {
-  const overlay = process.env[DOCS_OVERLAY_ENV]?.trim();
-  if (overlay !== undefined && overlay !== "" && hasDocsIndex(overlay)) {
-    return overlay;
-  }
-  return DOCS_DIST_DIR;
-}
-
-/** Whether a built docs site is available at `distDir` (overlay or shipped). */
-export function docsSiteExists(distDir: string = docsDistDir()): boolean {
-  return hasDocsIndex(distDir);
-}
-
-/**
- * Resolve a request path under the docs mount to a file inside the built
- * site, or undefined when it escapes the site or does not exist. VitePress
- * emits one `.html` per page, so clean URLs resolve through the chain:
- * exact file → directory `index.html` → `<path>.html`.
- */
-export function resolveDocsFile(
-  requestPath: string,
-  distDir: string = docsDistDir(),
-): string | undefined {
-  const decoded = requestPath
-    .split("/")
-    .filter(part => part !== "")
-    .join("/");
-  const normalized = normalize(decoded === "" ? "." : decoded);
-  if (normalized.startsWith("..") || normalized.includes(`..${sep}`)) {
-    return undefined;
-  }
-  const rootReal = realDir(distDir);
-  if (rootReal === undefined) {
-    return undefined;
-  }
-  const root = distDir.endsWith(sep) ? distDir : `${distDir}${sep}`;
-  const base = join(root, normalized);
-  if (base !== root.slice(0, -1) && !base.startsWith(root)) {
-    return undefined;
-  }
-  for (const candidate of [base, join(base, "index.html"), `${base}.html`]) {
-    const file = containedFile(candidate, rootReal);
-    if (file !== undefined) {
-      return file;
-    }
-  }
-  return undefined;
-}
-
-/** Serve one path from the built docs site. */
-export function renderDocsFile(requestPath: string, distDir: string = docsDistDir()): Response {
-  if (!docsSiteExists(distDir)) {
-    return new Response(fallbackHtml(), {
-      status: 503,
-      headers: { "content-type": "text/html; charset=utf-8" },
-    });
-  }
-  const filePath = resolveDocsFile(requestPath, distDir);
-  if (filePath === undefined) {
-    const root = realDir(distDir);
-    const notFound =
-      root === undefined ? undefined : containedFile(join(distDir, "404.html"), root);
-    return new Response(notFound !== undefined ? readFileSync(notFound, "utf8") : "Not found", {
-      status: 404,
-      headers: { "content-type": "text/html; charset=utf-8" },
-    });
-  }
-  const body = readFileSync(filePath);
-  const type = STATIC_CONTENT_TYPES[extname(filePath).toLowerCase()] ?? "application/octet-stream";
-  const hashed = filePath.includes(`${sep}assets${sep}`);
-  return new Response(new Uint8Array(body), {
-    headers: {
-      "content-type": type,
-      // VitePress content-hashes everything under assets/; pages are not
-      // hashed and must revalidate so rebuilt docs show up.
-      "cache-control": hashed ? "public, max-age=31536000, immutable" : "no-cache",
-    },
-  });
-}
-
-/**
- * If the docs site is missing and the local vitepress toolchain is
- * available, build it. No-op when the site already exists. Soft-skips
- * (logs) when vitepress is absent so published installs without a
- * prebuilt site still start.
- */
-export async function ensureDocsSiteBundle(
-  logger: (line: string) => void = console.log,
-): Promise<void> {
-  if (docsSiteExists(DOCS_DIST_DIR)) {
-    return;
-  }
-  const toolchain = resolveDocsToolchain();
-  if (toolchain === undefined) {
-    logger(
-      "[agent-sdk] docs site missing and vitepress toolchain unavailable; /docs will show a build hint",
-    );
-    return;
-  }
-  logger("[agent-sdk] building docs site (vitepress)...");
-  const code = await new Promise<number>((resolve, reject) => {
-    const child = spawn(process.execPath, [toolchain.vitepressCli, "build", "docs"], {
-      cwd: toolchain.packageRoot,
-      env: process.env,
-      stdio: "inherit",
-    });
-    child.on("error", reject);
-    child.on("exit", exitCode => resolve(exitCode ?? 1));
-  });
-  if (code !== 0) {
-    throw new Error(`docs vitepress build failed (exit ${code})`);
-  }
-  if (!docsSiteExists(DOCS_DIST_DIR)) {
-    throw new Error("docs vitepress build finished but dist/docs/index.html is missing");
-  }
-  logger("[agent-sdk] docs site build complete");
-}
-
-interface DocsToolchain {
-  packageRoot: string;
-  vitepressCli: string;
-}
-
-/** True when docs sources + a resolvable `vitepress` CLI are present. */
-function resolveDocsToolchain(): DocsToolchain | undefined {
-  const packageRoot = fileURLToPath(new URL("../..", import.meta.url));
-  if (!existsSync(join(packageRoot, "docs", ".vitepress", "config.mts"))) {
-    return undefined;
-  }
-  try {
-    const require = createRequire(join(packageRoot, "package.json"));
-    const pkgPath = require.resolve("vitepress/package.json");
-    const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as {
-      bin?: string | Record<string, string>;
-    };
-    const binRel =
-      typeof pkg.bin === "string" ? pkg.bin : (pkg.bin?.vitepress ?? "bin/vitepress.js");
-    const vitepressCli = join(dirname(pkgPath), binRel);
-    return existsSync(vitepressCli) ? { packageRoot, vitepressCli } : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-function fallbackHtml(): string {
-  return `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>agent-sdk docs</title>
-    <style>
-      body { margin: 0; background: #0e1116; color: #e6edf3; font: 14px/1.6 ui-sans-serif, system-ui, sans-serif; }
-      .box { max-width: 640px; margin: 64px auto; padding: 0 24px; }
-      code { background: #1b212b; padding: 2px 6px; border-radius: 6px; font-family: ui-monospace, monospace; }
-      h1 { font-size: 18px; }
-    </style>
-  </head>
-  <body>
-    <div class="box">
-      <h1>Docs site not built</h1>
-      <p>
-        The documentation site has not been built yet. <code>agent-sdk serve</code>
-        and <code>agent-sdk docs</code> auto-build it when the vitepress toolchain
-        is available; otherwise run <code>pnpm run docs:build</code> from
-        <code>packages/agent-serve</code>. The markdown sources are always
-        readable under <code>docs/</code>.
-      </p>
-    </div>
-  </body>
-</html>`;
-}

package/src/internal/duration.ts

@@ -1,37 +0,0 @@
-/**
- * Relative duration strings for reminder schedules (`every` / `delay`).
- * Thin wrapper around the `ms` package (`30s`, `5m`, `2h`, `1d`, …).
- */
-
-import ms from "ms";
-
-/** Parse a relative duration into milliseconds. Throws on invalid input. */
-export function parseDuration(input: string | number): number {
-  if (typeof input === "number") {
-    if (!Number.isFinite(input) || input < 0) {
-      throw new Error(`Invalid duration ms: ${input}`);
-    }
-    return Math.floor(input);
-  }
-  const trimmed = input.trim();
-  if (trimmed === "") {
-    throw new Error("Invalid duration: empty string");
-  }
-  if (/^\d+$/.test(trimmed)) {
-    return Number(trimmed);
-  }
-  const parsed = ms(trimmed as ms.StringValue);
-  if (typeof parsed !== "number" || !Number.isFinite(parsed) || parsed < 0) {
-    throw new Error(`Invalid duration "${input}": expected e.g. "30s", "5m", "2h", "1d"`);
-  }
-  return Math.floor(parsed);
-}
-
-export function isValidDuration(input: string | number): boolean {
-  try {
-    parseDuration(input);
-    return true;
-  } catch {
-    return false;
-  }
-}

package/src/internal/env-file.ts

@@ -1,83 +0,0 @@
-/**
- * Shared `.env` / `.env.local` writers for CLI commands that mint tokens.
- */
-
-import { chmod, readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-
-function isErrnoException(error: unknown): error is NodeJS.ErrnoException {
-  return error instanceof Error && "code" in error;
-}
-
-async function readOptionalFile(path: string): Promise<string> {
-  try {
-    return await readFile(path, "utf8");
-  } catch (error) {
-    if (isErrnoException(error) && error.code === "ENOENT") {
-      return "";
-    }
-    throw error;
-  }
-}
-
-/**
- * Append `KEY=value` lines to an env file, replacing every existing line
- * for the same key instead of appending duplicates. Creates the file when
- * missing.
- */
-export async function upsertEnvFile(
-  path: string,
-  entries: Array<{ key: string; value: string }>,
-): Promise<void> {
-  const existing = await readOptionalFile(path);
-  const lines = existing === "" ? [] : existing.replace(/\r?\n$/, "").split(/\r?\n/);
-  // A stale `export KEY=…` line would shadow or duplicate the bare line
-  // under some loaders; treat both spellings as the same entry.
-  const matchesKey = (line: string, key: string): boolean =>
-    line.startsWith(`${key}=`) || line.startsWith(`export ${key}=`);
-  for (const { key, value } of entries) {
-    const next = `${key}=${value}`;
-    let replaced = false;
-    for (let i = 0; i < lines.length;) {
-      if (!matchesKey(lines[i] ?? "", key)) {
-        i += 1;
-        continue;
-      }
-      if (replaced) {
-        lines.splice(i, 1);
-        continue;
-      }
-      lines[i] = next;
-      replaced = true;
-      i += 1;
-    }
-    if (!replaced) {
-      lines.push(next);
-    }
-  }
-  // writeFile's mode only applies on create; clamp pre-existing files too.
-  await writeFile(path, `${lines.join("\n")}\n`, { mode: 0o600 });
-  await chmod(path, 0o600);
-}
-
-/**
- * Ensure the agent directory's .gitignore covers .env.local (create or
- * append). A bare `.env` line does not count — that pattern matches only
- * the file literally named .env.
- */
-export async function ensureEnvLocalGitignored(dir: string): Promise<boolean> {
-  const path = join(dir, ".gitignore");
-  const existing = await readOptionalFile(path);
-  const covered = existing
-    .split(/\r?\n/)
-    .some(line => /^\.env(\.local\*?|\.\*|\*)$/.test(line.trim()));
-  if (covered) {
-    return false;
-  }
-  const next =
-    existing === "" || existing.endsWith("\n")
-      ? `${existing}.env.local\n`
-      : `${existing}\n.env.local\n`;
-  await writeFile(path, next);
-  return true;
-}

package/src/internal/eval-judge-model.ts

@@ -1,142 +0,0 @@
-/**
- * The model call behind `t.judge.*`.
- *
- * Grading is completion-only in intent: the judge reads a prompt and returns a
- * choice. It is nonetheless a real SDK session, and its prompt embeds output
- * from the agent under test — attacker-controlled text in exactly the way a
- * prompt injection needs. A reply that talks the judge into running a tool would
- * do so on the machine running the eval CLI, under the runner's credentials.
- *
- * The session is therefore confined on every axis the SDK exposes:
- *
- * - `sandboxOptions.enabled` so any tool call the judge is talked into is
- *   confined rather than run directly against the host.
- * - `mcpServers: {}` so no MCP surface is reachable.
- * - `settingSources: []` plus an empty temp `cwd`, so there is no repo to act on
- *   and no ambient `AGENTS.md` / `.cursor` rule can steer a verdict.
- *
- * The prompt side is hardened separately: `evals/judge.ts` fences untrusted
- * content behind a per-call boundary. Both halves matter — this one limits blast
- * radius, that one removes the instruction channel.
- *
- * Grading also declines outright when the credential's backend and the SDK's
- * backend disagree, rather than sending a key somewhere it was not minted for
- * (see {@link assertJudgeBackendMatch}).
- */
-
-import { mkdtemp, rm } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { EvalJudgeCaller } from "../evals/judge.js";
-import { EvalJudgeUnavailableError } from "../evals/judge.js";
-import type { ModelSetting } from "../types.js";
-import { DEFAULT_CURSOR_BACKEND_URL, resolveApiKey, SIGN_IN_HINT } from "./cursor/credentials.js";
-
-/** Env override for the default judge model (below `evals.config.ts`). */
-export const EVAL_JUDGE_MODEL_ENV = "AGENTKIT_EVAL_JUDGE_MODEL";
-
-/**
- * Backend the Cursor SDK will actually talk to.
- *
- * `Agent.create` takes a credential but no backend, so the SDK picks its own
- * host from `CURSOR_API_BASE_URL`. Kept next to {@link assertJudgeBackendMatch}
- * so the two stay in step if the SDK's resolution changes.
- */
-function sdkBackendUrl(): string {
-  const configured = process.env.CURSOR_API_BASE_URL?.trim();
-  return trimTrailingSlash(
-    configured === undefined || configured === "" ? DEFAULT_CURSOR_BACKEND_URL : configured,
-  );
-}
-
-function trimTrailingSlash(url: string): string {
-  return url.replace(/\/+$/, "");
-}
-
-/**
- * Refuse to grade when the judge credential belongs to a different backend than
- * the SDK will send it to.
- *
- * `resolveApiKey` resolves against `AGENT_SERVE_CURSOR_BACKEND_URL`, which the
- * SDK does not read. When only that override is set, the key and the judge
- * prompt — which embeds agent output — would go to the default host instead of
- * the intended one. There is no backend field on `AgentOptions` to reconcile
- * them, so the honest move is to decline rather than send a credential
- * somewhere it was not minted for.
- */
-export function assertJudgeBackendMatch(
-  credentialBackendUrl: string,
-  sdkBackend: string = sdkBackendUrl(),
-): void {
-  const credentialBackend = trimTrailingSlash(credentialBackendUrl);
-  if (credentialBackend === sdkBackend) {
-    return;
-  }
-  throw new EvalJudgeUnavailableError(
-    `eval judge credential is scoped to ${credentialBackend}, but the Cursor SDK would send it to ${sdkBackend}. ` +
-      "Set CURSOR_API_BASE_URL to the same backend (the SDK does not read AGENT_SERVE_CURSOR_BACKEND_URL).",
-  );
-}
-
-/**
- * Resolve the judge model, innermost first: per-call → per-eval →
- * `evals.config.ts` → {@link EVAL_JUDGE_MODEL_ENV}.
- */
-export function resolveJudgeModel(layers: {
-  call?: ModelSetting;
-  evalLevel?: ModelSetting;
-  config?: ModelSetting;
-  env?: string | undefined;
-}): ModelSetting | undefined {
-  const envModel = layers.env?.trim();
-  return (
-    layers.call ??
-    layers.evalLevel ??
-    layers.config ??
-    (envModel === undefined || envModel === "" ? undefined : envModel)
-  );
-}
-
-/**
- * Ask the judge model for a grade.
- *
- * Throws {@link EvalJudgeUnavailableError} when no credentials are available so
- * the runner can skip the eval visibly instead of reporting a spurious failure.
- */
-export const callJudgeModel: EvalJudgeCaller = async ({ prompt, model }) => {
-  const resolved = await resolveApiKey();
-  if (resolved === undefined) {
-    throw new EvalJudgeUnavailableError(
-      `no Cursor credentials for the eval judge. ${SIGN_IN_HINT}`,
-    );
-  }
-  assertJudgeBackendMatch(resolved.backendUrl);
-  // Imported lazily so a tree of fully deterministic evals never loads the SDK.
-  const { Agent } = await import("@cursor/sdk");
-  const cwd = await mkdtemp(join(tmpdir(), "agentkit-eval-judge-"));
-  const agent = await Agent.create({
-    apiKey: resolved.apiKey,
-    model: typeof model === "string" ? { id: model } : model,
-    // See the module comment: grading embeds untrusted agent output, so the
-    // session gets no MCP surface, no ambient settings, an empty working
-    // directory, and a sandbox around anything it does attempt.
-    mcpServers: {},
-    local: {
-      cwd,
-      settingSources: [],
-      sandboxOptions: { enabled: true },
-    },
-  });
-  try {
-    const run = await agent.send(prompt);
-    const result = await run.wait();
-    if (result.status === "error" || result.status === "cancelled") {
-      const detail = result.error?.message ?? result.result ?? result.status;
-      throw new Error(`eval judge run failed: ${detail}`);
-    }
-    return result.result ?? "";
-  } finally {
-    agent.close();
-    await rm(cwd, { recursive: true, force: true }).catch(() => undefined);
-  }
-};