Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
50.7 KB
Raw Blame
import { config } from './config.js'
import { ApiError, requestJson, withTimeout } from './httpClient.js'
import { assertSafeRouteSegment } from './pathSafety.js'
import {
  ApprovalDecisionResult,
  ContextBreakdownResult,
  HostActivitySnapshot,
  HostMessageRequest,
  HostMessageResponse,
  HostModelsResult,
  HostRuntimeHealth,
  HostRuntimeStatus,
  MessageToolStep,
  PendingApprovalLite,
  RpcAllowedServersResult,
  RpcConnectorsResult,
  SandboxUiApp,
  SessionLifecycleState,
  SessionMessagesQuery,
  SessionMessagesResult,
  SessionTokensLite,
  SessionsListQuery,
  SessionsListResult,
  SetHostModelResult,
} from './types.js'
import { boundedErrorExcerpt, hostAccessDenialMessage } from './upstreamErrors.js'

export type { SandboxUiApp } from './types.js'

/**
 * The runtime rejected a model that is not in the operator allowlist (R2/R3).
 * The `model_not_allowed` token is preserved in the message so the renderer can
 * distinguish it from a transport error after the value crosses the IPC bridge
 * (Error objects serialize to their message string) — mirrors the `404` token
 * convention used by {@link RpcProxyClient.loadSessionMessages}.
 */
const MODEL_NOT_ALLOWED = 'model_not_allowed'
/** CAS precondition failure on `POST …/hosts/:hostRef/model` (issue #654). */
const MODEL_SELECTION_CONFLICT = 'model_selection_conflict'

function wireObject(value: unknown, label: string): Record<string, unknown> {
  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
    throw new Error(`Invalid ${label}`)
  }
  return value as Record<string, unknown>
}

function wireString(value: unknown, label: string): string {
  if (typeof value !== 'string') throw new Error(`Invalid ${label}`)
  return value
}

function optionalWireString(value: unknown, label: string): string | undefined {
  if (value === undefined || value === null) return undefined
  return wireString(value, label)
}

/**
 * Strip everything that would let a title read off the wire misrender or spoof,
 * then trim (spec 15 §2.2/§5, A14). Removes the whole Unicode "Other" category
 * `\p{C}` (control, format — bidi overrides, zero-width joiners/marks, BOM — and
 * surrogate/private-use/unassigned) plus line/paragraph separators `\p{Zl}`/
 * `\p{Zp}` (U+2028/U+2029). This aligns with the server-side writer (which
 * strips `\p{C}` and collapses whitespace) and guarantees a single-line title in
 * the sidebar and the destructive rename dialog. A session title is authored on
 * one device and read on another; a stale host or a malicious device could ship
 * a bidi-override that spoofs the dialog, so the reader never trusts the value —
 * this is defense in depth on read (ZWJ is stripped too: anti-spoofing wins over
 * emoji fidelity for a value that gates a destructive dialog). Returns
 * `undefined` when nothing legible remains, so the caller falls back to the
 * local cache or a placeholder instead of rendering a blank title.
 */
// Mirror the server-side cap so a stale or hostile host cannot ship an oversized
// title past the reader's trust boundary. The server rejects >120 code points with
// a 400, so a legitimately stored title is always within this; on read we truncate
// (a parser must not drop the whole session over a too-long title) rather than reject.
const MAX_WIRE_TITLE_CODEPOINTS = 120

function sanitizeWireTitle(value: string): string | undefined {
  const cleaned = value.replace(/[\p{C}\p{Zl}\p{Zp}]/gu, '').trim()
  if (cleaned.length === 0) return undefined
  const points = Array.from(cleaned)
  return points.length > MAX_WIRE_TITLE_CODEPOINTS
    ? points.slice(0, MAX_WIRE_TITLE_CODEPOINTS).join('')
    : cleaned
}

function wireSafeInteger(
  value: unknown,
  label: string,
  minimum: number,
  optional = false
): number | undefined {
  if (optional && (value === undefined || value === null)) return undefined
  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < minimum) {
    throw new Error(`Invalid ${label}`)
  }
  return value
}

function optionalWireBoolean(value: unknown, label: string): boolean | undefined {
  if (value === undefined || value === null) return undefined
  if (typeof value !== 'boolean') throw new Error(`Invalid ${label}`)
  return value
}

function parseSessionState(value: unknown, label: string): SessionLifecycleState | undefined {
  if (value === undefined || value === null) return undefined
  if (value === 'idle' || value === 'processing' || value === 'awaiting_approval') return value
  if (typeof value === 'string') return undefined
  throw new Error(`Invalid ${label}`)
}

function parsePendingApproval(value: unknown, label: string): PendingApprovalLite | undefined {
  if (value === undefined || value === null) return undefined
  const record = wireObject(value, label)
  // U5 (mcp-oauth reactive consent): `reason`/`mcpServerName` are additive. They
  // ride the same REST wire as the generic approval descriptor and MUST be
  // surfaced so the renderer can branch a `connect_required` suspension into an
  // OAuth "Connect <server>" affordance instead of a generic tool approval. An
  // absent `reason` (or any value other than `connect_required`) keeps the
  // byte-identical generic-approval flow.
  const reason = optionalWireString(record.reason, `${label}.reason`)
  const mcpServerName = optionalWireString(record.mcpServerName, `${label}.mcpServerName`)
  return {
    requestId: wireString(record.requestId, `${label}.requestId`),
    displayName: wireString(record.displayName, `${label}.displayName`),
    ...(reason !== undefined ? { reason } : {}),
    ...(mcpServerName !== undefined ? { mcpServerName } : {}),
  }
}

function parseTokens(value: unknown, label: string): SessionTokensLite | undefined {
  if (value === undefined || value === null) return undefined
  const record = wireObject(value, label)
  return {
    input: wireSafeInteger(record.input, `${label}.input`, 0)!,
    output: wireSafeInteger(record.output, `${label}.output`, 0)!,
    ...(record.cacheRead !== undefined
      ? { cacheRead: wireSafeInteger(record.cacheRead, `${label}.cacheRead`, 0)! }
      : {}),
    ...(record.cacheWrite !== undefined
      ? { cacheWrite: wireSafeInteger(record.cacheWrite, `${label}.cacheWrite`, 0)! }
      : {}),
  }
}

function parseToolSteps(value: unknown, label: string): MessageToolStep[] {
  if (!Array.isArray(value)) throw new Error(`Invalid ${label}`)
  return value.map((step, index) => {
    const stepLabel = `${label}[${index}]`
    const record = wireObject(step, stepLabel)
    const state = record.state
    if (state !== 'completed' && state !== 'error') {
      throw new Error(`Invalid ${stepLabel}.state`)
    }
    return {
      toolName: wireString(record.toolName, `${stepLabel}.toolName`),
      displayName: wireString(record.displayName, `${stepLabel}.displayName`),
      state,
      ...(record.durationMs !== undefined
        ? { durationMs: wireSafeInteger(record.durationMs, `${stepLabel}.durationMs`, 0)! }
        : {}),
      ...(record.errorSummary !== undefined
        ? { errorSummary: wireString(record.errorSummary, `${stepLabel}.errorSummary`) }
        : {}),
    }
  })
}

/**
 * Longest sessions cursor the `rpc:listSessions` IPC handler accepts
 * (`sanitizeSessionsListQuery` in `ipc.ts`; mcp-host enforces the same bound).
 */
const SESSIONS_CURSOR_MAX_LENGTH = 2048

// Exported for tests: renderer/parser tests derive their fixtures from the real
// producer (pr-discipline T1) instead of hand-mocking the parsed shape.
export function parseSessionsListResult(value: unknown): SessionsListResult {
  const record = wireObject(value, 'sessions response')
  if (!Array.isArray(record.items)) throw new Error('Invalid sessions response.items')
  let firstItemError: unknown
  let droppedItemCount = 0
  const items = record.items.flatMap((item, index): SessionsListResult['items'] => {
    try {
      const entry = wireObject(item, `sessions response.items[${index}]`)
      const state = parseSessionState(entry.state, `sessions response.items[${index}].state`)
      return [
        {
          agent: wireString(entry.agent, `sessions response.items[${index}].agent`),
          chatId: wireString(entry.chatId, `sessions response.items[${index}].chatId`),
          turnCount: wireSafeInteger(
            entry.turnCount,
            `sessions response.items[${index}].turnCount`,
            0
          )!,
          ...(entry.messageCount != null
            ? {
                messageCount: wireSafeInteger(
                  entry.messageCount,
                  `sessions response.items[${index}].messageCount`,
                  0
                )!,
              }
            : {}),
          ...(() => {
            // A malformed optional title must not drop a real conversation: a
            // present-but-non-string value falls to "no title" (the session
            // survives, untitled), consistent with how null/absent/empty-after-
            // sanitize are handled here. Only mandatory fields (agent, chatId,
            // lastActivityAt) throw and drop the item.
            const title =
              typeof entry.title === 'string' ? sanitizeWireTitle(entry.title) : undefined
            return title !== undefined ? { title } : {}
          })(),
          lastActivityAt: wireString(
            entry.lastActivityAt,
            `sessions response.items[${index}].lastActivityAt`
          ),
          ...(state !== undefined ? { state } : {}),
          ...(entry.activeTaskId != null
            ? {
                activeTaskId: optionalWireString(
                  entry.activeTaskId,
                  `sessions response.items[${index}].activeTaskId`
                ),
              }
            : {}),
          ...(entry.pendingApproval != null
            ? {
                pendingApproval: parsePendingApproval(
                  entry.pendingApproval,
                  `sessions response.items[${index}].pendingApproval`
                ),
              }
            : {}),
          ...(entry.tokens != null
            ? { tokens: parseTokens(entry.tokens, `sessions response.items[${index}].tokens`) }
            : {}),
        },
      ]
    } catch (error) {
      firstItemError ??= error
      droppedItemCount += 1
      // R1-H1: a tolerant partial parse must not lose a session silently. A single
      // corrupt entry should not blank the whole sidebar (we still return the valid
      // items), but the drop has to leave a trace — otherwise a user's chat vanishes
      // from "Latest sessions" with no signal. Log the index + item error so the loss
      // is traceable in main-process logs, and count it into `droppedItemCount` below
      // so the renderer can observe that `items` is shorter than the server sent.
      console.warn(
        `[RpcProxyClient] Dropped malformed session catalog item at index ${index}:`,
        error
      )
      return []
    }
  })
  if (record.items.length > 0 && items.length === 0 && firstItemError) throw firstItemError
  const nextCursor =
    record.nextCursor != null
      ? wireString(record.nextCursor, 'sessions response.nextCursor')
      : undefined
  // R3-L10: the `rpc:listSessions` IPC handler refuses a longer cursor before
  // any request, so handing one to the renderer would only produce a status-less
  // error on "Load more". End the page chain here instead. The cursor is opaque
  // upstream state: log its length only, never its value.
  const cursorTooLong = nextCursor !== undefined && nextCursor.length > SESSIONS_CURSOR_MAX_LENGTH
  if (cursorTooLong) {
    console.warn(
      `[RpcProxyClient] Dropped a sessions nextCursor of ${nextCursor.length} characters (limit ${SESSIONS_CURSOR_MAX_LENGTH})`
    )
  }
  return {
    items,
    ...(droppedItemCount > 0 ? { droppedItemCount } : {}),
    ...(nextCursor !== undefined && !cursorTooLong ? { nextCursor } : {}),
  }
}

function parseSessionMessagesResult(
  value: unknown,
  expectedAgent: string,
  expectedChatId: string
): SessionMessagesResult {
  const record = wireObject(value, 'session messages response')
  const agent = wireString(record.agent, 'session messages response.agent')
  const chatId = wireString(record.chatId, 'session messages response.chatId')
  if (agent !== expectedAgent || chatId !== expectedChatId) {
    throw new Error('Invalid session messages response identity')
  }
  if (!Array.isArray(record.turns)) throw new Error('Invalid session messages response.turns')
  const state = parseSessionState(record.state, 'session messages response.state')
  return {
    agent,
    chatId,
    ...(record.totalTurns != null
      ? {
          totalTurns: wireSafeInteger(
            record.totalTurns,
            'session messages response.totalTurns',
            0
          )!,
        }
      : {}),
    ...(record.oldestTurnNumber != null
      ? {
          oldestTurnNumber: wireSafeInteger(
            record.oldestTurnNumber,
            'session messages response.oldestTurnNumber',
            0
          )!,
        }
      : {}),
    ...(record.latestTurnNumber != null
      ? {
          latestTurnNumber: wireSafeInteger(
            record.latestTurnNumber,
            'session messages response.latestTurnNumber',
            0
          )!,
        }
      : {}),
    ...(record.hasMoreBefore != null
      ? {
          hasMoreBefore: optionalWireBoolean(
            record.hasMoreBefore,
            'session messages response.hasMoreBefore'
          ),
        }
      : {}),
    ...(record.hasMoreAfter != null
      ? {
          hasMoreAfter: optionalWireBoolean(
            record.hasMoreAfter,
            'session messages response.hasMoreAfter'
          ),
        }
      : {}),
    ...(state !== undefined ? { state } : {}),
    ...(record.activeTaskId != null
      ? {
          activeTaskId: optionalWireString(
            record.activeTaskId,
            'session messages response.activeTaskId'
          ),
        }
      : {}),
    ...(record.pendingApproval != null
      ? {
          pendingApproval: parsePendingApproval(
            record.pendingApproval,
            'session messages response.pendingApproval'
          ),
        }
      : {}),
    ...(record.tokens != null
      ? { tokens: parseTokens(record.tokens, 'session messages response.tokens') }
      : {}),
    turns: record.turns.map((turn, index) => {
      const entry = wireObject(turn, `session messages response.turns[${index}]`)
      return {
        number: wireSafeInteger(
          entry.number,
          `session messages response.turns[${index}].number`,
          0
        )!,
        user_input: wireString(
          entry.user_input,
          `session messages response.turns[${index}].user_input`
        ),
        ...(entry.response != null
          ? {
              response: optionalWireString(
                entry.response,
                `session messages response.turns[${index}].response`
              ),
            }
          : {}),
        started_at: wireString(
          entry.started_at,
          `session messages response.turns[${index}].started_at`
        ),
        ...(entry.completed_at != null
          ? {
              completed_at: optionalWireString(
                entry.completed_at,
                `session messages response.turns[${index}].completed_at`
              ),
            }
          : {}),
        ...(entry.tokens != null
          ? {
              tokens: parseTokens(entry.tokens, `session messages response.turns[${index}].tokens`),
            }
          : {}),
        ...(entry.tool_steps != null
          ? {
              tool_steps: parseToolSteps(
                entry.tool_steps,
                `session messages response.turns[${index}].tool_steps`
              ),
            }
          : {}),
      }
    }),
  }
}

/**
 * mcp-host answers HTTP 200 with `{success:false, error}` when an approval was
 * already decided by another channel (spec-v2 §4.7.4). Parse the body into a
 * structured result; a genuine non-ok HTTP still throws upstream.
 */
async function parseApprovalDecisionResponse(response: Response): Promise<ApprovalDecisionResult> {
  const text = await response.text()
  if (!text) return { success: true }
  try {
    const parsed = JSON.parse(text) as { success?: unknown; error?: unknown }
    if (parsed && parsed.success === false) {
      return {
        success: false,
        error: typeof parsed.error === 'string' ? parsed.error : undefined,
      }
    }
    return { success: true }
  } catch {
    // A 200 with a non-JSON body historically meant success.
    return { success: true }
  }
}

// A sandbox-ui open/close runs on a single lifecycle queue, so a hung mint
// blocks every queued close behind it; and the refresh re-mints only 30 s
// before the cookie expires. The app-wide default (60 s) would be too loose
// for both.
// The embed's OAuth authorize-url call shares it: a hung one would leave the
// embed's click without any answer for a minute.
export const SANDBOX_UI_MINT_TIMEOUT_MS = 15_000

function rpcProxyUrl(baseUrl: string, path: string): string {
  return `${baseUrl.replace(/\/+$/, '')}${path}`
}

/**
 * Status mapping used by the renderer:
 *   401 / 403 → re-auth or lost ACL
 *   404       → app removed
 *   409       → app is updating; try again
 *   500 / 502 → generic open failure
 */
export class SandboxUiSessionError extends ApiError {
  // An ApiError so `AppService.shouldRefreshRpcToken` sees a 401 or a
  // missing-scope 403 and re-mints with a fresh RPC token. Such a 401 comes
  // from the short-lived RPC token, never from the user's session: it must
  // not be read as a reason to sign the user out.
  constructor(status: number, body: string) {
    super(
      `sandbox-ui session mint failed (${status}): ${boundedErrorExcerpt(body) || '<empty body>'}`,
      status,
      body
    )
    this.name = 'SandboxUiSessionError'
  }

  get body(): string {
    return this.bodyText
  }
}

async function readErrorBody(response: Response): Promise<string> {
  try {
    return await response.text()
  } catch (error) {
    return error instanceof Error
      ? `Failed to read error body: ${error.message}`
      : 'Failed to read error body'
  }
}

/**
 * Extracts the `error` code from a JSON error body (e.g. `model_not_allowed`),
 * used to disambiguate error sources that share an HTTP status. Returns null for
 * non-JSON or code-less bodies.
 */
function errorCodeFromBody(body: string): string | null {
  try {
    const parsed = JSON.parse(body) as { error?: unknown }
    return typeof parsed?.error === 'string' ? parsed.error : null
  } catch {
    return null
  }
}

/**
 * The single producer of Host-access denial errors for the raw-`fetch` methods:
 * the message strings and the `code` rule live in `upstreamErrors.ts` and are
 * shared with `httpClient.requestJson`.
 */
function hostAccessDenialError(status: number, body: string): ApiError | null {
  const message = hostAccessDenialMessage(status, body)
  return message ? new ApiError(message, status, body) : null
}

export class RpcProxyClient {
  constructor(private readonly getRpcProxyBaseUrl: () => string = () => config.rpcProxyBaseUrl) {}

  private url(path: string): string {
    return rpcProxyUrl(this.getRpcProxyBaseUrl(), path)
  }

  async health(): Promise<{ status: string }> {
    return requestJson<{ status: string }>('GET', this.url('/health'))
  }

  async listServers(rpcAccessToken: string): Promise<RpcAllowedServersResult> {
    return requestJson<RpcAllowedServersResult>('GET', this.url('/api/v1/rpc/servers'), {
      token: rpcAccessToken,
    })
  }

  /**
   * Proactive connectors read-model (spec 11 U2/U1) — the per-agent classified
   * fleet (`authorized`/`requires_setup`/`no_oauth`). Reuses the `mcp:servers:list`
   * scope (catalog read), like {@link listServers}; rpc-proxy derives the
   * `userId` from `auth.sub` and enumerates the agents server-side, so the token
   * only needs a valid host binding for the scope gate. Throws `ApiError` so
   * `AppService.shouldRefreshRpcToken` can drive the retry-after-refresh.
   */
  async getConnectors(rpcAccessToken: string): Promise<RpcConnectorsResult> {
    return requestJson<RpcConnectorsResult>('GET', this.url('/api/v1/rpc/connectors'), {
      token: rpcAccessToken,
    })
  }

  /**
   * Disconnect (revoke) an mcp-server's OAuth grant (spec 11 U4). Mirrors the
   * authorize-URL mint route but as a `DELETE`; the `userId` is derived by
   * rpc-proxy from `auth.sub` and is NEVER sent in the body (invariant 3). The
   * optional `contextId` is only a hint for the `oauth-context` flavor — control
   * -api resolves the authoritative Context server-side. Idempotent: a missing
   * grant answers 204. Throws `ApiError` (401/403-missing-scope → refresh retry).
   */
  async deleteMcpOauthGrant(
    rpcAccessToken: string,
    mcpServerName: string,
    contextId?: string
  ): Promise<void> {
    await requestJson<unknown>(
      'DELETE',
      this.url(`/api/v1/mcp-oauth/${encodeURIComponent(mcpServerName)}/grant`),
      {
        token: rpcAccessToken,
        // Body is optional; only send `contextId` when present. `userId` is NEVER
        // sent — rpc-proxy derives it from the JWT sub.
        body: contextId ? { contextId } : {},
      }
    )
  }

  async invokeHostMessage(
    rpcAccessToken: string,
    hostRef: string,
    payload: HostMessageRequest,
    options?: { async?: boolean }
  ): Promise<HostMessageResponse> {
    const query = options?.async ? '?async=true' : ''
    return requestJson<HostMessageResponse>(
      'POST',
      this.url(`/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/messages${query}`),
      {
        token: rpcAccessToken,
        body: payload,
      }
    )
  }

  async getTaskResult(
    rpcAccessToken: string,
    hostRef: string,
    taskId: string
  ): Promise<HostMessageResponse> {
    return requestJson<HostMessageResponse>(
      'GET',
      this.url(
        `/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/tasks/${encodeURIComponent(taskId)}/result`
      ),
      { token: rpcAccessToken }
    )
  }

  async getHostStatus(rpcAccessToken: string, hostRef: string): Promise<HostRuntimeStatus> {
    return requestJson<HostRuntimeStatus>(
      'GET',
      this.url(`/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/status`),
      {
        token: rpcAccessToken,
      }
    )
  }

  /**
   * Pre-warms a stateless host: asks rpc-proxy to scale the suspended pod
   * back up so it is Ready before the user's first message. Every response on
   * the wake contract is terminal — no polling, no retry:
   *   200 {status:'active'}          host already running
   *   202 {status:'wake-requested'}  scale-up triggered
   *   409 {status:'not-stateless'}   always-on host; nothing to wake
   * Anything else (401/403/404/5xx) is an error for the caller to log.
   */
  async prewarmHost(rpcAccessToken: string, hostRef: string): Promise<{ status: string }> {
    const response = await fetch(
      this.url(`/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/wake`),
      {
        method: 'POST',
        headers: { authorization: `Bearer ${rpcAccessToken}` },
      }
    )
    if (response.status === 200 || response.status === 202 || response.status === 409) {
      const payload = (await response.json()) as { status?: string }
      const status = payload?.status
      if (status !== 'active' && status !== 'wake-requested' && status !== 'not-stateless') {
        throw new ApiError(
          `Prewarm returned a contract-violating body (${response.status}): status=${String(status)}`,
          response.status,
          JSON.stringify(payload)
        )
      }
      return { status }
    }
    const body = await readErrorBody(response)
    throw new ApiError(
      `Prewarm failed (${response.status}): ${boundedErrorExcerpt(body)}`,
      response.status,
      body
    )
  }

  async getHostHealth(rpcAccessToken: string, hostRef: string): Promise<HostRuntimeHealth> {
    return requestJson<HostRuntimeHealth>(
      'GET',
      this.url(`/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/health`),
      {
        token: rpcAccessToken,
      }
    )
  }

  async getHostActivity(
    rpcAccessToken: string,
    hostRef: string,
    options?: { limit?: number; sinceEventId?: string }
  ): Promise<HostActivitySnapshot> {
    const params = new URLSearchParams()
    if (options?.limit) params.set('limit', String(options.limit))
    if (options?.sinceEventId) params.set('sinceEventId', options.sinceEventId)
    const query = params.toString()
    return requestJson<HostActivitySnapshot>(
      'GET',
      this.url(
        `/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/activity${query ? `?${query}` : ''}`
      ),
      { token: rpcAccessToken }
    )
  }

  /**
   * List every UI-bearing recipe the user is allowlisted on.
   * The RPC JWT must carry the `sandbox:ui:view` scope (issued by control-api
   * when the user appears in user_workflow_triggers for any recipe
   * with a `ui:` block). The recipe ACL is re-checked per recipe on session
   * mint — this list is purely the picker payload.
   */
  async listSandboxUiApps(rpcAccessToken: string): Promise<{ apps: SandboxUiApp[] }> {
    return requestJson<{ apps: SandboxUiApp[] }>('GET', this.url('/api/v1/sandbox-ui/apps'), {
      token: rpcAccessToken,
    })
  }

  /**
   * Mint the per-recipe UI session cookie.
   *
   * Returns the raw Set-Cookie header value so the main process can hand it
   * off to the WebContentsView's session.cookies.set() — rpc-proxy issues a
   * Path-scoped cookie that must be installed into the embed's per-recipe
   * partition before any view/* request.
   *
   * 204 → cookie minted; the Set-Cookie response header is non-empty.
   * Other → throws a typed error so the caller can decide whether to retry,
   *         show a toast, or refuse to mount the view.
   */
  async mintSandboxUiSession(
    rpcAccessToken: string,
    recipeNs: string,
    recipeName: string
  ): Promise<{ setCookie: string }> {
    const response = await fetch(
      this.url(
        `/api/v1/sandbox-ui/${encodeURIComponent(recipeNs)}/${encodeURIComponent(recipeName)}/session`
      ),
      {
        method: 'POST',
        headers: { authorization: `Bearer ${rpcAccessToken}` },
        signal: withTimeout(undefined, SANDBOX_UI_MINT_TIMEOUT_MS),
      }
    )
    if (response.status !== 204) {
      const body = await response.text()
      throw new SandboxUiSessionError(response.status, body)
    }
    const setCookie = response.headers.get('set-cookie') ?? ''
    if (!setCookie) {
      throw new SandboxUiSessionError(500, 'session minted without Set-Cookie header')
    }
    return { setCookie }
  }

  /**
   * Spec §9.9 — fetch the provider authorize URL for an embed-initiated
   * OAuth flow. The desktop main process calls this when the embed
   * navigates to `clerum://oauth?clientId=…`; the returned URL is opened
   * in the OS browser via `shell.openExternal`. rpc-proxy constructs the
   * redirect_uri (control-api's public callback) and forwards to
   * control-api's internal endpoint with the user identity asserted from
   * the JWT sub.
   */
  async requestSandboxUiOauthAuthorizeUrl(
    rpcAccessToken: string,
    recipeNs: string,
    recipeName: string,
    oauthClientId: string,
    background = false
  ): Promise<{ authorizeUrl: string }> {
    const response = await fetch(
      this.url(
        `/api/v1/sandbox-ui/${encodeURIComponent(recipeNs)}/${encodeURIComponent(recipeName)}/oauth/authorize-url`
      ),
      {
        method: 'POST',
        headers: {
          authorization: `Bearer ${rpcAccessToken}`,
          'content-type': 'application/json',
        },
        body: JSON.stringify({ oauthClientId, background }),
        signal: withTimeout(undefined, SANDBOX_UI_MINT_TIMEOUT_MS),
      }
    )
    if (!response.ok) {
      const body = await response.text()
      // An ApiError so `AppService.shouldRefreshRpcToken` can retry a 401 or a
      // missing-scope 403 with a fresh RPC token.
      throw new ApiError(
        `sandbox-ui authorize-url request failed (${response.status}): ${boundedErrorExcerpt(body) || '<empty>'}`,
        response.status,
        body
      )
    }
    const json = (await response.json()) as { authorizeUrl?: unknown }
    if (typeof json?.authorizeUrl !== 'string' || !json.authorizeUrl) {
      throw new Error('sandbox-ui authorize-url response missing authorizeUrl')
    }
    return { authorizeUrl: json.authorizeUrl }
  }

  /**
   * U5 (mcp-oauth reactive consent) — fetch the provider authorize URL for a
   * "Connect <server>" flow, initiated when a tool-call against an OAuth
   * mcp-server suspended with `connect_required`. Mirrors
   * `requestSandboxUiOauthAuthorizeUrl` but keyed by `mcpServerName` (never a
   * recipe): rpc-proxy derives the `userId` from `auth.sub` and forwards to
   * control-api's internal mint. The returned URL is opened via
   * `shell.openExternal`.
   *
   * Throws `ApiError` (not a bare Error) so `AppService.shouldRefreshRpcToken`
   * can see a 401/403-missing-scope status and drive the retry-after-refresh,
   * exactly like `approveToolCall`. A legitimate 403 (`context_membership_denied`),
   * 404 (`server_not_found`), 400 (`not_oauth_server`, …) or 502/503 propagates
   * verbatim in the message for the renderer to surface.
   */
  async requestMcpOauthAuthorizeUrl(
    rpcAccessToken: string,
    mcpServerName: string,
    contextId?: string
  ): Promise<{ authorizeUrl: string }> {
    const response = await fetch(
      this.url(`/api/v1/mcp-oauth/${encodeURIComponent(mcpServerName)}/authorize-url`),
      {
        method: 'POST',
        headers: {
          authorization: `Bearer ${rpcAccessToken}`,
          'content-type': 'application/json',
        },
        // Body is optional; only send `contextId` when present. The `userId` is
        // NEVER sent — rpc-proxy derives it from the JWT sub (invariant 3).
        body: JSON.stringify(contextId ? { contextId } : {}),
        signal: withTimeout(),
      }
    )
    if (!response.ok) {
      const body = await response.text()
      throw new ApiError(
        `mcp-oauth authorize-url request failed (${response.status}): ${boundedErrorExcerpt(body) || '<empty>'}`,
        response.status,
        body
      )
    }
    const json = (await response.json()) as { authorizeUrl?: unknown }
    if (typeof json?.authorizeUrl !== 'string' || !json.authorizeUrl) {
      throw new Error('mcp-oauth authorize-url response missing authorizeUrl')
    }
    return { authorizeUrl: json.authorizeUrl }
  }

  private async openHostStream(
    rpcAccessToken: string,
    path: string,
    onEvent: (event: { event: string; data: unknown }) => void,
    signal: AbortSignal,
    // Invoked for SSE comment lines (e.g. `: keepalive`). These carry no data
    // and are normally dropped, but they prove the connection is alive — the
    // progress stream wires this to a heartbeat so the client watchdog doesn't
    // falsely time out during a long, semantically-silent tool run.
    onKeepalive?: () => void
  ): Promise<void> {
    const response = await fetch(this.url(path), {
      method: 'GET',
      headers: {
        accept: 'text/event-stream',
        authorization: `Bearer ${rpcAccessToken}`,
      },
      signal,
    })
    if (!response.ok) {
      const body = await response.text()
      throw new Error(
        `Host stream failed (${response.status}): ${boundedErrorExcerpt(body) || response.statusText}`
      )
    }
    if (!response.body) {
      throw new Error('Host stream missing response body')
    }

    const reader = response.body.getReader()
    const decoder = new TextDecoder()
    let buffer = ''

    const processChunk = (chunk: string) => {
      buffer += chunk
      while (true) {
        const separator = buffer.indexOf('\n\n')
        if (separator === -1) break
        const rawEvent = buffer.slice(0, separator)
        buffer = buffer.slice(separator + 2)
        const lines = rawEvent.split(/\r?\n/)
        let eventName = 'message'
        let sawComment = false
        const dataLines: string[] = []
        for (const line of lines) {
          if (line.startsWith('event:')) {
            eventName = line.slice(6).trim() || 'message'
          } else if (line.startsWith('data:')) {
            dataLines.push(line.slice(5).trim())
          } else if (line.startsWith(':')) {
            sawComment = true
          }
        }
        if (!dataLines.length) {
          // A bare comment block (`: keepalive`) — signal liveness, then skip.
          if (sawComment) onKeepalive?.()
          continue
        }
        const payloadText = dataLines.join('\n')
        try {
          const data = JSON.parse(payloadText) as unknown
          onEvent({ event: eventName, data })
        } catch {
          onEvent({ event: 'error', data: { message: 'Invalid stream payload' } })
        }
      }
    }

    while (true) {
      const { done, value } = await reader.read()
      if (done) break
      processChunk(decoder.decode(value, { stream: true }))
    }
    const trailing = decoder.decode()
    if (trailing) processChunk(trailing)
  }

  async openHostStatusStream(
    rpcAccessToken: string,
    hostRef: string,
    onEvent: (event: { event: string; data: unknown }) => void,
    signal: AbortSignal
  ): Promise<void> {
    await this.openHostStream(
      rpcAccessToken,
      `/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/status/stream`,
      onEvent,
      signal
    )
  }

  async openHostActivityStream(
    rpcAccessToken: string,
    hostRef: string,
    onEvent: (event: { event: string; data: unknown }) => void,
    signal: AbortSignal
  ): Promise<void> {
    await this.openHostStream(
      rpcAccessToken,
      `/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/activity/stream`,
      onEvent,
      signal
    )
  }

  async openTaskProgressStream(
    rpcAccessToken: string,
    hostRef: string,
    taskId: string,
    onEvent: (event: { event: string; data: unknown }) => void,
    signal: AbortSignal
  ): Promise<void> {
    await this.openHostStream(
      rpcAccessToken,
      `/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/tasks/${encodeURIComponent(taskId)}/progress/stream`,
      onEvent,
      signal,
      // Surface mcp-host's `: keepalive` comments as heartbeats so the renderer's
      // task watchdog treats the connection as alive during long silent tools.
      () => onEvent({ event: 'heartbeat', data: { taskId, iteration: 0, elapsedMs: 0 } })
    )
  }

  async approveToolCall(
    rpcToken: string,
    hostRef: string,
    taskId: string,
    toolCallId: string
  ): Promise<ApprovalDecisionResult> {
    const response = await fetch(
      this.url(`/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/approvals/approve`),
      {
        method: 'POST',
        headers: {
          'content-type': 'application/json',
          authorization: `Bearer ${rpcToken}`,
        },
        body: JSON.stringify({ taskId, toolCallId }),
        signal: withTimeout(),
      }
    )
    if (!response.ok) {
      const body = await response.text()
      // ApiError (not a bare Error) so `AppService.shouldRefreshRpcToken` can see
      // the 401/403 status and drive the retry-after-refresh (§4.5-7).
      throw new ApiError(
        `Approve failed (${response.status}): ${boundedErrorExcerpt(body)}`,
        response.status,
        body
      )
    }
    return parseApprovalDecisionResponse(response)
  }

  async denyToolCall(
    rpcToken: string,
    hostRef: string,
    taskId: string,
    toolCallId: string,
    reason: string
  ): Promise<ApprovalDecisionResult> {
    const response = await fetch(
      this.url(`/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/approvals/deny`),
      {
        method: 'POST',
        headers: {
          'content-type': 'application/json',
          authorization: `Bearer ${rpcToken}`,
        },
        body: JSON.stringify({ taskId, toolCallId, reason }),
        signal: withTimeout(),
      }
    )
    if (!response.ok) {
      const body = await response.text()
      throw new ApiError(
        `Deny failed (${response.status}): ${boundedErrorExcerpt(body)}`,
        response.status,
        body
      )
    }
    return parseApprovalDecisionResponse(response)
  }

  async cancelTask(rpcToken: string, hostRef: string, taskId: string): Promise<void> {
    const response = await fetch(
      this.url(
        `/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/tasks/${encodeURIComponent(taskId)}/cancel`
      ),
      {
        method: 'POST',
        headers: {
          'content-type': 'application/json',
          authorization: `Bearer ${rpcToken}`,
        },
        signal: withTimeout(),
      }
    )
    if (!response.ok) {
      const body = await response.text()
      throw new ApiError(
        `cancelTask failed (${response.status}): ${boundedErrorExcerpt(body)}`,
        response.status,
        body
      )
    }
  }

  async listArtifacts(
    rpcToken: string,
    hostRef: string
  ): Promise<{
    artifacts: Array<{ name: string; format: string; sizeBytes: number; createdAt: string }>
  }> {
    const response = await fetch(
      this.url(`/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/artifacts`),
      {
        headers: { authorization: `Bearer ${rpcToken}` },
        signal: withTimeout(),
      }
    )
    if (!response.ok) {
      const body = await response.text()
      throw new ApiError(
        `List artifacts failed (${response.status}): ${boundedErrorExcerpt(body)}`,
        response.status,
        body
      )
    }
    return response.json() as Promise<{
      artifacts: Array<{ name: string; format: string; sizeBytes: number; createdAt: string }>
    }>
  }

  async downloadArtifact(rpcToken: string, hostRef: string, filename: string): Promise<Buffer> {
    const response = await fetch(
      this.url(
        `/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/artifacts/${encodeURIComponent(filename)}/download`
      ),
      {
        headers: { authorization: `Bearer ${rpcToken}` },
      }
    )
    if (!response.ok) {
      const body = await response.text()
      throw new Error(`Download artifact failed (${response.status}): ${boundedErrorExcerpt(body)}`)
    }
    return Buffer.from(await response.arrayBuffer())
  }

  async listSessions(
    rpcToken: string,
    hostRef: string,
    query: SessionsListQuery = {}
  ): Promise<SessionsListResult> {
    assertSafeRouteSegment('hostRef', hostRef)
    const requestUrl = new URL(
      this.url(`/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/sessions`)
    )
    if (query.agent) requestUrl.searchParams.set('agent', query.agent)
    if (query.limit !== undefined) requestUrl.searchParams.set('limit', String(query.limit))
    if (query.cursor) requestUrl.searchParams.set('cursor', query.cursor)
    const response = await fetch(requestUrl, {
      headers: { authorization: `Bearer ${rpcToken}` },
      signal: withTimeout(),
    })
    if (!response.ok) {
      const body = await response.text()
      const hostAccessDenial = hostAccessDenialError(response.status, body)
      if (hostAccessDenial) throw hostAccessDenial
      throw new ApiError(
        `List sessions failed (${response.status}): ${boundedErrorExcerpt(body)}`,
        response.status,
        body
      )
    }
    return parseSessionsListResult(await response.json())
  }

  async loadSessionMessages(
    rpcToken: string,
    hostRef: string,
    agent: string,
    chatId: string,
    query: SessionMessagesQuery = {}
  ): Promise<SessionMessagesResult> {
    assertSafeRouteSegment('hostRef', hostRef)
    assertSafeRouteSegment('agent', agent, { maxLength: 200, allowColon: false })
    assertSafeRouteSegment('chatId', chatId)
    const requestUrl = new URL(
      this.url(
        `/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/sessions/${encodeURIComponent(agent)}/${encodeURIComponent(chatId)}/messages`
      )
    )
    if (query.limit !== undefined) requestUrl.searchParams.set('limit', String(query.limit))
    if (query.beforeTurn !== undefined) {
      requestUrl.searchParams.set('beforeTurn', String(query.beforeTurn))
    }
    if (query.afterTurn !== undefined) {
      requestUrl.searchParams.set('afterTurn', String(query.afterTurn))
    }
    const response = await fetch(requestUrl, {
      headers: { authorization: `Bearer ${rpcToken}` },
      signal: withTimeout(),
    })
    if (response.status === 404) {
      // Preserve the status for the renderer. A transcript 404 is ambiguous
      // during Host wake and never confirms that local data may be deleted.
      throw new ApiError(`Session not found (404)`, 404, '')
    }
    if (!response.ok) {
      const body = await response.text()
      const hostAccessDenial = hostAccessDenialError(response.status, body)
      if (hostAccessDenial) throw hostAccessDenial
      throw new ApiError(
        `Load session messages failed (${response.status}): ${boundedErrorExcerpt(body)}`,
        response.status,
        body
      )
    }
    // F5: cast to the full wire shape — the server returns `state`/`activeTaskId`/
    // `pendingApproval` + per-turn `tool_steps`, and the renderer's recovery path
    // reads them. The previous cast dropped them, silently weakening the contract.
    return parseSessionMessagesResult(await response.json(), agent, chatId)
  }

  /**
   * On-demand snapshot of the active conversation's context-window composition.
   * Keyed by `(agent, chatId)` like {@link loadSessionMessages} — the server
   * derives the owning `userSub` from the verified caller token, never from the
   * path. Returns `{ breakdown: null }` when the session has no snapshot yet, and
   * also when the session is unknown to this user (the server replies with the
   * same anti-enumeration 404 in both cases) — the caller treats both as "no
   * breakdown to show" rather than an error.
   */
  async getContextBreakdown(
    rpcToken: string,
    hostRef: string,
    agent: string,
    chatId: string
  ): Promise<ContextBreakdownResult> {
    assertSafeRouteSegment('hostRef', hostRef)
    assertSafeRouteSegment('agent', agent, { maxLength: 200, allowColon: false })
    assertSafeRouteSegment('chatId', chatId)
    const response = await fetch(
      this.url(
        `/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/sessions/${encodeURIComponent(agent)}/${encodeURIComponent(chatId)}/context-breakdown`
      ),
      { headers: { authorization: `Bearer ${rpcToken}` }, signal: withTimeout() }
    )
    if (response.status === 404) {
      // Anti-enumeration 404 (no snapshot or session not owned by caller) — the
      // chip simply hides. NOT an error to surface to the user.
      return { breakdown: null }
    }
    if (!response.ok) {
      const body = await response.text()
      throw new ApiError(
        `Get context breakdown failed (${response.status}): ${boundedErrorExcerpt(body)}`,
        response.status,
        body
      )
    }
    return response.json() as Promise<ContextBreakdownResult>
  }

  /**
   * Lists the models selectable for a host's active provider, plus the current
   * per-session selection and degraded/blocked flags (R2 model selector). The
   * server derives the owning user from the verified token; `chatId` scopes the
   * `sessionModel`/`sessionModelBlocked` projection to that conversation.
   *
   * Returns `null` when the host predates the endpoint (404/501) so the caller
   * hides the selector rather than surfacing a noisy error (compat, R2.6). A
   * genuine failure (5xx, auth) still throws.
   */
  async getHostModels(
    rpcToken: string,
    hostRef: string,
    chatId: string
  ): Promise<HostModelsResult | null> {
    // The model LIST is host-level (operator allowlist); `chatId` only scopes the
    // per-session `sessionModel`/`sessionModelBlocked` projection. A brand-new chat
    // has no id yet, so omit the query entirely — the server returns the host list
    // with `sessionModel: null` (R2 new-chat composer selector).
    const trimmedChatId = String(chatId || '').trim()
    const modelsPath = trimmedChatId
      ? `/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/models?chatId=${encodeURIComponent(trimmedChatId)}`
      : `/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/models`
    const response = await fetch(this.url(modelsPath), {
      headers: { authorization: `Bearer ${rpcToken}` },
      signal: withTimeout(),
    })
    // 404 (host without the route) / 501 (route not implemented on this runtime)
    // → the feature is unavailable for this host; hide the selector silently.
    if (response.status === 404 || response.status === 501) {
      return null
    }
    if (!response.ok) {
      const body = await readErrorBody(response)
      throw new ApiError(
        `Get host models failed (${response.status}): ${boundedErrorExcerpt(body)}`,
        response.status,
        body
      )
    }
    return response.json() as Promise<HostModelsResult>
  }

  /**
   * Sets the per-session model for a host (R2.3). Applies to the next task only
   * (`effective: 'next-task'`). A model outside the operator allowlist is a 403
   * `{error:'model_not_allowed'}`, re-thrown with the {@link MODEL_NOT_ALLOWED}
   * token in the message so the renderer can show a targeted error and leave the
   * selection unchanged.
   */
  async setHostModel(
    rpcToken: string,
    hostRef: string,
    chatId: string,
    model: string,
    expectedRevision?: number
  ): Promise<SetHostModelResult> {
    const response = await fetch(
      this.url(`/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/model`),
      {
        method: 'POST',
        headers: {
          authorization: `Bearer ${rpcToken}`,
          'content-type': 'application/json',
        },
        // `expectedRevision` is omitted unless the host projected a revision
        // (issue #654 CAS), so an older host keeps receiving the exact body it
        // accepts today.
        body: JSON.stringify(
          expectedRevision === undefined ? { chatId, model } : { chatId, model, expectedRevision }
        ),
        signal: withTimeout(),
      }
    )
    if (!response.ok) {
      const body = await readErrorBody(response)
      // Disambiguate the two failure sources by the body's `error` code — NOT
      // by the 403 status alone. mcp-host rejects an off-allowlist model with
      // `{error:'model_not_allowed'}` (a policy decision — surface a targeted
      // message and leave the selection unchanged); rpc-proxy denies host access
      // with a plain 403 carrying a different code (a genuine access error).
      // mcp-host may answer 400 or 403 for the rejection, so key off the code,
      // not the status. Only the allowlist rejection embeds the token the
      // renderer detects.
      if (errorCodeFromBody(body) === MODEL_NOT_ALLOWED) {
        throw new ApiError(`Set host model rejected (${MODEL_NOT_ALLOWED})`, response.status, body)
      }
      // CAS precondition failed: another writer moved the session selection.
      // Terminal (never a wake/piggyback case) and surfaced by token so the
      // renderer can refetch instead of trusting the rejected optimistic state.
      if (errorCodeFromBody(body) === MODEL_SELECTION_CONFLICT) {
        throw new ApiError(
          `Set host model conflicted (${MODEL_SELECTION_CONFLICT})`,
          response.status,
          body
        )
      }
      throw new ApiError(
        `Set host model failed (${response.status}): ${boundedErrorExcerpt(body)}`,
        response.status,
        body
      )
    }
    return response.json() as Promise<SetHostModelResult>
  }

  /**
   * Spec 15 Fase B — renames a session (explicit user rename) via
   * `PATCH …/hosts/:hostRef/sessions/:agent/:chatId/name`. Keyed by
   * `(agent, chatId)` like {@link loadSessionMessages}; the server derives the
   * owning `userSub` from the verified token and validates/sanitizes the title.
   *
   * The status is preserved in the thrown {@link ApiError} message (the caller's
   * pending-rename queue keys off it: 404 = not materialized server-side yet →
   * keep pending; 400/403 = real rejection → rollback; 5xx/network → offline
   * retry). The raw title is NEVER put in the error message (user content, §5).
   */
  async renameSession(
    rpcToken: string,
    hostRef: string,
    agent: string,
    chatId: string,
    title: string
  ): Promise<{ title: string }> {
    assertSafeRouteSegment('hostRef', hostRef)
    assertSafeRouteSegment('agent', agent, { maxLength: 200, allowColon: false })
    assertSafeRouteSegment('chatId', chatId)
    const response = await fetch(
      this.url(
        `/api/v1/rpc/hosts/${encodeURIComponent(hostRef)}/sessions/${encodeURIComponent(agent)}/${encodeURIComponent(chatId)}/name`
      ),
      {
        method: 'PATCH',
        headers: { authorization: `Bearer ${rpcToken}`, 'content-type': 'application/json' },
        body: JSON.stringify({ title }),
        signal: withTimeout(),
      }
    )
    if (!response.ok) {
      // Body may echo the invalid title; read it for the ApiError payload but
      // keep the raw title out of the human-facing message.
      const body = await readErrorBody(response)
      const hostAccessDenial = hostAccessDenialError(response.status, body)
      if (hostAccessDenial) throw hostAccessDenial
      throw new ApiError(`Rename session failed (${response.status})`, response.status, body)
    }
    const parsed = (await response.json().catch(() => ({}))) as { title?: unknown }
    // Re-sanitize the server's echoed title on read (defense in depth, A14 rule).
    const sanitized = typeof parsed.title === 'string' ? sanitizeWireTitle(parsed.title) : undefined
    // Fall back to the requested title if the server echo is missing/illegible,
    // but sanitize that too so the same read-side normalization applies on every path.
    return { title: sanitized ?? sanitizeWireTitle(title) ?? title }
  }

  async getDesktopStatus(
    rpcAccessToken: string,
    hostRef: string
  ): Promise<{ hostRef: string; status: string; message?: string }> {
    return requestJson<{ hostRef: string; status: string; message?: string }>(
      'GET',
      this.url(`/api/v1/desktop/${encodeURIComponent(hostRef)}`),
      {
        token: rpcAccessToken,
      }
    )
  }

  /**
   * Exchanges JWT for a desktop session cookie.
   * Returns the raw Set-Cookie header value so the caller (main process)
   * can inject it into an Electron BrowserWindow's session.
   */
  async postDesktopSession(
    rpcAccessToken: string,
    hostRef: string
  ): Promise<{ ok: true; hostRef: string; setCookie: string[] }> {
    const res = await fetch(this.url(`/api/v1/desktop/${encodeURIComponent(hostRef)}/session`), {
      method: 'POST',
      headers: {
        authorization: `Bearer ${rpcAccessToken}`,
        'content-type': 'application/json',
      },
      body: '{}',
    })
    if (!res.ok) {
      const text = await readErrorBody(res)
      throw new ApiError(
        `Desktop session exchange failed: ${res.status} ${boundedErrorExcerpt(text) || res.statusText}`,
        res.status,
        text
      )
    }
    const body = (await res.json()) as { ok: true; hostRef: string }
    const cookies: string[] =
      typeof (res.headers as any).getSetCookie === 'function'
        ? (res.headers as any).getSetCookie()
        : [res.headers.get('set-cookie') || ''].filter(Boolean)
    if (!cookies.length) {
      throw new Error('Desktop session response missing Set-Cookie header')
    }
    return { ...body, setCookie: cookies }
  }
}