@cursorpool-dev/cli 0.5.6

package/node_modules/@cursor-pool/service/src/server.ts

@@ -0,0 +1,939 @@
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http';
+import { createCanaryStore, sanitizeAgentCanary } from './canary';
+import { appendAgentCanaryDiagnostic, appendAgentGatewayDiagnostic, appendAgentRequestCheckDiagnostic } from './diagnostics';
+import { buildHealth } from './health';
+import { sanitizeExtensionStatus, sanitizeServiceMetadata, type ServiceMetadata } from './metadata';
+import {
+  loginWithPassword,
+  loginWithCode,
+  logoutPlatform,
+  readPlatformGatewayForwardContext,
+  refreshPlatformRoute,
+  platformCatalog,
+  platformStatus,
+  selectPlatformProduct,
+  sendHeartbeat,
+  startPlatformMode,
+  stopPlatformMode,
+  type HeartbeatPayload,
+  type LoginWithPasswordOptions,
+  type LoginWithCodeOptions,
+  type LogoutPlatformOptions,
+  type PlatformDeviceInput,
+  type SendHeartbeatOptions,
+  type StartPlatformModeOptions,
+  type StopPlatformModeOptions,
+} from './platformSession';
+import {
+  completeGatewayForward,
+  createGatewayHttpForwarder,
+  createGatewayStore,
+  evaluateGatewayDecision,
+  resolveGatewayForward,
+  resolveGatewayForwardResult,
+  sanitizeAgentGateway,
+  type GatewayForwardResult,
+  type GatewayForwarder,
+} from './requestGateway';
+import { createRequestCheckStore, sanitizeAgentRequestCheck } from './requestCheck';
+import {
+  evaluateRequestGate,
+  evaluateRouteState,
+  INVALID_SESSION_GATE,
+  type RequestGateDecision,
+} from './requestGate';
+import { createRuntimeId, writeRuntimeInfo, type RuntimeInfo } from './runtime';
+import { buildAgentTakeoverResponse, createAgentTakeoverStore } from './takeover';
+import { readClientConfig } from '@cursor-pool/shared/clientConfig';
+
+const LOOPBACK_HOST = '127.0.0.1' as const;
+const DEFAULT_PORT = 56393;
+const TRUSTED_RENDERER_ORIGINS = new Set([
+  'vscode-file://vscode-app',
+]);
+
+export type StartServerOptions = {
+  port?: number;
+  runtimeFile?: string;
+  diagnosticsFile?: string;
+  maxDiagnostics?: number;
+  onMetadata?: (metadata: ServiceMetadata) => void | Promise<void>;
+  platformSessionFile?: string;
+  platformApiBaseUrl?: string;
+  clientConfigFile?: string;
+  platformExchangePasswordDeviceToken?: LoginWithPasswordOptions['exchangePasswordDeviceToken'];
+  platformExchangeDeviceToken?: LoginWithCodeOptions['exchangeDeviceToken'];
+  platformPostHeartbeat?: SendHeartbeatOptions['postHeartbeat'];
+  platformPostLogout?: LogoutPlatformOptions['postLogout'];
+  platformStartPoolSession?: StartPlatformModeOptions['startPoolSession'];
+  platformStopPoolSession?: StopPlatformModeOptions['stopPoolSession'];
+  gatewayForwarder?: GatewayForwarder;
+  onShutdown?: () => void | Promise<void>;
+};
+
+export type LocalService = RuntimeInfo & {
+  server: Server;
+  stop: () => Promise<void>;
+};
+
+const localServices = new Map<string, LocalService>();
+
+async function resolvePlatformApiBaseUrl(options: StartServerOptions) {
+  if (options.platformApiBaseUrl) {
+    return options.platformApiBaseUrl;
+  }
+  if (process.env.CURSOR_POOL_API_BASE_URL) {
+    return process.env.CURSOR_POOL_API_BASE_URL;
+  }
+  const config = await readClientConfig({ configFile: options.clientConfigFile });
+  return config.apiBaseUrl;
+}
+
+function runtimeKey(runtime: RuntimeInfo) {
+  return `${runtime.host}:${runtime.port}:${runtime.runtimeId}`;
+}
+
+export async function stopLocalService(runtime: RuntimeInfo | null) {
+  if (!runtime) {
+    return false;
+  }
+
+  const service = localServices.get(runtimeKey(runtime));
+  if (!service) {
+    return false;
+  }
+
+  await service.stop();
+  return true;
+}
+
+async function readJsonRequest(request: IncomingMessage): Promise<Record<string, unknown>> {
+  const chunks: Buffer[] = [];
+
+  for await (const chunk of request) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+
+  if (chunks.length === 0) {
+    return {};
+  }
+
+  const body = Buffer.concat(chunks).toString('utf8');
+  if (!body) {
+    return {};
+  }
+
+  return JSON.parse(body) as Record<string, unknown>;
+}
+
+function writeJson(response: ServerResponse, statusCode: number, payload: Record<string, unknown>) {
+  const body = JSON.stringify(payload);
+  response.writeHead(statusCode, {
+    'content-type': 'application/json',
+    'content-length': Buffer.byteLength(body),
+  });
+  response.end(body);
+}
+
+function trustedRendererOrigin(request: IncomingMessage) {
+  const origin = request.headers.origin;
+  if (typeof origin !== 'string') {
+    return undefined;
+  }
+  if (TRUSTED_RENDERER_ORIGINS.has(origin) || origin.startsWith('vscode-webview://')) {
+    return origin;
+  }
+  return undefined;
+}
+
+function applyCorsHeaders(request: IncomingMessage, response: ServerResponse) {
+  const origin = trustedRendererOrigin(request);
+  if (!origin) {
+    return false;
+  }
+  response.setHeader('access-control-allow-origin', origin);
+  response.setHeader('access-control-allow-methods', 'GET,POST,OPTIONS');
+  response.setHeader('access-control-allow-headers', 'content-type,authorization');
+  return true;
+}
+
+function writeCorsPreflight(request: IncomingMessage, response: ServerResponse) {
+  if (!applyCorsHeaders(request, response)) {
+    response.writeHead(403);
+    response.end();
+    return;
+  }
+  response.writeHead(204, {
+    'access-control-max-age': '600',
+  });
+  response.end();
+}
+
+function writeEventStream(response: ServerResponse, events: Record<string, unknown>[]) {
+  const body = `${events.map((event) => `data: ${JSON.stringify(event)}\n\n`).join('')}data: [DONE]\n\n`;
+  response.writeHead(200, {
+    'content-type': 'text/event-stream; charset=utf-8',
+    'cache-control': 'no-cache',
+    'connection': 'keep-alive',
+    'content-length': Buffer.byteLength(body),
+  });
+  response.end(body);
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return typeof value === 'object' && value !== null ? value as Record<string, unknown> : {};
+}
+
+function safeOpenAiModel(value: unknown) {
+  return typeof value === 'string' && /^[A-Za-z0-9._:-]{1,96}$/.test(value)
+    ? value
+    : 'unknown';
+}
+
+function openAiModelsResponse() {
+  return {
+    object: 'list',
+    data: [
+      {
+        id: 'gpt-test',
+        object: 'model',
+        created: 0,
+        owned_by: 'cursor-pool',
+        api_types: ['chat_completions'],
+        capabilities: {
+          supports_tool_use: true,
+          supports_streaming: true,
+          output_modalities: ['text'],
+          context_length: 128000,
+          max_output_tokens: 8192,
+          supports_reasoning: false,
+          supports_vision: false,
+        },
+      },
+    ],
+  };
+}
+
+async function resolveOpenAiGatewayForward(
+  body: Record<string, unknown>,
+  runtime: RuntimeInfo,
+  options: StartServerOptions,
+  retryAfterRefresh = true,
+) {
+  let gate: RequestGateDecision;
+  try {
+    gate = await evaluateRequestGate({ sessionFile: options.platformSessionFile });
+  } catch {
+    gate = { ...INVALID_SESSION_GATE };
+  }
+  const route = gate.state === 'allowed'
+    ? await evaluateRouteState({ sessionFile: options.platformSessionFile })
+    : { state: 'missing' as const };
+  const decision = evaluateGatewayDecision(gate, route);
+  const requestId = typeof body.requestId === 'string'
+    ? body.requestId
+    : `openai-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+  const model = safeOpenAiModel(body.model);
+  const gateway = sanitizeAgentGateway({
+    requestId,
+    source: 'cursor-agent-exec',
+    model,
+  }, {
+    runtimeId: runtime.runtimeId,
+    decision,
+  });
+  const forwardContext = decision.state === 'accepted'
+    ? await readPlatformGatewayForwardContext({ sessionFile: options.platformSessionFile })
+    : {};
+  const forwarder = options.gatewayForwarder ?? (
+    decision.state === 'accepted'
+      ? createGatewayHttpForwarder({
+        apiBaseUrl: forwardContext.apiBaseUrl,
+        deviceToken: forwardContext.deviceToken,
+      })
+      : undefined
+  );
+  const { result, safe } = await resolveGatewayForwardResult({
+    gateway,
+    routeToken: forwardContext.routeToken ?? '',
+    poolSessionId: forwardContext.poolSessionId,
+    productId: decision.state === 'accepted' ? decision.productId : 'unknown',
+    model,
+    requestId: gateway.requestId,
+    settlementMode: 'client_response',
+    openAiRequest: body,
+    forwarder,
+  });
+  if (
+    retryAfterRefresh &&
+    (
+      decision.state === 'route-expired' ||
+      safe.state === 'skipped' && safe.reason === 'not-accepted' ||
+      safe.state === 'rejected' && safe.reason === 'pool-session-expired'
+    )
+  ) {
+    const refreshed = await refreshPlatformRoute({
+      sessionFile: options.platformSessionFile,
+      startPoolSession: options.platformStartPoolSession,
+    });
+    if (refreshed.state === 'active') {
+      return resolveOpenAiGatewayForward(body, runtime, options, false);
+    }
+  }
+  return {
+    gateway: {
+      ...gateway,
+      forward: safe,
+    },
+    forward: safe,
+    forwardResult: result,
+    completionContext: {
+      apiBaseUrl: forwardContext.apiBaseUrl,
+      deviceToken: forwardContext.deviceToken,
+      routeToken: forwardContext.routeToken,
+      poolSessionId: forwardContext.poolSessionId,
+      productId: decision.state === 'accepted' ? decision.productId : undefined,
+      requestId: gateway.requestId,
+    },
+    model,
+  };
+}
+
+function openAiChatCompletionResponse(model: string, content: string) {
+  const now = Math.floor(Date.now() / 1000);
+  return {
+    id: `chatcmpl-${now}`,
+    object: 'chat.completion',
+    created: now,
+    model,
+    choices: [
+      {
+        index: 0,
+        message: {
+          role: 'assistant',
+          content,
+        },
+        finish_reason: 'stop',
+      },
+    ],
+    usage: {
+      prompt_tokens: 0,
+      completion_tokens: 0,
+      total_tokens: 0,
+    },
+  };
+}
+
+function openAiChatCompletionStreamEvents(model: string, content: string) {
+  const now = Math.floor(Date.now() / 1000);
+  const id = `chatcmpl-${now}`;
+  return [
+    {
+      id,
+      object: 'chat.completion.chunk',
+      created: now,
+      model,
+      choices: [
+        {
+          index: 0,
+          delta: {
+            role: 'assistant',
+          },
+          finish_reason: null,
+        },
+      ],
+    },
+    {
+      id,
+      object: 'chat.completion.chunk',
+      created: now,
+      model,
+      choices: [
+        {
+          index: 0,
+          delta: {
+            content,
+          },
+          finish_reason: null,
+        },
+      ],
+    },
+    {
+      id,
+      object: 'chat.completion.chunk',
+      created: now,
+      model,
+      choices: [
+        {
+          index: 0,
+          delta: {},
+          finish_reason: 'stop',
+        },
+      ],
+    },
+  ];
+}
+
+function openAiErrorResponse(message: string) {
+  return {
+    error: {
+      message,
+      type: 'cursor_pool_gateway_error',
+      code: 'cursor_pool_gateway_error',
+    },
+  };
+}
+
+function openAiBypassResponse() {
+  return {
+    error: {
+      message: 'Cursor Pool platform mode is inactive; use the official Cursor path.',
+      type: 'cursor_pool_bypass',
+      code: 'cursor_pool_bypass',
+    },
+  };
+}
+
+function openAiFailClosedContent(forward: ReturnType<typeof sanitizeAgentGateway>['forward']) {
+  if (forward.state === 'rejected') {
+    return `Cursor Pool 号池 provider 未就绪：${forward.reason}`;
+  }
+  if (forward.state === 'not-configured') {
+    return 'Cursor Pool 号池 provider 未配置，当前请求已被平台接管但无法转发。';
+  }
+  if (forward.state === 'timeout') {
+    return 'Cursor Pool 号池 provider 响应超时，当前请求已被平台接管但没有完成。';
+  }
+  if (forward.state === 'network-error') {
+    return 'Cursor Pool 号池 provider 网络不可用，当前请求已被平台接管但无法转发。';
+  }
+  if (forward.state === 'skipped') {
+    return 'Cursor Pool 平台模式未允许本次请求。';
+  }
+  return 'Cursor Pool provider 暂时没有返回可显示内容';
+}
+
+function isOpenAiObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function forwardedOpenAiResponse(result: GatewayForwardResult): Record<string, unknown> | undefined {
+  return result.state === 'forwarded' && isOpenAiObject(result.openAiResponse)
+    ? result.openAiResponse
+    : undefined;
+}
+
+function forwardedOpenAiStreamEvents(result: GatewayForwardResult): Record<string, unknown>[] | undefined {
+  if (result.state !== 'forwarded' || !Array.isArray(result.openAiStreamEvents)) {
+    return undefined;
+  }
+  const events = result.openAiStreamEvents.filter(isOpenAiObject);
+  return events.length > 0 ? events : undefined;
+}
+
+async function completeForwardAfterClientResponse(context: {
+  apiBaseUrl?: string;
+  deviceToken?: string;
+  routeToken?: string;
+  poolSessionId?: string;
+  productId?: string;
+  requestId: string;
+}) {
+  if (!context.routeToken || !context.poolSessionId || !context.productId) {
+    return;
+  }
+  await completeGatewayForward({
+    apiBaseUrl: context.apiBaseUrl,
+    deviceToken: context.deviceToken,
+    routeToken: context.routeToken,
+    poolSessionId: context.poolSessionId,
+    productId: context.productId,
+    requestId: context.requestId,
+  });
+}
+
+async function routeRequest(
+  request: IncomingMessage,
+  response: ServerResponse,
+  runtime: RuntimeInfo,
+  options: StartServerOptions,
+  canaryStore: ReturnType<typeof createCanaryStore>,
+  requestCheckStore: ReturnType<typeof createRequestCheckStore>,
+  gatewayStore: ReturnType<typeof createGatewayStore>,
+  takeoverStore: ReturnType<typeof createAgentTakeoverStore>,
+  stop: () => Promise<void>,
+) {
+  try {
+    if (request.method === 'OPTIONS') {
+      writeCorsPreflight(request, response);
+      return;
+    }
+    applyCorsHeaders(request, response);
+
+    if (request.method === 'GET' && request.url === '/health') {
+      writeJson(response, 200, buildHealth(runtime));
+      return;
+    }
+
+    if (request.method === 'GET' && request.url === '/models') {
+      writeJson(response, 200, openAiModelsResponse());
+      return;
+    }
+
+    if (request.method === 'POST' && request.url === '/chat/completions') {
+      let clientClosed = false;
+      let responseFinished = false;
+      response.once('finish', () => {
+        responseFinished = true;
+      });
+      response.once('close', () => {
+        if (!responseFinished) {
+          clientClosed = true;
+        }
+      });
+      const clientConnected = () => !clientClosed && !response.destroyed && !response.writableEnded;
+      const body = await readJsonRequest(request);
+      const { gateway, forward, forwardResult, completionContext, model } = await resolveOpenAiGatewayForward(body, runtime, options);
+      const recordedGateway = gatewayStore.record(gateway);
+      try {
+        await appendAgentGatewayDiagnostic(recordedGateway, {
+          diagnosticsFile: options.diagnosticsFile,
+          maxEntries: options.maxDiagnostics,
+        });
+      } catch {
+        // OpenAI-compatible diagnostics must not break local agent execution.
+      }
+      if (!clientConnected()) {
+        return;
+      }
+      if (gateway.decision.state !== 'accepted') {
+        writeJson(response, 409, openAiBypassResponse());
+        return;
+      }
+      if (forward.state !== 'forwarded') {
+        const content = openAiFailClosedContent(forward);
+        if (body.stream === true) {
+          writeEventStream(response, openAiChatCompletionStreamEvents(model, content));
+          return;
+        }
+        writeJson(response, 200, openAiChatCompletionResponse(model, content));
+        return;
+      }
+      if (body.stream === true) {
+        const providerEvents = forwardedOpenAiStreamEvents(forwardResult);
+        if (providerEvents) {
+          writeEventStream(response, providerEvents);
+          await completeForwardAfterClientResponse(completionContext);
+          return;
+        }
+        writeEventStream(
+          response,
+          openAiChatCompletionStreamEvents(
+            model,
+            forward.content ?? 'Cursor Pool provider 暂时没有返回可显示内容',
+          ),
+        );
+        await completeForwardAfterClientResponse(completionContext);
+        return;
+      }
+      const providerResponse = forwardedOpenAiResponse(forwardResult);
+      if (providerResponse) {
+        writeJson(response, 200, providerResponse);
+        await completeForwardAfterClientResponse(completionContext);
+        return;
+      }
+      writeJson(
+        response,
+        200,
+        openAiChatCompletionResponse(
+          model,
+          forward.content ?? 'Cursor Pool provider 暂时没有返回可显示内容',
+        ),
+      );
+      await completeForwardAfterClientResponse(completionContext);
+      return;
+    }
+
+    if (request.method === 'POST' && request.url === '/cursor-metadata') {
+      const metadata = sanitizeServiceMetadata(await readJsonRequest(request));
+      await options.onMetadata?.(metadata);
+      writeJson(response, 200, { ok: true, metadata });
+      return;
+    }
+
+    if (request.method === 'POST' && request.url === '/agent/canary') {
+      let gate: RequestGateDecision;
+      try {
+        gate = await evaluateRequestGate({ sessionFile: options.platformSessionFile });
+      } catch {
+        gate = { ...INVALID_SESSION_GATE };
+      }
+      const canary = canaryStore.record(
+        sanitizeAgentCanary(await readJsonRequest(request), { runtimeId: runtime.runtimeId, gate }),
+      );
+      try {
+        await appendAgentCanaryDiagnostic(canary, {
+          diagnosticsFile: options.diagnosticsFile,
+          maxEntries: options.maxDiagnostics,
+        });
+      } catch {
+        // Canary diagnostics must not break the Cursor Agent request path.
+      }
+      writeJson(response, 200, { ok: true, canary });
+      return;
+    }
+
+    if (request.method === 'GET' && request.url === '/agent/canary/latest') {
+      writeJson(response, 200, { ok: true, canary: canaryStore.latest() });
+      return;
+    }
+
+    if (request.method === 'POST' && request.url === '/agent/request-check') {
+      let decision: RequestGateDecision;
+      try {
+        decision = await evaluateRequestGate({ sessionFile: options.platformSessionFile });
+      } catch {
+        decision = { ...INVALID_SESSION_GATE };
+      }
+      const route = decision.state === 'allowed'
+        ? await evaluateRouteState({ sessionFile: options.platformSessionFile })
+        : { state: 'missing' as const };
+      const check = requestCheckStore.record(
+        sanitizeAgentRequestCheck(await readJsonRequest(request), {
+          runtimeId: runtime.runtimeId,
+          decision,
+          route,
+        }),
+      );
+      try {
+        await appendAgentRequestCheckDiagnostic(check, {
+          diagnosticsFile: options.diagnosticsFile,
+          maxEntries: options.maxDiagnostics,
+        });
+      } catch {
+        // Request-check diagnostics must not break the local request pre-check path.
+      }
+      writeJson(response, 200, { ok: decision.state === 'allowed', check });
+      return;
+    }
+
+    if (request.method === 'GET' && request.url === '/agent/request-check/latest') {
+      writeJson(response, 200, { ok: true, check: requestCheckStore.latest() });
+      return;
+    }
+
+    if (request.method === 'POST' && request.url === '/agent/request-gateway') {
+      let gate: RequestGateDecision;
+      try {
+        gate = await evaluateRequestGate({ sessionFile: options.platformSessionFile });
+      } catch {
+        gate = { ...INVALID_SESSION_GATE };
+      }
+      const route = gate.state === 'allowed'
+        ? await evaluateRouteState({ sessionFile: options.platformSessionFile })
+        : { state: 'missing' as const };
+      const decision = evaluateGatewayDecision(gate, route);
+      const body = await readJsonRequest(request);
+      const gateway = sanitizeAgentGateway(body, {
+        runtimeId: runtime.runtimeId,
+        decision,
+      });
+      const forwardContext = decision.state === 'accepted'
+        ? await readPlatformGatewayForwardContext({ sessionFile: options.platformSessionFile })
+        : {};
+      const forwarder = options.gatewayForwarder ?? (
+        decision.state === 'accepted'
+          ? createGatewayHttpForwarder({
+            apiBaseUrl: forwardContext.apiBaseUrl,
+            deviceToken: forwardContext.deviceToken,
+          })
+          : undefined
+      );
+      gateway.forward = await resolveGatewayForward({
+        gateway,
+        routeToken: forwardContext.routeToken ?? '',
+        poolSessionId: forwardContext.poolSessionId,
+        productId: decision.state === 'accepted' ? decision.productId : 'unknown',
+        model: gateway.model,
+        requestId: gateway.requestId,
+        forwarder,
+      });
+      const recordedGateway = gatewayStore.record(gateway);
+      try {
+        await appendAgentGatewayDiagnostic(recordedGateway, {
+          diagnosticsFile: options.diagnosticsFile,
+          maxEntries: options.maxDiagnostics,
+        });
+      } catch {
+        // Gateway diagnostics must not break the local gateway preflight path.
+      }
+      writeJson(response, 200, {
+        ok: decision.state === 'accepted' && recordedGateway.forward.state === 'forwarded',
+        gateway: recordedGateway,
+      });
+      return;
+    }
+
+    if (request.method === 'GET' && request.url === '/agent/request-gateway/latest') {
+      writeJson(response, 200, { ok: true, gateway: gatewayStore.latest() });
+      return;
+    }
+
+    if (request.method === 'POST' && request.url === '/agent/takeover') {
+      const body = await readJsonRequest(request);
+      let gate: RequestGateDecision;
+      try {
+        gate = await evaluateRequestGate({ sessionFile: options.platformSessionFile });
+      } catch {
+        gate = { ...INVALID_SESSION_GATE };
+      }
+      const route = gate.state === 'allowed'
+        ? await evaluateRouteState({ sessionFile: options.platformSessionFile })
+        : { state: 'missing' as const };
+      let forward;
+      if (route.state === 'ready') {
+        const decision = evaluateGatewayDecision(gate, route);
+        const gateway = sanitizeAgentGateway(body, {
+          runtimeId: runtime.runtimeId,
+          decision,
+        });
+        const forwardContext = await readPlatformGatewayForwardContext({ sessionFile: options.platformSessionFile });
+        const forwarder = options.gatewayForwarder ?? createGatewayHttpForwarder({
+          apiBaseUrl: forwardContext.apiBaseUrl,
+          deviceToken: forwardContext.deviceToken,
+        });
+        forward = await resolveGatewayForward({
+          gateway,
+          routeToken: forwardContext.routeToken ?? '',
+          poolSessionId: forwardContext.poolSessionId,
+          productId: decision.state === 'accepted' ? decision.productId : 'unknown',
+          model: gateway.model,
+          requestId: gateway.requestId,
+          forwarder,
+        });
+      }
+      const takeover = takeoverStore.record(
+        buildAgentTakeoverResponse(body, gate, route, forward),
+      );
+      writeJson(response, 200, takeover);
+      return;
+    }
+
+    if (request.method === 'GET' && request.url === '/agent/takeover/latest') {
+      writeJson(response, 200, { ok: true, takeover: takeoverStore.latest() });
+      return;
+    }
+
+    if (request.method === 'POST' && request.url === '/extension/status') {
+      const status = sanitizeExtensionStatus(await readJsonRequest(request));
+      writeJson(response, 200, { ok: true, status });
+      return;
+    }
+
+    if (request.method === 'GET' && request.url === '/platform/status') {
+      writeJson(response, 200, await platformStatus({ sessionFile: options.platformSessionFile }));
+      return;
+    }
+
+    if (request.method === 'GET' && request.url === '/platform/catalog') {
+      writeJson(response, 200, await platformCatalog({ sessionFile: options.platformSessionFile }));
+      return;
+    }
+
+    if (request.method === 'POST' && request.url === '/platform/selection') {
+      const body = await readJsonRequest(request);
+      if (typeof body.productId !== 'string' || body.productId.trim() === '') {
+        throw new Error('invalid platform selection request');
+      }
+
+      const selection = await selectPlatformProduct({
+        sessionFile: options.platformSessionFile,
+        productId: body.productId,
+      });
+      writeJson(response, 200, selection);
+      return;
+    }
+
+    if (request.method === 'POST' && request.url === '/platform/login') {
+      const body = await readJsonRequest(request);
+      const apiBaseUrl = await resolvePlatformApiBaseUrl(options);
+      if (typeof body.email === 'string' || typeof body.password === 'string') {
+        if (
+          typeof body.email !== 'string' ||
+          typeof body.password !== 'string' ||
+          typeof apiBaseUrl !== 'string' ||
+          apiBaseUrl.trim() === ''
+        ) {
+          throw new Error('invalid platform login request');
+        }
+
+        let login;
+        try {
+          login = await loginWithPassword({
+            email: body.email,
+            password: body.password,
+            apiBaseUrl,
+            sessionFile: options.platformSessionFile,
+            device: asRecord(body.device) as PlatformDeviceInput,
+            exchangePasswordDeviceToken: options.platformExchangePasswordDeviceToken,
+          });
+        } catch (error) {
+          const platformCode = (error as { platformCode?: unknown }).platformCode;
+          writeJson(response, 400, {
+            ok: false,
+            error: 'platform login failed',
+            ...(typeof platformCode === 'string' ? { code: platformCode } : {}),
+          });
+          return;
+        }
+        writeJson(response, 200, login);
+        return;
+      }
+
+      if (typeof body.code !== 'string' || typeof body.apiBaseUrl !== 'string') {
+        throw new Error('invalid platform login request');
+      }
+
+      writeJson(response, 200, await loginWithCode({
+        code: body.code,
+        apiBaseUrl: body.apiBaseUrl,
+        sessionFile: options.platformSessionFile,
+        device: asRecord(body.device) as PlatformDeviceInput,
+        exchangeDeviceToken: options.platformExchangeDeviceToken,
+      }));
+      return;
+    }
+
+    if (request.method === 'POST' && request.url === '/platform/heartbeat') {
+      writeJson(response, 200, await sendHeartbeat({
+        sessionFile: options.platformSessionFile,
+        payload: await readJsonRequest(request) as HeartbeatPayload,
+        postHeartbeat: options.platformPostHeartbeat,
+      }));
+      return;
+    }
+
+    if (request.method === 'POST' && request.url === '/platform/logout') {
+      writeJson(response, 200, await logoutPlatform({
+        sessionFile: options.platformSessionFile,
+        postLogout: options.platformPostLogout,
+      }));
+      return;
+    }
+
+    if (request.method === 'POST' && request.url === '/mode/start') {
+      writeJson(response, 200, await startPlatformMode({
+        sessionFile: options.platformSessionFile,
+        startPoolSession: options.platformStartPoolSession,
+      }));
+      return;
+    }
+
+    if (request.method === 'POST' && request.url === '/mode/stop') {
+      writeJson(response, 200, await stopPlatformMode({
+        sessionFile: options.platformSessionFile,
+        stopPoolSession: options.platformStopPoolSession,
+      }));
+      return;
+    }
+
+    if (request.method === 'POST' && request.url === '/shutdown') {
+      writeJson(response, 200, { ok: true });
+      response.once('finish', () => {
+        void stop().then(() => options.onShutdown?.());
+      });
+      return;
+    }
+
+    writeJson(response, 404, { ok: false, error: 'not found' });
+  } catch {
+    writeJson(response, 400, { ok: false, error: 'invalid request' });
+  }
+}
+
+function listen(server: Server, port: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const onError = (error: Error) => {
+      server.off('listening', onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off('error', onError);
+      resolve();
+    };
+
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(port, LOOPBACK_HOST);
+  });
+}
+
+async function closeServer(server: Server) {
+  if (!server.listening) {
+    return;
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    server.close((error) => (error ? reject(error) : resolve()));
+  });
+}
+
+export async function startServer(options: StartServerOptions = {}): Promise<LocalService> {
+  let requestedPort = options.port ?? DEFAULT_PORT;
+
+  for (;;) {
+    const runtime: RuntimeInfo = {
+      host: LOOPBACK_HOST,
+      port: requestedPort,
+      runtimeId: createRuntimeId(),
+    };
+    const canaryStore = createCanaryStore();
+    const requestCheckStore = createRequestCheckStore();
+    const gatewayStore = createGatewayStore();
+    const takeoverStore = createAgentTakeoverStore();
+    const server = createServer((request, response) => {
+      void routeRequest(
+        request,
+        response,
+        runtime,
+        options,
+        canaryStore,
+        requestCheckStore,
+        gatewayStore,
+        takeoverStore,
+        stopService,
+      );
+    });
+    const stopService = async () => {
+      await closeServer(server);
+      localServices.delete(runtimeKey(runtime));
+    };
+
+    try {
+      await listen(server, requestedPort);
+      const address = server.address();
+      if (typeof address !== 'object' || address === null) {
+        await closeServer(server);
+        throw new Error('service did not bind a TCP address');
+      }
+
+      runtime.port = address.port;
+      await writeRuntimeInfo(runtime, { runtimeFile: options.runtimeFile });
+
+      const service: LocalService = {
+        ...runtime,
+        server,
+        stop: stopService,
+      };
+      localServices.set(runtimeKey(runtime), service);
+
+      return service;
+    } catch (error) {
+      await closeServer(server);
+      if ((error as NodeJS.ErrnoException).code !== 'EADDRINUSE') {
+        throw error;
+      }
+      requestedPort = 0;
+    }
+  }
+}