@cursor/july 0.1.1

package/dist/internal/peer-connections.js

@@ -0,0 +1,67 @@
+/**
+ * Peer MCP connections: `defineConnection({ agent: "<slug>" })` addresses
+ * another agent mounted on the same serve host. Discovery keeps the
+ * transport symbolic (the target slug); the server resolves it to that
+ * agent's MCP endpoint (`/<slug>/v1/mcp`) once mounts and the listen
+ * address are known.
+ *
+ * Local-runtime turns (and host-side `ctx.host.mcp` calls) use the loopback
+ * server URL. Cloud-runtime turns run on a VM that cannot reach loopback,
+ * so they use the serve `publicUrl` when configured — and omit the peer
+ * (with a startup warning) when it is not.
+ */
+import { isPeerConnectionTransport } from "../types.js";
+import { MCP_ENDPOINT_PATH } from "./mcp-endpoint.js";
+/**
+ * Validate every peer MCP connection across `mounts` and return them grouped by
+ * the referencing mount's slug. Throws on references to unknown slugs and on
+ * self-references (an agent asking itself recurses forever).
+ */
+export function collectPeerConnections(mounts) {
+    const knownSlugs = new Set(mounts.map(({ slug }) => slug).filter((slug) => slug !== ""));
+    const bySlug = new Map();
+    for (const { slug, project } of mounts) {
+        const refs = [];
+        for (const connection of project.agent.connections) {
+            if (!isPeerConnectionTransport(connection.transport)) {
+                continue;
+            }
+            const targetSlug = connection.transport.agent;
+            const label = slug === "" ? project.name : slug;
+            if (targetSlug === slug) {
+                throw new Error(`Agent "${label}" connection "${connection.name}" references itself (agent: "${targetSlug}"); an agent cannot be its own peer.`);
+            }
+            if (!knownSlugs.has(targetSlug)) {
+                const available = [...knownSlugs].sort().join(", ") || "(none)";
+                throw new Error(`Agent "${label}" connection "${connection.name}" references unknown peer agent "${targetSlug}". Mounted agents: ${available}. Peers require multi-agent serve (each agent mounted under its directory-name slug).`);
+            }
+            refs.push({ name: connection.name, targetSlug });
+        }
+        if (refs.length > 0) {
+            bySlug.set(slug, refs);
+        }
+    }
+    return bySlug;
+}
+/**
+ * Resolve validated peer refs to concrete MCP URLs once the server is
+ * listening. `serverUrl` is the loopback base (`http://127.0.0.1:<port>`);
+ * `publicUrl` (when configured) is the externally reachable base used for
+ * cloud-runtime turns. When the host requires a bearer token, it is attached
+ * so peer calls pass the target agent's auth chain.
+ */
+export function resolvePeerConnections(args) {
+    const serverBase = trimTrailingSlash(args.serverUrl);
+    const publicBase = args.publicUrl === undefined
+        ? undefined
+        : trimTrailingSlash(args.publicUrl);
+    const headers = args.authToken === undefined
+        ? undefined
+        : { authorization: `Bearer ${args.authToken}` };
+    return args.refs.map((ref) => (Object.assign(Object.assign({ name: ref.name, localUrl: `${serverBase}/${ref.targetSlug}${MCP_ENDPOINT_PATH}` }, (publicBase === undefined
+        ? {}
+        : { cloudUrl: `${publicBase}/${ref.targetSlug}${MCP_ENDPOINT_PATH}` })), (headers === undefined ? {} : { headers }))));
+}
+function trimTrailingSlash(url) {
+    return url.endsWith("/") ? url.slice(0, -1) : url;
+}

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

@@ -0,0 +1,35 @@
+/**
+ * Serves the built Vite playground SPA and the multi-agent index 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.
+ */
+export declare function renderPlaygroundIndexHtml(baseHref: string): string;
+/** Serve one built asset from `dist/playground/assets/` by filename. */
+export declare function renderPlaygroundAsset(file: string): Response;
+/** One row on the multi-agent index page. */
+export interface AgentIndexEntry {
+    slug: string;
+    name: string;
+    model: string;
+    tools: number;
+    channels: number;
+}
+/** Standalone index page listing every mounted agent (multi-agent serving). */
+export declare function renderAgentsIndexHtml(agents: AgentIndexEntry[]): 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;AAcH,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiBvD,CAAC;AAEF,uEAAuE;AACvE,wBAAgB,sBAAsB,IAAI,OAAO,CAEhD;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUlE;AAED,wEAAwE;AACxE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAsB5D;AAED,6CAA6C;AAC7C,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;CAClB;AAED,+EAA+E;AAC/E,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,EAAE,GAAG,MAAM,CAiBvE"}

package/dist/internal/playground/static.js

@@ -0,0 +1,162 @@
+/**
+ * Serves the built Vite playground SPA and the multi-agent index 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",
+    ".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",
+};
+/** 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.
+ */
+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",
+        },
+    });
+}
+/** Standalone index page listing every mounted agent (multi-agent serving). */
+export function renderAgentsIndexHtml(agents) {
+    const cards = agents
+        .map((agent) => {
+        const meta = `${agent.model || "—"} · ${agent.tools} tool${agent.tools === 1 ? "" : "s"} · ${agent.channels} channel${agent.channels === 1 ? "" : "s"}`;
+        return `      <a class="card" href="/${escapeHtml(agent.slug)}/playground">
+        <div class="card-name">${escapeHtml(agent.name)}</div>
+        <div class="card-slug">/${escapeHtml(agent.slug)}</div>
+        <div class="card-meta">${escapeHtml(meta)}</div>
+      </a>`;
+    })
+        .join("\n");
+    return AGENTS_INDEX_TEMPLATE.replace("<!--CARDS-->", cards || '      <div class="card-meta">No agents mounted.</div>').replace("<!--COUNT-->", String(agents.length));
+}
+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-serve 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-serve 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 AGENTS_INDEX_TEMPLATE = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>agent-serve — agents</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; }
+      .agents-wrap { max-width: 880px; margin: 0 auto; padding: 48px 24px; }
+      .agents-wrap h1 { font-size: 20px; font-weight: 650; margin: 0 0 2px; }
+      .agents-wrap .sub { color: #8b949e; font-size: 13px; margin-bottom: 28px; }
+      .agents-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; }
+    </style>
+  </head>
+  <body>
+    <div class="agents-wrap">
+      <h1>agent-serve</h1>
+      <div class="sub"><!--COUNT--> agents mounted</div>
+      <div class="agents-grid">
+<!--CARDS-->
+      </div>
+    </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.
+ */
+/** `@anysphere/agent-serve` 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,4EAA4E;AAC5E,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;AAmCD,0EAA0E;AAC1E,wBAAgB,0BAA0B,IAAI,mBAAmB,GAAG,SAAS,CAW5E;AAED,wBAAgB,4BAA4B,IAAI,OAAO,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,aAAa,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,GACtC,MAAM,GAAG,SAAS,CAKpB;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,MAAM,GAAG,SAAS,CAUpB;AAED,oEAAoE;AACpE,wBAAsB,kBAAkB,CACtC,MAAM,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkB,GAC3C,OAAO,CAAC,IAAI,CAAC,CAoBf;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,CA4ElC;AAED,wBAAgB,iBAAiB,IAAI,MAAM,CAM1C"}

package/dist/internal/playground/toolchain.js

@@ -0,0 +1,226 @@
+/**
+ * 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.
+ */
+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 { 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";
+/** `@anysphere/agent-serve` package root (works from `src/` or `dist/`). */
+export function packageRoot() {
+    // src|dist/internal/playground/toolchain.ts → packages/agent-serve/
+    return fileURLToPath(new URL("../../..", import.meta.url));
+}
+/** Resolve the absolute path to vite's CLI bin without using blocked package exports. */
+function resolveViteCli(root) {
+    var _a;
+    var _b;
+    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"));
+                if (pkg.name === "vite") {
+                    const binRel = typeof pkg.bin === "string"
+                        ? pkg.bin
+                        : ((_b = (_a = pkg.bin) === null || _a === void 0 ? void 0 : _a.vite) !== null && _b !== void 0 ? _b : "bin/vite.js");
+                    const binAbs = join(dir, binRel);
+                    return existsSync(binAbs) ? binAbs : undefined;
+                }
+            }
+            const parent = dirname(dir);
+            if (parent === dir) {
+                break;
+            }
+            dir = parent;
+        }
+    }
+    catch (_c) {
+        return undefined;
+    }
+    return undefined;
+}
+/** True when playground sources + a resolvable `vite` CLI are present. */
+export function resolvePlaygroundToolchain() {
+    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() {
+    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) {
+    var _a;
+    if (mounts.length === 1 && ((_a = mounts[0]) === null || _a === void 0 ? void 0 : _a.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 = process.env) {
+    var _a;
+    const raw = (_a = env.AGENT_SERVE_BASE) === null || _a === void 0 ? void 0 : _a.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 function runPlaygroundBuild() {
+    return __awaiter(this, arguments, void 0, function* (logger = console.log) {
+        const toolchain = resolvePlaygroundToolchain();
+        if (toolchain === undefined) {
+            throw new Error("playground vite toolchain unavailable (need playground/ sources and the vite package)");
+        }
+        logger("[agent-serve] building playground (vite)...");
+        const code = yield 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-serve] 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 function ensurePlaygroundBundle() {
+    return __awaiter(this, arguments, void 0, function* (logger = console.log) {
+        if (playgroundBundleExists()) {
+            return;
+        }
+        if (resolvePlaygroundToolchain() === undefined) {
+            logger("[agent-serve] playground bundle missing and vite toolchain unavailable; /playground will show a build hint");
+            return;
+        }
+        yield runPlaygroundBuild(logger);
+    });
+}
+/**
+ * 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) {
+    var _a;
+    const logger = (_a = options.logger) !== null && _a !== void 0 ? _a : console.log;
+    const toolchain = resolvePlaygroundToolchain();
+    if (toolchain === undefined) {
+        return undefined;
+    }
+    const port = playgroundDevPort();
+    const multiAgent = options.multiAgent === true;
+    const env = Object.assign(Object.assign({}, 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;
+        }
+    }
+    const modeNote = multiAgent
+        ? " (multi-agent)"
+        : options.basePath
+            ? ` (base ${options.basePath})`
+            : "";
+    logger(`[agent-serve] playground HMR starting on http://127.0.0.1:${port}${modeNote}`);
+    const child = spawn(process.execPath, [toolchain.viteCli, "--config", VITE_CONFIG], {
+        cwd: toolchain.packageRoot,
+        env,
+        stdio: "inherit",
+    });
+    let stopped = false;
+    child.on("error", (err) => {
+        if (stopped) {
+            return;
+        }
+        logger(`[agent-serve] playground HMR 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-serve] playground HMR 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() {
+    var _a;
+    const parsed = Number((_a = process.env.AGENT_SERVE_PLAYGROUND_PORT) !== null && _a !== void 0 ? _a : "5273");
+    if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+        return 5273;
+    }
+    return parsed;
+}
+function spawnVite(toolchain, args, options) {
+    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 !== null && code !== void 0 ? code : 1);
+        });
+    });
+}

package/dist/internal/reminder-runner.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Per-session reminder runner: durable wake subscriptions with
+ * prompt XOR run, every/cron/delay/at schedules, and until as
+ * function XOR prompt.
+ */
+import type { ReminderCreateInput, ReminderInfo } from "../types.js";
+import { type ReminderRecord } from "./reminder-store.js";
+import { type SessionEngine } from "./session-engine.js";
+export { ReminderValidationError } from "./reminder-schedule.js";
+export declare class UnknownReminderError extends Error {
+    readonly availableReminderIds: string[];
+    constructor(reminderId: string, availableReminderIds: string[]);
+}
+export declare class ReminderRunner {
+    private readonly engine;
+    private readonly logger;
+    private readonly store;
+    private readonly handlers;
+    private readonly timers;
+    private readonly firing;
+    /** Single-flight idle gates keyed by `channelId:continuationToken`. */
+    private readonly idleGates;
+    private started;
+    constructor(engine: SessionEngine, logger?: (line: string) => void);
+    get storeRoot(): string;
+    /** Start deadline timers for armed reminders (call after restore). */
+    start(): Promise<void>;
+    stop(): void;
+    create(input: ReminderCreateInput): Promise<ReminderInfo>;
+    list(filter?: {
+        status?: ReminderRecord["status"];
+        purpose?: string;
+        continuationToken?: string;
+    }): Promise<ReminderInfo[]>;
+    cancel(id: string, reason?: string): Promise<ReminderInfo | undefined>;
+    /** Cancel all armed reminders matching a continuation token (e.g. PR closed). */
+    cancelForContinuation(continuationToken: string, reason: string): Promise<number>;
+    /** Fire one reminder immediately (dev / hillclimb). */
+    dispatch(reminderId: string): Promise<{
+        reminderId: string;
+        outcome: "fired" | "noop";
+        reason?: string;
+    }>;
+    private armTimer;
+    private clearTimer;
+    private fire;
+    private isSessionBusy;
+    private whenSessionIdle;
+    /**
+     * Follow-ups must use the bound session's principal. If the session is gone,
+     * disarm rather than creating a fresh APP_AUTH conversation.
+     */
+    private resolveFollowupAuth;
+    private deliverPrompt;
+    private sendFollowup;
+    private buildFireContext;
+    private buildUntilContext;
+    private disarm;
+    private afterFire;
+}
+export type { ReminderRecord } from "./reminder-store.js";
+//# sourceMappingURL=reminder-runner.d.ts.map

package/dist/internal/reminder-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reminder-runner.d.ts","sourceRoot":"","sources":["../../src/internal/reminder-runner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAEV,mBAAmB,EAGnB,YAAY,EAEb,MAAM,aAAa,CAAC;AASrB,OAAO,EAEL,KAAK,cAAc,EAEpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAoB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE3E,OAAO,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAC;AAEjE,qBAAa,oBAAqB,SAAQ,KAAK;IAG3C,QAAQ,CAAC,oBAAoB,EAAE,MAAM,EAAE;IAFzC,YACE,UAAU,EAAE,MAAM,EACT,oBAAoB,EAAE,MAAM,EAAE,EAIxC;CACF;AAyDD,qBAAa,cAAc;IAUvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAVzB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmC;IAC5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAC5D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,uEAAuE;IACvE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoC;IAC9D,OAAO,CAAC,OAAO,CAAS;IAExB,YACmB,MAAM,EAAE,aAAa,EACrB,MAAM,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAe,EAG3D;IAED,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,sEAAsE;IAChE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CA4B3B;IAED,IAAI,IAAI,IAAI,CAOX;IAEK,MAAM,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC,CA8D9D;IAEK,IAAI,CAAC,MAAM,CAAC,EAAE;QAClB,MAAM,CAAC,EAAE,cAAc,CAAC,QAAQ,CAAC,CAAC;QAClC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,iBAAiB,CAAC,EAAE,MAAM,CAAC;KAC5B,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CA4B1B;IAEK,MAAM,CACV,EAAE,EAAE,MAAM,EACV,MAAM,SAAoB,GACzB,OAAO,CAAC,YAAY,GAAG,SAAS,CAAC,CAkBnC;IAED,iFAAiF;IAC3E,qBAAqB,CACzB,iBAAiB,EAAE,MAAM,EACzB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAUjB;IAED,uDAAuD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;QAC1C,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC;QAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC,CAQD;IAED,OAAO,CAAC,QAAQ;IA4ChB,OAAO,CAAC,UAAU;YAQJ,IAAI;YAiHJ,aAAa;IAY3B,OAAO,CAAC,eAAe;IAsBvB;;;OAGG;YACW,mBAAmB;YAcnB,aAAa;YAcb,YAAY;IA0C1B,OAAO,CAAC,gBAAgB;IAyDxB,OAAO,CAAC,iBAAiB;YAeX,MAAM;YAYN,SAAS;CAoFxB;AAGD,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC"}