@cursor/bdk 0.2.1

package/dist/internal/platform-timers.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Timed-work client used by the kit. Local serve implements this in-process
+ * (`createLocalControlPlane`). Cursor hosting (`--no-control-plane`) uses
+ * the HTTP client below against the Cursor backend. Authors never see this
+ * surface.
+ *
+ * The control plane owns reminder *documents* and clocks. The kit only
+ * executes fires.
+ */
+import { type ReminderControlPlane } from "./reminder-control-plane-protocol.js";
+import { type ReminderRecord } from "./reminder-store.js";
+export interface PlatformTimers {
+    upsertSchedule(input: {
+        name: string;
+        cron: string;
+    }): Promise<void>;
+    deleteSchedule(name: string): Promise<void>;
+    putReminder(record: ReminderRecord): Promise<void>;
+    getReminder(id: string): Promise<ReminderRecord | undefined>;
+    listReminders(): Promise<ReminderRecord[]>;
+    deleteReminder(id: string): Promise<void>;
+}
+export interface CursorHostedPlatformTimersOptions {
+    baseUrl?: string;
+    apiKey?: string;
+    fetch?: typeof fetch;
+}
+export declare function createCursorHostedPlatformTimers(options?: CursorHostedPlatformTimersOptions): PlatformTimers;
+/**
+ * Cursor-hosted HTTP ReminderControlPlane for architecture v2.
+ * Speaks factory `/internal/agentsdk/reminders` (ELB → factory ECS).
+ * CP owns ids and time. v1 PUT/DELETE reminders stay on timed-work.
+ */
+export declare function createCursorHostedReminderControlPlane(options?: CursorHostedPlatformTimersOptions): ReminderControlPlane;
+//# sourceMappingURL=platform-timers.d.ts.map

package/dist/internal/platform-timers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-timers.d.ts","sourceRoot":"","sources":["../../src/internal/platform-timers.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAEL,KAAK,oBAAoB,EAK1B,MAAM,sCAAsC,CAAC;AAC9C,OAAO,EAAoB,KAAK,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAI5E,MAAM,WAAW,cAAc;IAC7B,cAAc,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IAC7D,aAAa,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAC3C,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,iCAAiC;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAqED,wBAAgB,gCAAgC,CAC9C,OAAO,GAAE,iCAAsC,GAC9C,cAAc,CAoEhB;AAuED;;;;GAIG;AACH,wBAAgB,sCAAsC,CACpD,OAAO,GAAE,iCAAsC,GAC9C,oBAAoB,CAgHtB"}

package/dist/internal/platform-timers.js

@@ -0,0 +1,277 @@
+/**
+ * Timed-work client used by the kit. Local serve implements this in-process
+ * (`createLocalControlPlane`). Cursor hosting (`--no-control-plane`) uses
+ * the HTTP client below against the Cursor backend. Authors never see this
+ * surface.
+ *
+ * The control plane owns reminder *documents* and clocks. The kit only
+ * executes fires.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { REMINDER_CP_PROTOCOL_VERSION, } from "./reminder-control-plane-protocol.js";
+import { isReminderRecord } from "./reminder-store.js";
+const DEFAULT_CURSOR_EXTERNAL_API_URL = "https://api.cursor.com";
+function resolveApiKey(options) {
+    var _a;
+    var _b;
+    const key = (_a = ((_b = options.apiKey) !== null && _b !== void 0 ? _b : process.env.CURSOR_API_KEY)) === null || _a === void 0 ? void 0 : _a.trim();
+    if (key === undefined || key === "") {
+        throw new Error("platform timers require CURSOR_API_KEY (deployment pod credential on Cursor hosting)");
+    }
+    return key;
+}
+function resolveBaseUrl(options) {
+    var _a, _b;
+    const raw = ((_b = (_a = options.baseUrl) !== null && _a !== void 0 ? _a : process.env.CURSOR_API_BASE_URL) !== null && _b !== void 0 ? _b : DEFAULT_CURSOR_EXTERNAL_API_URL).trim();
+    return raw.endsWith("/") ? raw.slice(0, -1) : raw;
+}
+function timedWorkFetch(options, method, path, body) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const fetchImpl = (_a = options.fetch) !== null && _a !== void 0 ? _a : globalThis.fetch;
+        if (typeof fetchImpl !== "function") {
+            throw new Error("platform timers require fetch");
+        }
+        return fetchImpl(`${resolveBaseUrl(options)}${path}`, Object.assign({ method, headers: Object.assign({ Authorization: `Bearer ${resolveApiKey(options)}` }, (body === undefined ? {} : { "Content-Type": "application/json" })) }, (body === undefined ? {} : { body: JSON.stringify(body) })));
+    });
+}
+function timedWorkRpc(options, method, path, body) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const response = yield timedWorkFetch(options, method, path, body);
+        if (response.ok) {
+            return;
+        }
+        const text = yield response.text();
+        let detail = `HTTP ${response.status}`;
+        try {
+            const parsed = text.length === 0 ? {} : JSON.parse(text);
+            if (parsed !== null &&
+                typeof parsed === "object" &&
+                "error" in parsed &&
+                typeof parsed.error === "string") {
+                detail = parsed.error;
+            }
+        }
+        catch (_a) {
+            // Keep the status-only detail.
+        }
+        throw new Error(`platform timers ${method} ${path}: ${detail}`);
+    });
+}
+export function createCursorHostedPlatformTimers(options = {}) {
+    return {
+        upsertSchedule(input) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield timedWorkRpc(options, "PUT", `/internal/agent-serve/timed-work/schedules/${encodeURIComponent(input.name)}`, { cron: input.cron });
+            });
+        },
+        deleteSchedule(name) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield timedWorkRpc(options, "DELETE", `/internal/agent-serve/timed-work/schedules/${encodeURIComponent(name)}`);
+            });
+        },
+        putReminder(record) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield timedWorkRpc(options, "PUT", `/internal/agent-serve/timed-work/reminders/${encodeURIComponent(record.id)}`, record);
+            });
+        },
+        getReminder(id) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const response = yield timedWorkFetch(options, "GET", `/internal/agent-serve/timed-work/reminders/${encodeURIComponent(id)}`);
+                if (response.status === 404) {
+                    return undefined;
+                }
+                if (!response.ok) {
+                    throw new Error(`platform timers GET /reminders/${id}: HTTP ${response.status}`);
+                }
+                const parsed = yield response.json();
+                return isReminderRecord(parsed) ? parsed : undefined;
+            });
+        },
+        listReminders() {
+            return __awaiter(this, void 0, void 0, function* () {
+                const response = yield timedWorkFetch(options, "GET", "/internal/agent-serve/timed-work/reminders");
+                if (!response.ok) {
+                    throw new Error(`platform timers GET /reminders: HTTP ${response.status}`);
+                }
+                const parsed = yield response.json();
+                if (parsed === null ||
+                    typeof parsed !== "object" ||
+                    !("reminders" in parsed) ||
+                    !Array.isArray(parsed.reminders)) {
+                    return [];
+                }
+                return parsed.reminders.filter(isReminderRecord);
+            });
+        },
+        deleteReminder(id) {
+            return __awaiter(this, void 0, void 0, function* () {
+                yield timedWorkRpc(options, "DELETE", `/internal/agent-serve/timed-work/reminders/${encodeURIComponent(id)}`);
+            });
+        },
+    };
+}
+/** v2 reminder CP is factory ECS (`/internal/agentsdk/*`), not timed-work. */
+const AGENTSDK_REMINDERS_PREFIX = "/internal/agentsdk";
+/**
+ * Bounded retries for idempotent CP outcome writes after the guest handler
+ * has already run. Delivery is at-least-once: a transient apply failure may
+ * re-enter the handler on the next Temporal admission. Do not claim
+ * exactly-once handler execution.
+ */
+const APPLY_REMINDER_OUTCOME_MAX_ATTEMPTS = 3;
+const APPLY_REMINDER_OUTCOME_RETRY_DELAY_MS = 50;
+function sleepMs(ms) {
+    return __awaiter(this, void 0, void 0, function* () {
+        yield new Promise(resolve => setTimeout(resolve, ms));
+    });
+}
+function withBoundedApplyRetries(run) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let lastError;
+        for (let attempt = 1; attempt <= APPLY_REMINDER_OUTCOME_MAX_ATTEMPTS; attempt++) {
+            try {
+                return yield run();
+            }
+            catch (error) {
+                lastError = error;
+                if (attempt >= APPLY_REMINDER_OUTCOME_MAX_ATTEMPTS) {
+                    break;
+                }
+                yield sleepMs(APPLY_REMINDER_OUTCOME_RETRY_DELAY_MS * attempt);
+            }
+        }
+        throw lastError;
+    });
+}
+function timedWorkJsonFetch(options, method, path, body) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const fetchImpl = (_a = options.fetch) !== null && _a !== void 0 ? _a : globalThis.fetch;
+        if (typeof fetchImpl !== "function") {
+            throw new Error("reminder control plane requires fetch");
+        }
+        return fetchImpl(`${resolveBaseUrl(options)}${path}`, Object.assign({ method, headers: Object.assign({ Authorization: `Bearer ${resolveApiKey(options)}` }, (body === undefined ? {} : { "Content-Type": "application/json" })) }, (body === undefined ? {} : { body: JSON.stringify(body) })));
+    });
+}
+const CP_ERROR_BODY_LIMIT = 512;
+/**
+ * Read failures carry status and a bounded body: the guest logs them once
+ * per process, and a 405 body names the route the caller should be on.
+ */
+function reminderCpReadError(what, response) {
+    return __awaiter(this, void 0, void 0, function* () {
+        let body = "";
+        try {
+            body = (yield response.text()).trim();
+        }
+        catch (_a) {
+            // Status-only detail.
+        }
+        const detail = body === "" ? "" : ` ${body.slice(0, CP_ERROR_BODY_LIMIT)}`;
+        return new Error(`reminder CP ${what} failed: HTTP ${response.status}${detail}`);
+    });
+}
+/**
+ * Cursor-hosted HTTP ReminderControlPlane for architecture v2.
+ * Speaks factory `/internal/agentsdk/reminders` (ELB → factory ECS).
+ * CP owns ids and time. v1 PUT/DELETE reminders stay on timed-work.
+ */
+export function createCursorHostedReminderControlPlane(options = {}) {
+    return {
+        protocolVersion: REMINDER_CP_PROTOCOL_VERSION,
+        createReminder(intent) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const response = yield timedWorkJsonFetch(options, "POST", `${AGENTSDK_REMINDERS_PREFIX}/reminders`, intent);
+                if (!response.ok) {
+                    const text = yield response.text();
+                    throw new Error(`reminder CP create failed: HTTP ${response.status} ${text}`);
+                }
+                const parsed = yield response.json();
+                if (!isReminderRecord(parsed)) {
+                    throw new Error("reminder CP create returned invalid record");
+                }
+                return parsed;
+            });
+        },
+        getReminder(id) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const response = yield timedWorkJsonFetch(options, "GET", `${AGENTSDK_REMINDERS_PREFIX}/reminders/${encodeURIComponent(id)}`);
+                if (response.status === 404) {
+                    return undefined;
+                }
+                if (!response.ok) {
+                    throw yield reminderCpReadError("get", response);
+                }
+                const parsed = yield response.json();
+                return isReminderRecord(parsed) ? parsed : undefined;
+            });
+        },
+        listReminders() {
+            return __awaiter(this, void 0, void 0, function* () {
+                const response = yield timedWorkJsonFetch(options, "GET", `${AGENTSDK_REMINDERS_PREFIX}/reminders`);
+                if (!response.ok) {
+                    throw yield reminderCpReadError("list", response);
+                }
+                const parsed = yield response.json();
+                if (parsed === null ||
+                    typeof parsed !== "object" ||
+                    !("reminders" in parsed) ||
+                    !Array.isArray(parsed.reminders)) {
+                    return [];
+                }
+                return parsed.reminders.filter(isReminderRecord);
+            });
+        },
+        cancelReminder(id, reason) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const response = yield timedWorkJsonFetch(options, "POST", `${AGENTSDK_REMINDERS_PREFIX}/reminders/${encodeURIComponent(id)}/cancel`, reason === undefined ? {} : { reason });
+                if (response.status === 404) {
+                    return undefined;
+                }
+                if (!response.ok) {
+                    throw new Error(`reminder CP cancel failed: HTTP ${response.status}`);
+                }
+                const parsed = yield response.json();
+                return isReminderRecord(parsed) ? parsed : undefined;
+            });
+        },
+        rekeyReminders(channelId, oldToken, newToken) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const response = yield timedWorkJsonFetch(options, "POST", `${AGENTSDK_REMINDERS_PREFIX}/reminders/rekey`, { channelId, oldToken, newToken });
+                if (!response.ok) {
+                    throw new Error(`reminder CP rekey failed: HTTP ${response.status}`);
+                }
+                const parsed = yield response.json();
+                if (parsed === null ||
+                    typeof parsed !== "object" ||
+                    typeof parsed.count !== "number") {
+                    throw new Error("reminder CP rekey returned invalid body");
+                }
+                return parsed.count;
+            });
+        },
+        applyReminderOutcome(claim, outcome) {
+            return __awaiter(this, void 0, void 0, function* () {
+                // Handler side effects may already have run; retry only the idempotent
+                // CP write. Exhausted failures stay thrown so Temporal can re-admit
+                // (at-least-once — not exactly-once).
+                return yield withBoundedApplyRetries(() => __awaiter(this, void 0, void 0, function* () {
+                    const response = yield timedWorkJsonFetch(options, "POST", `${AGENTSDK_REMINDERS_PREFIX}/reminders/outcome`, { claim, outcome });
+                    if (!response.ok) {
+                        throw new Error(`reminder CP outcome apply failed: HTTP ${response.status}`);
+                    }
+                    return (yield response.json());
+                }));
+            });
+        },
+    };
+}

package/dist/internal/playground/static.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+/** Content types for the static bundles this server ships (playground, docs). */
+export declare const STATIC_CONTENT_TYPES: Record<string, string>;
+/** Whether `pnpm run build:playground` has produced the SPA bundle. */
+export declare function playgroundBundleExists(): boolean;
+/**
+ * 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 declare function renderPlaygroundIndexHtml(baseHref: string): string;
+/** Serve one built asset from `dist/playground/assets/` by filename. */
+export declare function renderPlaygroundAsset(file: string): Response;
+/** 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 declare function renderAgentsIndexHtml(agents: AgentIndexEntry[], options?: HostHomeOptions): string;
+//# sourceMappingURL=static.d.ts.map

package/dist/internal/playground/static.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static.d.ts","sourceRoot":"","sources":["../../../src/internal/playground/static.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAmBvD,CAAC;AAEF,uEAAuE;AACvE,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUlE;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAoB5D;AAED,kEAAkE;AAClE,MAAM,MAAM,eAAe,GAAG;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAEjD,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,eAAe,CAAC;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kFAAkF;IAClF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,eAAe,EAAE,EACzB,OAAO,GAAE,eAAoB,GAC5B,MAAM,CA+BR"}

package/dist/internal/playground/static.js

@@ -0,0 +1,231 @@
+/**
+ * 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 = {
+    ".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() {
+    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) {
+    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) {
+    var _a;
+    // 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 = (_a = STATIC_CONTENT_TYPES[extname(safe).toLowerCase()]) !== null && _a !== void 0 ? _a : "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",
+        },
+    });
+}
+/**
+ * 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, options = {}) {
+    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, docs, multi) {
+    const rows = [
+        { 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) {
+    return value
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}
+function fallbackHtml(baseHref) {
+    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/dist/internal/playground/toolchain.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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.
+ */
+/** Package root (works from `src/` or `dist/`). */
+export declare function packageRoot(): string;
+export interface PlaygroundToolchain {
+    packageRoot: string;
+    viteCli: string;
+    viteConfig: string;
+}
+/** True when playground sources + a resolvable `vite` CLI are present. */
+export declare function resolvePlaygroundToolchain(): PlaygroundToolchain | undefined;
+export declare function playgroundToolchainAvailable(): boolean;
+/**
+ * `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 declare function playgroundDevBasePath(mounts: ReadonlyArray<{
+    slug: string;
+}>): string | undefined;
+/**
+ * Optional pin for multi-agent Vite HMR (SPA at root, rewrite `/v1` → base).
+ * Empty / unset → multi-agent path mode (`AGENT_SERVE_MULTI`).
+ */
+export declare function playgroundDevBaseFromEnv(env?: NodeJS.ProcessEnv): string | undefined;
+/** Run `vite build` for the playground; throws on non-zero exit. */
+export declare function runPlaygroundBuild(logger?: (line: string) => void): Promise<void>;
+/**
+ * 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 declare function ensurePlaygroundBundle(logger?: (line: string) => void): Promise<void>;
+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 declare 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;
+export declare function playgroundDevPort(): number;
+//# sourceMappingURL=toolchain.d.ts.map

package/dist/internal/playground/toolchain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolchain.d.ts","sourceRoot":"","sources":["../../../src/internal/playground/toolchain.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAWH,mDAAmD;AACnD,wBAAgB,WAAW,IAAI,MAAM,CAGpC;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAgCD,0EAA0E;AAC1E,wBAAgB,0BAA0B,IAAI,mBAAmB,GAAG,SAAS,CAW5E;AAED,wBAAgB,4BAA4B,IAAI,OAAO,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG,MAAM,GAAG,SAAS,CAKjG;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,SAAS,CAUjG;AAED,oEAAoE;AACpE,wBAAsB,kBAAkB,CACtC,MAAM,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkB,GAC3C,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkB,GAC3C,OAAO,CAAC,IAAI,CAAC,CAWf;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC,GAAG,mBAAmB,GAAG,SAAS,CA8ElC;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAM1C"}