@cursor/bdk 0.2.3 → 0.2.4

package/src/internal/server.ts

@@ -1,3147 +0,0 @@
-/**
- * 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).
-  // Not on a hosted v2 guest: under `--no-control-plane` with no v1 mount
-  // this process never polls `/v0/scm-events` (the hosted control plane
-  // owns ingest), and a persistent slot starts before its first credential
-  // is bound, so demanding one here would refuse a guest that never needed it.
-  const hostedControlPlaneOwnsIngest =
-    noControlPlane && mounts.every(mount => isV2Project(mount.project));
-  const cursorEventsAuth =
-    effectiveCursorEvents === undefined || hostedControlPlaneOwnsIngest
-      ? 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",
-      );
-    }
-  } else if (hostedControlPlaneOwnsIngest && effectiveCursorEvents !== undefined) {
-    // No credential was required above, so no relay object was built; the
-    // outcome is the same skip.
-    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,
-  });
-}