@cursor/bdk 0.2.1

package/dist/internal/server.js

@@ -0,0 +1,2464 @@
+/**
+ * The HTTP host: a plain node:http server that adapts requests to the Fetch
+ * API, resolves route auth, and dispatches to the built-in HTTP channel
+ * routes, custom channel routes (under `/v1/channels/<id>`), and the
+ * server-level health / info / dev-dispatch routes.
+ */
+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());
+    });
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+var __asyncValues = (this && this.__asyncValues) || function (o) {
+    if (!Symbol.asyncIterator) throw new TypeError("Symbol.asyncIterator is not defined.");
+    var m = o[Symbol.asyncIterator], i;
+    return m ? m.call(o) : (o = typeof __values === "function" ? __values(o) : o[Symbol.iterator](), i = {}, verb("next"), verb("throw"), verb("return"), i[Symbol.asyncIterator] = function () { return this; }, i);
+    function verb(n) { i[n] = o[n] && function (v) { return new Promise(function (resolve, reject) { v = o[n](v), settle(resolve, reject, v.done, v.value); }); }; }
+    function settle(resolve, reject, d, v) { Promise.resolve(v).then(function(v) { resolve({ value: v, done: d }); }, reject); }
+};
+import { Buffer } from "node:buffer";
+import { once } from "node:events";
+import { createServer } from "node:http";
+import { join } from "node:path";
+import { CURSOR_BITBUCKET_REPOS_HEADER, } from "../channels/bitbucket/api.js";
+import { getBitbucketCursorAccountRuntime, resolveCursorBitbucketProxyUrl, } from "../channels/bitbucket/cursor-account.js";
+import { dispatchDeploymentEvent, getDeploymentsChannelOptions, } from "../channels/deployments/deployments-channel.js";
+import { createCursorAccountGithubTokenResolver, createCursorGithubProxyHostResolver, cursorGithubPermissionsForChannel, getGithubCursorAccountRuntime, resolveCursorGithubCredentialScope, resolveCursorGithubPermissions, resolveCursorGithubProxyUrl, } from "../channels/github/cursor-account.js";
+import { findGitHubChannelTargets } from "../channels/github/forward.js";
+import { CURSOR_GITLAB_PROJECTS_HEADER, } from "../channels/gitlab/api.js";
+import { getGitLabCursorAccountRuntime, resolveCursorGitLabProxyUrl, } from "../channels/gitlab/cursor-account.js";
+import { getOriginCursorAccountRuntime, parseCursorOriginRepoScope, } from "../channels/origin/cursor-account.js";
+import { findOriginChannelTargets } from "../channels/origin/origin-channel.js";
+import { appendSlackQuietHint } from "../channels/slack/agentic-posted.js";
+import { allowAll, bearerAuth, localDevStrict } from "../channels.js";
+import { ARTIFACTS_PAGE_DEFAULT_LIMIT, ARTIFACTS_PAGE_MAX_LIMIT, InvalidArtifactCursorError, } from "./artifacts-store.js";
+import { browserOriginGuardOptionsForPublicUrl, isTrustedBrowserMutation, } from "./browser-origin-guard.js";
+import { invokeChannelRoute } from "./channel-route-dispatch.js";
+import { selectConversationMirror } from "./conversation-mirror.js";
+import { CursorAccountMcpBridge, collectCursorAccountConnections, cursorAccountMcpPath, } from "./cursor/account-mcp.js";
+import { CursorBackendClient } from "./cursor/backend-client.js";
+import { cursorBackendUrl, cursorExternalApiUrl, resolveApiKey, resolveApiKeySync, SIGN_IN_HINT, } from "./cursor/credentials.js";
+import { CursorGithubCredentialProvider } from "./cursor/github-credentials.js";
+import { DeploymentEventRelay, fanOutDeploymentEvent, mergeResolvedSubscriptions, resolveDeploymentSubscriptions, } from "./cursor-deployment-relay.js";
+import { CursorEventRelay, formatCursorScmDispatchOutcome, formatCursorScmEventLog, scmEventToGitHubPayload, scmMetadataToOriginPayload, } from "./cursor-event-relay.js";
+import { AGENT_SERVE_GENERATION_ENV_VAR } from "./cursor-relay-core.js";
+import { buildAgentDeployManifest } from "./deploy-manifest.js";
+import { formatDiagnostics, hasErrorDiagnostics, projectInfo } from "./discovery.js";
+import { packageVersion } from "./distribution.js";
+import { docsSiteExists, ensureDocsSiteBundle, renderDocsFile } from "./docs-site.js";
+import { EvalRunConflictError, EvalRunEmptyError, EvalRunNotRunningError, EvalRunStore, EvalRunUnknownError, } from "./eval-run-store.js";
+import { GUEST_NETWORK_PATH, guestNetworkReadinessResponse } from "./guest-network.js";
+import { collectGitHubTriggerTargets, collectOriginTriggerTargets, handleAgentServeTrigger, } from "./handleAgentServeTrigger.js";
+import { createHostPlatforms, warmupHostGitHubAuth } from "./host-platforms.js";
+import { registerHostedDeliveryRoute } from "./hosted-delivery.js";
+import { HOSTED_DELIVERY_HEADER, HOSTED_GUEST_RETRY_TERMINAL, hostedGuestErrorResponse, } from "./hosted-delivery-protocol.js";
+import { hostedErrorMessageOnly, hostedErrorStackSnippet } from "./hosted-execution-diag.js";
+import { flushHostedExecutionProcessDeath } from "./hosted-execution-flush.js";
+import { buildHttpChannelRoutes, errorResponse, jsonResponse, readJsonObject, requireSessionOwner, } from "./http-channel.js";
+import { incomingHeadersToFetch, incomingRequestHost } from "./incoming-headers-to-fetch.js";
+import { DEFAULT_SERVE_PORT, listenHttpServer } from "./listen-port.js";
+import { createLocalControlPlane } from "./local-control-plane.js";
+import { createLogRing } from "./log-ring.js";
+import { createAgentMcpEndpoint, createToolMcpEndpoint, MCP_ENDPOINT_PATH, TOOL_MCP_ENDPOINT_PATH, } from "./mcp-endpoint.js";
+import { mcpOauthServeCallbackPath, mcpOauthServeCallbackUrl } from "./mcp-oauth-on-demand.js";
+import { isLoopbackAddress } from "./net.js";
+import { createOtelCollector } from "./otel/collector.js";
+import { pickAuthoredOtel, resolveOtelConfig } from "./otel/config.js";
+import { instrumentHttp } from "./otel/http.js";
+import { createOtelRuntime, forceFlushOtelRuntime, shutdownOtelRuntime } from "./otel/runtime.js";
+import { collectPeerConnections } from "./peer-connections.js";
+import { PLATFORM_SCHEDULE_CATALOG_FILENAME, syncHostedPlatformSchedules, } from "./platform-schedule-sync.js";
+import { createCursorHostedPlatformTimers, createCursorHostedReminderControlPlane, } from "./platform-timers.js";
+import { renderAgentsIndexHtml, renderPlaygroundAsset, renderPlaygroundIndexHtml, } from "./playground/static.js";
+import { ensurePlaygroundBundle, playgroundDevBaseFromEnv, playgroundDevBasePath, startPlaygroundDevServer, } from "./playground/toolchain.js";
+import { collectMemoryHealthFields, sumEventLogStats } from "./process-memory-telemetry.js";
+import { claimFromDescriptor, } from "./reminder-control-plane-protocol.js";
+import { ReminderRunner, ReminderValidationError, rejectAnonymousReminderHandlers, UnknownReminderError, } from "./reminder-runner.js";
+import { mapThrownRequestError } from "./request-error-status.js";
+import { assertAccountConnectionsNotAnonymous, resolveMountConnections, validateMountConnectionsConfig, } from "./resolved-connections.js";
+import { Router } from "./router.js";
+import { RuntimeDispatchingRunner } from "./runtime-dispatch-runner.js";
+import { ScheduleRunner, UnknownScheduleError } from "./schedule-runner.js";
+import { CursorSdkRunner } from "./sdk-runner.js";
+import { HTTP_CHANNEL_ID, InvalidContinuationTokenError, SessionEngine, ToolInputError, ToolNotDirectlyCallableError, UnknownToolError, WorkspaceUnavailableError, } from "./session-engine.js";
+import { registerSessionRunFatalFlush, selectSessionRunLogStore, unregisterSessionRunFatalFlush, } from "./session-run-log.js";
+import { sessionUrlsForRequest } from "./session-urls.js";
+import { readSkillDetail, skillListEntry, UnknownSkillError } from "./skill-catalog.js";
+import { flushLocalStartLog, selectStartLogStore } from "./start-log-store.js";
+import { catalogDetailEntry, catalogListEntry } from "./tool-catalog.js";
+function memoryHealthFields(engines) {
+    return collectMemoryHealthFields({
+        eventLog: () => sumEventLogStats(engines.map(engine => engine.eventLogMemoryStats())),
+    });
+}
+const MAX_BODY_BYTES = 32 * 1024 * 1024;
+function localControlPlaneRoute(runtimes) {
+    for (const runtime of runtimes) {
+        if (runtime.controlPlane !== undefined) {
+            return input => runtime.controlPlane.routeContinuation(input);
+        }
+    }
+    return undefined;
+}
+function firstLocalControlPlane(runtimes) {
+    var _a;
+    return (_a = runtimes.find(runtime => runtime.controlPlane !== undefined)) === null || _a === void 0 ? void 0 : _a.controlPlane;
+}
+function isV2Project(project) {
+    return project.agent.architecture === "v2";
+}
+/**
+ * Start an HTTP server hosting one or more agents. A single agent with an
+ * empty slug serves at `/v1/*` and `/playground`; multiple agents each serve
+ * under `/<slug>/v1/*` and `/<slug>/playground`, with an index at `/`.
+ */
+export function startServer(mounts_1) {
+    return __awaiter(this, arguments, void 0, function* (mounts, options = {}) {
+        var _a, _b, _c, _d, _e, _f;
+        var _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3, _4, _5, _6;
+        var _7;
+        if (mounts.length === 0) {
+            throw new Error("startServer requires at least one agent mount");
+        }
+        const multi = mounts.length > 1 || ((_a = mounts[0]) === null || _a === void 0 ? void 0 : _a.slug) !== "";
+        for (const { slug, project } of mounts) {
+            if (hasErrorDiagnostics(project)) {
+                const label = slug === "" ? project.name : `${slug} (${project.name})`;
+                throw new Error(`Refusing to serve agent ${label} — it has errors:\n${formatDiagnostics(project.diagnostics.filter(d => d.severity === "error"))}`);
+            }
+        }
+        const logRing = createLogRing({ capacity: 2000 });
+        const logger = logRing.wrap((_g = options.logger) !== null && _g !== void 0 ? _g : ((line) => console.log(line)));
+        const dev = (_h = options.dev) !== null && _h !== void 0 ? _h : false;
+        const playground = (_j = options.playground) !== null && _j !== void 0 ? _j : true;
+        const hosted = options;
+        const noControlPlane = hosted.noControlPlane === true;
+        const scmProxyRequested = hosted.cursorScmProxy === true;
+        const runSchedules = (_k = options.schedules) !== null && _k !== void 0 ? _k : !dev;
+        const runReminders = (_l = options.reminders) !== null && _l !== void 0 ? _l : !dev;
+        // CURSOR_AGENTKIT_VERSION is still the env the SDK reads when building
+        // its client-version header (wire prefix remains `agentkit-`). Setting it
+        // here makes the internal-only agentkit_enabled gate apply to every turn.
+        (_m = (_7 = process.env).CURSOR_AGENTKIT_VERSION) !== null && _m !== void 0 ? _m : (_7.CURSOR_AGENTKIT_VERSION = packageVersion());
+        const authoredOtel = pickAuthoredOtel(mounts.map(m => ({
+            slug: m.slug,
+            name: m.project.name,
+            otel: m.project.otel,
+        })));
+        const resolveOtelExport = () => resolveOtelConfig({
+            authored: authoredOtel,
+            serve: options.otel,
+        });
+        const otelRuntime = createOtelRuntime(resolveOtelExport(), logger, {
+            resolveExport: resolveOtelExport,
+        });
+        const cursorGithubTargets = collectCursorGithubTargets(mounts);
+        const cursorOriginTargets = collectCursorOriginTargets(mounts);
+        const cursorGithubConfig = resolveCursorGithubEventConfig({
+            configured: options.cursorEvents,
+            targets: cursorGithubTargets,
+        });
+        const cursorOriginScope = resolveCursorOriginRepoScope({
+            explicitRepos: (_o = (_b = options.cursorEvents) === null || _b === void 0 ? void 0 : _b.repos) !== null && _o !== void 0 ? _o : [],
+            targets: cursorOriginTargets,
+        });
+        const effectiveCursorEvents = (_p = cursorGithubConfig.cursorEvents) !== null && _p !== void 0 ? _p : (cursorOriginScope === undefined ? undefined : { repos: [...cursorOriginScope.repos] });
+        // One resolution for every Cursor credential consumer (SDK runner, account
+        // MCP bridge, SCM event relay, GitHub credentials): explicit option →
+        // CURSOR_API_KEY → CURSOR_API_KEY_FILE (or the hosted default path) →
+        // CURSOR_SERVICE_ACCOUNT_KEY → stored `agent-sdk login`. SDK / GitHub /
+        // account MCP re-read later; Slack and deployment-event relays capture
+        // the key at start.
+        const accountKey = yield resolveApiKey(options.apiKey === undefined ? {} : { apiKey: options.apiKey });
+        // First present source wins (we define the order): option → env → file →
+        // service account → stored login. Re-read so bind can drop env or file
+        // onto a listening process.
+        const liveCursorApiKey = () => { var _a; return (_a = resolveApiKeySync(options.apiKey === undefined ? {} : { apiKey: options.apiKey })) === null || _a === void 0 ? void 0 : _a.apiKey; };
+        // The SCM relay reads the event stream as the signed-in user, so
+        // `cursorEvents` cannot work signed out. Require the credential before any
+        // slow or stateful startup work (playground build, channel onStart, cron).
+        const cursorEventsAuth = effectiveCursorEvents === undefined
+            ? undefined
+            : requireCursorEventsAuth(effectiveCursorEvents, accountKey);
+        // Two architectures + local CP + cursor-events would register two
+        // /v0/scm-events consumers (engine offset vs control-plane offset).
+        // Fail before engines or relays start. `--no-control-plane` mixed is one
+        // July consumer (v1 engine); hosted CP owns v2.
+        assertSingleCursorEventsLane({
+            noControlPlane,
+            config: effectiveCursorEvents,
+            auth: cursorEventsAuth,
+            v1Mounts: mounts.filter(mount => !isV2Project(mount.project)),
+            v2Mounts: mounts.filter(mount => isV2Project(mount.project)),
+            githubRepos: (_q = (_c = cursorGithubConfig.cursorEvents) === null || _c === void 0 ? void 0 : _c.repos) !== null && _q !== void 0 ? _q : [],
+            originRepos: (_r = cursorOriginScope === null || cursorOriginScope === void 0 ? void 0 : cursorOriginScope.repos) !== null && _r !== void 0 ? _r : [],
+        });
+        let cursorGithubCredentials;
+        // Proxy-wired GitHub token resolver for `ctx.host.github` when no startup
+        // token mint runs (empty repo scope): host Octokit calls must route
+        // through github-proxy exactly like channel Octokit calls.
+        let hostGithubProxyResolver;
+        if (cursorGithubTargets.length > 0) {
+            const githubProxyRequested = scmProxyRequested;
+            const needsGithubAuth = cursorGithubConfig.scope !== undefined || githubProxyRequested;
+            if (needsGithubAuth) {
+                const currentGithubApiKey = () => {
+                    const fromEvents = cursorEventsAuth === null || cursorEventsAuth === void 0 ? void 0 : cursorEventsAuth.apiKey.trim();
+                    if (fromEvents !== undefined && fromEvents !== "") {
+                        return fromEvents;
+                    }
+                    return liveCursorApiKey();
+                };
+                const githubApiKeyNow = currentGithubApiKey();
+                if (githubApiKeyNow === undefined && options.allowAnonymous !== true) {
+                    throw new Error("githubChannel({ cursorAccount: true }) could not resolve Cursor event authentication.");
+                }
+                if (options.allowAnonymous === true) {
+                    if (options.allowAnonymousCursorGithub !== true) {
+                        throw new Error("githubChannel({ cursorAccount: true }) cannot be served with --allow-anonymous because admitted callers could use the signed-in account's GitHub access. If every admitted caller is trusted (e.g. behind an SSO proxy), opt in with --allow-anonymous-cursor-github.");
+                    }
+                    logger("[agent-sdk] warning: --allow-anonymous-cursor-github — every admitted HTTP caller can drive sessions holding the signed-in account's repo-scoped GitHub credential; serve this only behind a trusted boundary (e.g. an SSO proxy)");
+                    if (githubApiKeyNow === undefined) {
+                        logger("[agent-sdk] GitHub auth: listening unsigned; credentials bind at task via CURSOR_API_KEY or CURSOR_API_KEY_FILE");
+                    }
+                }
+                if (cursorGithubConfig.permissions === "contents-write") {
+                    logger('[agent-sdk] warning: Cursor GitHub credentials include contents:write — the host holds a push-capable token shared with model-driven tools and untrusted webhook content; prefer permissions: "pr-write" unless this agent must push code');
+                }
+                const githubAuthBaseUrl = cursorExternalApiUrl();
+                const requireGithubApiKey = () => __awaiter(this, void 0, void 0, function* () {
+                    const apiKey = currentGithubApiKey();
+                    if (apiKey === undefined) {
+                        throw new Error(`githubChannel({ cursorAccount: true }) has no Cursor credential yet. ${SIGN_IN_HINT}`);
+                    }
+                    return apiKey;
+                });
+                const githubProxyUrl = githubProxyRequested
+                    ? resolveCursorGithubProxyUrl(githubAuthBaseUrl)
+                    : undefined;
+                if (cursorGithubConfig.scope !== undefined && githubApiKeyNow !== undefined) {
+                    const provider = new CursorGithubCredentialProvider({
+                        client: new CursorBackendClient({
+                            backendUrl: githubAuthBaseUrl,
+                            apiKey: githubApiKeyNow,
+                            getApiKey: () => { var _a; return (_a = currentGithubApiKey()) !== null && _a !== void 0 ? _a : ""; },
+                            logger,
+                        }),
+                        scope: cursorGithubConfig.scope,
+                        logger,
+                    });
+                    cursorGithubCredentials = provider;
+                    if (githubProxyUrl !== undefined) {
+                        // Proxy mode: channel Octokit calls carry the Cursor API key to the
+                        // backend forwarder, which swaps in the installation token server-side
+                        // and logs every call with per-deployment attribution. The provider
+                        // still runs so child `gh` processes get a `GH_TOKEN` lease (v1).
+                        const proxyTransport = {
+                            apiBaseUrl: githubProxyUrl,
+                            headers: {
+                                "x-cursor-github-repos": cursorGithubConfig.scope.repos.join(","),
+                                "x-cursor-github-permissions": cursorGithubConfig.permissions,
+                            },
+                        };
+                        for (const target of cursorGithubTargets) {
+                            target.accountRuntime.credentials.bind(requireGithubApiKey);
+                            target.accountRuntime.credentials.bindProxyTransport(proxyTransport);
+                        }
+                        logger(`[agent-sdk] GitHub auth: channel API calls route through ${githubProxyUrl}`);
+                    }
+                    else {
+                        for (const target of cursorGithubTargets) {
+                            target.accountRuntime.credentials.bind(() => provider.getToken());
+                        }
+                    }
+                }
+                else if (githubProxyUrl !== undefined) {
+                    // `cursorAccount: true` with no `--repo`: skip the startup token mint
+                    // (it requires a repo list) and let github-proxy take the repo from
+                    // each Octokit call. Hosted freeze bakes this flag into the template
+                    // so restore is GitHub-ready once Bind drops the key.
+                    const proxyTransport = {
+                        apiBaseUrl: githubProxyUrl,
+                        headers: {
+                            "x-cursor-github-permissions": cursorGithubConfig.permissions,
+                        },
+                    };
+                    for (const target of cursorGithubTargets) {
+                        target.accountRuntime.credentials.bind(requireGithubApiKey);
+                        target.accountRuntime.credentials.bindProxyTransport(proxyTransport);
+                    }
+                    // `ctx.host.github` gets the same proxy transport; without this it
+                    // would fall back to ambient auth (env token / `gh`) or an
+                    // unauthenticated Octokit, and every host GitHub call would 404.
+                    hostGithubProxyResolver = createCursorGithubProxyHostResolver({
+                        getApiKey: requireGithubApiKey,
+                        transport: proxyTransport,
+                    });
+                    logger(`[agent-sdk] GitHub auth: channel and host API calls route through ${githubProxyUrl} (repo scope per request)`);
+                }
+            }
+        }
+        // GitLab `cursorAccount` channels: `ctx.gitlab` routes through the SCM
+        // proxy in proxy mode. Without `--cursor-scm-proxy` the runtime stays
+        // unbound and the handle falls back to direct `GITLAB_TOKEN` access.
+        if (scmProxyRequested) {
+            const gitlabProxyUrl = resolveCursorGitLabProxyUrl(cursorExternalApiUrl());
+            let gitlabTargets = 0;
+            for (const mount of mounts) {
+                for (const channel of mount.project.channels) {
+                    const runtime = getGitLabCursorAccountRuntime(channel.definition);
+                    if (runtime === undefined) {
+                        continue;
+                    }
+                    gitlabTargets += 1;
+                    const transport = Object.assign({ apiBaseUrl: gitlabProxyUrl }, (runtime.scope === undefined
+                        ? {}
+                        : {
+                            headers: {
+                                [CURSOR_GITLAB_PROJECTS_HEADER]: runtime.scope.projects.join(","),
+                            },
+                        }));
+                    runtime.credentials.bind(() => __awaiter(this, void 0, void 0, function* () {
+                        const apiKey = liveCursorApiKey();
+                        if (apiKey === undefined) {
+                            throw new Error(`gitlabChannel({ cursorAccount }) has no Cursor credential yet. ${SIGN_IN_HINT}`);
+                        }
+                        return apiKey;
+                    }));
+                    runtime.credentials.bindProxyTransport(transport);
+                }
+            }
+            if (gitlabTargets > 0) {
+                logger(`[agent-sdk] GitLab auth: channel API calls route through ${gitlabProxyUrl}`);
+            }
+            // Bitbucket `cursorAccount` channels: same shape, `/v0/bitbucket-proxy`
+            // with `x-cursor-bitbucket-repos` scope. The proxy picks Cloud 2.0 or
+            // the DC host's 1.0 upstream per tenant; the pack picks the dialect
+            // from the delivery payload.
+            const bitbucketProxyUrl = resolveCursorBitbucketProxyUrl(cursorExternalApiUrl());
+            let bitbucketTargets = 0;
+            for (const mount of mounts) {
+                for (const channel of mount.project.channels) {
+                    const runtime = getBitbucketCursorAccountRuntime(channel.definition);
+                    if (runtime === undefined) {
+                        continue;
+                    }
+                    bitbucketTargets += 1;
+                    const transport = Object.assign({ apiBaseUrl: bitbucketProxyUrl }, (runtime.scope === undefined
+                        ? {}
+                        : {
+                            headers: {
+                                [CURSOR_BITBUCKET_REPOS_HEADER]: runtime.scope.repos.join(","),
+                            },
+                        }));
+                    runtime.credentials.bind(() => __awaiter(this, void 0, void 0, function* () {
+                        const apiKey = liveCursorApiKey();
+                        if (apiKey === undefined) {
+                            throw new Error(`bitbucketChannel({ cursorAccount }) has no Cursor credential yet. ${SIGN_IN_HINT}`);
+                        }
+                        return apiKey;
+                    }));
+                    runtime.credentials.bindProxyTransport(transport);
+                }
+            }
+            if (bitbucketTargets > 0) {
+                logger(`[agent-sdk] Bitbucket auth: channel API calls route through ${bitbucketProxyUrl}`);
+            }
+        }
+        const resolvedCursorGithubCredentials = cursorGithubCredentials;
+        const hostGithubToken = hostGithubProxyResolver !== null && hostGithubProxyResolver !== void 0 ? hostGithubProxyResolver : (resolvedCursorGithubCredentials === undefined
+            ? undefined
+            : createCursorAccountGithubTokenResolver(() => resolvedCursorGithubCredentials.getToken()));
+        const hostPlatforms = createHostPlatforms(hostGithubToken === undefined ? {} : { githubCredentials: { token: hostGithubToken } });
+        if (playground) {
+            // Auto-build dist/playground when missing (monorepo / source checkout).
+            // Published installs already ship the bundle; vite may be absent there.
+            yield ensurePlaygroundBundle(logger);
+        }
+        const docsSite = (_s = options.docs) !== null && _s !== void 0 ? _s : true;
+        if (docsSite) {
+            // Same pattern for the documentation site at /docs.
+            yield ensureDocsSiteBundle(logger);
+        }
+        if (options.allowAnonymous === true) {
+            logger("[agent-sdk] warning: --allow-anonymous admits every HTTP caller as the same principal; use only on a trusted network (e.g. Tailscale) and prefer --bearer-token for shared hosts");
+        }
+        // v2 hosted engines mirror the SDK conversation store to the deployment's
+        // shared file storage so a fresh pod resumes threads instead of forking
+        // them. Hosted serve is single-agent; a multi-mount serve (dev) has no
+        // single agent name to mint keys under and does not mirror.
+        const conversationMirror = mounts.length === 1 && mounts[0] !== undefined
+            ? selectConversationMirror({ project: mounts[0].project, logger })
+            : undefined;
+        const sessionRunLog = (_t = options.sessionRunLog) !== null && _t !== void 0 ? _t : (mounts.length === 1 && mounts[0] !== undefined
+            ? selectSessionRunLogStore({
+                project: mounts[0].project,
+                logger,
+                snapshotLogs: () => logRing.since(),
+            })
+            : undefined);
+        const startLogStore = (_u = options.startLogStore) !== null && _u !== void 0 ? _u : (mounts.length === 1 && mounts[0] !== undefined
+            ? selectStartLogStore({
+                project: mounts[0].project,
+                logger,
+            })
+            : undefined);
+        // The running claim stamps this before the turn; process-death flush
+        // reuses it so the tee snapshot lands under the same ses_ key.
+        let lastStartLogId;
+        const flushStartLog = (startLogId) => __awaiter(this, void 0, void 0, function* () {
+            lastStartLogId = startLogId;
+            if (startLogStore === undefined) {
+                return;
+            }
+            yield flushLocalStartLog({ store: startLogStore, startLogId });
+        });
+        if (sessionRunLog !== undefined) {
+            registerSessionRunFatalFlush((error) => __awaiter(this, void 0, void 0, function* () {
+                yield flushHostedExecutionProcessDeath({
+                    flushProcessDeath: (reason, flushError) => sessionRunLog.flushProcessDeath(reason, flushError),
+                    flushStartLog,
+                    startLogId: lastStartLogId,
+                    reason: "uncaught_exception",
+                    error,
+                });
+            }));
+        }
+        const sdkRunner = (_v = options.runner) !== null && _v !== void 0 ? _v : new CursorSdkRunner(Object.assign(Object.assign(Object.assign({}, (options.apiKey === undefined || options.apiKey.trim() === ""
+            ? {}
+            : { apiKey: options.apiKey })), (conversationMirror === undefined ? {} : { conversationMirror })), { logger }));
+        // Grok Bot turns run on Cursor's hosted Grok Bot (Sand) harness through
+        // the /v0/grokbot session API; the SDK side is a thin remote client. The
+        // dispatching runner is only interposed when a mount needs it. An
+        // injected test runner receives every turn, grokbot included.
+        const hasGrokBotMounts = mounts.some(mount => mount.project.agent.runtime === "grokbot");
+        // Fail closed like cursor-account GitHub/MCP: grokbot turns execute on the
+        // signed-in account's hosted computer, so anonymous admission needs its
+        // own opt-in.
+        if (hasGrokBotMounts && options.allowAnonymous === true) {
+            if (options.allowAnonymousGrokbot !== true) {
+                throw new Error('runtime: "grokbot" cannot be served with --allow-anonymous because admitted callers could drive the signed-in account\'s hosted Grok Bot computer. If every admitted caller is trusted (e.g. behind an SSO proxy), opt in with --allow-anonymous-grokbot.');
+            }
+            logger("[agent-sdk] warning: --allow-anonymous-grokbot — every admitted HTTP caller can drive turns on the signed-in account's hosted Grok Bot computer; serve this only behind a trusted boundary (e.g. an SSO proxy)");
+        }
+        let runner = sdkRunner;
+        if (hasGrokBotMounts && options.runner === undefined) {
+            // Cursor-internal client, left out of the npm tarball (`files`); loaded
+            // only when a mount needs it, so a published install fails here, before
+            // listen, rather than on the first turn.
+            const { GrokBotRunner } = yield import("./grokbot/runner.js").catch(() => {
+                throw new Error('runtime: "grokbot" is not available in the published @cursor/bdk package');
+            });
+            runner = new RuntimeDispatchingRunner({
+                sdkRunner,
+                grokbot: new GrokBotRunner({
+                    apiKey: options.apiKey,
+                    // `/v0/grokbot` lives on the external API (api.cursor.com), not
+                    // api2. Prefer that default over the account key's backendUrl.
+                    // Do not pass stored login as apiKey: that would pin it as an
+                    // option and beat a later CURSOR_API_KEY_FILE bind.
+                    backendUrl: cursorExternalApiUrl(),
+                }),
+            });
+            logger("[agent-sdk] grokbot runtime: remote client (turns run on the hosted Grok Bot harness)");
+        }
+        const router = new Router();
+        const runtimes = [];
+        const channelStopHooks = [];
+        let githubAuthWarmed = false;
+        // Validate peer MCP connections (defineConnection({ agent })) against the
+        // mount set before anything starts: unknown slugs and self-references are
+        // authoring errors. URLs resolve after listen, once the port is known.
+        const peerRefsBySlug = collectPeerConnections(mounts);
+        // Cursor account MCP connections (defineConnection({ cursorAccount: true }))
+        // need a signed-in host: their tools execute on the Cursor backend with
+        // the account's stored OAuth credentials. Fail fast at serve start instead
+        // of at the first turn.
+        const accountRefsBySlug = collectCursorAccountConnections(mounts);
+        assertAccountConnectionsNotAnonymous({
+            allowAnonymous: options.allowAnonymous,
+            allowAnonymousCursorAccountMcp: options.allowAnonymousCursorAccountMcp,
+            hasAccountConnections: accountRefsBySlug.size > 0,
+        });
+        if (options.allowAnonymous === true &&
+            options.allowAnonymousCursorAccountMcp === true &&
+            accountRefsBySlug.size > 0) {
+            logger("[agent-sdk] warning: --allow-anonymous-cursor-account-mcp — every admitted HTTP caller can drive Cursor account MCP connectors; serve this only behind a trusted boundary (e.g. an SSO proxy or hosted alias token)");
+        }
+        let accountBridge;
+        if (accountRefsBySlug.size > 0) {
+            if (accountKey === undefined && options.allowAnonymous !== true) {
+                throw new Error(`This project has Cursor account MCP connections (defineConnection({ cursorAccount: true })) but the host is not signed in to Cursor. ${SIGN_IN_HINT}`);
+            }
+            if (accountKey === undefined) {
+                logger("[agent-sdk] Cursor account MCP: listening unsigned; credentials bind at task via CURSOR_API_KEY or CURSOR_API_KEY_FILE");
+            }
+            accountBridge = new CursorAccountMcpBridge({
+                client: new CursorBackendClient({
+                    backendUrl: (_w = accountKey === null || accountKey === void 0 ? void 0 : accountKey.backendUrl) !== null && _w !== void 0 ? _w : cursorBackendUrl(),
+                    apiKey: (_x = accountKey === null || accountKey === void 0 ? void 0 : accountKey.apiKey) !== null && _x !== void 0 ? _x : "",
+                    getApiKey: () => { var _a; return (_a = liveCursorApiKey()) !== null && _a !== void 0 ? _a : ""; },
+                    logger,
+                }),
+                logger,
+                // Cloud turns reach the bridge through the serve publicUrl; without
+                // one, the bridge admits loopback callers only.
+                allowRemoteCallers: options.publicUrl !== undefined,
+            });
+        }
+        for (const { slug, project } of mounts) {
+            // Each agent gets an isolated state root so their sessions never mix.
+            const baseStateRoot = (_y = options.stateRoot) !== null && _y !== void 0 ? _y : join(project.rootDir, ".agent-serve");
+            const stateRoot = slug === "" ? baseStateRoot : join(baseStateRoot, slug);
+            const otelCollector = otelRuntime === undefined
+                ? undefined
+                : createOtelCollector(otelRuntime, project.name, logger);
+            const engine = new SessionEngine({
+                project,
+                stateRoot,
+                runner,
+                logger,
+                platforms: hostPlatforms,
+                otel: otelCollector,
+                otelMeter: otelRuntime === null || otelRuntime === void 0 ? void 0 : otelRuntime.meter,
+            });
+            engine.oauthCallbackHub.secrets = options.mcpOauthSecrets;
+            engine.oauthCallbackHub.secretsBind = {
+                slug: slug === "" ? undefined : slug,
+                cloudToolsUrl: options.cloudToolsUrl,
+            };
+            engine.oauthCallbackHub.logger = logger;
+            // Rehydrate sessions from the authored storage sink before any
+            // channel or route can address them (continuation tokens must resolve).
+            yield engine.restoreStoredSessions();
+            // Resolve a shared harness workspace in the background: on a large repo
+            // that takes seconds, and a deployment coming online should absorb it
+            // rather than whoever sends the first message. No-op unless the agent
+            // pins `local.workspaceDir`.
+            void engine.prewarmSharedWorkspace();
+            if (!githubAuthWarmed) {
+                // Soft ambient GitHub auth check before channel onStart (which may call
+                // host.github). Missing auth is a warning only — serve still starts.
+                yield warmupHostGitHubAuth(Object.assign({ logger, github: engine.host.github }, (cursorGithubCredentials === undefined ? {} : { authSource: "cursor-account" })));
+                githubAuthWarmed = true;
+            }
+            const scheduleRunner = new ScheduleRunner(engine, project, logger);
+            let reminderRunner;
+            const architecture = project.agent.architecture;
+            const useReminderCpProtocol = architecture === "v2";
+            const localControlPlane = noControlPlane
+                ? undefined
+                : yield createLocalControlPlane(Object.assign(Object.assign({ fireSchedule: name => scheduleRunner.dispatch(name) }, (useReminderCpProtocol
+                    ? {
+                        executeReminder: descriptor => reminderRunner.executeFire(descriptor),
+                    }
+                    : {
+                        fireReminder: (id, fireCount) => reminderRunner.dispatch(id, {
+                            expectedFireCount: fireCount,
+                        }),
+                    })), { stateDir: join(stateRoot, "control-plane"), armReminderClocks: runReminders, logger }));
+            const timerClient = noControlPlane ? createCursorHostedPlatformTimers() : localControlPlane;
+            const hostedReminderControlPlane = noControlPlane && useReminderCpProtocol
+                ? createCursorHostedReminderControlPlane()
+                : undefined;
+            const reminderControlPlane = useReminderCpProtocol
+                ? (localControlPlane !== null && localControlPlane !== void 0 ? localControlPlane : hostedReminderControlPlane)
+                : undefined;
+            reminderRunner = new ReminderRunner(engine, logger, timerClient, {
+                namedHandlers: (_z = project.reminders) !== null && _z !== void 0 ? _z : [],
+                // Architecture v2 rejects anonymous run/until everywhere (local + hosted).
+                rejectAnonymousHandlers: rejectAnonymousReminderHandlers({
+                    noControlPlane,
+                    architecture,
+                }),
+                architecture,
+                controlPlane: reminderControlPlane,
+                // Hosted admissions build their channel args with no request
+                // principal (`buildChannelHandlerArgs` → `auth: null`), so a fire that
+                // opens a session on a fresh pod uses the same one and a session
+                // restored from durable storage still matches.
+                hostedGuest: hostedReminderControlPlane === undefined ? undefined : { fireAuth: () => null },
+            });
+            const evalRuns = new EvalRunStore(project.rootDir, logger, 
+            // Playground eval history mirrors onto the defineStorage evals table.
+            (_d = engine.storage) === null || _d === void 0 ? void 0 : _d.evalRuns());
+            // Eval history restores with the same startup step as sessions (reads
+            // also hydrate lazily, but doing it here surfaces store problems at
+            // boot and makes /v1/dev/evals complete from the first request).
+            yield evalRuns.hydrate();
+            engine.setReminders({
+                create: input => reminderRunner.create(input),
+                list: filter => reminderRunner.list(filter),
+                cancel: (id, reason) => reminderRunner.cancel(id, reason),
+                cancelForContinuation: (token, reason) => reminderRunner.cancelForContinuation(token, reason),
+                rekeyContinuation: (channelId, oldToken, newToken) => reminderRunner.rekeyContinuation(channelId, oldToken, newToken),
+                dispatch: id => reminderRunner.dispatch(id),
+            });
+            engine.setEvals({
+                list: () => evalRuns.list(),
+                get: runId => evalRuns.get(runId),
+                listRunsWithActive: () => evalRuns.listRunsWithActive(),
+                start: input => evalRuns.start(input),
+                cancel: runId => evalRuns.cancel(runId),
+            });
+            const runtime = Object.assign(Object.assign({ slug,
+                project,
+                engine,
+                scheduleRunner,
+                reminderRunner,
+                evalRuns }, (localControlPlane === undefined ? {} : { controlPlane: localControlPlane })), (reminderControlPlane === undefined ? {} : { reminderControlPlane }));
+            runtimes.push(runtime);
+            const accountRefs = accountRefsBySlug.get(slug);
+            mountAgentRoutes(router, runtime, Object.assign(Object.assign(Object.assign(Object.assign({ dev,
+                playground,
+                noControlPlane,
+                multi,
+                logger,
+                logRing, diagStateRoot: baseStateRoot, sessionRunLog,
+                flushStartLog, flushOtel: () => forceFlushOtelRuntime(otelRuntime) }, (options.authToken === undefined ? {} : { authToken: options.authToken })), (options.allowAnonymous === true ? { allowAnonymous: true } : {})), (accountRefs !== undefined && accountBridge !== undefined
+                ? { accountBridge, accountRefs }
+                : {})), (sdkRunner instanceof CursorSdkRunner
+                ? {
+                    evictSdkSession: (sessionId) => {
+                        sdkRunner.evictSession(sessionId);
+                    },
+                }
+                : {})));
+            for (const channel of project.channels) {
+                const definition = channel.definition;
+                if (definition.onStop !== undefined) {
+                    channelStopHooks.push(() => { var _a; return (_a = definition.onStop) === null || _a === void 0 ? void 0 : _a.call(definition); });
+                }
+                if (definition.onStart !== undefined) {
+                    const startArgs = {
+                        send: (message, sendOptions) => engine.send(channel.id, message, sendOptions),
+                        architecture: project.agent.architecture,
+                        getSession: sessionId => engine.getChannelSession(channel.id, sessionId),
+                        receive: (target, input) => engine.receive(target, input),
+                        callTool: (toolName, input, callOptions) => engine.callTool(toolName, input, callOptions),
+                        emitAssistantMessage: (sessionId, text) => engine.emitAssistantMessage(sessionId, text),
+                        host: engine.host,
+                        waitUntil: promise => {
+                            engine.trackBackground(promise);
+                        },
+                        resolveApproval: (sessionId, callId, decision, auth) => engine.resolveApproval(sessionId, callId, decision, auth),
+                        resolveAuth: (sessionId, callId, decision, auth) => engine.resolveAuth(sessionId, callId, decision, auth),
+                        hasContinuationSession: continuationToken => engine.hasContinuationSession(channel.id, continuationToken),
+                        isContinuationBusy: continuationToken => engine.isContinuationBusy(channel.id, continuationToken),
+                        getContinuationLastBotMessageTs: continuationToken => engine.getContinuationLastBotMessageTs(channel.id, continuationToken),
+                        interruptContinuation: continuationToken => engine.interruptContinuation(channel.id, continuationToken),
+                        logger,
+                        artifacts: engine.artifacts,
+                    };
+                    try {
+                        yield definition.onStart(startArgs);
+                    }
+                    catch (error) {
+                        logger(`[agent-sdk] channel "${channel.id}" onStart failed: ${error instanceof Error ? ((_0 = error.stack) !== null && _0 !== void 0 ? _0 : error.message) : String(error)}`);
+                    }
+                }
+            }
+            if (timerClient !== undefined && runSchedules) {
+                yield syncHostedPlatformSchedules({
+                    timers: timerClient,
+                    schedules: project.schedules,
+                    catalogPath: join(stateRoot, PLATFORM_SCHEDULE_CATALOG_FILENAME),
+                    logger,
+                });
+            }
+            if (timerClient !== undefined) {
+                yield reminderRunner.hydrate();
+            }
+            localControlPlane === null || localControlPlane === void 0 ? void 0 : localControlPlane.startClocks();
+        }
+        if (docsSite) {
+            // The framework documentation site, mounted at /docs in both layouts
+            // ("docs" is a reserved slug). Static, no secrets; unauthenticated like
+            // the playground assets.
+            router.add({
+                method: "GET",
+                pattern: "/docs",
+                auth: "none",
+                handler: () => renderDocsFile(""),
+            });
+            router.add({
+                method: "GET",
+                pattern: "/docs/*path",
+                auth: "none",
+                handler: (_request, ctx) => { var _a; return renderDocsFile((_a = ctx.params.path) !== null && _a !== void 0 ? _a : ""); },
+            });
+        }
+        if (multi) {
+            // Host-level liveness for ALB / ECS health checks. Per-agent health stays
+            // at `/<slug>/v1/health`; without this, multi-mode has no `/v1/health`.
+            router.add({
+                method: "GET",
+                pattern: "/v1/health",
+                auth: "none",
+                handler: () => jsonResponse(Object.assign({ ok: true, agents: runtimes.map(({ slug, project }) => ({
+                        slug,
+                        name: project.name,
+                    })) }, memoryHealthFields(runtimes.map(runtime => runtime.engine)))),
+            });
+        }
+        // Orienting `/` for every layout (single empty-slug and multi).
+        // Lists playground links plus live routes (playground, health, docs).
+        if (playground) {
+            const entries = buildAgentIndexEntries(runtimes);
+            const indexHtml = renderAgentsIndexHtml(entries, {
+                docs: docsSite,
+                multi,
+            });
+            router.add({
+                method: "GET",
+                pattern: "/",
+                auth: "none",
+                handler: () => new Response(indexHtml, {
+                    headers: { "content-type": "text/html; charset=utf-8" },
+                }),
+            });
+            if (multi) {
+                router.add({
+                    method: "GET",
+                    pattern: "/v1/agents",
+                    auth: "none",
+                    handler: () => jsonResponse({ agents: entries }),
+                });
+            }
+        }
+        // Shared GitHub webhook ingress: one URL fans out to every mounted agent
+        // that declared a github channel. Signature verification is the caller's
+        // job (backend `/github_webhook` already verified); we only admit loopback
+        // so this route is not a public unsigned endpoint. Agents decide whether
+        // to run via their onPullRequest / onComment / … hooks.
+        const collectGitHubTargetsFrom = (selected) => collectGitHubTriggerTargets({
+            mounts: selected.map(runtime => ({
+                slug: runtime.slug,
+                channels: runtime.project.channels,
+                buildHandlerArgs: channelId => buildChannelHandlerArgs({ runtime, channelId }),
+            })),
+        });
+        const collectOriginTargetsFrom = (selected) => collectOriginTriggerTargets({
+            mounts: selected.map(runtime => ({
+                slug: runtime.slug,
+                channels: runtime.project.channels,
+                buildHandlerArgs: channelId => buildChannelHandlerArgs({ runtime, channelId }),
+            })),
+        });
+        const collectGitHubTargets = () => collectGitHubTargetsFrom(runtimes);
+        const v1Runtimes = runtimes.filter(runtime => !isV2Project(runtime.project));
+        const v2Runtimes = runtimes.filter(runtime => isV2Project(runtime.project));
+        const v1Mounts = mounts.filter(mount => !isV2Project(mount.project));
+        const v2Mounts = mounts.filter(mount => isV2Project(mount.project));
+        router.add({
+            method: "POST",
+            pattern: "/v1/webhooks/github",
+            auth: [localDevStrict()],
+            handler: (request) => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                var _b, _c;
+                const bodyText = yield request.text();
+                const routeContinuation = localControlPlaneRoute(runtimes);
+                const result = yield handleAgentServeTrigger(Object.assign({ type: "github", bodyText, eventName: request.headers.get("x-github-event"), deliveryId: (_b = request.headers.get("x-github-delivery")) !== null && _b !== void 0 ? _b : undefined, targets: collectGitHubTargets() }, (routeContinuation === undefined ? {} : { routeContinuation })));
+                const status = result.ok ? 202 : ((_c = (_a = result.targets[0]) === null || _a === void 0 ? void 0 : _a.status) !== null && _c !== void 0 ? _c : 500);
+                return jsonResponse(result, { status });
+            }),
+        });
+        for (const { slug, project } of mounts) {
+            validateMountConnectionsConfig(Object.assign(Object.assign({ slug,
+                project, accountRefs: accountRefsBySlug.get(slug) }, (options.publicUrl === undefined ? {} : { publicUrl: options.publicUrl })), { cloudToolsBridge: options.cloudToolsUrl !== undefined }));
+        }
+        yield cursorGithubCredentials === null || cursorGithubCredentials === void 0 ? void 0 : cursorGithubCredentials.start();
+        // Cursor SCM events: v1 stays on the engine poll. v2 ingest is local-CP
+        // only — hosted `--no-control-plane` skips the July poll (hosted CP wakes).
+        const routeContinuation = localControlPlaneRoute(runtimes);
+        const cursorEventsCommon = {
+            config: effectiveCursorEvents,
+            githubRepos: (_1 = (_e = cursorGithubConfig.cursorEvents) === null || _e === void 0 ? void 0 : _e.repos) !== null && _1 !== void 0 ? _1 : [],
+            originRepos: (_2 = cursorOriginScope === null || cursorOriginScope === void 0 ? void 0 : cursorOriginScope.repos) !== null && _2 !== void 0 ? _2 : [],
+            stateRoot: options.stateRoot,
+            auth: cursorEventsAuth,
+            logger,
+            cursorAccountOnly: options.cursorEvents === undefined &&
+                (cursorGithubTargets.length > 0 || cursorOriginTargets.length > 0),
+        };
+        const cursorEventRelay = startCursorEventRelay(Object.assign(Object.assign({}, cursorEventsCommon), { mounts: v1Mounts, collectGitHubTargets: () => collectGitHubTargetsFrom(v1Runtimes), collectOriginTargets: () => collectOriginTargetsFrom(v1Runtimes), lane: "engine", skippedV2: v2Mounts.length > 0 }));
+        const controlPlaneScmRelay = startCursorEventRelay(Object.assign(Object.assign(Object.assign(Object.assign({}, cursorEventsCommon), { mounts: v2Mounts, collectGitHubTargets: () => collectGitHubTargetsFrom(v2Runtimes), collectOriginTargets: () => collectOriginTargetsFrom(v2Runtimes) }), (routeContinuation === undefined ? {} : { routeContinuation })), { lane: "control-plane", start: false, stateDirName: join("control-plane", "cursor-events") }));
+        const localCp = firstLocalControlPlane(runtimes);
+        if (controlPlaneScmRelay !== undefined) {
+            if (localCp !== undefined) {
+                localCp.attachScmEvents(controlPlaneScmRelay);
+            }
+            else {
+                logger("[agent-sdk] cursor-events: skipping v2 scm-events poll (--no-control-plane); hosted CP owns ingest");
+            }
+        }
+        // Cursor deployment-events relay: automatic when a mounted agent authored
+        // `deploymentsChannel({ ... })`.
+        const cursorDeploymentRelay = startCursorDeploymentRelay({
+            options,
+            runtimes,
+            accountKey,
+            logger,
+        });
+        // Trust --public-url's host when a reverse proxy rewrites Host.
+        const browserOriginGuard = browserOriginGuardOptionsForPublicUrl(options.publicUrl);
+        const server = createServer((req, res) => {
+            void instrumentHttp(otelRuntime, req, res, () => handleRequest(router, req, res, logger, browserOriginGuard));
+        });
+        const host = (_3 = options.host) !== null && _3 !== void 0 ? _3 : "127.0.0.1";
+        const portWasExplicit = options.port !== undefined;
+        const requestedPort = (_4 = options.port) !== null && _4 !== void 0 ? _4 : DEFAULT_SERVE_PORT;
+        let boundPort;
+        try {
+            boundPort = yield listenHttpServer({
+                server,
+                host,
+                port: requestedPort,
+                portWasExplicit,
+                logger,
+            });
+        }
+        catch (error) {
+            yield cursorDeploymentRelay === null || cursorDeploymentRelay === void 0 ? void 0 : cursorDeploymentRelay.stop();
+            yield cursorEventRelay === null || cursorEventRelay === void 0 ? void 0 : cursorEventRelay.stop();
+            yield controlPlaneScmRelay === null || controlPlaneScmRelay === void 0 ? void 0 : controlPlaneScmRelay.stop();
+            cursorGithubCredentials === null || cursorGithubCredentials === void 0 ? void 0 : cursorGithubCredentials.stop();
+            yield shutdownOtelRuntime(otelRuntime);
+            throw error;
+        }
+        const address = server.address();
+        const displayHost = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+        const url = `http://${displayHost}:${boundPort}`;
+        const oauthOrigin = ((_5 = options.publicUrl) !== null && _5 !== void 0 ? _5 : url).replace(/\/$/, "");
+        // Resolve peer + Cursor account MCP connections now that the listen port is
+        // known (see resolved-connections.ts for the URL/runtime rules).
+        for (const runtime of runtimes) {
+            const peerRefs = peerRefsBySlug.get(runtime.slug);
+            const accountRefs = accountRefsBySlug.get(runtime.slug);
+            const resolved = resolveMountConnections(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ slug: runtime.slug, project: runtime.project, serverUrl: url }, (peerRefs === undefined ? {} : { peerRefs })), (accountRefs !== undefined && accountBridge !== undefined
+                ? { accountRefs, accountBridge }
+                : {})), (options.publicUrl === undefined ? {} : { publicUrl: options.publicUrl })), (options.authToken === undefined ? {} : { authToken: options.authToken })), { cloudToolsBridge: options.cloudToolsUrl !== undefined, logger }));
+            if (resolved.length > 0) {
+                runtime.engine.setResolvedConnections(resolved);
+            }
+            const oauthBase = runtime.slug === "" ? "" : `/${runtime.slug}`;
+            runtime.engine.setMcpOauthCallbackUrl(mcpOauthServeCallbackUrl(oauthOrigin, oauthBase));
+            if (accountBridge !== undefined && accountRefs !== undefined) {
+                const bridge = accountBridge;
+                runtime.engine.setCursorAccountAuthProbe((connection) => __awaiter(this, void 0, void 0, function* () {
+                    const ref = accountRefs.find(entry => entry.name === connection);
+                    if (ref === undefined) {
+                        return undefined;
+                    }
+                    return yield bridge.probeAuthUrl(ref);
+                }));
+            }
+            const hasServerTools = runtime.project.agent.tools.some(tool => tool.execution === "server");
+            // Host-bridged connections ride the same endpoint as server tools, so
+            // the cloud tools connection is set whenever either needs it.
+            const bridgeableNames = runtime.engine.cloudBridgeableConnectionNames();
+            const cloudCapable = runtime.project.agent.runtime === "cloud" || runtime.project.agent.cloud !== undefined;
+            if ((hasServerTools || bridgeableNames.length > 0) && cloudCapable) {
+                const basePath = runtime.slug === "" ? "" : `/${runtime.slug}`;
+                const publicToolsUrl = (_6 = options.cloudToolsUrl) !== null && _6 !== void 0 ? _6 : (options.publicUrl === undefined
+                    ? undefined
+                    : `${options.publicUrl.replace(/\/$/, "")}${basePath}${TOOL_MCP_ENDPOINT_PATH}`);
+                if (publicToolsUrl === undefined) {
+                    if (hasServerTools) {
+                        logger(`[agent-sdk] warning: agent "${runtime.project.name}" has server tools but no --public-url or --cloud-tools-url; cloud turns omit those tools.`);
+                    }
+                }
+                else {
+                    const resolveCloudToolsHeaders = options.cloudToolsUrl === undefined
+                        ? undefined
+                        : () => {
+                            const apiKey = liveCursorApiKey();
+                            return apiKey === undefined ? undefined : { authorization: `Bearer ${apiKey}` };
+                        };
+                    const headers = options.cloudToolsUrl !== undefined
+                        ? resolveCloudToolsHeaders === null || resolveCloudToolsHeaders === void 0 ? void 0 : resolveCloudToolsHeaders()
+                        : options.authToken === undefined
+                            ? undefined
+                            : { authorization: `Bearer ${options.authToken}` };
+                    if (options.cloudToolsUrl !== undefined && headers === undefined) {
+                        if (options.allowAnonymous !== true) {
+                            throw new Error(`Agent "${runtime.project.name}" needs a Cursor API key to authenticate --cloud-tools-url. ${SIGN_IN_HINT}`);
+                        }
+                        logger(`[agent-sdk] --cloud-tools-url: listening unsigned; Bearer resolves after task-time credential binding`);
+                    }
+                    runtime.engine.setCloudServerToolsConnection(Object.assign({ type: "http", url: publicToolsUrl }, (headers === undefined ? {} : { headers })), resolveCloudToolsHeaders);
+                }
+            }
+        }
+        const agents = runtimes.map(({ slug, project }) => ({
+            slug,
+            project,
+            url: slug === "" ? url : `${url}/${slug}`,
+        }));
+        for (const runtime of runtimes) {
+            runtime.evalRuns.loopbackUrl = runtime.slug === "" ? url : `${url}/${runtime.slug}`;
+        }
+        const runtimeBySlug = new Map(runtimes.map(r => [r.slug, r]));
+        // --dev: spawn Vite HMR. Single-agent infers the slug base; multi-agent
+        // serves `/<slug>/playground` on the HMR origin (optional AGENT_SERVE_BASE
+        // pins one slug at the HMR root instead).
+        let playgroundDev;
+        if (playground && dev) {
+            const pinnedBase = mounts.length === 1 ? playgroundDevBasePath(mounts) : playgroundDevBaseFromEnv();
+            const multiAgent = mounts.length > 1 && pinnedBase === undefined;
+            playgroundDev = startPlaygroundDevServer({
+                targetUrl: url,
+                basePath: pinnedBase,
+                multiAgent,
+                logger,
+            });
+        }
+        const handle = {
+            url,
+            port: address.port,
+            project: (_f = runtimes[0]) === null || _f === void 0 ? void 0 : _f.project,
+            agents,
+            dispatchSchedule: (name, slug) => {
+                var _a;
+                var _b;
+                if (slug === void 0) { slug = (_b = (_a = runtimes[0]) === null || _a === void 0 ? void 0 : _a.slug) !== null && _b !== void 0 ? _b : ""; }
+                const runtime = runtimeBySlug.get(slug);
+                if (runtime === undefined) {
+                    throw new Error(`Unknown agent slug "${slug}"`);
+                }
+                return runtime.scheduleRunner.dispatch(name);
+            },
+            createReminder: (input, slug) => {
+                var _a;
+                var _b;
+                if (slug === void 0) { slug = (_b = (_a = runtimes[0]) === null || _a === void 0 ? void 0 : _a.slug) !== null && _b !== void 0 ? _b : ""; }
+                const runtime = runtimeBySlug.get(slug);
+                if (runtime === undefined) {
+                    throw new Error(`Unknown agent slug "${slug}"`);
+                }
+                return runtime.reminderRunner.create(input);
+            },
+            listReminders: (filter, slug) => {
+                var _a;
+                var _b;
+                if (slug === void 0) { slug = (_b = (_a = runtimes[0]) === null || _a === void 0 ? void 0 : _a.slug) !== null && _b !== void 0 ? _b : ""; }
+                const runtime = runtimeBySlug.get(slug);
+                if (runtime === undefined) {
+                    throw new Error(`Unknown agent slug "${slug}"`);
+                }
+                return runtime.reminderRunner.list(filter);
+            },
+            cancelReminder: (id, options) => {
+                var _a;
+                var _b, _c;
+                const slug = (_c = (_b = options === null || options === void 0 ? void 0 : options.slug) !== null && _b !== void 0 ? _b : (_a = runtimes[0]) === null || _a === void 0 ? void 0 : _a.slug) !== null && _c !== void 0 ? _c : "";
+                const runtime = runtimeBySlug.get(slug);
+                if (runtime === undefined) {
+                    throw new Error(`Unknown agent slug "${slug}"`);
+                }
+                return runtime.reminderRunner.cancel(id, options === null || options === void 0 ? void 0 : options.reason);
+            },
+            dispatchReminder: (id, slug) => {
+                var _a;
+                var _b;
+                if (slug === void 0) { slug = (_b = (_a = runtimes[0]) === null || _a === void 0 ? void 0 : _a.slug) !== null && _b !== void 0 ? _b : ""; }
+                const runtime = runtimeBySlug.get(slug);
+                if (runtime === undefined) {
+                    throw new Error(`Unknown agent slug "${slug}"`);
+                }
+                return runtime.reminderRunner.dispatch(id);
+            },
+            callTool: (toolName, input, options) => {
+                var _a;
+                var _b;
+                const _c = options !== null && options !== void 0 ? options : {}, { slug } = _c, callOptions = __rest(_c, ["slug"]);
+                const runtime = runtimeBySlug.get((_b = slug !== null && slug !== void 0 ? slug : (_a = runtimes[0]) === null || _a === void 0 ? void 0 : _a.slug) !== null && _b !== void 0 ? _b : "");
+                if (runtime === undefined) {
+                    throw new Error(`Unknown agent slug "${slug}"`);
+                }
+                return runtime.engine.callTool(toolName, input, callOptions);
+            },
+            close: () => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                var _b;
+                if (sessionRunLog !== undefined) {
+                    yield flushHostedExecutionProcessDeath({
+                        flushProcessDeath: reason => sessionRunLog.flushProcessDeath(reason),
+                        flushStartLog,
+                        startLogId: lastStartLogId,
+                        reason: "process_exit",
+                    });
+                    unregisterSessionRunFatalFlush();
+                }
+                playgroundDev === null || playgroundDev === void 0 ? void 0 : playgroundDev.stop();
+                yield cursorDeploymentRelay === null || cursorDeploymentRelay === void 0 ? void 0 : cursorDeploymentRelay.stop();
+                yield cursorEventRelay === null || cursorEventRelay === void 0 ? void 0 : cursorEventRelay.stop();
+                yield controlPlaneScmRelay === null || controlPlaneScmRelay === void 0 ? void 0 : controlPlaneScmRelay.stop();
+                for (const runtime of runtimes) {
+                    (_a = runtime.controlPlane) === null || _a === void 0 ? void 0 : _a.stop();
+                    runtime.scheduleRunner.stop();
+                    runtime.reminderRunner.stop();
+                    // Before the engines close their storage coordinators, so the
+                    // interrupted-batch write can still reach the sink.
+                    runtime.evalRuns.close();
+                }
+                for (const stop of channelStopHooks) {
+                    try {
+                        yield stop();
+                    }
+                    catch (error) {
+                        logger(`[agent-sdk] channel onStop failed: ${error instanceof Error ? ((_b = error.stack) !== null && _b !== void 0 ? _b : error.message) : String(error)}`);
+                    }
+                }
+                server.close();
+                server.closeAllConnections();
+                try {
+                    yield Promise.all(runtimes.map(runtime => runtime.engine.close()));
+                }
+                finally {
+                    cursorGithubCredentials === null || cursorGithubCredentials === void 0 ? void 0 : cursorGithubCredentials.stop();
+                    yield shutdownOtelRuntime(otelRuntime);
+                }
+            }),
+        };
+        if ((playgroundDev === null || playgroundDev === void 0 ? void 0 : playgroundDev.url) !== undefined) {
+            handle.playgroundDevUrl = playgroundDev.url;
+        }
+        if (docsSite && docsSiteExists()) {
+            handle.docsUrl = `${handle.url}/docs`;
+        }
+        return handle;
+    });
+}
+function mountAgentRoutes(router, runtime, args) {
+    var _a, _b, _c;
+    const { slug, project, engine, scheduleRunner, reminderRunner, reminderControlPlane } = runtime;
+    const { dev, playground, noControlPlane, multi, logger, logRing, sessionRunLog, flushStartLog } = args;
+    // "" (single) -> "/v1/..."; "my-agent" (multi) -> "/my-agent/v1/...".
+    const base = slug === "" ? "" : `/${slug}`;
+    // The Cursor account MCP bridge for this mount's account MCP connections:
+    // loopback-only + per-boot bearer secret, never on the public auth chain.
+    if (args.accountBridge !== undefined && args.accountRefs !== undefined) {
+        const bridge = args.accountBridge;
+        const refByName = new Map(args.accountRefs.map(ref => [ref.name, ref]));
+        router.add({
+            method: "POST",
+            pattern: `${base}${cursorAccountMcpPath(":connection")}`,
+            auth: [bridge.authPolicy()],
+            handler: (request, ctx) => {
+                var _a, _b;
+                const ref = refByName.get((_a = ctx.params.connection) !== null && _a !== void 0 ? _a : "");
+                if (ref === undefined) {
+                    return errorResponse(404, "not_found", `No Cursor account MCP connection named "${(_b = ctx.params.connection) !== null && _b !== void 0 ? _b : ""}" on this agent.`);
+                }
+                return bridge.handle(request, ref, appendSlackQuietHint);
+            },
+        });
+    }
+    const defaultAuth = args.authToken !== undefined
+        ? [bearerAuth(args.authToken)]
+        : args.allowAnonymous === true
+            ? [allowAll()]
+            : [localDevStrict()];
+    const httpAuth = (_a = project.httpChannel.auth) !== null && _a !== void 0 ? _a : defaultAuth;
+    // Temporal posts this marker on a direct pod port-token fetch. The alias
+    // proxy strips it, so webhook/playground tokens cannot present it.
+    const platformTimerFireAuth = request => {
+        if (request.headers.get("x-agent-serve-timed-work") === "1") {
+            return {
+                authenticator: "app",
+                principalId: "agent-serve:timed-work",
+                principalType: "runtime",
+            };
+        }
+        return null;
+    };
+    // A v2 mount served under `--no-control-plane` is a hosted v2 guest: the
+    // hosted control plane drives it through the hosted delivery route below.
+    // Session HTTP is a control-plane surface, so such a guest mounts no
+    // `/v1/session*` or `/v1/sessions` routes — session starts arrive as hosted
+    // admissions (`agentsdk.session` on the built-in http channel) and session
+    // reads come from the control plane's runs surface and durable storage.
+    // Local dev, self-hosted serve, and hosted v1 keep the engine mounts.
+    const hostedV2Guest = noControlPlane === true && isV2Project(project);
+    if (hostedV2Guest) {
+        registerHostedDeliveryRoute(Object.assign(Object.assign(Object.assign(Object.assign({ router,
+            base, 
+            // The built-in http channel is not in `project.channels`; the control
+            // plane's session start (`agentsdk.session`) is delivered to it.
+            channels: [...project.channels, { id: HTTP_CHANNEL_ID, definition: project.httpChannel }], buildHandlerArgs: (channelId, hostedSessionId) => buildChannelHandlerArgs({
+                runtime,
+                channelId,
+                hostedSessionId,
+            }), fireReminder: (reminderId, fireCount) => reminderRunner.dispatch(reminderId, { expectedFireCount: fireCount }), executeReminderDescriptor: (descriptor) => __awaiter(this, void 0, void 0, function* () {
+                if (reminderControlPlane === undefined) {
+                    throw new Error("hosted reminder CP client is not configured");
+                }
+                const fireDescriptor = descriptor;
+                const outcome = yield reminderRunner.executeFire(fireDescriptor);
+                // applyReminderOutcome is idempotent and internally retries transient
+                // CP failures. Handler execution is at-least-once across Temporal
+                // re-admission if apply ultimately fails.
+                const apply = yield reminderControlPlane.applyReminderOutcome(claimFromDescriptor(fireDescriptor), outcome);
+                // Cancel/rekey winning the race is a successful no-op from the guest's
+                // perspective (fired work may have run; lifecycle authority stayed CP).
+                if (!apply.applied && apply.reason === "missing") {
+                    return {
+                        reminderId: descriptor.id,
+                        outcome: "noop",
+                        reason: apply.reason,
+                    };
+                }
+                return {
+                    reminderId: descriptor.id,
+                    outcome: "fired",
+                };
+            }), drainSessionDurability: sessionId => engine.drainSessionDurability(sessionId), flushOtel: args.flushOtel }, (args.diagStateRoot === undefined ? {} : { stateRoot: args.diagStateRoot })), (sessionRunLog === undefined
+            ? {}
+            : {
+                persistSessionRun: (document) => __awaiter(this, void 0, void 0, function* () {
+                    yield sessionRunLog.persist(document);
+                }),
+                flushStartLog,
+            })), { snapshotLogs: () => logRing.since() }), (args.evictSdkSession === undefined ? {} : { evictSdkSession: args.evictSdkSession })));
+    }
+    // Playground lists/opens Slack (and other channel) sessions across
+    // principals when `--dev` (loopback) or `--allow-anonymous` (trusted
+    // shared host, e.g. corp Okta ALB). Never when bearer / custom channel
+    // auth is set — those keep strict per-principal isolation.
+    const relaxSessionReadAuth = args.authToken === undefined &&
+        project.httpChannel.auth === undefined &&
+        (dev || args.allowAnonymous === true);
+    const relaxSessionReadAuthBeyondLoopback = args.allowAnonymous === true;
+    // Separate from read-relax: playground Approve/Deny on Slack-owned parked
+    // tools (Slack principals never match local/anonymous HTTP auth).
+    const relaxSessionApprovalAuth = relaxSessionReadAuth;
+    router.add({
+        method: "GET",
+        pattern: `${base}${mcpOauthServeCallbackPath()}`,
+        auth: "none",
+        handler: request => engine.oauthCallbackHub.handleCallback(request),
+    });
+    router.add({
+        method: "GET",
+        pattern: `${base}/v1/health`,
+        auth: "none",
+        // Temporal consumes this response before promoting a newly deployed pod.
+        // Include the framework build there so deploy observability gets the
+        // version from the process that will serve turns, with no second request.
+        handler: () => jsonResponse(Object.assign({ ok: true, name: project.name, version: packageVersion() }, memoryHealthFields([engine]))),
+    });
+    // TAS polls this after `/v1/health` and before the hosted POST. Auth none
+    // mirrors health: the engine is reachable only through the anyrun port
+    // proxy (network token) or the alias route.
+    router.add({
+        method: "GET",
+        pattern: `${base}${GUEST_NETWORK_PATH}`,
+        auth: "none",
+        handler: () => guestNetworkReadinessResponse(),
+    });
+    // Bootstrap the SPA can't derive from its own URL (agent name, dev mode, and
+    // — in multi-agent mode — where the agents index lives).
+    router.add({
+        method: "GET",
+        pattern: `${base}/v1/meta`,
+        auth: "none",
+        handler: () => jsonResponse(Object.assign({ name: project.name, dev, basePath: base, 
+            // Framework version, for SPA/engine skew observability now that the
+            // hosted playground shell is served centrally (backend deploys)
+            // while engines stay on their install-time version.
+            version: packageVersion() }, (multi ? { indexPath: "/" } : {}))),
+    });
+    router.add({
+        method: "GET",
+        pattern: `${base}/v1/info`,
+        auth: httpAuth,
+        handler: () => jsonResponse(projectInfo(project)),
+    });
+    // Hosted-only: the control plane's provision flow reads the deploy manifest
+    // from the running engine (same derivation as `july manifest`) right after
+    // the health probe, so every deploy surface — CLI, UI, redeploy — gets its
+    // declarations from the installed code without a client-side extraction
+    // step. `auth: "none"` mirrors `/v1/health`: hosted engines are reachable
+    // only through the anyrun port proxy (network token) or the alias route
+    // (alias token), and the route is not registered outside hosted mode, so
+    // self-hosted `july serve` never exposes the manifest unauthenticated.
+    if (process.env[AGENT_SERVE_GENERATION_ENV_VAR] !== undefined) {
+        router.add({
+            method: "GET",
+            pattern: `${base}/v1/manifest`,
+            auth: "none",
+            handler: () => jsonResponse(buildAgentDeployManifest(project)),
+        });
+    }
+    // Playground Logs tab: recent ServeOptions.logger lines (channels, sessions,
+    // webhook capture). `after` is an exclusive index cursor for polling.
+    router.add({
+        method: "GET",
+        pattern: `${base}/v1/logs`,
+        auth: httpAuth,
+        handler: request => {
+            var _a;
+            var _b;
+            const url = new URL(request.url);
+            const afterRaw = url.searchParams.get("after");
+            const after = afterRaw === null || afterRaw === "" ? -1 : Number.parseInt(afterRaw, 10);
+            const cursor = Number.isFinite(after) ? after : -1;
+            const entries = logRing.since(cursor);
+            return jsonResponse({
+                entries,
+                nextAfter: entries.length === 0 ? cursor : ((_b = (_a = entries[entries.length - 1]) === null || _a === void 0 ? void 0 : _a.index) !== null && _b !== void 0 ? _b : cursor),
+            });
+        },
+    });
+    // Session list is session surface: not mounted on a hosted v2 guest (the
+    // control plane owns session reads there; see hostedV2Guest above).
+    if (!hostedV2Guest) {
+        router.add({
+            method: "GET",
+            pattern: `${base}/v1/sessions`,
+            auth: httpAuth,
+            handler: (request, ctx) => __awaiter(this, void 0, void 0, function* () {
+                // Same gate as requireSessionOwner / relaxSessionReadAuth: never with
+                // bearer or custom channel auth (strict per-principal isolation).
+                // `--allow-anonymous` alone is a shared-principal trust boundary (corp
+                // Okta ALB); `--dev` alone stays loopback-only.
+                const includeAll = relaxSessionReadAuth &&
+                    (relaxSessionReadAuthBeyondLoopback ||
+                        (typeof ctx.requestIp === "string" && isLoopbackAddress(ctx.requestIp)));
+                // `?latest=1` — only the newest visible session. Clients binding a
+                // default session (agsh) do not need the whole list, and on hosted
+                // storage the whole list is a database scan.
+                const latest = new URL(request.url).searchParams.get("latest");
+                const listed = latest === "1" || latest === "true"
+                    ? yield engine.latestSessionWithSource(ctx.auth, { includeAll })
+                    : yield engine.listSessionsWithSource(ctx.auth, { includeAll });
+                return jsonResponse({
+                    sessions: listed.sessions,
+                    source: listed.source,
+                });
+            }),
+        });
+    }
+    // Durable artifacts (ctx.artifacts / tag_artifact), newest-updated first.
+    // Cursor-paginated: pass `pageToken` from the previous response's
+    // `nextPageToken`. A page can be short (even empty) with a nextPageToken
+    // when a sparse filter exhausted the per-call scan budget.
+    router.add({
+        method: "GET",
+        pattern: `${base}/v1/artifacts`,
+        auth: httpAuth,
+        handler: (request, ctx) => __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c;
+            const url = new URL(request.url);
+            const limitRaw = url.searchParams.get("limit");
+            let limit = ARTIFACTS_PAGE_DEFAULT_LIMIT;
+            if (limitRaw !== null && limitRaw !== "") {
+                const parsed = Number.parseInt(limitRaw, 10);
+                if (!Number.isInteger(parsed) || parsed < 1) {
+                    return errorResponse(400, "invalid_request", "`limit` must be a positive integer.");
+                }
+                limit = Math.min(parsed, ARTIFACTS_PAGE_MAX_LIMIT);
+            }
+            const kind = (_a = url.searchParams.get("kind")) !== null && _a !== void 0 ? _a : undefined;
+            const sessionId = (_b = url.searchParams.get("sessionId")) !== null && _b !== void 0 ? _b : undefined;
+            const pageToken = (_c = url.searchParams.get("pageToken")) !== null && _c !== void 0 ? _c : undefined;
+            // Same includeAll gate as /v1/sessions: never with bearer or custom
+            // channel auth (strict per-principal isolation); otherwise session
+            // ownership applies (see SessionEngine.pageArtifacts).
+            const includeAll = relaxSessionReadAuth &&
+                (relaxSessionReadAuthBeyondLoopback ||
+                    (typeof ctx.requestIp === "string" && isLoopbackAddress(ctx.requestIp)));
+            let page;
+            try {
+                page = yield engine.pageArtifacts(ctx.auth, {
+                    includeAll,
+                    filter: { kind, sessionId },
+                    limit,
+                    cursor: pageToken,
+                });
+            }
+            catch (error) {
+                if (error instanceof InvalidArtifactCursorError) {
+                    return errorResponse(400, "invalid_request", "`pageToken` is not a valid page token.");
+                }
+                throw error;
+            }
+            return jsonResponse({
+                artifacts: page.records,
+                nextPageToken: page.nextCursor,
+            });
+        }),
+    });
+    // File/blob payload of one artifact (`tag({ contents })`).
+    router.add({
+        method: "GET",
+        pattern: `${base}/v1/artifacts/:id/content`,
+        auth: httpAuth,
+        handler: (_request, ctx) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            var _b, _c;
+            const includeAll = relaxSessionReadAuth &&
+                (relaxSessionReadAuthBeyondLoopback ||
+                    (typeof ctx.requestIp === "string" && isLoopbackAddress(ctx.requestIp)));
+            const found = yield engine.getArtifactContent(ctx.auth, (_b = ctx.params.id) !== null && _b !== void 0 ? _b : "", { includeAll });
+            if (found === undefined) {
+                return errorResponse(404, "not_found", "No such artifact, or it carries no content.");
+            }
+            // A view over bytes is a valid fetch body; the DOM lib types are
+            // narrower than the runtime.
+            // contentType is author/model-controlled and the playground shares
+            // this origin: force download, never render or sniff.
+            return new Response(found.body, {
+                headers: {
+                    "content-type": (_c = (_a = found.record.content) === null || _a === void 0 ? void 0 : _a.contentType) !== null && _c !== void 0 ? _c : "application/octet-stream",
+                    "content-disposition": "attachment",
+                    "x-content-type-options": "nosniff",
+                },
+            });
+        }),
+    });
+    // The agent's MCP surface: peers and external MCP clients delegate to
+    // this agent (ask / check / call_tool) over streamable HTTP. Stateless —
+    // POST only; GET/DELETE get a spec-compliant 405 from the endpoint.
+    const mcpEndpoint = createAgentMcpEndpoint({ engine, logger });
+    for (const method of ["POST", "GET", "DELETE"]) {
+        router.add({
+            method,
+            pattern: `${base}${MCP_ENDPOINT_PATH}`,
+            auth: httpAuth,
+            handler: (request, ctx) => mcpEndpoint.handle(request, ctx.auth),
+        });
+    }
+    const toolMcpEndpoint = createToolMcpEndpoint({ engine, logger });
+    for (const method of ["POST", "GET", "DELETE"]) {
+        router.add({
+            method,
+            pattern: `${base}${TOOL_MCP_ENDPOINT_PATH}`,
+            auth: defaultAuth,
+            handler: (request, ctx) => toolMcpEndpoint.handle(request, ctx.auth),
+        });
+    }
+    // The live tool catalog: the session's tool namespace as a turn would
+    // assemble it — authored server tools plus advertised MCP passthroughs —
+    // under model-facing names. `/v1/info` stays the static authored
+    // manifest; this is the runtime view only the running deployment can
+    // answer. `session` / `continuationToken` query parameters bind the
+    // listing to a session identity (advertised inventories can be
+    // tenant-scoped and resolved per session).
+    const resolveCatalogBinding = (request, ctx) => __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const url = new URL(request.url);
+        const sessionId = (_a = url.searchParams.get("session")) !== null && _a !== void 0 ? _a : undefined;
+        const continuationToken = (_b = url.searchParams.get("continuationToken")) !== null && _b !== void 0 ? _b : undefined;
+        if (sessionId !== undefined) {
+            const record = yield engine.sessions.get(sessionId);
+            if (record === undefined) {
+                return {
+                    errorResponse: errorResponse(404, "session_not_found", `Unknown session ${sessionId}.`),
+                };
+            }
+            const ownership = requireSessionOwner(record, ctx.auth, {
+                relax: relaxSessionReadAuth,
+                beyondLoopback: relaxSessionReadAuthBeyondLoopback,
+                requestIp: ctx.requestIp,
+            });
+            if (ownership !== undefined) {
+                return { errorResponse: ownership };
+            }
+        }
+        return { sessionId, continuationToken };
+    });
+    router.add({
+        method: "GET",
+        pattern: `${base}/v1/tools`,
+        auth: httpAuth,
+        handler: (request, ctx) => __awaiter(this, void 0, void 0, function* () {
+            const binding = yield resolveCatalogBinding(request, ctx);
+            if ("errorResponse" in binding) {
+                return binding.errorResponse;
+            }
+            try {
+                const catalog = yield engine.listCatalogTools(Object.assign({ auth: ctx.auth }, binding));
+                return jsonResponse({
+                    tools: catalog.tools.map(catalogListEntry),
+                    // JSON.stringify drops the key when there is nothing to report.
+                    connectionErrors: catalog.connectionErrors.length === 0 ? undefined : catalog.connectionErrors,
+                });
+            }
+            catch (error) {
+                if (error instanceof InvalidContinuationTokenError) {
+                    return errorResponse(400, "invalid_continuation_token", error.message);
+                }
+                throw error;
+            }
+        }),
+    });
+    router.add({
+        method: "GET",
+        pattern: `${base}/v1/tools/:toolName`,
+        auth: httpAuth,
+        handler: (request, ctx) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const toolName = (_a = ctx.params.toolName) !== null && _a !== void 0 ? _a : "";
+            const binding = yield resolveCatalogBinding(request, ctx);
+            if ("errorResponse" in binding) {
+                return binding.errorResponse;
+            }
+            try {
+                const described = yield engine.describeCatalogTool(toolName, Object.assign({ auth: ctx.auth }, binding));
+                if (described.tool === undefined) {
+                    return jsonResponse({
+                        ok: false,
+                        error: "unknown_tool",
+                        message: `Unknown tool "${toolName}".`,
+                        availableTools: described.availableTools,
+                    }, { status: 404 });
+                }
+                return jsonResponse(catalogDetailEntry(described.tool));
+            }
+            catch (error) {
+                if (error instanceof InvalidContinuationTokenError) {
+                    return errorResponse(400, "invalid_continuation_token", error.message);
+                }
+                throw error;
+            }
+        }),
+    });
+    // Deterministic tool invocation: run an authored server tool directly,
+    // without a model turn deciding to call it.
+    router.add({
+        method: "POST",
+        pattern: `${base}/v1/tools/:toolName`,
+        auth: httpAuth,
+        handler: (request, ctx) => __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const toolName = (_a = ctx.params.toolName) !== null && _a !== void 0 ? _a : "";
+            const body = yield readJsonObject(request);
+            if (body === undefined) {
+                return errorResponse(400, "invalid_request", 'Expected a JSON object body, e.g. {"input": {...}}.');
+            }
+            if (body.sessionId !== undefined && typeof body.sessionId !== "string") {
+                return errorResponse(400, "invalid_request", "`sessionId` must be a string when provided.");
+            }
+            if (body.continuationToken !== undefined && typeof body.continuationToken !== "string") {
+                return errorResponse(400, "invalid_request", "`continuationToken` must be a string when provided.");
+            }
+            const continuationToken = body.continuationToken;
+            const sessionId = body.sessionId;
+            if (sessionId !== undefined) {
+                const record = yield engine.sessions.get(sessionId);
+                if (record === undefined) {
+                    return errorResponse(404, "session_not_found", `Unknown session ${sessionId}.`);
+                }
+                const ownership = requireSessionOwner(record, ctx.auth, {
+                    relax: relaxSessionReadAuth,
+                    beyondLoopback: relaxSessionReadAuthBeyondLoopback,
+                    requestIp: ctx.requestIp,
+                });
+                if (ownership !== undefined) {
+                    return ownership;
+                }
+            }
+            try {
+                const outcome = yield engine.callTool(toolName, (_b = body.input) !== null && _b !== void 0 ? _b : {}, {
+                    auth: ctx.auth,
+                    sessionId,
+                    continuationToken,
+                });
+                return jsonResponse(Object.assign({ ok: !outcome.isError }, outcome));
+            }
+            catch (error) {
+                if (error instanceof UnknownToolError) {
+                    return jsonResponse({
+                        ok: false,
+                        error: "unknown_tool",
+                        message: error.message,
+                        availableTools: error.availableToolNames,
+                    }, { status: 404 });
+                }
+                if (error instanceof ToolNotDirectlyCallableError) {
+                    return errorResponse(400, "tool_not_callable", error.message);
+                }
+                if (error instanceof ToolInputError) {
+                    return errorResponse(400, "invalid_tool_input", error.message);
+                }
+                if (error instanceof InvalidContinuationTokenError) {
+                    return errorResponse(400, "invalid_continuation_token", error.message);
+                }
+                if (error instanceof WorkspaceUnavailableError) {
+                    return errorResponse(500, "workspace_unavailable", error.message);
+                }
+                throw error;
+            }
+        }),
+    });
+    // Deterministic skill reads: the body the harness would receive, plus
+    // resolved sibling files. Read-only, so plain GETs with no session binding.
+    router.add({
+        method: "GET",
+        pattern: `${base}/v1/skills`,
+        auth: httpAuth,
+        handler: () => __awaiter(this, void 0, void 0, function* () {
+            return jsonResponse({
+                skills: project.agent.skills.map(skillListEntry),
+            });
+        }),
+    });
+    router.add({
+        method: "GET",
+        pattern: `${base}/v1/skills/:skillName`,
+        auth: httpAuth,
+        handler: (_request, ctx) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const skillName = (_a = ctx.params.skillName) !== null && _a !== void 0 ? _a : "";
+            try {
+                return jsonResponse(yield readSkillDetail(project.agent.skills, skillName));
+            }
+            catch (error) {
+                if (error instanceof UnknownSkillError) {
+                    return jsonResponse({
+                        ok: false,
+                        error: "unknown_skill",
+                        message: error.message,
+                        availableSkills: error.availableSkillNames,
+                    }, { status: 404 });
+                }
+                throw error;
+            }
+        }),
+    });
+    if (playground) {
+        // Serve the built Vite SPA. `<base href>` is injected so the SPA's relative
+        // asset URLs resolve under this mount regardless of the trailing slash the
+        // browser lands on. Render per request so a mid-run `build:playground`
+        // is picked up without restarting. In dev, run `pnpm run dev:playground`
+        // (Vite + HMR) instead; it proxies `/v1` here.
+        router.add({
+            method: "GET",
+            pattern: `${base}/playground`,
+            auth: "none",
+            handler: () => new Response(renderPlaygroundIndexHtml(`${base}/playground/`), {
+                headers: { "content-type": "text/html; charset=utf-8" },
+            }),
+        });
+        router.add({
+            method: "GET",
+            pattern: `${base}/playground/assets/:file`,
+            auth: "none",
+            handler: (_request, ctx) => { var _a; return renderPlaygroundAsset((_a = ctx.params.file) !== null && _a !== void 0 ? _a : ""); },
+        });
+    }
+    // The built-in HTTP session channel (`/v1/session*`, including the
+    // session-scoped approvals/auths routes) is session surface: not mounted on
+    // a hosted v2 guest (see hostedV2Guest above). The `http` channel itself
+    // stays registered with the hosted delivery route, which is how the control
+    // plane's session starts reach it.
+    if (!hostedV2Guest) {
+        for (const route of buildHttpChannelRoutes({
+            engine,
+            config: project.httpChannel,
+            auth: httpAuth,
+            basePath: base,
+            // Dev playground lists every session (`includeAll`); allow opening them
+            // (see relaxSessionReadAuth above).
+            relaxSessionReadAuth,
+            relaxSessionReadAuthBeyondLoopback,
+            relaxSessionApprovalAuth,
+        })) {
+            router.add(route);
+        }
+    }
+    // Playground eval list/run — available without `--dev` (corp / allow-anonymous).
+    // Schedule/reminder hand-dispatch stays `--dev` only below.
+    router.add({
+        method: "GET",
+        pattern: `${base}/v1/dev/evals`,
+        auth: httpAuth,
+        handler: () => __awaiter(this, void 0, void 0, function* () { return jsonResponse(yield runtime.evalRuns.list()); }),
+    });
+    router.add({
+        method: "GET",
+        pattern: `${base}/v1/dev/evals/runs`,
+        auth: httpAuth,
+        handler: () => __awaiter(this, void 0, void 0, function* () {
+            return jsonResponse(yield runtime.evalRuns.listRunsWithActive());
+        }),
+    });
+    router.add({
+        method: "POST",
+        pattern: `${base}/v1/dev/evals/runs`,
+        auth: httpAuth,
+        handler: (request) => __awaiter(this, void 0, void 0, function* () {
+            const body = yield readJsonObject(request);
+            const filterIds = asStringArray(body === null || body === void 0 ? void 0 : body.filterIds);
+            const tags = asStringArray(body === null || body === void 0 ? void 0 : body.tags);
+            const timeoutMs = asPositiveInt(body === null || body === void 0 ? void 0 : body.timeoutMs);
+            const verbose = (body === null || body === void 0 ? void 0 : body.verbose) === true;
+            const authHeader = request.headers.get("authorization");
+            const bearerToken = (authHeader === null || authHeader === void 0 ? void 0 : authHeader.toLowerCase().startsWith("bearer "))
+                ? authHeader.slice("bearer ".length).trim()
+                : undefined;
+            try {
+                const snap = yield runtime.evalRuns.start(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, (filterIds === undefined ? {} : { filterIds })), (tags === undefined ? {} : { tags })), (bearerToken === undefined || bearerToken === "" ? {} : { bearerToken })), (timeoutMs === undefined ? {} : { timeoutMs })), (verbose ? { verbose: true } : {})));
+                return jsonResponse(snap, { status: 202 });
+            }
+            catch (error) {
+                if (error instanceof EvalRunConflictError) {
+                    return jsonResponse({
+                        ok: false,
+                        error: "eval_run_in_progress",
+                        activeRunId: error.activeRunId,
+                    }, { status: 409 });
+                }
+                if (error instanceof EvalRunEmptyError) {
+                    return jsonResponse({ ok: false, error: "no_matching_evals" }, { status: 404 });
+                }
+                const message = error instanceof Error ? error.message : String(error);
+                return jsonResponse({ ok: false, error: "eval_start_failed", message }, { status: 400 });
+            }
+        }),
+    });
+    router.add({
+        method: "GET",
+        pattern: `${base}/v1/dev/evals/runs/:runId`,
+        auth: httpAuth,
+        handler: (_request, ctx) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const runId = (_a = ctx.params.runId) !== null && _a !== void 0 ? _a : "";
+            const snap = yield runtime.evalRuns.get(runId);
+            if (snap === undefined) {
+                return jsonResponse({ ok: false, error: "unknown_eval_run" }, { status: 404 });
+            }
+            return jsonResponse(snap);
+        }),
+    });
+    router.add({
+        method: "POST",
+        pattern: `${base}/v1/dev/evals/runs/:runId/cancel`,
+        auth: httpAuth,
+        handler: (_request, ctx) => __awaiter(this, void 0, void 0, function* () {
+            var _a;
+            const runId = (_a = ctx.params.runId) !== null && _a !== void 0 ? _a : "";
+            try {
+                const snap = yield runtime.evalRuns.cancel(runId);
+                return jsonResponse(snap);
+            }
+            catch (error) {
+                if (error instanceof EvalRunUnknownError) {
+                    return jsonResponse({ ok: false, error: "unknown_eval_run" }, { status: 404 });
+                }
+                if (error instanceof EvalRunNotRunningError) {
+                    return jsonResponse({
+                        ok: false,
+                        error: "eval_run_not_running",
+                        runId: error.runId,
+                        status: error.status,
+                        message: error.message,
+                    }, { status: 409 });
+                }
+                const message = error instanceof Error ? error.message : String(error);
+                return jsonResponse({ ok: false, error: "eval_cancel_failed", message }, { status: 400 });
+            }
+        }),
+    });
+    if (noControlPlane === true) {
+        router.add({
+            method: "POST",
+            pattern: `${base}/v1/internal/schedules/:scheduleId/fire`,
+            auth: [platformTimerFireAuth],
+            handler: (_request, ctx) => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const scheduleId = (_a = ctx.params.scheduleId) !== null && _a !== void 0 ? _a : "";
+                try {
+                    const { sessionIds } = yield scheduleRunner.dispatch(scheduleId);
+                    return jsonResponse({ scheduleId, sessionIds });
+                }
+                catch (error) {
+                    if (error instanceof UnknownScheduleError) {
+                        return jsonResponse({
+                            ok: false,
+                            error: "unknown_schedule",
+                            availableScheduleIds: error.availableScheduleIds,
+                        }, { status: 404 });
+                    }
+                    throw error;
+                }
+            }),
+        });
+        router.add({
+            method: "POST",
+            pattern: `${base}/v1/internal/reminders/:reminderId/fire`,
+            auth: [platformTimerFireAuth],
+            handler: (request, ctx) => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const reminderId = (_a = ctx.params.reminderId) !== null && _a !== void 0 ? _a : "";
+                const fireCountRaw = new URL(request.url).searchParams.get("fireCount");
+                const expectedFireCount = fireCountRaw === null ? undefined : Number(fireCountRaw);
+                try {
+                    const result = yield reminderRunner.dispatch(reminderId, expectedFireCount !== undefined && Number.isInteger(expectedFireCount)
+                        ? { expectedFireCount }
+                        : {});
+                    return jsonResponse(result);
+                }
+                catch (error) {
+                    if (error instanceof UnknownReminderError) {
+                        return jsonResponse({
+                            ok: false,
+                            error: "unknown_reminder",
+                            availableReminderIds: error.availableReminderIds,
+                        }, { status: 404 });
+                    }
+                    if (error instanceof ReminderValidationError) {
+                        return jsonResponse({ ok: false, error: "invalid_reminder", message: error.message }, { status: 400 });
+                    }
+                    throw error;
+                }
+            }),
+        });
+    }
+    if (dev) {
+        router.add({
+            method: "POST",
+            pattern: `${base}/v1/dev/schedules/:scheduleId`,
+            auth: httpAuth,
+            handler: (_request, ctx) => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const scheduleId = (_a = ctx.params.scheduleId) !== null && _a !== void 0 ? _a : "";
+                try {
+                    const { sessionIds } = yield scheduleRunner.dispatch(scheduleId);
+                    return jsonResponse({ scheduleId, sessionIds });
+                }
+                catch (error) {
+                    if (error instanceof UnknownScheduleError) {
+                        return jsonResponse({
+                            ok: false,
+                            error: "unknown_schedule",
+                            availableScheduleIds: error.availableScheduleIds,
+                        }, { status: 404 });
+                    }
+                    throw error;
+                }
+            }),
+        });
+        router.add({
+            method: "POST",
+            pattern: `${base}/v1/dev/reminders/:reminderId`,
+            auth: httpAuth,
+            handler: (_request, ctx) => __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                const reminderId = (_a = ctx.params.reminderId) !== null && _a !== void 0 ? _a : "";
+                try {
+                    const listed = yield reminderRunner.list();
+                    const reminder = listed.find(r => r.id === reminderId);
+                    if (reminder === undefined) {
+                        const ids = listed.map(r => r.id);
+                        throw new UnknownReminderError(reminderId, ids);
+                    }
+                    const ownership = yield assertReminderReadable({
+                        engine,
+                        reminder,
+                        auth: ctx.auth,
+                        requestIp: ctx.requestIp,
+                        relax: relaxSessionReadAuth,
+                        beyondLoopback: relaxSessionReadAuthBeyondLoopback,
+                    });
+                    if (ownership !== undefined) {
+                        return ownership;
+                    }
+                    const result = yield reminderRunner.dispatch(reminderId);
+                    return jsonResponse(result);
+                }
+                catch (error) {
+                    if (error instanceof UnknownReminderError) {
+                        return jsonResponse({
+                            ok: false,
+                            error: "unknown_reminder",
+                            availableReminderIds: error.availableReminderIds,
+                        }, { status: 404 });
+                    }
+                    if (error instanceof ReminderValidationError) {
+                        return jsonResponse({ ok: false, error: "invalid_reminder", message: error.message }, { status: 400 });
+                    }
+                    throw error;
+                }
+            }),
+        });
+        router.add({
+            method: "GET",
+            pattern: `${base}/v1/dev/reminders`,
+            auth: httpAuth,
+            handler: (_request, ctx) => __awaiter(this, void 0, void 0, function* () {
+                const all = yield reminderRunner.list();
+                const reminders = [];
+                for (const reminder of all) {
+                    const denied = yield assertReminderReadable({
+                        engine,
+                        reminder,
+                        auth: ctx.auth,
+                        requestIp: ctx.requestIp,
+                        relax: relaxSessionReadAuth,
+                        beyondLoopback: relaxSessionReadAuthBeyondLoopback,
+                    });
+                    if (denied === undefined) {
+                        reminders.push(reminder);
+                    }
+                }
+                return jsonResponse({ reminders });
+            }),
+        });
+    }
+    for (const channel of project.channels) {
+        const channelAuth = (_b = channel.definition.auth) !== null && _b !== void 0 ? _b : defaultAuth;
+        for (const channelRoute of (_c = channel.definition.routes) !== null && _c !== void 0 ? _c : []) {
+            router.add({
+                method: channelRoute.method,
+                pattern: `${base}/v1/channels/${channel.id}${channelRoute.path}`,
+                auth: channelAuth,
+                handler: (request, ctx) => invokeChannelRoute({
+                    route: channelRoute,
+                    request,
+                    handlerArgs: buildChannelHandlerArgs({
+                        runtime,
+                        channelId: channel.id,
+                        params: ctx.params,
+                        requestIp: ctx.requestIp,
+                        auth: ctx.auth,
+                    }),
+                }),
+            });
+        }
+    }
+}
+/**
+ * `cursorEvents` (`--cursor-events`) long-polls `/v0/scm-events` as the host's
+ * Cursor user, so a signed-out host has no way to receive deliveries. Fail the
+ * serve instead of starting with a relay that could never run.
+ */
+function requireCursorEventsAuth(config, accountKey) {
+    var _a, _b, _c;
+    const apiKey = ((_b = (_a = config.apiKey) !== null && _a !== void 0 ? _a : accountKey === null || accountKey === void 0 ? void 0 : accountKey.apiKey) !== null && _b !== void 0 ? _b : "").trim();
+    if (apiKey === "") {
+        throw new Error(`[agent-sdk] --cursor-events (serve({ cursorEvents })) requires a signed-in Cursor account: the SCM event stream is read as the host's user. ${SIGN_IN_HINT}`);
+    }
+    return {
+        apiKey,
+        // `/v0/scm-events/*` lives on the external API (api.cursor.com), not
+        // api2. Prefer that default over the account key's backendUrl, which
+        // follows cursorBackendUrl() (api2) when CURSOR_API_KEY is set.
+        baseUrl: (_c = config.baseUrl) !== null && _c !== void 0 ? _c : cursorExternalApiUrl(),
+    };
+}
+/**
+ * Opt-in Cursor SCM events relay. Credentials are already required by
+ * {@link requireCursorEventsAuth}; the remaining unusable configs (no repos,
+ * no github/origin channel) warn and leave the relay off — serve still starts.
+ *
+ * GitHub and Origin subscriptions are registered independently so mirrored
+ * `owner/name` slugs do not mix. `--cursor-events --repo` feeds GitHub
+ * channels; Origin is subscribed only when an `originChannel({ cursorAccount })`
+ * opted in.
+ */
+function collectCursorEventSubscriptions(input) {
+    const githubTargets = findGitHubChannelTargets(input.mounts);
+    const originTargets = findOriginChannelTargets(input.mounts);
+    const githubEvents = [...new Set(githubTargets.flatMap(target => target.events))];
+    const originEvents = [...new Set(originTargets.flatMap(target => target.events))];
+    const githubRepos = [...new Set(input.githubRepos.map(repo => repo.trim().toLowerCase()))].filter(repo => repo.length > 0);
+    const originRepos = [...new Set(input.originRepos.map(repo => repo.trim().toLowerCase()))].filter(repo => repo.length > 0);
+    const subscriptions = [];
+    if (githubEvents.length > 0 && githubRepos.length > 0) {
+        for (const repo of githubRepos) {
+            subscriptions.push({
+                provider: "github",
+                repo,
+                events: githubEvents,
+            });
+        }
+    }
+    if (originEvents.length > 0 && originRepos.length > 0) {
+        for (const repo of originRepos) {
+            subscriptions.push({
+                provider: "origin",
+                repo,
+                events: originEvents,
+            });
+        }
+    }
+    return subscriptions;
+}
+/**
+ * Local CP + `--cursor-events` + both architectures would start two
+ * consumers (different offset dirs). Refuse that at serve start.
+ * `--no-control-plane` is one July consumer — hosted CP owns v2.
+ */
+function assertSingleCursorEventsLane(input) {
+    if (input.noControlPlane || input.config === undefined || input.auth === undefined) {
+        return;
+    }
+    const shared = {
+        githubRepos: input.githubRepos,
+        originRepos: input.originRepos,
+    };
+    if (collectCursorEventSubscriptions(Object.assign({ mounts: input.v1Mounts }, shared)).length === 0 ||
+        collectCursorEventSubscriptions(Object.assign({ mounts: input.v2Mounts }, shared)).length === 0) {
+        return;
+    }
+    throw new Error("[agent-sdk] cursor-events: refusing to serve v1 and v2 github/origin agents in one process — they would open two /v0/scm-events consumers. Serve one architecture per process.");
+}
+function startCursorEventRelay(input) {
+    var _a;
+    var _b, _c;
+    const { config, stateRoot, mounts, auth, logger } = input;
+    if (config === undefined || auth === undefined) {
+        return undefined;
+    }
+    const subscriptions = collectCursorEventSubscriptions({
+        mounts,
+        githubRepos: input.githubRepos,
+        originRepos: input.originRepos,
+    });
+    if (subscriptions.length === 0) {
+        if (input.lane === "engine" && input.skippedV2 === true) {
+            logger("[agent-sdk] cursor-events: no v1 github/origin targets; v2 ingest is control-plane only");
+        }
+        else if (input.lane === "control-plane") {
+            return undefined;
+        }
+        else if (input.githubRepos.every(repo => repo.trim() === "") &&
+            input.originRepos.every(repo => repo.trim() === "")) {
+            logger("[agent-sdk] cursor-events: no repos configured (pass --repo owner/name); relay disabled");
+        }
+        else {
+            logger("[agent-sdk] cursor-events: no mounted agent declares a github or origin channel; relay disabled");
+        }
+        return undefined;
+    }
+    const baseStateRoot = stateRoot !== null && stateRoot !== void 0 ? stateRoot : join((_b = (_a = mounts[0]) === null || _a === void 0 ? void 0 : _a.project.rootDir) !== null && _b !== void 0 ? _b : process.cwd(), ".agent-serve");
+    const relay = new CursorEventRelay({
+        baseUrl: auth.baseUrl,
+        apiKey: auth.apiKey,
+        subscriptions,
+        stateDir: join(baseStateRoot, (_c = input.stateDirName) !== null && _c !== void 0 ? _c : "cursor-events"),
+        logger,
+        dispatch: (event) => __awaiter(this, void 0, void 0, function* () {
+            if (event.provider === "origin") {
+                const targets = input.collectOriginTargets().filter(target => {
+                    const cursorAccount = target.options.cursorAccount;
+                    if (input.cursorAccountOnly &&
+                        cursorAccount !== true &&
+                        typeof cursorAccount !== "object") {
+                        return false;
+                    }
+                    return typeof cursorAccount !== "object"
+                        ? true
+                        : cursorAccount.repos.some(repo => repo.toLowerCase() === event.repo.toLowerCase());
+                });
+                const result = yield handleAgentServeTrigger(Object.assign({ type: "origin", bodyText: JSON.stringify(scmMetadataToOriginPayload(event)), targets }, (input.routeContinuation === undefined
+                    ? {}
+                    : { routeContinuation: input.routeContinuation })));
+                logCursorScmDispatch(logger, event, result);
+                return;
+            }
+            if (event.provider !== "github")
+                return;
+            const targets = input.collectGitHubTargets().filter(target => {
+                const cursorAccount = target.options.cursorAccount;
+                if (input.cursorAccountOnly &&
+                    cursorAccount !== true &&
+                    typeof cursorAccount !== "object") {
+                    return false;
+                }
+                return typeof cursorAccount !== "object"
+                    ? true
+                    : cursorAccount.repos.some(repo => repo.toLowerCase() === event.repo.toLowerCase());
+            });
+            const result = yield handleAgentServeTrigger(Object.assign({ type: "github", bodyText: JSON.stringify(scmEventToGitHubPayload(event)), eventName: event.eventName, deliveryId: event.deliveryId, targets }, (input.routeContinuation === undefined
+                ? {}
+                : { routeContinuation: input.routeContinuation })));
+            logCursorScmDispatch(logger, event, result);
+        }),
+    });
+    if (input.start === false) {
+        return relay;
+    }
+    relay.start();
+    logger(`[agent-sdk] cursor-events: relaying ${subscriptions.length} subscription(s) from ${auth.baseUrl}`);
+    return relay;
+}
+function logCursorScmDispatch(logger, event, result) {
+    const outcomes = result.targets.map(target => formatCursorScmDispatchOutcome(target)).join(", ");
+    const rejected = result.targets.filter(target => target.status >= 400);
+    if (rejected.length > 0) {
+        logger(`[agent-sdk] cursor-events: dropped ${formatCursorScmEventLog(event)} before hook: ${rejected.map(formatCursorScmDispatchOutcome).join(", ")}`);
+    }
+    logger(`[agent-sdk] cursor-events: dispatched ${formatCursorScmEventLog(event)}${outcomes === "" ? "" : ` → ${outcomes}`}`);
+}
+function collectCursorGithubTargets(mounts) {
+    const targets = [];
+    for (const mount of mounts) {
+        for (const channel of mount.project.channels) {
+            const accountRuntime = getGithubCursorAccountRuntime(channel.definition);
+            if (accountRuntime !== undefined) {
+                targets.push({
+                    slug: mount.slug,
+                    channelId: channel.id,
+                    accountRuntime,
+                });
+            }
+        }
+    }
+    return targets;
+}
+function cursorGithubPermissionsForTarget(target) {
+    var _a;
+    var _b;
+    const authored = typeof target.accountRuntime.options.cursorAccount === "object"
+        ? target.accountRuntime.options.cursorAccount.permissions
+        : undefined;
+    return ((_b = (_a = target.accountRuntime.scope) === null || _a === void 0 ? void 0 : _a.permissions) !== null && _b !== void 0 ? _b : cursorGithubPermissionsForChannel(target.accountRuntime.options, authored));
+}
+function resolveCursorGithubEventConfig(input) {
+    var _a;
+    var _b;
+    if (input.targets.length === 0) {
+        return {
+            cursorEvents: input.configured,
+            scope: undefined,
+            permissions: "pr-write",
+        };
+    }
+    const repos = [
+        ...((_b = (_a = input.configured) === null || _a === void 0 ? void 0 : _a.repos) !== null && _b !== void 0 ? _b : []),
+        ...input.targets.flatMap(target => { var _a; var _b; return [...((_b = (_a = target.accountRuntime.scope) === null || _a === void 0 ? void 0 : _a.repos) !== null && _b !== void 0 ? _b : [])]; }),
+    ];
+    const permissions = resolveCursorGithubPermissions(input.targets.map(cursorGithubPermissionsForTarget));
+    const scope = resolveCursorGithubCredentialScope(repos, permissions);
+    if (scope === undefined) {
+        return {
+            cursorEvents: input.configured,
+            scope: undefined,
+            permissions,
+        };
+    }
+    return {
+        cursorEvents: Object.assign(Object.assign({}, input.configured), { repos: [...scope.repos] }),
+        scope,
+        permissions,
+    };
+}
+function collectCursorOriginTargets(mounts) {
+    const targets = [];
+    for (const mount of mounts) {
+        for (const channel of mount.project.channels) {
+            const accountRuntime = getOriginCursorAccountRuntime(channel.definition);
+            if (accountRuntime !== undefined) {
+                targets.push({
+                    slug: mount.slug,
+                    channelId: channel.id,
+                    accountRuntime,
+                });
+            }
+        }
+    }
+    return targets;
+}
+/**
+ * Origin cursorAccount repos. `true` takes the host's explicit `--repo`
+ * list (not GitHub channel-declared repos). `{ repos }` is self-contained.
+ */
+function resolveCursorOriginRepoScope(input) {
+    if (input.targets.length === 0) {
+        return undefined;
+    }
+    const wantsHostRepos = input.targets.some(target => target.accountRuntime.options.cursorAccount === true);
+    const repos = [
+        ...(wantsHostRepos ? input.explicitRepos : []),
+        ...input.targets.flatMap(target => { var _a; var _b; return (_b = (_a = target.accountRuntime.scope) === null || _a === void 0 ? void 0 : _a.repos) !== null && _b !== void 0 ? _b : []; }),
+    ];
+    if (repos.length === 0) {
+        return undefined;
+    }
+    return parseCursorOriginRepoScope(repos);
+}
+function buildAgentIndexEntries(runtimes) {
+    return runtimes.map(({ slug, project }) => {
+        var _a;
+        var _b;
+        const hasSlack = project.channels.some(channel => { var _a; return ((_a = channel.definition.meta) === null || _a === void 0 ? void 0 : _a.kind) === "slack"; });
+        return {
+            slug,
+            name: project.name,
+            model: typeof project.agent.model === "string"
+                ? project.agent.model
+                : ((_b = (_a = project.agent.model) === null || _a === void 0 ? void 0 : _a.id) !== null && _b !== void 0 ? _b : ""),
+            tools: project.agent.tools.length,
+            channels: project.channels.length + 1,
+            slack: hasSlack ? { kind: "socket" } : undefined,
+        };
+    });
+}
+/** Every mounted `deploymentsChannel`. Subscriptions are re-resolved live. */
+function collectCursorDeploymentTargets(runtimes) {
+    const targets = [];
+    for (const runtime of runtimes) {
+        for (const channel of runtime.project.channels) {
+            const options = getDeploymentsChannelOptions(channel.definition);
+            if (options === undefined) {
+                continue;
+            }
+            targets.push({
+                runtime,
+                channelId: channel.id,
+                options,
+            });
+        }
+    }
+    return targets;
+}
+function liveDeploymentSubscriptionUnion(targets) {
+    return mergeResolvedSubscriptions(targets.map(target => resolveDeploymentSubscriptions(target.options)));
+}
+/**
+ * Cursor deployment-events relay: automatic when a mounted agent authored
+ * `deploymentsChannel({ ... })`. One relay per process reads
+ * `/v0/deployment-events` for the union of every channel's deploy sources, and
+ * each event is routed to the channels that asked for it — the same ownership
+ * `startCursorEventRelay` has.
+ */
+function startCursorDeploymentRelay(input) {
+    var _a;
+    const { options, runtimes, accountKey, logger } = input;
+    const targets = collectCursorDeploymentTargets(runtimes);
+    if (targets.length === 0) {
+        return undefined;
+    }
+    if (accountKey === undefined) {
+        if (input.options.allowAnonymous === true) {
+            logger("[agent-sdk] deployment-events: skipped while unsigned; long-poll relays need a key at start");
+            return undefined;
+        }
+        throw new Error(`This project has channels subscribed to deployment events (deploymentsChannel({ ... })) but the host is not signed in to Cursor. ${SIGN_IN_HINT}`);
+    }
+    // Union is re-resolved on each heartbeat and fan-out so a channel that
+    // fills `deploySourceUris` after start registers the new URIs. This wire
+    // names every source, so a channel that omits the option registers nothing.
+    const initial = liveDeploymentSubscriptionUnion(targets);
+    if (initial.length === 0) {
+        logger(`[agent-sdk] deployment-events: no deploy sources yet on ${targets
+            .map(target => `${target.runtime.slug || target.runtime.project.name}/${target.channelId}`)
+            .join(", ")}; the relay will register when a channel lists some`);
+    }
+    // Same host split as scm-events: `/v0/deployment-events/*` is on
+    // api.cursor.com, not api2.
+    const baseStateRoot = (_a = options.stateRoot) !== null && _a !== void 0 ? _a : join(targets[0].runtime.project.rootDir, ".agent-serve");
+    const relay = new DeploymentEventRelay({
+        baseUrl: cursorExternalApiUrl(),
+        apiKey: accountKey.apiKey,
+        stateDir: join(baseStateRoot, "deployment-events"),
+        subscriptions: () => liveDeploymentSubscriptionUnion(targets),
+        logger,
+        dispatch: (event) => __awaiter(this, void 0, void 0, function* () {
+            return fanOutDeploymentEvent({
+                event,
+                logger,
+                targets: targets.map(target => ({
+                    name: `${target.runtime.slug || target.runtime.project.name}/${target.channelId}`,
+                    subscriptions: resolveDeploymentSubscriptions(target.options),
+                    deliver: delivered => dispatchDeploymentEvent({
+                        options: target.options,
+                        event: delivered,
+                        args: buildChannelHandlerArgs({
+                            runtime: target.runtime,
+                            channelId: target.channelId,
+                        }),
+                    }),
+                })),
+            });
+        }),
+    });
+    relay.start();
+    logger(`[agent-sdk] deployment-events: relaying ${initial.length} deploy-source subscription(s) to ${targets.length} channel(s)`);
+    return relay;
+}
+function buildChannelHandlerArgs(input) {
+    var _a, _b, _c;
+    const { runtime, channelId } = input;
+    const base = runtime.slug === "" ? "" : `/${runtime.slug}`;
+    const auth = (_a = input.auth) !== null && _a !== void 0 ? _a : null;
+    return {
+        params: (_b = input.params) !== null && _b !== void 0 ? _b : {},
+        requestIp: (_c = input.requestIp) !== null && _c !== void 0 ? _c : null,
+        auth,
+        host: runtime.engine.host,
+        artifacts: runtime.engine.artifacts,
+        send: (message, sendOptions = {}) => runtime.engine.send(channelId, message, Object.assign(Object.assign({}, sendOptions), { auth: sendOptions.auth !== undefined ? sendOptions.auth : auth, hostedSessionId: input.hostedSessionId })),
+        getSession: sessionId => runtime.engine.getChannelSession(channelId, sessionId),
+        receive: (target, inputReceive) => runtime.engine.receive(target, inputReceive),
+        callTool: (toolName, toolInput, callOptions) => runtime.engine.callTool(toolName, toolInput, callOptions),
+        waitUntil: promise => {
+            runtime.engine.trackBackground(promise);
+        },
+        sessionUrls: (req, sessionId) => sessionUrlsForRequest(req, base, sessionId),
+        hasContinuationSession: continuationToken => runtime.engine.hasContinuationSession(channelId, continuationToken),
+        isContinuationBusy: continuationToken => runtime.engine.isContinuationBusy(channelId, continuationToken),
+        getContinuationLastBotMessageTs: continuationToken => runtime.engine.getContinuationLastBotMessageTs(channelId, continuationToken),
+        interruptContinuation: continuationToken => runtime.engine.interruptContinuation(channelId, continuationToken),
+    };
+}
+function handleRequest(router, req, res, logger, browserOriginGuard) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        let response;
+        let hostedDeliveryRequest = false;
+        const method = (_a = req.method) !== null && _a !== void 0 ? _a : "GET";
+        try {
+            const request = yield toFetchRequest(req);
+            hostedDeliveryRequest = request.headers.get(HOSTED_DELIVERY_HEADER) === "1";
+            const requestErrorResponse = (status, error, message) => hostedDeliveryRequest
+                ? hostedGuestErrorResponse({
+                    status,
+                    error,
+                    retry: HOSTED_GUEST_RETRY_TERMINAL,
+                    message,
+                })
+                : errorResponse(status, error, message);
+            const url = new URL(request.url);
+            const match = router.match(request.method, url.pathname);
+            if (!isTrustedBrowserMutation(request, browserOriginGuard)) {
+                response = requestErrorResponse(403, "forbidden_origin", "Cross-origin browser mutations are not allowed.");
+            }
+            else if (match === undefined) {
+                response = router.hasPath(url.pathname)
+                    ? requestErrorResponse(405, "method_not_allowed", `${request.method} is not supported on ${url.pathname}.`)
+                    : requestErrorResponse(404, "not_found", `No route for ${request.method} ${url.pathname}.`);
+            }
+            else {
+                const requestIp = (_b = req.socket.remoteAddress) !== null && _b !== void 0 ? _b : null;
+                let auth = null;
+                let unauthorized = false;
+                if (match.route.auth !== "none") {
+                    auth = yield resolveAuth(match.route.auth, request, requestIp);
+                    unauthorized = auth === null;
+                }
+                response = unauthorized
+                    ? requestErrorResponse(401, "unauthorized", "No auth policy admitted this request. In production, configure channel auth (e.g. bearerAuth) — the default localDevStrict() policy only admits loopback callers with a loopback Host.")
+                    : yield match.route.handler(request, {
+                        params: match.params,
+                        requestIp,
+                        auth,
+                    });
+            }
+        }
+        catch (error) {
+            const mapped = mapThrownRequestError(error);
+            if (mapped !== undefined) {
+                response = hostedDeliveryRequest
+                    ? hostedGuestErrorResponse({
+                        status: mapped.status,
+                        error: mapped.code,
+                        retry: mapped.retry,
+                        message: mapped.message,
+                    })
+                    : errorResponse(mapped.status, mapped.code, mapped.message);
+            }
+            else {
+                logger(`[agent-sdk] request failed: ${error instanceof Error ? ((_c = error.stack) !== null && _c !== void 0 ? _c : error.message) : String(error)}`);
+                const snippet = hostedErrorStackSnippet(error);
+                const message = hostedDeliveryRequest
+                    ? hostedErrorMessageOnly(error)
+                    : snippet.length > 0
+                        ? `Internal server error: ${snippet}`
+                        : "Internal server error.";
+                response = hostedDeliveryRequest
+                    ? hostedGuestErrorResponse({
+                        status: 500,
+                        error: "internal_error",
+                        retry: HOSTED_GUEST_RETRY_TERMINAL,
+                        message,
+                    })
+                    : errorResponse(500, "internal_error", message);
+            }
+        }
+        try {
+            yield writeFetchResponse(response, res, method);
+        }
+        catch (error) {
+            logger(`[agent-sdk] response write failed: ${error instanceof Error ? error.message : String(error)}`);
+            res.destroy();
+        }
+    });
+}
+function resolveAuth(policies, request, requestIp) {
+    return __awaiter(this, void 0, void 0, function* () {
+        for (const policy of policies) {
+            const result = yield policy(request, { requestIp });
+            if (result !== null) {
+                return result;
+            }
+        }
+        return null;
+    });
+}
+function toFetchRequest(req) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b;
+        const method = (_a = req.method) !== null && _a !== void 0 ? _a : "GET";
+        const hostHeader = incomingRequestHost(req.headers);
+        const url = new URL((_b = req.url) !== null && _b !== void 0 ? _b : "/", `http://${hostHeader}`);
+        // Drop HTTP/2 pseudo-headers (`:method`, …) — Fetch `Headers` rejects them.
+        const headers = incomingHeadersToFetch(req.headers);
+        if (method === "GET" || method === "HEAD") {
+            return new Request(url, { method, headers });
+        }
+        const body = yield readBody(req);
+        // Buffer is a Uint8Array at runtime; TS's BodyInit wants ArrayBuffer-backed
+        // typed arrays, so re-view without copying.
+        return new Request(url, {
+            method,
+            headers,
+            body: new Uint8Array(body.buffer, body.byteOffset, body.byteLength),
+        });
+    });
+}
+function readBody(req) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, req_1, req_1_1;
+        var _b, e_1, _c, _d;
+        const chunks = [];
+        let total = 0;
+        try {
+            for (_a = true, req_1 = __asyncValues(req); req_1_1 = yield req_1.next(), _b = req_1_1.done, !_b; _a = true) {
+                _d = req_1_1.value;
+                _a = false;
+                const chunk = _d;
+                const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                total += buffer.length;
+                if (total > MAX_BODY_BYTES) {
+                    throw new Error("Request body too large");
+                }
+                chunks.push(buffer);
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (!_a && !_b && (_c = req_1.return)) yield _c.call(req_1);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+        return Buffer.concat(chunks);
+    });
+}
+function writeFetchResponse(response_1, res_1) {
+    return __awaiter(this, arguments, void 0, function* (response, res, method = "GET") {
+        const headers = {};
+        response.headers.forEach((value, key) => {
+            headers[key] = value;
+        });
+        res.writeHead(response.status, headers);
+        // HEAD responses must not include a body (RFC 9110 §9.3.2). Cancel any
+        // handler-produced stream so long-lived GET handlers (e.g. session SSE)
+        // still unsubscribe when served via the HEAD→GET fallback.
+        if (method === "HEAD" || response.body === null) {
+            if (response.body !== null) {
+                void response.body.cancel().catch(() => { });
+            }
+            res.end();
+            return;
+        }
+        const reader = response.body.getReader();
+        let clientGone = false;
+        const closed = new Promise(resolve => {
+            res.once("close", () => {
+                if (!res.writableFinished) {
+                    clientGone = true;
+                    void reader.cancel().catch(() => { });
+                }
+                resolve();
+            });
+        });
+        try {
+            while (!clientGone) {
+                const { done, value } = yield reader.read();
+                if (done) {
+                    break;
+                }
+                if (value !== undefined && value.length > 0) {
+                    if (!res.write(value) && !clientGone) {
+                        // Race against close so a vanished client can't wedge the loop
+                        // waiting for a drain that will never come.
+                        yield Promise.race([once(res, "drain"), closed]);
+                    }
+                }
+            }
+        }
+        catch (_a) {
+            void reader.cancel().catch(() => { });
+        }
+        res.end();
+    });
+}
+/**
+ * Dev reminder routes may only inspect/fire reminders whose bound session
+ * belongs to the caller (same principal), matching session read routes.
+ * Loopback `--dev` (and `--allow-anonymous`) can relax ownership like
+ * `GET /v1/sessions`.
+ */
+function asStringArray(value) {
+    if (!Array.isArray(value)) {
+        return undefined;
+    }
+    const out = [];
+    for (const item of value) {
+        if (typeof item === "string" && item.trim() !== "") {
+            out.push(item);
+        }
+    }
+    return out.length === 0 ? undefined : out;
+}
+function asPositiveInt(value) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        return undefined;
+    }
+    const n = Math.floor(value);
+    return n > 0 ? n : undefined;
+}
+function assertReminderReadable(input) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const existing = yield input.engine.sessions.findByContinuation(input.reminder.channelId, input.reminder.continuationToken);
+        if (existing === undefined) {
+            // No live session — still gate on relax/loopback so a shared-dev caller
+            // cannot enumerate orphan reminder metadata across principals.
+            const relaxOwnership = input.relax === true &&
+                (input.beyondLoopback === true ||
+                    (typeof input.requestIp === "string" && isLoopbackAddress(input.requestIp)));
+            if (relaxOwnership) {
+                return undefined;
+            }
+            // Without a session principal to compare, deny non-relaxed callers.
+            return errorResponse(403, "forbidden", "This reminder is bound to a session that is not visible to the caller.");
+        }
+        return requireSessionOwner(existing, input.auth, {
+            relax: input.relax,
+            beyondLoopback: input.beyondLoopback,
+            requestIp: input.requestIp,
+        });
+    });
+}