@cursor/bdk 0.2.1

package/src/internal/server.ts

@@ -0,0 +1,3135 @@
+/**
+ * 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.
+ */
+
+import { Buffer } from "node:buffer";
+import { once } from "node:events";
+import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import { join } from "node:path";
+import {
+  type BitbucketProxyTransport,
+  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 type { DeploymentsChannelOptions } from "../channels/deployments/types.js";
+import {
+  type CursorAccountGithubTokenResolver,
+  type CursorGithubRepoScope,
+  createCursorAccountGithubTokenResolver,
+  createCursorGithubProxyHostResolver,
+  cursorGithubPermissionsForChannel,
+  type GithubCursorAccountRuntime,
+  getGithubCursorAccountRuntime,
+  resolveCursorGithubCredentialScope,
+  resolveCursorGithubPermissions,
+  resolveCursorGithubProxyUrl,
+} from "../channels/github/cursor-account.js";
+import { findGitHubChannelTargets } from "../channels/github/forward.js";
+import {
+  CURSOR_GITLAB_PROJECTS_HEADER,
+  type GitLabProxyTransport,
+} from "../channels/gitlab/api.js";
+import {
+  getGitLabCursorAccountRuntime,
+  resolveCursorGitLabProxyUrl,
+} from "../channels/gitlab/cursor-account.js";
+import {
+  getOriginCursorAccountRuntime,
+  type OriginCursorAccountRuntime,
+  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 type {
+  AgentProject,
+  AgentServeHandle,
+  ArtifactPage,
+  AuthContext,
+  AuthPolicy,
+  ChannelHandlerArgs,
+  ChannelStartArgs,
+  MountedAgentInfo,
+  ReminderInfo,
+  ServeOptions,
+} from "../types.js";
+import {
+  ARTIFACTS_PAGE_DEFAULT_LIMIT,
+  ARTIFACTS_PAGE_MAX_LIMIT,
+  InvalidArtifactCursorError,
+} from "./artifacts-store.js";
+import {
+  type BrowserOriginGuardOptions,
+  browserOriginGuardOptionsForPublicUrl,
+  isTrustedBrowserMutation,
+} from "./browser-origin-guard.js";
+import { invokeChannelRoute } from "./channel-route-dispatch.js";
+import { selectConversationMirror } from "./conversation-mirror.js";
+import {
+  type CursorAccountConnectionRef,
+  CursorAccountMcpBridge,
+  collectCursorAccountConnections,
+  cursorAccountMcpPath,
+} from "./cursor/account-mcp.js";
+import { CursorBackendClient } from "./cursor/backend-client.js";
+import {
+  cursorBackendUrl,
+  cursorExternalApiUrl,
+  type ResolvedApiKey,
+  resolveApiKey,
+  resolveApiKeySync,
+  SIGN_IN_HINT,
+} from "./cursor/credentials.js";
+import { CursorGithubCredentialProvider } from "./cursor/github-credentials.js";
+import {
+  DeploymentEventRelay,
+  fanOutDeploymentEvent,
+  mergeResolvedSubscriptions,
+  type ResolvedSubscription,
+  resolveDeploymentSubscriptions,
+} from "./cursor-deployment-relay.js";
+import {
+  CursorEventRelay,
+  type CursorScmSubscription,
+  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 type { HostedReminderFireDescriptorPayload } from "./hosted-delivery-protocol.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, type LocalControlPlane } from "./local-control-plane.js";
+import type { RouteLocalIngressContinuation } from "./local-ingress.js";
+import { createLogRing, type LogRing } 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 type { McpOauthSecretsTarget } from "./mcp-oauth-persist.js";
+import { isLoopbackAddress } from "./net.js";
+import { createOtelCollector, type OtelCollector } 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 {
+  type AgentIndexEntry,
+  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,
+  type ReminderControlPlane,
+  type ReminderFireDescriptor,
+} 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, type ServerRouteContext } from "./router.js";
+import { RuntimeDispatchingRunner } from "./runtime-dispatch-runner.js";
+import { ScheduleRunner, UnknownScheduleError } from "./schedule-runner.js";
+import { type AgentRunner, 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: readonly SessionEngine[]) {
+  return collectMemoryHealthFields({
+    eventLog: () => sumEventLogStats(engines.map(engine => engine.eventLogMemoryStats())),
+  });
+}
+
+const MAX_BODY_BYTES = 32 * 1024 * 1024;
+
+/** One agent to serve: its slug (empty for single-agent mode) and project. */
+export interface AgentMount {
+  slug: string;
+  project: AgentProject;
+}
+
+interface MountedRuntime {
+  slug: string;
+  project: AgentProject;
+  engine: SessionEngine;
+  scheduleRunner: ScheduleRunner;
+  reminderRunner: ReminderRunner;
+  controlPlane?: LocalControlPlane;
+  /**
+   * Hosted (or local) reminder CP client for architecture v2 descriptor
+   * execution. Undefined when the project is not on the CP protocol.
+   */
+  reminderControlPlane?: ReminderControlPlane;
+  /** Playground eval batches (`/v1/dev/evals`); loopbackUrl set after listen. */
+  evalRuns: EvalRunStore;
+}
+
+function localControlPlaneRoute(
+  runtimes: readonly MountedRuntime[],
+): RouteLocalIngressContinuation | undefined {
+  for (const runtime of runtimes) {
+    if (runtime.controlPlane !== undefined) {
+      return input => runtime.controlPlane!.routeContinuation(input);
+    }
+  }
+  return undefined;
+}
+
+function firstLocalControlPlane(
+  runtimes: readonly MountedRuntime[],
+): LocalControlPlane | undefined {
+  return runtimes.find(runtime => runtime.controlPlane !== undefined)?.controlPlane;
+}
+
+function isV2Project(project: { agent: { architecture?: string } }): boolean {
+  return project.agent.architecture === "v2";
+}
+
+/** Internal-only options for {@link startServer} (not on public `serve`). */
+export interface StartServerInternalOptions {
+  /** Test seam: replace the Cursor SDK runner (integration tests). */
+  runner?: AgentRunner;
+  /** Test seam: bind the `--store` secrets client for on-demand MCP OAuth. */
+  mcpOauthSecrets?: McpOauthSecretsTarget;
+  /** Test seam: persist hosted-execution run logs without a live store. */
+  sessionRunLog?: ReturnType<typeof selectSessionRunLogStore>;
+  /** Test seam: persist the engine start.log tee without a live store. */
+  startLogStore?: ReturnType<typeof selectStartLogStore>;
+}
+
+/**
+ * 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 async function startServer(
+  mounts: AgentMount[],
+  options: ServeOptions & StartServerInternalOptions = {},
+): Promise<AgentServeHandle> {
+  if (mounts.length === 0) {
+    throw new Error("startServer requires at least one agent mount");
+  }
+  const multi = mounts.length > 1 || mounts[0]?.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(options.logger ?? ((line: string) => console.log(line)));
+  const dev = options.dev ?? false;
+  const playground = options.playground ?? true;
+  const hosted = options as {
+    noControlPlane?: boolean;
+    /** `--cursor-scm-proxy`: every cursorAccount SCM pack routes via the backend forwarder. */
+    cursorScmProxy?: boolean;
+  };
+  const noControlPlane = hosted.noControlPlane === true;
+  const scmProxyRequested = hosted.cursorScmProxy === true;
+  const runSchedules = options.schedules ?? !dev;
+  const runReminders = options.reminders ?? !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.
+  process.env.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: options.cursorEvents?.repos ?? [],
+    targets: cursorOriginTargets,
+  });
+  const effectiveCursorEvents =
+    cursorGithubConfig.cursorEvents ??
+    (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 = await 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 = (): string | undefined =>
+    resolveApiKeySync(options.apiKey === undefined ? {} : { apiKey: options.apiKey })?.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: cursorGithubConfig.cursorEvents?.repos ?? [],
+    originRepos: cursorOriginScope?.repos ?? [],
+  });
+
+  let cursorGithubCredentials: CursorGithubCredentialProvider | undefined;
+  // 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: CursorAccountGithubTokenResolver | undefined;
+  if (cursorGithubTargets.length > 0) {
+    const githubProxyRequested = scmProxyRequested;
+    const needsGithubAuth = cursorGithubConfig.scope !== undefined || githubProxyRequested;
+    if (needsGithubAuth) {
+      const currentGithubApiKey = (): string | undefined => {
+        const fromEvents = 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 = async (): Promise<string> => {
+        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: () => currentGithubApiKey() ?? "",
+            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: Omit<GitLabProxyTransport, "getApiKey"> = {
+          apiBaseUrl: gitlabProxyUrl,
+          ...(runtime.scope === undefined
+            ? {}
+            : {
+                headers: {
+                  [CURSOR_GITLAB_PROJECTS_HEADER]: runtime.scope.projects.join(","),
+                },
+              }),
+        };
+        runtime.credentials.bind(async () => {
+          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: Omit<BitbucketProxyTransport, "getApiKey"> = {
+          apiBaseUrl: bitbucketProxyUrl,
+          ...(runtime.scope === undefined
+            ? {}
+            : {
+                headers: {
+                  [CURSOR_BITBUCKET_REPOS_HEADER]: runtime.scope.repos.join(","),
+                },
+              }),
+        };
+        runtime.credentials.bind(async () => {
+          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 ??
+    (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.
+    await ensurePlaygroundBundle(logger);
+  }
+  const docsSite = options.docs ?? true;
+  if (docsSite) {
+    // Same pattern for the documentation site at /docs.
+    await 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 =
+    options.sessionRunLog ??
+    (mounts.length === 1 && mounts[0] !== undefined
+      ? selectSessionRunLogStore({
+          project: mounts[0].project,
+          logger,
+          snapshotLogs: () => logRing.since(),
+        })
+      : undefined);
+  const startLogStore =
+    options.startLogStore ??
+    (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: string | undefined;
+  const flushStartLog = async (startLogId: string): Promise<void> => {
+    lastStartLogId = startLogId;
+    if (startLogStore === undefined) {
+      return;
+    }
+    await flushLocalStartLog({ store: startLogStore, startLogId });
+  };
+  if (sessionRunLog !== undefined) {
+    registerSessionRunFatalFlush(async error => {
+      await flushHostedExecutionProcessDeath({
+        flushProcessDeath: (reason, flushError) =>
+          sessionRunLog.flushProcessDeath(reason, flushError),
+        flushStartLog,
+        startLogId: lastStartLogId,
+        reason: "uncaught_exception",
+        error,
+      });
+    });
+  }
+  const sdkRunner =
+    options.runner ??
+    new CursorSdkRunner({
+      ...(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: AgentRunner = 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 } = await 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: MountedRuntime[] = [];
+  const channelStopHooks: Array<() => void | Promise<void>> = [];
+  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: CursorAccountMcpBridge | undefined;
+  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: accountKey?.backendUrl ?? cursorBackendUrl(),
+        apiKey: accountKey?.apiKey ?? "",
+        getApiKey: () => liveCursorApiKey() ?? "",
+        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 = options.stateRoot ?? join(project.rootDir, ".agent-serve");
+    const stateRoot = slug === "" ? baseStateRoot : join(baseStateRoot, slug);
+    const otelCollector: OtelCollector | undefined =
+      otelRuntime === undefined
+        ? undefined
+        : createOtelCollector(otelRuntime, project.name, logger);
+    const engine = new SessionEngine({
+      project,
+      stateRoot,
+      runner,
+      logger,
+      platforms: hostPlatforms,
+      otel: otelCollector,
+      otelMeter: 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).
+    await 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.
+      await warmupHostGitHubAuth({
+        logger,
+        github: engine.host.github,
+        ...(cursorGithubCredentials === undefined ? {} : { authSource: "cursor-account" }),
+      });
+      githubAuthWarmed = true;
+    }
+    const scheduleRunner = new ScheduleRunner(engine, project, logger);
+    let reminderRunner!: ReminderRunner;
+    const architecture = project.agent.architecture;
+    const useReminderCpProtocol = architecture === "v2";
+    const localControlPlane = noControlPlane
+      ? undefined
+      : await createLocalControlPlane({
+          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 ?? hostedReminderControlPlane)
+      : undefined;
+    reminderRunner = new ReminderRunner(engine, logger, timerClient, {
+      namedHandlers: project.reminders ?? [],
+      // 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.
+      engine.storage?.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).
+    await 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: MountedRuntime = {
+      slug,
+      project,
+      engine,
+      scheduleRunner,
+      reminderRunner,
+      evalRuns,
+      ...(localControlPlane === undefined ? {} : { controlPlane: localControlPlane }),
+      ...(reminderControlPlane === undefined ? {} : { reminderControlPlane }),
+    };
+    runtimes.push(runtime);
+    const accountRefs = accountRefsBySlug.get(slug);
+    mountAgentRoutes(router, runtime, {
+      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: string) => {
+              sdkRunner.evictSession(sessionId);
+            },
+          }
+        : {}),
+    });
+    for (const channel of project.channels) {
+      const definition = channel.definition;
+      if (definition.onStop !== undefined) {
+        channelStopHooks.push(() => definition.onStop?.());
+      }
+      if (definition.onStart !== undefined) {
+        const startArgs: ChannelStartArgs = {
+          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 {
+          await definition.onStart(startArgs);
+        } catch (error) {
+          logger(
+            `[agent-sdk] channel "${channel.id}" onStart failed: ${
+              error instanceof Error ? (error.stack ?? error.message) : String(error)
+            }`,
+          );
+        }
+      }
+    }
+    if (timerClient !== undefined && runSchedules) {
+      await syncHostedPlatformSchedules({
+        timers: timerClient,
+        schedules: project.schedules,
+        catalogPath: join(stateRoot, PLATFORM_SCHEDULE_CATALOG_FILENAME),
+        logger,
+      });
+    }
+    if (timerClient !== undefined) {
+      await reminderRunner.hydrate();
+    }
+    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) => renderDocsFile(ctx.params.path ?? ""),
+    });
+  }
+
+  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({
+          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: readonly MountedRuntime[]) =>
+    collectGitHubTriggerTargets({
+      mounts: selected.map(runtime => ({
+        slug: runtime.slug,
+        channels: runtime.project.channels,
+        buildHandlerArgs: channelId => buildChannelHandlerArgs({ runtime, channelId }),
+      })),
+    });
+  const collectOriginTargetsFrom = (selected: readonly MountedRuntime[]) =>
+    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: async request => {
+      const bodyText = await request.text();
+      const routeContinuation = localControlPlaneRoute(runtimes);
+      const result = await handleAgentServeTrigger({
+        type: "github",
+        bodyText,
+        eventName: request.headers.get("x-github-event"),
+        deliveryId: request.headers.get("x-github-delivery") ?? undefined,
+        targets: collectGitHubTargets(),
+        ...(routeContinuation === undefined ? {} : { routeContinuation }),
+      });
+      const status = result.ok ? 202 : (result.targets[0]?.status ?? 500);
+      return jsonResponse(result, { status });
+    },
+  });
+
+  for (const { slug, project } of mounts) {
+    validateMountConnectionsConfig({
+      slug,
+      project,
+      accountRefs: accountRefsBySlug.get(slug),
+      ...(options.publicUrl === undefined ? {} : { publicUrl: options.publicUrl }),
+      cloudToolsBridge: options.cloudToolsUrl !== undefined,
+    });
+  }
+
+  await 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: cursorGithubConfig.cursorEvents?.repos ?? [],
+    originRepos: cursorOriginScope?.repos ?? [],
+    stateRoot: options.stateRoot,
+    auth: cursorEventsAuth,
+    logger,
+    cursorAccountOnly:
+      options.cursorEvents === undefined &&
+      (cursorGithubTargets.length > 0 || cursorOriginTargets.length > 0),
+  };
+  const cursorEventRelay = startCursorEventRelay({
+    ...cursorEventsCommon,
+    mounts: v1Mounts,
+    collectGitHubTargets: () => collectGitHubTargetsFrom(v1Runtimes),
+    collectOriginTargets: () => collectOriginTargetsFrom(v1Runtimes),
+    lane: "engine",
+    skippedV2: v2Mounts.length > 0,
+  });
+  const controlPlaneScmRelay = startCursorEventRelay({
+    ...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 = options.host ?? "127.0.0.1";
+  const portWasExplicit = options.port !== undefined;
+  const requestedPort = options.port ?? DEFAULT_SERVE_PORT;
+  let boundPort: number;
+  try {
+    boundPort = await listenHttpServer({
+      server,
+      host,
+      port: requestedPort,
+      portWasExplicit,
+      logger,
+    });
+  } catch (error) {
+    await cursorDeploymentRelay?.stop();
+    await cursorEventRelay?.stop();
+    await controlPlaneScmRelay?.stop();
+    cursorGithubCredentials?.stop();
+    await shutdownOtelRuntime(otelRuntime);
+    throw error;
+  }
+  const address = server.address() as AddressInfo;
+  const displayHost = host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+  const url = `http://${displayHost}:${boundPort}`;
+  const oauthOrigin = (options.publicUrl ?? 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({
+      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(async connection => {
+        const ref = accountRefs.find(entry => entry.name === connection);
+        if (ref === undefined) {
+          return undefined;
+        }
+        return await 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 =
+        options.cloudToolsUrl ??
+        (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
+            : (): Record<string, string> | undefined => {
+                const apiKey = liveCursorApiKey();
+                return apiKey === undefined ? undefined : { authorization: `Bearer ${apiKey}` };
+              };
+        const headers =
+          options.cloudToolsUrl !== undefined
+            ? 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(
+          {
+            type: "http",
+            url: publicToolsUrl,
+            ...(headers === undefined ? {} : { headers }),
+          },
+          resolveCloudToolsHeaders,
+        );
+      }
+    }
+  }
+
+  const agents: MountedAgentInfo[] = 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: ReturnType<typeof startPlaygroundDevServer>;
+  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: AgentServeHandle = {
+    url,
+    port: address.port,
+    project: runtimes[0]?.project as AgentProject,
+    agents,
+    dispatchSchedule: (name, slug = runtimes[0]?.slug ?? "") => {
+      const runtime = runtimeBySlug.get(slug);
+      if (runtime === undefined) {
+        throw new Error(`Unknown agent slug "${slug}"`);
+      }
+      return runtime.scheduleRunner.dispatch(name);
+    },
+    createReminder: (input, slug = runtimes[0]?.slug ?? "") => {
+      const runtime = runtimeBySlug.get(slug);
+      if (runtime === undefined) {
+        throw new Error(`Unknown agent slug "${slug}"`);
+      }
+      return runtime.reminderRunner.create(input);
+    },
+    listReminders: (filter, slug = runtimes[0]?.slug ?? "") => {
+      const runtime = runtimeBySlug.get(slug);
+      if (runtime === undefined) {
+        throw new Error(`Unknown agent slug "${slug}"`);
+      }
+      return runtime.reminderRunner.list(filter);
+    },
+    cancelReminder: (id, options) => {
+      const slug = options?.slug ?? runtimes[0]?.slug ?? "";
+      const runtime = runtimeBySlug.get(slug);
+      if (runtime === undefined) {
+        throw new Error(`Unknown agent slug "${slug}"`);
+      }
+      return runtime.reminderRunner.cancel(id, options?.reason);
+    },
+    dispatchReminder: (id, slug = runtimes[0]?.slug ?? "") => {
+      const runtime = runtimeBySlug.get(slug);
+      if (runtime === undefined) {
+        throw new Error(`Unknown agent slug "${slug}"`);
+      }
+      return runtime.reminderRunner.dispatch(id);
+    },
+    callTool: (toolName, input, options) => {
+      const { slug, ...callOptions } = options ?? {};
+      const runtime = runtimeBySlug.get(slug ?? runtimes[0]?.slug ?? "");
+      if (runtime === undefined) {
+        throw new Error(`Unknown agent slug "${slug}"`);
+      }
+      return runtime.engine.callTool(toolName, input, callOptions);
+    },
+    close: async () => {
+      if (sessionRunLog !== undefined) {
+        await flushHostedExecutionProcessDeath({
+          flushProcessDeath: reason => sessionRunLog.flushProcessDeath(reason),
+          flushStartLog,
+          startLogId: lastStartLogId,
+          reason: "process_exit",
+        });
+        unregisterSessionRunFatalFlush();
+      }
+      playgroundDev?.stop();
+      await cursorDeploymentRelay?.stop();
+      await cursorEventRelay?.stop();
+      await controlPlaneScmRelay?.stop();
+      for (const runtime of runtimes) {
+        runtime.controlPlane?.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 {
+          await stop();
+        } catch (error) {
+          logger(
+            `[agent-sdk] channel onStop failed: ${
+              error instanceof Error ? (error.stack ?? error.message) : String(error)
+            }`,
+          );
+        }
+      }
+      server.close();
+      server.closeAllConnections();
+      try {
+        await Promise.all(runtimes.map(runtime => runtime.engine.close()));
+      } finally {
+        cursorGithubCredentials?.stop();
+        await shutdownOtelRuntime(otelRuntime);
+      }
+    },
+  };
+  if (playgroundDev?.url !== undefined) {
+    handle.playgroundDevUrl = playgroundDev.url;
+  }
+  if (docsSite && docsSiteExists()) {
+    handle.docsUrl = `${handle.url}/docs`;
+  }
+  return handle;
+}
+
+function mountAgentRoutes(
+  router: Router,
+  runtime: MountedRuntime,
+  args: {
+    dev: boolean;
+    playground: boolean;
+    noControlPlane?: boolean;
+    multi: boolean;
+    logger: (line: string) => void;
+    logRing: LogRing;
+    sessionRunLog?: ReturnType<typeof selectSessionRunLogStore>;
+    flushStartLog?: (startLogId: string) => Promise<void>;
+    flushOtel?: () => Promise<void>;
+    authToken?: string;
+    allowAnonymous?: boolean;
+    /** Cursor account bridge + this mount's account MCP connections, when authored. */
+    accountBridge?: CursorAccountMcpBridge;
+    accountRefs?: CursorAccountConnectionRef[];
+    /**
+     * Serve `--state-root`. Hosted-execution writes `hosted-execution.json`
+     * here so the Temporal host can read a stable path after the POST.
+     */
+    diagStateRoot?: string;
+    /**
+     * Drop the cached SDK agent handle after a hosted turn so hibernate
+     * cannot snapshot a frozen Connect/HTTP2 session. Injected test
+     * runners may omit this.
+     */
+    evictSdkSession?: (sessionId: string) => void;
+  },
+): void {
+  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) => {
+        const ref = refByName.get(ctx.params.connection ?? "");
+        if (ref === undefined) {
+          return errorResponse(
+            404,
+            "not_found",
+            `No Cursor account MCP connection named "${ctx.params.connection ?? ""}" on this agent.`,
+          );
+        }
+        return bridge.handle(request, ref, appendSlackQuietHint);
+      },
+    });
+  }
+  const defaultAuth: AuthPolicy[] =
+    args.authToken !== undefined
+      ? [bearerAuth(args.authToken)]
+      : args.allowAnonymous === true
+        ? [allowAll()]
+        : [localDevStrict()];
+  const httpAuth = project.httpChannel.auth ?? 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: AuthPolicy = 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({
+      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: async descriptor => {
+        if (reminderControlPlane === undefined) {
+          throw new Error("hosted reminder CP client is not configured");
+        }
+        const fireDescriptor = descriptor as unknown as ReminderFireDescriptor;
+        const outcome = await 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 = await 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" as const,
+            reason: apply.reason,
+          };
+        }
+        return {
+          reminderId: descriptor.id,
+          outcome: "fired" as const,
+        };
+      },
+      drainSessionDurability: sessionId => engine.drainSessionDurability(sessionId),
+      flushOtel: args.flushOtel,
+      ...(args.diagStateRoot === undefined ? {} : { stateRoot: args.diagStateRoot }),
+      ...(sessionRunLog === undefined
+        ? {}
+        : {
+            persistSessionRun: async document => {
+              await 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({
+        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({
+        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 => {
+      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 : (entries[entries.length - 1]?.index ?? 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: async (request, ctx) => {
+        // 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"
+            ? await engine.latestSessionWithSource(ctx.auth, { includeAll })
+            : await 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: async (request, ctx) => {
+      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 = url.searchParams.get("kind") ?? undefined;
+      const sessionId = url.searchParams.get("sessionId") ?? undefined;
+      const pageToken = url.searchParams.get("pageToken") ?? 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: ArtifactPage;
+      try {
+        page = await 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: async (_request, ctx) => {
+      const includeAll =
+        relaxSessionReadAuth &&
+        (relaxSessionReadAuthBeyondLoopback ||
+          (typeof ctx.requestIp === "string" && isLoopbackAddress(ctx.requestIp)));
+      const found = await engine.getArtifactContent(ctx.auth, ctx.params.id ?? "", { 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 as unknown as BodyInit, {
+        headers: {
+          "content-type": found.record.content?.contentType ?? "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"] as const) {
+    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"] as const) {
+    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 = async (
+    request: Request,
+    ctx: Pick<ServerRouteContext, "auth" | "requestIp">,
+  ): Promise<{ sessionId?: string; continuationToken?: string } | { errorResponse: Response }> => {
+    const url = new URL(request.url);
+    const sessionId = url.searchParams.get("session") ?? undefined;
+    const continuationToken = url.searchParams.get("continuationToken") ?? undefined;
+    if (sessionId !== undefined) {
+      const record = await 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: async (request, ctx) => {
+      const binding = await resolveCatalogBinding(request, ctx);
+      if ("errorResponse" in binding) {
+        return binding.errorResponse;
+      }
+      try {
+        const catalog = await engine.listCatalogTools({
+          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: async (request, ctx) => {
+      const toolName = ctx.params.toolName ?? "";
+      const binding = await resolveCatalogBinding(request, ctx);
+      if ("errorResponse" in binding) {
+        return binding.errorResponse;
+      }
+      try {
+        const described = await engine.describeCatalogTool(toolName, {
+          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: async (request, ctx) => {
+      const toolName = ctx.params.toolName ?? "";
+      const body = await 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 = await 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 = await engine.callTool(toolName, body.input ?? {}, {
+          auth: ctx.auth,
+          sessionId,
+          continuationToken,
+        });
+        return jsonResponse({ 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: async () =>
+      jsonResponse({
+        skills: project.agent.skills.map(skillListEntry),
+      }),
+  });
+
+  router.add({
+    method: "GET",
+    pattern: `${base}/v1/skills/:skillName`,
+    auth: httpAuth,
+    handler: async (_request, ctx) => {
+      const skillName = ctx.params.skillName ?? "";
+      try {
+        return jsonResponse(await 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) => renderPlaygroundAsset(ctx.params.file ?? ""),
+    });
+  }
+
+  // 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: async () => jsonResponse(await runtime.evalRuns.list()),
+  });
+  router.add({
+    method: "GET",
+    pattern: `${base}/v1/dev/evals/runs`,
+    auth: httpAuth,
+    handler: async () => {
+      return jsonResponse(await runtime.evalRuns.listRunsWithActive());
+    },
+  });
+  router.add({
+    method: "POST",
+    pattern: `${base}/v1/dev/evals/runs`,
+    auth: httpAuth,
+    handler: async request => {
+      const body = await readJsonObject(request);
+      const filterIds = asStringArray(body?.filterIds);
+      const tags = asStringArray(body?.tags);
+      const timeoutMs = asPositiveInt(body?.timeoutMs);
+      const verbose = body?.verbose === true;
+      const authHeader = request.headers.get("authorization");
+      const bearerToken = authHeader?.toLowerCase().startsWith("bearer ")
+        ? authHeader.slice("bearer ".length).trim()
+        : undefined;
+      try {
+        const snap = await runtime.evalRuns.start({
+          ...(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: async (_request, ctx) => {
+      const runId = ctx.params.runId ?? "";
+      const snap = await 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: async (_request, ctx) => {
+      const runId = ctx.params.runId ?? "";
+      try {
+        const snap = await 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: async (_request, ctx) => {
+        const scheduleId = ctx.params.scheduleId ?? "";
+        try {
+          const { sessionIds } = await 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: async (request, ctx) => {
+        const reminderId = ctx.params.reminderId ?? "";
+        const fireCountRaw = new URL(request.url).searchParams.get("fireCount");
+        const expectedFireCount = fireCountRaw === null ? undefined : Number(fireCountRaw);
+        try {
+          const result = await 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: async (_request, ctx) => {
+        const scheduleId = ctx.params.scheduleId ?? "";
+        try {
+          const { sessionIds } = await 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: async (_request, ctx) => {
+        const reminderId = ctx.params.reminderId ?? "";
+        try {
+          const listed = await 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 = await assertReminderReadable({
+            engine,
+            reminder,
+            auth: ctx.auth,
+            requestIp: ctx.requestIp,
+            relax: relaxSessionReadAuth,
+            beyondLoopback: relaxSessionReadAuthBeyondLoopback,
+          });
+          if (ownership !== undefined) {
+            return ownership;
+          }
+          const result = await 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: async (_request, ctx) => {
+        const all = await reminderRunner.list();
+        const reminders: ReminderInfo[] = [];
+        for (const reminder of all) {
+          const denied = await 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 = channel.definition.auth ?? defaultAuth;
+    for (const channelRoute of channel.definition.routes ?? []) {
+      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,
+            }),
+          }),
+      });
+    }
+  }
+}
+
+/** Cursor account credential + backend the SCM relay reads the stream with. */
+interface CursorEventsAuth {
+  apiKey: string;
+  baseUrl: string;
+}
+
+/**
+ * `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: NonNullable<ServeOptions["cursorEvents"]>,
+  accountKey: ResolvedApiKey | undefined,
+): CursorEventsAuth {
+  const apiKey = (config.apiKey ?? accountKey?.apiKey ?? "").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: config.baseUrl ?? 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: {
+  mounts: readonly AgentMount[];
+  githubRepos: readonly string[];
+  originRepos: readonly string[];
+}): CursorScmSubscription[] {
+  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: CursorScmSubscription[] = [];
+  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: {
+  noControlPlane: boolean;
+  config: ServeOptions["cursorEvents"];
+  auth: CursorEventsAuth | undefined;
+  v1Mounts: readonly AgentMount[];
+  v2Mounts: readonly AgentMount[];
+  githubRepos: readonly string[];
+  originRepos: readonly string[];
+}): void {
+  if (input.noControlPlane || input.config === undefined || input.auth === undefined) {
+    return;
+  }
+  const shared = {
+    githubRepos: input.githubRepos,
+    originRepos: input.originRepos,
+  };
+  if (
+    collectCursorEventSubscriptions({ mounts: input.v1Mounts, ...shared }).length === 0 ||
+    collectCursorEventSubscriptions({ 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: {
+  config: ServeOptions["cursorEvents"];
+  githubRepos: readonly string[];
+  originRepos: readonly string[];
+  stateRoot: string | undefined;
+  mounts: AgentMount[];
+  auth: CursorEventsAuth | undefined;
+  logger: (line: string) => void;
+  collectGitHubTargets: () => ReturnType<typeof collectGitHubTriggerTargets>;
+  collectOriginTargets: () => ReturnType<typeof collectOriginTriggerTargets>;
+  routeContinuation?: RouteLocalIngressContinuation;
+  cursorAccountOnly: boolean;
+  /** Engine = v1 poll. Control-plane = v2 poll (started by local CP). */
+  lane: "engine" | "control-plane";
+  /** When the engine lane has no v1 targets, mention skipped v2 mounts. */
+  skippedV2?: boolean;
+  /** When false, return an unstarted relay (local CP calls start). */
+  start?: boolean;
+  /** Offset dir under stateRoot. Defaults to `cursor-events`. */
+  stateDirName?: string;
+}): CursorEventRelay | undefined {
+  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 ?? join(mounts[0]?.project.rootDir ?? process.cwd(), ".agent-serve");
+  const relay = new CursorEventRelay({
+    baseUrl: auth.baseUrl,
+    apiKey: auth.apiKey,
+    subscriptions,
+    stateDir: join(baseStateRoot, input.stateDirName ?? "cursor-events"),
+    logger,
+    dispatch: async event => {
+      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 = await handleAgentServeTrigger({
+          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 = await handleAgentServeTrigger({
+        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: (line: string) => void,
+  event: Parameters<typeof formatCursorScmEventLog>[0],
+  result: Awaited<ReturnType<typeof handleAgentServeTrigger>>,
+): void {
+  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}`}`,
+  );
+}
+
+interface CursorGithubTarget {
+  slug: string;
+  channelId: string;
+  accountRuntime: GithubCursorAccountRuntime;
+}
+
+function collectCursorGithubTargets(mounts: AgentMount[]): CursorGithubTarget[] {
+  const targets: CursorGithubTarget[] = [];
+  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;
+}
+
+interface CursorGithubConfigResolution {
+  cursorEvents: ServeOptions["cursorEvents"];
+  scope: CursorGithubRepoScope | undefined;
+  permissions: CursorGithubRepoScope["permissions"];
+}
+
+function cursorGithubPermissionsForTarget(
+  target: CursorGithubTarget,
+): CursorGithubRepoScope["permissions"] {
+  const authored =
+    typeof target.accountRuntime.options.cursorAccount === "object"
+      ? target.accountRuntime.options.cursorAccount.permissions
+      : undefined;
+  return (
+    target.accountRuntime.scope?.permissions ??
+    cursorGithubPermissionsForChannel(target.accountRuntime.options, authored)
+  );
+}
+
+function resolveCursorGithubEventConfig(input: {
+  configured: ServeOptions["cursorEvents"];
+  targets: CursorGithubTarget[];
+}): CursorGithubConfigResolution {
+  if (input.targets.length === 0) {
+    return {
+      cursorEvents: input.configured,
+      scope: undefined,
+      permissions: "pr-write",
+    };
+  }
+  const repos = [
+    ...(input.configured?.repos ?? []),
+    ...input.targets.flatMap(target => [...(target.accountRuntime.scope?.repos ?? [])]),
+  ];
+  const permissions = resolveCursorGithubPermissions(
+    input.targets.map(cursorGithubPermissionsForTarget),
+  );
+  const scope = resolveCursorGithubCredentialScope(repos, permissions);
+  if (scope === undefined) {
+    return {
+      cursorEvents: input.configured,
+      scope: undefined,
+      permissions,
+    };
+  }
+  return {
+    cursorEvents: {
+      ...input.configured,
+      repos: [...scope.repos],
+    },
+    scope,
+    permissions,
+  };
+}
+
+interface CursorOriginTarget {
+  slug: string;
+  channelId: string;
+  accountRuntime: OriginCursorAccountRuntime;
+}
+
+function collectCursorOriginTargets(mounts: AgentMount[]): CursorOriginTarget[] {
+  const targets: CursorOriginTarget[] = [];
+  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: {
+  explicitRepos: readonly string[];
+  targets: CursorOriginTarget[];
+}): ReturnType<typeof parseCursorOriginRepoScope> | undefined {
+  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 => target.accountRuntime.scope?.repos ?? []),
+  ];
+  if (repos.length === 0) {
+    return undefined;
+  }
+  return parseCursorOriginRepoScope(repos);
+}
+
+function buildAgentIndexEntries(runtimes: MountedRuntime[]): AgentIndexEntry[] {
+  return runtimes.map(({ slug, project }) => {
+    const hasSlack = project.channels.some(channel => channel.definition.meta?.kind === "slack");
+    return {
+      slug,
+      name: project.name,
+      model:
+        typeof project.agent.model === "string"
+          ? project.agent.model
+          : (project.agent.model?.id ?? ""),
+      tools: project.agent.tools.length,
+      channels: project.channels.length + 1,
+      slack: hasSlack ? { kind: "socket" as const } : undefined,
+    };
+  });
+}
+
+interface CursorDeploymentTarget {
+  runtime: MountedRuntime;
+  channelId: string;
+  options: DeploymentsChannelOptions;
+}
+
+/** Every mounted `deploymentsChannel`. Subscriptions are re-resolved live. */
+function collectCursorDeploymentTargets(runtimes: MountedRuntime[]): CursorDeploymentTarget[] {
+  const targets: CursorDeploymentTarget[] = [];
+  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: readonly CursorDeploymentTarget[],
+): ResolvedSubscription[] {
+  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: {
+  options: ServeOptions;
+  runtimes: MountedRuntime[];
+  accountKey: ResolvedApiKey | undefined;
+  logger: (line: string) => void;
+}): DeploymentEventRelay | undefined {
+  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 =
+    options.stateRoot ?? 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: async event =>
+      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: {
+  runtime: MountedRuntime;
+  channelId: string;
+  params?: Record<string, string>;
+  requestIp?: string | null;
+  auth?: AuthContext | null;
+  hostedSessionId?: string;
+}): ChannelHandlerArgs {
+  const { runtime, channelId } = input;
+  const base = runtime.slug === "" ? "" : `/${runtime.slug}`;
+  const auth = input.auth ?? null;
+  return {
+    params: input.params ?? {},
+    requestIp: input.requestIp ?? null,
+    auth,
+    host: runtime.engine.host,
+    artifacts: runtime.engine.artifacts,
+    send: (message, sendOptions = {}) =>
+      runtime.engine.send(channelId, message, {
+        ...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),
+  };
+}
+
+async function handleRequest(
+  router: Router,
+  req: IncomingMessage,
+  res: ServerResponse,
+  logger: (line: string) => void,
+  browserOriginGuard?: BrowserOriginGuardOptions,
+): Promise<void> {
+  let response: Response;
+  let hostedDeliveryRequest = false;
+  const method = req.method ?? "GET";
+  try {
+    const request = await toFetchRequest(req);
+    hostedDeliveryRequest = request.headers.get(HOSTED_DELIVERY_HEADER) === "1";
+    const requestErrorResponse = (status: number, error: string, message: string) =>
+      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 = req.socket.remoteAddress ?? null;
+      let auth: AuthContext | null = null;
+      let unauthorized = false;
+      if (match.route.auth !== "none") {
+        auth = await 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.",
+          )
+        : await 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 ? (error.stack ?? 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 {
+    await writeFetchResponse(response, res, method);
+  } catch (error) {
+    logger(
+      `[agent-sdk] response write failed: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+    res.destroy();
+  }
+}
+
+async function resolveAuth(
+  policies: AuthPolicy[],
+  request: Request,
+  requestIp: string | null,
+): Promise<AuthContext | null> {
+  for (const policy of policies) {
+    const result = await policy(request, { requestIp });
+    if (result !== null) {
+      return result;
+    }
+  }
+  return null;
+}
+
+async function toFetchRequest(req: IncomingMessage): Promise<Request> {
+  const method = req.method ?? "GET";
+  const hostHeader = incomingRequestHost(req.headers);
+  const url = new URL(req.url ?? "/", `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 = await 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) as Uint8Array<ArrayBuffer>,
+  });
+}
+
+async function readBody(req: IncomingMessage): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  let total = 0;
+  for await (const chunk of req) {
+    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);
+  }
+  return Buffer.concat(chunks);
+}
+
+async function writeFetchResponse(
+  response: Response,
+  res: ServerResponse,
+  method = "GET",
+): Promise<void> {
+  const headers: Record<string, string> = {};
+  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<void>(resolve => {
+    res.once("close", () => {
+      if (!res.writableFinished) {
+        clientGone = true;
+        void reader.cancel().catch(() => {});
+      }
+      resolve();
+    });
+  });
+
+  try {
+    while (!clientGone) {
+      const { done, value } = await 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.
+          await Promise.race([once(res, "drain"), closed]);
+        }
+      }
+    }
+  } catch {
+    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: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const out: string[] = [];
+  for (const item of value) {
+    if (typeof item === "string" && item.trim() !== "") {
+      out.push(item);
+    }
+  }
+  return out.length === 0 ? undefined : out;
+}
+
+function asPositiveInt(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return undefined;
+  }
+  const n = Math.floor(value);
+  return n > 0 ? n : undefined;
+}
+
+async function assertReminderReadable(input: {
+  engine: SessionEngine;
+  reminder: ReminderInfo;
+  auth: AuthContext | null;
+  requestIp?: string | null;
+  relax: boolean;
+  beyondLoopback: boolean;
+}): Promise<Response | undefined> {
+  const existing = await 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,
+  });
+}