@cursor/bdk 0.2.2 → 0.2.4

package/src/internal/playground/static.ts

@@ -1,278 +0,0 @@
-/**
- * Serves the built Vite playground SPA and the host home page.
- *
- * The playground is a Vite + React app (see `playground/`). `serve` auto-builds
- * `dist/playground/` when the local vite toolchain is present (see
- * `toolchain.ts`); `pnpm run build` also emits it for publish. In `--dev`,
- * Vite HMR is spawned separately; this module only serves the static bundle.
- *
- * The server mounts the SPA at `/playground` (single agent) or
- * `/<slug>/playground` (multi), so the built `index.html` — whose asset URLs
- * are relative — gets a `<base href>` injected to resolve them under the mount.
- */
-
-import { existsSync, readFileSync } from "node:fs";
-import { extname, join, normalize } from "node:path";
-import { fileURLToPath } from "node:url";
-
-// src/internal/playground/static.ts -> packages/agent-serve/dist/playground/.
-// Resolves the same from compiled dist/internal/playground/static.js.
-const DIST_DIR = fileURLToPath(new URL("../../../dist/playground/", import.meta.url));
-const INDEX_HTML = join(DIST_DIR, "index.html");
-const ASSETS_DIR = join(DIST_DIR, "assets");
-
-/** Content types for the static bundles this server ships (playground, docs). */
-export const STATIC_CONTENT_TYPES: Record<string, string> = {
-  ".html": "text/html; charset=utf-8",
-  ".js": "text/javascript; charset=utf-8",
-  ".md": "text/markdown; charset=utf-8",
-  ".mjs": "text/javascript; charset=utf-8",
-  ".css": "text/css; charset=utf-8",
-  ".map": "application/json; charset=utf-8",
-  ".json": "application/json; charset=utf-8",
-  ".svg": "image/svg+xml",
-  ".png": "image/png",
-  ".jpg": "image/jpeg",
-  ".jpeg": "image/jpeg",
-  ".gif": "image/gif",
-  ".webp": "image/webp",
-  ".ico": "image/x-icon",
-  ".woff": "font/woff",
-  ".woff2": "font/woff2",
-  ".ttf": "font/ttf",
-  ".txt": "text/plain; charset=utf-8",
-};
-
-/** Whether `pnpm run build:playground` has produced the SPA bundle. */
-export function playgroundBundleExists(): boolean {
-  return existsSync(INDEX_HTML);
-}
-
-/**
- * The SPA `index.html` with a `<base href>` injected so its relative asset
- * URLs resolve under the mount point (`/playground/` or `/<slug>/playground/`).
- * Falls back to a helpful placeholder page when the bundle is missing.
- * The hosted alias performs the same injection for its central copy
- * (`backend/server/src/agentServe/aliasPlaygroundShell.ts`) — keep them
- * behaviorally aligned.
- */
-export function renderPlaygroundIndexHtml(baseHref: string): string {
-  if (!playgroundBundleExists()) {
-    return fallbackHtml(baseHref);
-  }
-  const html = readFileSync(INDEX_HTML, "utf8");
-  const baseTag = `<base href="${escapeHtml(baseHref)}" />`;
-  if (html.includes("<head>")) {
-    return html.replace("<head>", `<head>\n    ${baseTag}`);
-  }
-  return `${baseTag}\n${html}`;
-}
-
-/** Serve one built asset from `dist/playground/assets/` by filename. */
-export function renderPlaygroundAsset(file: string): Response {
-  // The route captures a single path segment, but normalize + reject anything
-  // that escapes the assets dir defensively.
-  const safe = normalize(file).replace(/^(\.\.[/\\])+/, "");
-  if (safe.includes("/") || safe.includes("\\") || safe === "") {
-    return new Response("Not found", { status: 404 });
-  }
-  const filePath = join(ASSETS_DIR, safe);
-  if (!filePath.startsWith(ASSETS_DIR) || !existsSync(filePath)) {
-    return new Response("Not found", { status: 404 });
-  }
-  const body = readFileSync(filePath);
-  const type = STATIC_CONTENT_TYPES[extname(safe).toLowerCase()] ?? "application/octet-stream";
-  return new Response(new Uint8Array(body), {
-    headers: {
-      "content-type": type,
-      // Vite emits content-hashed filenames, so they are safe to cache hard.
-      "cache-control": "public, max-age=31536000, immutable",
-    },
-  });
-}
-
-/** Slack surface summary for the host home / `GET /v1/agents`. */
-export type AgentIndexSlack = { kind: "socket" };
-
-/** One row on the host home page and `GET /v1/agents`. */
-export interface AgentIndexEntry {
-  slug: string;
-  name: string;
-  model: string;
-  tools: number;
-  channels: number;
-  slack?: AgentIndexSlack;
-}
-
-export interface HostHomeOptions {
-  /** When false, omit `/docs` from the route list. Default true. */
-  docs?: boolean;
-  /** Same as the serve host's `multi` — mounts `/v1/agents` + host `/v1/health`. */
-  multi?: boolean;
-}
-
-/**
- * Orienting `/` page: mounted agents (playground links) plus live host routes.
- * Used for both single-agent (empty slug) and multi-agent mounts.
- */
-export function renderAgentsIndexHtml(
-  agents: AgentIndexEntry[],
-  options: HostHomeOptions = {},
-): string {
-  const docs = options.docs !== false;
-  const multi = options.multi === true;
-  const cards = agents
-    .map(agent => {
-      const playground = agent.slug === "" ? "/playground" : `/${agent.slug}/playground`;
-      const slugLabel = agent.slug === "" ? "/" : `/${agent.slug}`;
-      const meta = `${agent.model || "—"} · ${agent.tools} tool${
-        agent.tools === 1 ? "" : "s"
-      } · ${agent.channels} channel${agent.channels === 1 ? "" : "s"}`;
-      return `      <a class="card" href="${escapeHtml(playground)}">
-        <div class="card-name">${escapeHtml(agent.name)}</div>
-        <div class="card-slug">${escapeHtml(slugLabel)} → playground</div>
-        <div class="card-meta">${escapeHtml(meta)}</div>
-      </a>`;
-    })
-    .join("\n");
-
-  const routes = hostRouteRows(agents, docs, multi)
-    .map(
-      row =>
-        `        <tr><td><a href="${escapeHtml(row.href)}"><code>${escapeHtml(row.path)}</code></a></td><td>${escapeHtml(row.blurb)}</td></tr>`,
-    )
-    .join("\n");
-
-  return HOST_HOME_TEMPLATE.replace(
-    "<!--CARDS-->",
-    cards || '      <div class="card-meta">No agents mounted.</div>',
-  )
-    .replace("<!--COUNT-->", String(agents.length))
-    .replace("<!--ROUTES-->", routes);
-}
-
-function hostRouteRows(
-  agents: AgentIndexEntry[],
-  docs: boolean,
-  multi: boolean,
-): Array<{ path: string; href: string; blurb: string }> {
-  const rows: Array<{ path: string; href: string; blurb: string }> = [
-    { path: "/", href: "/", blurb: "This page" },
-  ];
-  for (const agent of agents) {
-    const base = agent.slug === "" ? "" : `/${agent.slug}`;
-    const label = agent.slug === "" ? agent.name : agent.slug;
-    rows.push({
-      path: `${base}/playground`,
-      href: `${base}/playground`,
-      blurb: `Playground — ${label}`,
-    });
-    rows.push({
-      path: `${base}/v1/health`,
-      href: `${base}/v1/health`,
-      blurb: `Health — ${label}`,
-    });
-  }
-  if (multi) {
-    rows.push({
-      path: "/v1/agents",
-      href: "/v1/agents",
-      blurb: "JSON index of mounted agents",
-    });
-    rows.push({
-      path: "/v1/health",
-      href: "/v1/health",
-      blurb: "Host liveness",
-    });
-  }
-  if (docs) {
-    rows.push({
-      path: "/docs",
-      href: "/docs/",
-      blurb: "Agent SDK documentation",
-    });
-  }
-  return rows;
-}
-
-function escapeHtml(value: string): string {
-  return value
-    .replace(/&/g, "&amp;")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;");
-}
-
-function fallbackHtml(baseHref: string): string {
-  return `<!doctype html>
-<html lang="en">
-  <head>
-    <base href="${escapeHtml(baseHref)}" />
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>agent-sdk playground</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; }
-      a { color: #6cb6ff; }
-    </style>
-  </head>
-  <body>
-    <div class="box">
-      <h1>Playground bundle not built</h1>
-      <p>
-        The Vite playground has not been built yet. <code>agent-sdk serve</code>
-        auto-builds it when the local vite toolchain is available; otherwise run
-        <code>pnpm run build:playground</code> from <code>packages/agent-serve</code>,
-        or <code>pnpm run dev:playground</code> for Vite HMR.
-      </p>
-    </div>
-  </body>
-</html>`;
-}
-
-const HOST_HOME_TEMPLATE = `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Agent SDK</title>
-    <style>
-      :root { color-scheme: dark; }
-      body { margin: 0; background: #0e1116; color: #e6edf3; font: 14px/1.6 ui-sans-serif, system-ui, -apple-system, sans-serif; }
-      .wrap { max-width: 880px; margin: 0 auto; padding: 48px 24px; }
-      h1 { font-size: 20px; font-weight: 650; margin: 0 0 2px; }
-      h2 { font-size: 13px; font-weight: 600; text-transform: uppercase; letter-spacing: 0.04em; color: #8b949e; margin: 36px 0 12px; }
-      .sub { color: #8b949e; font-size: 13px; margin-bottom: 28px; }
-      .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 14px; }
-      .card { display: block; text-decoration: none; color: inherit; background: #161b22; border: 1px solid #30363d; border-radius: 12px; padding: 16px 18px; transition: border-color 0.12s; }
-      .card:hover { border-color: #6cb6ff; }
-      .card-name { font-size: 15px; font-weight: 600; }
-      .card-slug { font-family: ui-monospace, monospace; font-size: 12px; color: #6cb6ff; margin-top: 2px; }
-      .card-meta { color: #6e7681; font-size: 12px; margin-top: 10px; }
-      table.routes { width: 100%; border-collapse: collapse; font-size: 13px; }
-      table.routes td { padding: 8px 0; border-bottom: 1px solid #21262d; vertical-align: top; }
-      table.routes td:first-child { width: 42%; padding-right: 16px; }
-      table.routes code { font-family: ui-monospace, monospace; font-size: 12px; color: #6cb6ff; }
-      table.routes a { text-decoration: none; }
-      table.routes a:hover code { text-decoration: underline; }
-      .muted { color: #8b949e; }
-    </style>
-  </head>
-  <body>
-    <div class="wrap">
-      <h1>Agent SDK</h1>
-      <div class="sub"><!--COUNT--> agent(s) on this host. Open a playground or use a route below.</div>
-      <h2>Agents</h2>
-      <div class="grid">
-<!--CARDS-->
-      </div>
-      <h2>Routes</h2>
-      <table class="routes">
-<!--ROUTES-->
-      </table>
-    </div>
-  </body>
-</html>`;

package/src/internal/playground/toolchain.ts

@@ -1,270 +0,0 @@
-/**
- * Local Vite toolchain for the playground SPA.
- *
- * Published installs ship `dist/playground/` and do not need this — vite is a
- * devDependency and `playground/` sources may be absent. In a monorepo / source
- * checkout, `serve` uses this to auto-build a missing bundle and (with `--dev`)
- * spawn the Vite HMR server.
- */
-
-import { spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { createRequire } from "node:module";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { playgroundBundleExists } from "./static.js";
-
-const VITE_CONFIG = "playground/vite.config.ts";
-
-/** Package root (works from `src/` or `dist/`). */
-export function packageRoot(): string {
-  // src|dist/internal/playground/toolchain.ts → packages/agent-serve/
-  return fileURLToPath(new URL("../../..", import.meta.url));
-}
-
-export interface PlaygroundToolchain {
-  packageRoot: string;
-  viteCli: string;
-  viteConfig: string;
-}
-
-/** Resolve the absolute path to vite's CLI bin without using blocked package exports. */
-function resolveViteCli(root: string): string | undefined {
-  try {
-    const require = createRequire(join(root, "package.json"));
-    let dir = dirname(require.resolve("vite"));
-    for (let i = 0; i < 6; i++) {
-      const pkgPath = join(dir, "package.json");
-      if (existsSync(pkgPath)) {
-        const pkg = JSON.parse(readFileSync(pkgPath, "utf8")) as {
-          name?: string;
-          bin?: string | Record<string, string>;
-        };
-        if (pkg.name === "vite") {
-          const binRel = typeof pkg.bin === "string" ? pkg.bin : (pkg.bin?.vite ?? "bin/vite.js");
-          const binAbs = join(dir, binRel);
-          return existsSync(binAbs) ? binAbs : undefined;
-        }
-      }
-      const parent = dirname(dir);
-      if (parent === dir) {
-        break;
-      }
-      dir = parent;
-    }
-  } catch {
-    return undefined;
-  }
-  return undefined;
-}
-
-/** True when playground sources + a resolvable `vite` CLI are present. */
-export function resolvePlaygroundToolchain(): PlaygroundToolchain | undefined {
-  const root = packageRoot();
-  const viteConfig = join(root, VITE_CONFIG);
-  if (!existsSync(viteConfig)) {
-    return undefined;
-  }
-  const viteCli = resolveViteCli(root);
-  if (viteCli === undefined) {
-    return undefined;
-  }
-  return { packageRoot: root, viteCli, viteConfig };
-}
-
-export function playgroundToolchainAvailable(): boolean {
-  return resolvePlaygroundToolchain() !== undefined;
-}
-
-/**
- * `AGENT_SERVE_BASE` for the Vite proxy when serving a single slugged agent.
- * Multi-agent serve uses path-based HMR (`/<slug>/playground`) unless the
- * caller pins one slug via {@link playgroundDevBaseFromEnv}.
- */
-export function playgroundDevBasePath(mounts: ReadonlyArray<{ slug: string }>): string | undefined {
-  if (mounts.length === 1 && mounts[0]?.slug !== "") {
-    return `/${mounts[0].slug}`;
-  }
-  return undefined;
-}
-
-/**
- * Optional pin for multi-agent Vite HMR (SPA at root, rewrite `/v1` → base).
- * Empty / unset → multi-agent path mode (`AGENT_SERVE_MULTI`).
- */
-export function playgroundDevBaseFromEnv(env: NodeJS.ProcessEnv = process.env): string | undefined {
-  const raw = env.AGENT_SERVE_BASE?.trim();
-  if (raw === undefined || raw === "") {
-    return undefined;
-  }
-  const normalized = raw.replace(/\/+$/, "");
-  if (normalized === "" || normalized === "/") {
-    return undefined;
-  }
-  return normalized.startsWith("/") ? normalized : `/${normalized}`;
-}
-
-/** Run `vite build` for the playground; throws on non-zero exit. */
-export async function runPlaygroundBuild(
-  logger: (line: string) => void = console.log,
-): Promise<void> {
-  const toolchain = resolvePlaygroundToolchain();
-  if (toolchain === undefined) {
-    throw new Error(
-      "playground vite toolchain unavailable (need playground/ sources and the vite package)",
-    );
-  }
-  logger("[agent-sdk] building playground (vite)...");
-  const code = await spawnVite(toolchain, ["build", "--config", VITE_CONFIG], {
-    env: process.env,
-  });
-  if (code !== 0) {
-    throw new Error(`playground vite build failed (exit ${code})`);
-  }
-  if (!playgroundBundleExists()) {
-    throw new Error("playground vite build finished but dist/playground/index.html is missing");
-  }
-  logger("[agent-sdk] playground build complete");
-}
-
-/**
- * If the SPA bundle is missing and the local toolchain is available, build it.
- * No-op when the bundle already exists. Soft-skips (logs) when vite is absent
- * so published installs without a prebuilt bundle still start.
- */
-export async function ensurePlaygroundBundle(
-  logger: (line: string) => void = console.log,
-): Promise<void> {
-  if (playgroundBundleExists()) {
-    return;
-  }
-  if (resolvePlaygroundToolchain() === undefined) {
-    logger(
-      "[agent-sdk] playground bundle missing and vite toolchain unavailable; /playground will show a build hint",
-    );
-    return;
-  }
-  await runPlaygroundBuild(logger);
-}
-
-export interface PlaygroundDevServer {
-  url: string;
-  stop(): void;
-}
-
-/**
- * Spawn Vite HMR for the playground, proxying API calls at {@link targetUrl}.
- * Multi-agent mode serves `/<slug>/playground` + the agents index at `/`.
- * Returns undefined when the toolchain is unavailable.
- */
-export function startPlaygroundDevServer(options: {
-  targetUrl: string;
-  basePath?: string;
-  /** Path-based multi-agent HMR (no single-slug `/v1` rewrite). */
-  multiAgent?: boolean;
-  logger?: (line: string) => void;
-}): PlaygroundDevServer | undefined {
-  const logger = options.logger ?? console.log;
-  const toolchain = resolvePlaygroundToolchain();
-  if (toolchain === undefined) {
-    return undefined;
-  }
-
-  const port = playgroundDevPort();
-  const multiAgent = options.multiAgent === true;
-  const env: NodeJS.ProcessEnv = {
-    ...process.env,
-    AGENT_SERVE_PLAYGROUND_PORT: String(port),
-    AGENT_SERVE_TARGET: options.targetUrl,
-  };
-  if (multiAgent) {
-    env.AGENT_SERVE_MULTI = "1";
-    delete env.AGENT_SERVE_BASE;
-  } else {
-    delete env.AGENT_SERVE_MULTI;
-    if (options.basePath !== undefined && options.basePath !== "") {
-      env.AGENT_SERVE_BASE = options.basePath;
-    } else {
-      delete env.AGENT_SERVE_BASE;
-    }
-  }
-
-  // Quiet + isolated from the TTY: the serve banner owns the terminal.
-  // Piped stdio keeps Vite from seeing a TTY (so it cannot clearScreen), and
-  // silent logging drops the "VITE ready" / URL spam. Errors still surface via
-  // spawn/exit handlers below.
-  const child = spawn(
-    process.execPath,
-    [toolchain.viteCli, "--config", VITE_CONFIG, "--logLevel", "silent"],
-    {
-      cwd: toolchain.packageRoot,
-      env,
-      stdio: ["ignore", "ignore", "pipe"],
-    },
-  );
-
-  child.stderr?.on("data", (chunk: Buffer) => {
-    const text = chunk.toString().trimEnd();
-    if (text !== "") {
-      logger(`[agent-sdk] playground: ${text}`);
-    }
-  });
-
-  let stopped = false;
-  child.on("error", err => {
-    if (stopped) {
-      return;
-    }
-    logger(
-      `[agent-sdk] playground spawn failed: ${err.message} — static /playground still served when built`,
-    );
-  });
-  child.on("exit", (code, signal) => {
-    if (stopped) {
-      return;
-    }
-    if (code !== 0 && code !== null) {
-      logger(
-        `[agent-sdk] playground exited (code ${code}${
-          signal ? `, signal ${signal}` : ""
-        }) — static /playground still served when built`,
-      );
-    }
-  });
-
-  return {
-    url: `http://127.0.0.1:${port}/`,
-    stop: () => {
-      stopped = true;
-      if (!child.killed) {
-        child.kill("SIGTERM");
-      }
-    },
-  };
-}
-
-export function playgroundDevPort(): number {
-  const parsed = Number(process.env.AGENT_SERVE_PLAYGROUND_PORT ?? "5273");
-  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
-    return 5273;
-  }
-  return parsed;
-}
-
-function spawnVite(
-  toolchain: PlaygroundToolchain,
-  args: string[],
-  options: { env: NodeJS.ProcessEnv },
-): Promise<number> {
-  return new Promise((resolve, reject) => {
-    const child = spawn(process.execPath, [toolchain.viteCli, ...args], {
-      cwd: toolchain.packageRoot,
-      env: options.env,
-      stdio: "inherit",
-    });
-    child.on("error", reject);
-    child.on("exit", code => {
-      resolve(code ?? 1);
-    });
-  });
-}