@cursorpool-dev/cli 0.5.6

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

@@ -0,0 +1,1178 @@
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+export const DEFAULT_PLATFORM_SESSION_FILE = '~/.cursor-pool/session.json';
+
+export type PlatformUserSummary = {
+  id: string;
+  email: string;
+};
+
+export type PlatformDeviceSummary = {
+  id: string;
+  status: string;
+  lastHeartbeatAt: string;
+};
+
+export type PlatformProductSummary = {
+  id: string;
+  name: string;
+  description: string;
+  status: 'available' | 'unavailable';
+  minCredits: number;
+  usageLabel: string;
+};
+
+export type PoolSessionSummary = {
+  id: string;
+  productId: string;
+  providerType: string;
+  status: 'active' | 'refresh-required' | 'stopping' | 'stopped' | 'expired' | 'failed';
+  startedAt: string;
+  expiresAt: string;
+  routeTokenExpiresAt: string;
+  routeStrategy: 'platform-gateway';
+  bannedModels: string[];
+  availableModels?: string[];
+  capabilities: {
+    streaming: boolean;
+    usageEstimate: boolean;
+    hardSpendLimit: boolean;
+  };
+};
+
+export type LocalRouteTokenState = {
+  token: string;
+  expiresAt: string;
+};
+
+export type SafeRouteState =
+  | { state: 'missing' }
+  | { state: 'ready'; expiresAt: string }
+  | { state: 'expired'; expiresAt: string };
+
+export type PlatformModeReleaseReason =
+  | 'product-missing'
+  | 'product-unavailable'
+  | 'insufficient-credits'
+  | 'invalid-token'
+  | 'device-inactive';
+
+export type PlatformModeSnapshot =
+  | { state: 'inactive'; releaseReason?: PlatformModeReleaseReason; releasedAt?: string }
+  | { state: 'active'; productId: string; startedAt: string };
+
+export type PlatformModeResult =
+  | PlatformModeSnapshot
+  | { state: 'logged-out' }
+  | { state: 'offline' }
+  | { state: 'invalid-token' }
+  | { state: 'product-not-selected' }
+  | { state: 'product-not-found'; productId: string }
+  | { state: 'product-unavailable'; productId: string }
+  | { state: 'provider-unavailable' }
+  | { state: 'provider-rate-limited' }
+  | { state: 'manual-review-required' }
+  | { state: 'model-banned' }
+  | { state: 'device-inactive' }
+  | {
+      state: 'insufficient-credits';
+      productId: string;
+      requiredCredits: number;
+      currentCredits: number;
+    };
+
+export type PlatformSession = {
+  apiBaseUrl: string;
+  deviceToken: string;
+  createdAt: string;
+  user: PlatformUserSummary;
+  device: PlatformDeviceSummary;
+  selectedProductId?: string;
+  platformMode?: 'active' | 'inactive';
+  activeProductId?: string;
+  platformModeStartedAt?: string;
+  lastModeReleaseReason?: PlatformModeReleaseReason;
+  lastModeReleasedAt?: string;
+  poolSession?: PoolSessionSummary;
+  routeToken?: LocalRouteTokenState;
+};
+
+export type PlatformStatus =
+  | { state: 'logged-out' }
+  | {
+      state: 'logged-in';
+      user: PlatformUserSummary;
+      device: PlatformDeviceSummary;
+      mode: PlatformModeSnapshot;
+    }
+  | {
+      state: 'offline';
+      user?: PlatformUserSummary;
+      device?: PlatformDeviceSummary;
+      mode?: PlatformModeSnapshot;
+    }
+  | {
+      state: 'invalid-token';
+      user?: PlatformUserSummary;
+      device?: PlatformDeviceSummary;
+      mode?: PlatformModeSnapshot;
+    };
+
+export type PlatformCatalog =
+  | { state: 'logged-out'; products: [] }
+  | {
+      state: 'logged-in';
+      account: { credits: number };
+      mode: PlatformModeSnapshot;
+      selectedProductId?: string;
+      products: PlatformProductSummary[];
+    }
+  | { state: 'offline'; products: [] }
+  | { state: 'invalid-token'; mode?: PlatformModeSnapshot; products: [] };
+
+export type PlatformSelectionResult =
+  | { state: 'selected'; selectedProductId: string }
+  | { state: 'logged-out' }
+  | { state: 'offline' }
+  | { state: 'invalid-token' }
+  | { state: 'product-not-found'; productId: string }
+  | { state: 'product-unavailable'; productId: string };
+
+export type PlatformDeviceInput = {
+  name?: string;
+  os?: string;
+  arch?: string;
+  cursorVersion?: string;
+  cursorCommit?: string;
+  cliVersion?: string;
+  extensionVersion?: string;
+  serviceVersion?: string;
+};
+
+export type HeartbeatPayload = {
+  cursorVersion?: string;
+  cursorCommit?: string;
+  serviceStatus?: string;
+  patchStatus?: string;
+  extensionStatus?: string;
+};
+
+type DeviceTokenResponse = {
+  deviceToken: string;
+  user: PlatformUserSummary;
+  device: PlatformDeviceSummary;
+};
+
+type HeartbeatResponse = {
+  ok: boolean;
+  device: PlatformDeviceSummary;
+};
+
+type MeResponse = {
+  user: PlatformUserSummary;
+  device: PlatformDeviceSummary;
+};
+
+type AccountSummaryResponse = {
+  credits: number;
+};
+
+type ProductsResponse = {
+  products: unknown[];
+};
+
+type RequestJsonError = Error & {
+  status?: number;
+  platformCode?: string;
+};
+
+type RequestErrorStatusOptions = PlatformSessionOptions & {
+  releaseActiveModeOnUnauthorized?: boolean;
+};
+
+const SAFE_POOL_TOKEN_PATTERN = /^[A-Za-z0-9._:-]{1,128}$/;
+const SECRET_LIKE_PATTERN = /(api[_-]?key|authorization|bearer|cursor[_-]?auth|provider[_-]?secret|secret|token|sk-[A-Za-z0-9])/i;
+
+export type LoginWithCodeOptions = {
+  code: string;
+  apiBaseUrl: string;
+  sessionFile?: string;
+  device?: PlatformDeviceInput;
+  exchangeDeviceToken?: (request: {
+    code: string;
+    apiBaseUrl: string;
+    device: PlatformDeviceInput;
+  }) => Promise<DeviceTokenResponse>;
+};
+
+export type LoginWithPasswordOptions = {
+  email: string;
+  password: string;
+  apiBaseUrl: string;
+  sessionFile?: string;
+  device?: PlatformDeviceInput;
+  exchangePasswordDeviceToken?: (request: {
+    email: string;
+    password: string;
+    apiBaseUrl: string;
+    device: PlatformDeviceInput;
+  }) => Promise<DeviceTokenResponse>;
+};
+
+export type PlatformSessionOptions = {
+  sessionFile?: string;
+};
+
+export type PoolSessionFailureReason =
+  | 'INSUFFICIENT_CREDITS'
+  | 'DEVICE_INVALID'
+  | 'PRODUCT_UNAVAILABLE'
+  | 'PROVIDER_UNAVAILABLE'
+  | 'MODEL_BANNED'
+  | 'RATE_LIMITED'
+  | 'MANUAL_REVIEW_REQUIRED';
+
+export type StartPoolSessionResult =
+  | { state: 'started'; session: PoolSessionSummary; routeToken: string }
+  | { state: 'failed'; reason: PoolSessionFailureReason };
+
+export type StartPoolSessionRequest = {
+  session: PlatformSession;
+  productId: string;
+  client?: {
+    runtimeId?: string;
+    serviceVersion?: string;
+    cursorVersion?: string;
+    cursorCommit?: string;
+  };
+};
+
+export type StartPlatformModeOptions = PlatformSessionOptions & {
+  startPoolSession?: (request: StartPoolSessionRequest) => Promise<StartPoolSessionResult>;
+};
+
+export type RefreshPlatformRouteResult =
+  | { state: 'active'; productId: string; startedAt: string }
+  | { state: 'not-refreshable' }
+  | { state: 'failed'; reason: PlatformModeResult['state'] };
+
+export type StopPoolSessionReason =
+  | 'user-stop'
+  | 'logout'
+  | 'invalid-token'
+  | 'device-inactive'
+  | 'product-unavailable'
+  | 'insufficient-credits'
+  | 'session-expired'
+  | 'local-error';
+
+export type StopPoolSessionRequest = {
+  session: PlatformSession;
+  poolSessionId: string;
+  reason: StopPoolSessionReason;
+};
+
+export type StopPoolSessionResult = {
+  state: 'stopped';
+  sessionId: string;
+};
+
+export type StopPlatformModeOptions = PlatformSessionOptions & {
+  stopPoolSession?: (request: StopPoolSessionRequest) => Promise<StopPoolSessionResult>;
+};
+
+export type PlatformSessionSnapshot =
+  | { state: 'missing' }
+  | { state: 'invalid' }
+  | { state: 'valid'; session: PlatformSession };
+
+export type SendHeartbeatOptions = PlatformSessionOptions & {
+  payload?: HeartbeatPayload;
+  postHeartbeat?: (request: {
+    session: PlatformSession;
+    payload: HeartbeatPayload;
+  }) => Promise<HeartbeatResponse>;
+};
+
+export type LogoutPlatformOptions = PlatformSessionOptions & {
+  postLogout?: (request: { session: PlatformSession }) => Promise<void>;
+};
+
+export function resolvePlatformSessionFile(sessionFile = DEFAULT_PLATFORM_SESSION_FILE) {
+  if (sessionFile.startsWith('~/')) {
+    return join(homedir(), sessionFile.slice(2));
+  }
+  return sessionFile;
+}
+
+function cleanApiBaseUrl(apiBaseUrl: string) {
+  return apiBaseUrl.replace(/\/+$/, '');
+}
+
+function isSafePoolToken(value: unknown): value is string {
+  return typeof value === 'string' && SAFE_POOL_TOKEN_PATTERN.test(value) && !SECRET_LIKE_PATTERN.test(value);
+}
+
+function cleanPoolTokens(values: string[]) {
+  return values.filter(isSafePoolToken);
+}
+
+function sanitizePoolSessionSummary(value: PoolSessionSummary): PoolSessionSummary {
+  return {
+    id: value.id,
+    productId: value.productId,
+    providerType: value.providerType,
+    status: value.status,
+    startedAt: value.startedAt,
+    expiresAt: value.expiresAt,
+    routeTokenExpiresAt: value.routeTokenExpiresAt,
+    routeStrategy: 'platform-gateway',
+    bannedModels: cleanPoolTokens(value.bannedModels),
+    ...(value.availableModels !== undefined
+      ? { availableModels: cleanPoolTokens(value.availableModels) }
+      : {}),
+    capabilities: {
+      streaming: value.capabilities.streaming,
+      usageEstimate: value.capabilities.usageEstimate,
+      hardSpendLimit: value.capabilities.hardSpendLimit,
+    },
+  };
+}
+
+function asStatus(session: PlatformSession): PlatformStatus {
+  return {
+    state: 'logged-in',
+    user: session.user,
+    device: session.device,
+    mode: platformModeFromSession(session),
+  };
+}
+
+function isPlatformModeReleaseReason(value: unknown): value is PlatformModeReleaseReason {
+  return (
+    value === 'product-missing' ||
+    value === 'product-unavailable' ||
+    value === 'insufficient-credits' ||
+    value === 'invalid-token' ||
+    value === 'device-inactive'
+  );
+}
+
+function inactiveModeFromSession(session: PlatformSession | null): PlatformModeSnapshot {
+  if (
+    isPlatformModeReleaseReason(session?.lastModeReleaseReason) &&
+    typeof session.lastModeReleasedAt === 'string'
+  ) {
+    return {
+      state: 'inactive',
+      releaseReason: session.lastModeReleaseReason,
+      releasedAt: session.lastModeReleasedAt,
+    };
+  }
+
+  return { state: 'inactive' };
+}
+
+function platformModeFromSession(session: PlatformSession | null): PlatformModeSnapshot {
+  if (
+    session?.platformMode === 'active' &&
+    typeof session.activeProductId === 'string' &&
+    typeof session.platformModeStartedAt === 'string'
+  ) {
+    return {
+      state: 'active',
+      productId: session.activeProductId,
+      startedAt: session.platformModeStartedAt,
+    };
+  }
+
+  return inactiveModeFromSession(session);
+}
+
+function clearPlatformMode(session: PlatformSession): PlatformSession {
+  const {
+    platformMode: _platformMode,
+    activeProductId: _activeProductId,
+    platformModeStartedAt: _platformModeStartedAt,
+    poolSession: _poolSession,
+    routeToken: _routeToken,
+    ...inactiveSession
+  } = session;
+  return inactiveSession;
+}
+
+function clearModeRelease(session: PlatformSession): PlatformSession {
+  const {
+    lastModeReleaseReason: _lastModeReleaseReason,
+    lastModeReleasedAt: _lastModeReleasedAt,
+    ...activeSession
+  } = session;
+  return activeSession;
+}
+
+function releasePlatformMode(
+  session: PlatformSession,
+  reason: PlatformModeReleaseReason,
+): { session: PlatformSession; mode: PlatformModeSnapshot } {
+  const releasedAt = new Date().toISOString();
+  return {
+    session: {
+      ...clearPlatformMode(session),
+      lastModeReleaseReason: reason,
+      lastModeReleasedAt: releasedAt,
+    },
+    mode: { state: 'inactive', releaseReason: reason, releasedAt },
+  };
+}
+
+async function releaseActivePlatformMode(
+  session: PlatformSession,
+  reason: PlatformModeReleaseReason,
+  options: PlatformSessionOptions,
+): Promise<{ session: PlatformSession; mode: PlatformModeSnapshot }> {
+  const mode = platformModeFromSession(session);
+  if (mode.state !== 'active') {
+    return { session, mode };
+  }
+
+  const released = releasePlatformMode(session, reason);
+  await writePlatformSession(released.session, options);
+  return released;
+}
+
+async function releaseForInactiveDevice(
+  session: PlatformSession,
+  options: PlatformSessionOptions,
+): Promise<{ session: PlatformSession; mode: PlatformModeSnapshot }> {
+  if (session.device.status === 'active') {
+    return { session, mode: platformModeFromSession(session) };
+  }
+
+  return releaseActivePlatformMode(session, 'device-inactive', options);
+}
+
+function isUserSummary(value: unknown): value is PlatformUserSummary {
+  const user = value as PlatformUserSummary;
+  return typeof user?.id === 'string' && typeof user.email === 'string';
+}
+
+function isDeviceSummary(value: unknown): value is PlatformDeviceSummary {
+  const device = value as PlatformDeviceSummary;
+  return (
+    typeof device?.id === 'string' &&
+    typeof device.status === 'string' &&
+    typeof device.lastHeartbeatAt === 'string'
+  );
+}
+
+function isProductSummary(value: unknown): value is PlatformProductSummary {
+  const product = value as PlatformProductSummary;
+  return (
+    typeof product?.id === 'string' &&
+    typeof product.name === 'string' &&
+    typeof product.description === 'string' &&
+    (product.status === 'available' || product.status === 'unavailable') &&
+    Number.isInteger(product.minCredits) &&
+    product.minCredits >= 0 &&
+    typeof product.usageLabel === 'string'
+  );
+}
+
+function sanitizeProductSummary(value: unknown): PlatformProductSummary | undefined {
+  if (!isProductSummary(value)) {
+    return undefined;
+  }
+
+  return {
+    id: value.id,
+    name: value.name,
+    description: value.description,
+    status: value.status,
+    minCredits: value.minCredits,
+    usageLabel: value.usageLabel,
+  };
+}
+
+function isPoolSessionSummary(value: unknown): value is PoolSessionSummary {
+  const session = value as PoolSessionSummary;
+  return (
+    typeof session?.id === 'string' &&
+    typeof session.productId === 'string' &&
+    typeof session.providerType === 'string' &&
+    (
+      session.status === 'active' ||
+      session.status === 'refresh-required' ||
+      session.status === 'stopping' ||
+      session.status === 'stopped' ||
+      session.status === 'expired' ||
+      session.status === 'failed'
+    ) &&
+    typeof session.startedAt === 'string' &&
+    typeof session.expiresAt === 'string' &&
+    typeof session.routeTokenExpiresAt === 'string' &&
+    session.routeStrategy === 'platform-gateway' &&
+    Array.isArray(session.bannedModels) &&
+    session.bannedModels.every((model) => typeof model === 'string') &&
+    (
+      session.availableModels === undefined ||
+      (
+        Array.isArray(session.availableModels) &&
+        session.availableModels.every((model) => typeof model === 'string')
+      )
+    ) &&
+    typeof session.capabilities?.streaming === 'boolean' &&
+    typeof session.capabilities.usageEstimate === 'boolean' &&
+    typeof session.capabilities.hardSpendLimit === 'boolean'
+  );
+}
+
+function isLocalRouteTokenState(value: unknown): value is LocalRouteTokenState {
+  const route = value as LocalRouteTokenState;
+  return typeof route?.token === 'string' && typeof route.expiresAt === 'string';
+}
+
+function isPlatformSession(value: unknown): value is PlatformSession {
+  const session = value as PlatformSession;
+  return (
+    typeof session?.apiBaseUrl === 'string' &&
+    typeof session.deviceToken === 'string' &&
+    typeof session.createdAt === 'string' &&
+    isUserSummary(session.user) &&
+    isDeviceSummary(session.device) &&
+    (session.selectedProductId === undefined || typeof session.selectedProductId === 'string') &&
+    (session.platformMode === undefined || session.platformMode === 'active' || session.platformMode === 'inactive') &&
+    (session.activeProductId === undefined || typeof session.activeProductId === 'string') &&
+    (session.platformModeStartedAt === undefined || typeof session.platformModeStartedAt === 'string') &&
+    (
+      session.lastModeReleaseReason === undefined ||
+      isPlatformModeReleaseReason(session.lastModeReleaseReason)
+    ) &&
+    (session.lastModeReleasedAt === undefined || typeof session.lastModeReleasedAt === 'string') &&
+    (session.poolSession === undefined || isPoolSessionSummary(session.poolSession)) &&
+    (session.routeToken === undefined || isLocalRouteTokenState(session.routeToken))
+  );
+}
+
+export async function readPlatformSessionSnapshot(
+  options: PlatformSessionOptions = {},
+): Promise<PlatformSessionSnapshot> {
+  const sessionFile = resolvePlatformSessionFile(options.sessionFile);
+
+  try {
+    const session = JSON.parse(await readFile(sessionFile, 'utf8')) as unknown;
+    return isPlatformSession(session) ? { state: 'valid', session } : { state: 'invalid' };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { state: 'missing' };
+    }
+    if (error instanceof SyntaxError) {
+      return { state: 'invalid' };
+    }
+    throw error;
+  }
+}
+
+export async function readPlatformRouteForwardContext(
+  options: PlatformSessionOptions = {},
+): Promise<{
+  routeToken?: string;
+  poolSessionId?: string;
+}> {
+  const snapshot = await readPlatformSessionSnapshot(options);
+  if (snapshot.state !== 'valid') {
+    return {};
+  }
+
+  return {
+    routeToken: snapshot.session.routeToken?.token,
+    poolSessionId: snapshot.session.poolSession?.id,
+  };
+}
+
+export async function readPlatformGatewayForwardContext(
+  options: PlatformSessionOptions = {},
+): Promise<{
+  apiBaseUrl?: string;
+  deviceToken?: string;
+  routeToken?: string;
+  poolSessionId?: string;
+}> {
+  const snapshot = await readPlatformSessionSnapshot(options);
+  if (snapshot.state !== 'valid') {
+    return {};
+  }
+
+  return {
+    apiBaseUrl: snapshot.session.apiBaseUrl,
+    deviceToken: snapshot.session.deviceToken,
+    routeToken: snapshot.session.routeToken?.token,
+    poolSessionId: snapshot.session.poolSession?.id,
+  };
+}
+
+async function readPlatformSession(options: PlatformSessionOptions = {}): Promise<PlatformSession | null> {
+  const snapshot = await readPlatformSessionSnapshot(options);
+  return snapshot.state === 'valid' ? snapshot.session : null;
+}
+
+export async function cachedPlatformStatus(options: PlatformSessionOptions = {}): Promise<PlatformStatus> {
+  const session = await readPlatformSession(options);
+  if (!session) {
+    return { state: 'logged-out' };
+  }
+
+  return { state: 'offline', user: session.user, device: session.device };
+}
+
+async function writePlatformSession(session: PlatformSession, options: PlatformSessionOptions = {}) {
+  const sessionFile = resolvePlatformSessionFile(options.sessionFile);
+  await mkdir(dirname(sessionFile), { recursive: true, mode: 0o700 });
+  await writeFile(sessionFile, `${JSON.stringify(session, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+  await chmod(sessionFile, 0o600);
+}
+
+async function clearPlatformSession(options: PlatformSessionOptions = {}) {
+  await rm(resolvePlatformSessionFile(options.sessionFile), { force: true });
+}
+
+async function requestJson<T>(
+  url: string,
+  options: { method?: string; body?: Record<string, unknown>; token?: string } = {},
+): Promise<T> {
+  const headers: Record<string, string> = {};
+  if (options.body) {
+    headers['content-type'] = 'application/json';
+  }
+  if (options.token) {
+    headers.authorization = `Bearer ${options.token}`;
+  }
+
+  const response = await fetch(url, {
+    method: options.method ?? 'GET',
+    headers,
+    body: options.body ? JSON.stringify(options.body) : undefined,
+  });
+
+  if (!response.ok) {
+    const error = new Error(`Request failed with status ${response.status}`) as RequestJsonError;
+    error.status = response.status;
+    try {
+      const body = await response.json() as {
+        detail?: unknown;
+      };
+      const detail = body.detail as { code?: unknown } | undefined;
+      if (typeof detail?.code === 'string' && /^[A-Z0-9_:-]{1,96}$/.test(detail.code)) {
+        error.platformCode = detail.code;
+      }
+    } catch {
+      // Platform errors may be non-JSON; status is still enough for offline/invalid-token handling.
+    }
+    throw error;
+  }
+
+  return (await response.json()) as T;
+}
+
+async function exchangeDeviceToken(request: {
+  code: string;
+  apiBaseUrl: string;
+  device: PlatformDeviceInput;
+}) {
+  return requestJson<DeviceTokenResponse>(`${cleanApiBaseUrl(request.apiBaseUrl)}/auth/device-token`, {
+    method: 'POST',
+    body: {
+      code: request.code,
+      device: request.device,
+    },
+  });
+}
+
+async function exchangePasswordDeviceToken(request: {
+  email: string;
+  password: string;
+  apiBaseUrl: string;
+  device: PlatformDeviceInput;
+}) {
+  return requestJson<DeviceTokenResponse>(`${cleanApiBaseUrl(request.apiBaseUrl)}/auth/password-device-token`, {
+    method: 'POST',
+    body: {
+      email: request.email,
+      password: request.password,
+      device: request.device,
+    },
+  });
+}
+
+async function fetchMe(session: PlatformSession) {
+  return requestJson<MeResponse>(`${cleanApiBaseUrl(session.apiBaseUrl)}/me`, {
+    token: session.deviceToken,
+  });
+}
+
+async function fetchAccountSummary(session: PlatformSession) {
+  return requestJson<AccountSummaryResponse>(`${cleanApiBaseUrl(session.apiBaseUrl)}/account/summary`, {
+    token: session.deviceToken,
+  });
+}
+
+async function fetchProducts(session: PlatformSession) {
+  const response = await requestJson<ProductsResponse>(`${cleanApiBaseUrl(session.apiBaseUrl)}/products`, {
+    token: session.deviceToken,
+  });
+
+  return {
+    products: Array.isArray(response.products)
+      ? response.products.flatMap((product) => {
+          const sanitized = sanitizeProductSummary(product);
+          return sanitized ? [sanitized] : [];
+        })
+      : [],
+  };
+}
+
+async function postHeartbeat(request: { session: PlatformSession; payload: HeartbeatPayload }) {
+  return requestJson<HeartbeatResponse>(`${cleanApiBaseUrl(request.session.apiBaseUrl)}/devices/heartbeat`, {
+    method: 'POST',
+    body: request.payload,
+    token: request.session.deviceToken,
+  });
+}
+
+async function postLogout(request: { session: PlatformSession }) {
+  await requestJson(`${cleanApiBaseUrl(request.session.apiBaseUrl)}/auth/logout`, {
+    method: 'POST',
+    token: request.session.deviceToken,
+  });
+}
+
+async function startPoolSession(request: StartPoolSessionRequest): Promise<StartPoolSessionResult> {
+  return requestJson<StartPoolSessionResult>(
+    `${cleanApiBaseUrl(request.session.apiBaseUrl)}/pool-sessions/start`,
+    {
+      method: 'POST',
+      token: request.session.deviceToken,
+      body: {
+        productId: request.productId,
+        ...(request.client ? { client: request.client } : {}),
+      },
+    },
+  );
+}
+
+async function stopPoolSession(request: StopPoolSessionRequest): Promise<StopPoolSessionResult> {
+  return requestJson<StopPoolSessionResult>(
+    `${cleanApiBaseUrl(request.session.apiBaseUrl)}/pool-sessions/${request.poolSessionId}/stop`,
+    {
+      method: 'POST',
+      token: request.session.deviceToken,
+      body: {
+        reason: request.reason,
+      },
+    },
+  );
+}
+
+function poolFailureToModeResult(
+  reason: PoolSessionFailureReason,
+  product: PlatformProductSummary,
+  currentCredits: number,
+): PlatformModeResult {
+  if (reason === 'INSUFFICIENT_CREDITS') {
+    return {
+      state: 'insufficient-credits',
+      productId: product.id,
+      requiredCredits: product.minCredits,
+      currentCredits,
+    };
+  }
+  if (reason === 'DEVICE_INVALID') {
+    return { state: 'device-inactive' };
+  }
+  if (reason === 'PRODUCT_UNAVAILABLE') {
+    return { state: 'product-unavailable', productId: product.id };
+  }
+  if (reason === 'PROVIDER_UNAVAILABLE') {
+    return { state: 'provider-unavailable' };
+  }
+  if (reason === 'RATE_LIMITED') {
+    return { state: 'provider-rate-limited' };
+  }
+  if (reason === 'MODEL_BANNED') {
+    return { state: 'model-banned' };
+  }
+  return { state: 'manual-review-required' };
+}
+
+async function statusFromRequestError(
+  error: unknown,
+  session: PlatformSession,
+  options: RequestErrorStatusOptions = {},
+): Promise<PlatformStatus> {
+  if ((error as RequestJsonError).status === 401) {
+    const currentSession = await readPlatformSession(options) ?? session;
+    const { mode } = options.releaseActiveModeOnUnauthorized
+      ? await releaseActivePlatformMode(currentSession, 'invalid-token', options)
+      : { mode: platformModeFromSession(currentSession) };
+    return { state: 'invalid-token', user: currentSession.user, device: currentSession.device, mode };
+  }
+
+  return { state: 'offline', user: session.user, device: session.device, mode: platformModeFromSession(session) };
+}
+
+export async function loginWithCode(options: LoginWithCodeOptions): Promise<PlatformStatus> {
+  const tokenResponse = await (options.exchangeDeviceToken ?? exchangeDeviceToken)({
+    code: options.code,
+    apiBaseUrl: options.apiBaseUrl,
+    device: options.device ?? {},
+  });
+  const session: PlatformSession = {
+    apiBaseUrl: cleanApiBaseUrl(options.apiBaseUrl),
+    deviceToken: tokenResponse.deviceToken,
+    createdAt: new Date().toISOString(),
+    user: tokenResponse.user,
+    device: tokenResponse.device,
+  };
+
+  await writePlatformSession(session, { sessionFile: options.sessionFile });
+  return asStatus(session);
+}
+
+export async function loginWithPassword(options: LoginWithPasswordOptions): Promise<PlatformStatus> {
+  const tokenResponse = await (options.exchangePasswordDeviceToken ?? exchangePasswordDeviceToken)({
+    email: options.email,
+    password: options.password,
+    apiBaseUrl: options.apiBaseUrl,
+    device: options.device ?? {},
+  });
+  const session: PlatformSession = {
+    apiBaseUrl: cleanApiBaseUrl(options.apiBaseUrl),
+    deviceToken: tokenResponse.deviceToken,
+    createdAt: new Date().toISOString(),
+    user: tokenResponse.user,
+    device: tokenResponse.device,
+  };
+
+  await writePlatformSession(session, { sessionFile: options.sessionFile });
+  return asStatus(session);
+}
+
+export async function platformStatus(options: PlatformSessionOptions = {}): Promise<PlatformStatus> {
+  const session = await readPlatformSession(options);
+  if (!session) {
+    return { state: 'logged-out' };
+  }
+
+  let me: MeResponse;
+  try {
+    me = await fetchMe(session);
+  } catch (error) {
+    return statusFromRequestError(error, session, {
+      ...options,
+      releaseActiveModeOnUnauthorized: true,
+    });
+  }
+
+  const currentSession = await readPlatformSession(options);
+  if (!currentSession) {
+    return { state: 'logged-out' };
+  }
+
+  const updatedSession = { ...currentSession, user: me.user, device: me.device };
+  await writePlatformSession(updatedSession, options);
+  const released = await releaseForInactiveDevice(updatedSession, options);
+  return {
+    state: 'logged-in',
+    user: released.session.user,
+    device: released.session.device,
+    mode: released.mode,
+  };
+}
+
+export async function platformCatalog(options: PlatformSessionOptions = {}): Promise<PlatformCatalog> {
+  const session = await readPlatformSession(options);
+  if (!session) {
+    return { state: 'logged-out', products: [] };
+  }
+
+  const [account, products] = await Promise.allSettled([
+    fetchAccountSummary(session),
+    fetchProducts(session),
+  ]);
+
+  const failures = [account, products].filter((result) => result.status === 'rejected');
+  if (failures.some((result) => (result.reason as RequestJsonError).status === 401)) {
+    const { mode } = await releaseActivePlatformMode(session, 'invalid-token', options);
+    return { state: 'invalid-token', mode, products: [] };
+  }
+  if (failures.length > 0) {
+    return { state: 'offline', products: [] };
+  }
+
+  const catalogProducts = products.value.products;
+  const selectedProductId = catalogProducts.some((product) => product.id === session.selectedProductId)
+    ? session.selectedProductId
+    : undefined;
+  let updatedSession = session;
+  let mode = platformModeFromSession(session);
+  let shouldWriteSession = false;
+  if (session.selectedProductId && !selectedProductId) {
+    const { selectedProductId: _staleSelection, ...sessionWithoutStaleSelection } = session;
+    if (mode.state === 'active') {
+      const released = releasePlatformMode(sessionWithoutStaleSelection, 'product-missing');
+      updatedSession = released.session;
+      mode = released.mode;
+    } else {
+      updatedSession = clearPlatformMode(sessionWithoutStaleSelection);
+      mode = { state: 'inactive' };
+    }
+    shouldWriteSession = true;
+  } else if (mode.state === 'active') {
+    const activeProduct = catalogProducts.find((product) => product.id === mode.productId);
+    const releaseReason = !activeProduct
+      ? 'product-missing'
+      : activeProduct.status !== 'available'
+        ? 'product-unavailable'
+        : account.value.credits < activeProduct.minCredits
+          ? 'insufficient-credits'
+          : undefined;
+    if (releaseReason) {
+      const released = releasePlatformMode(updatedSession, releaseReason);
+      updatedSession = released.session;
+      mode = released.mode;
+      shouldWriteSession = true;
+    }
+  }
+
+  if (shouldWriteSession) {
+    await writePlatformSession(updatedSession, options);
+  }
+
+  return {
+    state: 'logged-in',
+    account: { credits: account.value.credits },
+    mode,
+    ...(selectedProductId ? { selectedProductId } : {}),
+    products: catalogProducts,
+  };
+}
+
+export async function selectPlatformProduct(
+  options: PlatformSessionOptions & { productId: string },
+): Promise<PlatformSelectionResult> {
+  const session = await readPlatformSession(options);
+  if (!session) {
+    return { state: 'logged-out' };
+  }
+
+  const catalog = await platformCatalog(options);
+  if (catalog.state === 'invalid-token' || catalog.state === 'offline') {
+    return { state: catalog.state };
+  }
+  if (catalog.state === 'logged-out') {
+    return { state: 'logged-out' };
+  }
+
+  const currentSession = await readPlatformSession(options);
+  if (!currentSession) {
+    return { state: 'logged-out' };
+  }
+
+  const product = catalog.products.find((candidate) => candidate.id === options.productId);
+  if (!product) {
+    return { state: 'product-not-found', productId: options.productId };
+  }
+  if (product.status !== 'available') {
+    return { state: 'product-unavailable', productId: options.productId };
+  }
+
+  await writePlatformSession({ ...currentSession, selectedProductId: options.productId }, options);
+  return { state: 'selected', selectedProductId: options.productId };
+}
+
+export async function startPlatformMode(options: StartPlatformModeOptions = {}): Promise<PlatformModeResult> {
+  const session = await readPlatformSession(options);
+  if (!session) {
+    return { state: 'logged-out' };
+  }
+
+  const catalog = await platformCatalog(options);
+  if (catalog.state === 'logged-out' || catalog.state === 'offline' || catalog.state === 'invalid-token') {
+    return { state: catalog.state };
+  }
+
+  const currentSession = await readPlatformSession(options);
+  if (!currentSession) {
+    return { state: 'logged-out' };
+  }
+
+  if (!currentSession.selectedProductId) {
+    return { state: 'product-not-selected' };
+  }
+
+  const product = catalog.products.find((candidate) => candidate.id === currentSession.selectedProductId);
+  if (!product) {
+    return { state: 'product-not-found', productId: currentSession.selectedProductId };
+  }
+  if (product.status !== 'available') {
+    return { state: 'product-unavailable', productId: product.id };
+  }
+  if (catalog.account.credits < product.minCredits) {
+    return {
+      state: 'insufficient-credits',
+      productId: product.id,
+      requiredCredits: product.minCredits,
+      currentCredits: catalog.account.credits,
+    };
+  }
+
+  let pool: StartPoolSessionResult;
+  try {
+    pool = await (options.startPoolSession ?? startPoolSession)({
+      session: currentSession,
+      productId: product.id,
+    });
+  } catch {
+    return { state: 'offline' };
+  }
+
+  if (pool.state === 'failed') {
+    return poolFailureToModeResult(pool.reason, product, catalog.account.credits);
+  }
+
+  const startedAt = new Date().toISOString();
+  await writePlatformSession({
+    ...clearModeRelease(currentSession),
+    platformMode: 'active',
+    activeProductId: product.id,
+    platformModeStartedAt: startedAt,
+    poolSession: sanitizePoolSessionSummary(pool.session),
+    routeToken: {
+      token: pool.routeToken,
+      expiresAt: pool.session.routeTokenExpiresAt,
+    },
+  }, options);
+
+  return { state: 'active', productId: product.id, startedAt };
+}
+
+export async function refreshPlatformRoute(
+  options: StartPlatformModeOptions = {},
+): Promise<RefreshPlatformRouteResult> {
+  const session = await readPlatformSession(options);
+  if (
+    !session ||
+    session.device.status !== 'active' ||
+    session.platformMode !== 'active' ||
+    !session.activeProductId
+  ) {
+    return { state: 'not-refreshable' };
+  }
+
+  let pool: StartPoolSessionResult;
+  try {
+    pool = await (options.startPoolSession ?? startPoolSession)({
+      session,
+      productId: session.activeProductId,
+    });
+  } catch {
+    return { state: 'failed', reason: 'offline' };
+  }
+
+  if (pool.state === 'failed') {
+    return { state: 'failed', reason: poolFailureToModeResult(pool.reason, {
+      id: session.activeProductId,
+      name: session.activeProductId,
+      description: '',
+      status: 'available',
+      minCredits: 0,
+      usageLabel: '',
+    }, 0).state };
+  }
+
+  const startedAt = new Date().toISOString();
+  await writePlatformSession({
+    ...clearModeRelease(session),
+    platformMode: 'active',
+    activeProductId: session.activeProductId,
+    platformModeStartedAt: startedAt,
+    poolSession: sanitizePoolSessionSummary(pool.session),
+    routeToken: {
+      token: pool.routeToken,
+      expiresAt: pool.session.routeTokenExpiresAt,
+    },
+  }, options);
+
+  return { state: 'active', productId: session.activeProductId, startedAt };
+}
+
+export async function stopPlatformMode(options: StopPlatformModeOptions = {}): Promise<PlatformModeSnapshot> {
+  const session = await readPlatformSession(options);
+  if (session) {
+    if (session.poolSession) {
+      try {
+        await (options.stopPoolSession ?? stopPoolSession)({
+          session,
+          poolSessionId: session.poolSession.id,
+          reason: 'user-stop',
+        });
+      } catch {
+        // Local stop must clear route capability even when the platform API is unreachable.
+      }
+    }
+
+    await writePlatformSession(clearPlatformMode(session), options);
+  }
+
+  return { state: 'inactive' };
+}
+
+export async function sendHeartbeat(options: SendHeartbeatOptions = {}): Promise<PlatformStatus> {
+  const session = await readPlatformSession(options);
+  if (!session) {
+    return { state: 'logged-out' };
+  }
+
+  let heartbeat: HeartbeatResponse;
+  try {
+    heartbeat = await (options.postHeartbeat ?? postHeartbeat)({
+      session,
+      payload: options.payload ?? {},
+    });
+  } catch (error) {
+    return statusFromRequestError(error, session, {
+      ...options,
+      releaseActiveModeOnUnauthorized: true,
+    });
+  }
+
+  const currentSession = await readPlatformSession(options);
+  if (!currentSession) {
+    return { state: 'logged-out' };
+  }
+
+  const updatedSession = { ...currentSession, device: heartbeat.device };
+  await writePlatformSession(updatedSession, options);
+  const released = await releaseForInactiveDevice(updatedSession, options);
+  return {
+    state: 'logged-in',
+    user: released.session.user,
+    device: released.session.device,
+    mode: released.mode,
+  };
+}
+
+export async function logoutPlatform(options: LogoutPlatformOptions = {}): Promise<PlatformStatus> {
+  const session = await readPlatformSession(options);
+  if (session) {
+    try {
+      await (options.postLogout ?? postLogout)({ session });
+    } catch {
+      // Local logout must succeed even when the platform API is unreachable.
+    }
+  }
+
+  await clearPlatformSession(options);
+  return { state: 'logged-out' };
+}