@danceiny/gotry 0.0.1-rc.16 → 0.0.1-rc.18

package/ts/src/booking-surface/server-v2.ts

@@ -0,0 +1,247 @@
+/** Request adapter for the unified Booking Copilot HTTP/SSE server. */
+
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import {
+  BOOKING_SURFACE_SCHEMA_V2_SHA256,
+  BOOKING_SURFACE_SCHEMA_VERSION_V2,
+  BOOKING_COPILOT_V2_ACCEPTED_TURN_KINDS,
+  type BookingCopilotV2IngressMode,
+  BOOKING_READ_ACTION_KINDS_V2,
+  BOOKING_SURFACE_ALLOWED_ACTIONS_V2,
+  type BookingCopilotTurnV2,
+  type BookingIngressBindingV2,
+  type BookingIngressPrincipalV2,
+  type IngressTurnV2,
+  type UserTurnV2,
+  type BookingSurfaceEventV2,
+  type BookingWorkspaceSnapshotV2,
+} from './contracts-v2.ts'
+import {
+  BookingCopilotTaskRuntimeV2,
+  type BookingPlannerSessionFactoryV2,
+  type BookingCopilotTaskStateV2,
+  type BookingIngressRequestBindingInputV2,
+} from './runtime-v2.ts'
+import { validateBookingSurfaceV2 } from './validation-v2.ts'
+import { normalizeBookingErrorCode, safeBookingErrorMessage } from './error-codes.ts'
+
+export interface BookingCopilotV2Adapter {
+  runtime: BookingCopilotTaskRuntimeV2
+  plannerFactory: BookingPlannerSessionFactoryV2
+  /** Optional BFF-owned identity binding. GoTry never accepts browser identity. */
+  ingressBinding?: BookingIngressBindingV2
+  /** Principal authenticated by the HotelByte BFF, never by browser input. */
+  principal?: BookingIngressPrincipalV2
+  /** Explicit process composition mode; omitted means infer from a complete pair. */
+  ingressMode?: BookingCopilotV2IngressMode
+}
+
+const sessionsByAdapter = new WeakMap<BookingCopilotV2Adapter, Map<string, ReturnType<BookingPlannerSessionFactoryV2>>>()
+const decisionFlightsByAdapter = new WeakMap<BookingCopilotV2Adapter, Map<string, Promise<BookingSurfaceEventV2[]>>>()
+function sessionsFor(adapter: BookingCopilotV2Adapter): Map<string, ReturnType<BookingPlannerSessionFactoryV2>> {
+  let sessions = sessionsByAdapter.get(adapter)
+  if (!sessions) { sessions = new Map(); sessionsByAdapter.set(adapter, sessions) }
+  return sessions
+}
+function decisionFlightsFor(adapter: BookingCopilotV2Adapter): Map<string, Promise<BookingSurfaceEventV2[]>> {
+  let flights = decisionFlightsByAdapter.get(adapter)
+  if (!flights) { flights = new Map(); decisionFlightsByAdapter.set(adapter, flights) }
+  return flights
+}
+async function runDecisionSingleFlight(adapter: BookingCopilotV2Adapter, key: string, work: () => Promise<BookingSurfaceEventV2[]>): Promise<BookingSurfaceEventV2[]> {
+  const flights = decisionFlightsFor(adapter)
+  const prior = flights.get(key)
+  if (prior) return prior
+  const current = work()
+  flights.set(key, current)
+  try { return await current } finally { if (flights.get(key) === current) flights.delete(key) }
+}
+
+function send(res: ServerResponse, status: number, body: unknown): void { res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' }); res.end(JSON.stringify(body)) }
+function readBody(req: IncomingMessage, max: number): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []; let size = 0; let tooLarge = false
+    req.on('data', (chunk: Buffer) => { size += chunk.length; if (size > max) tooLarge = true; else chunks.push(chunk) })
+    req.on('end', () => tooLarge ? reject(new Error('payload_too_large')) : resolve(Buffer.concat(chunks).toString('utf8')))
+    req.on('error', reject)
+  })
+}
+function write(res: ServerResponse, event: BookingSurfaceEventV2): void { res.write(`event: ${event.kind}\ndata: ${JSON.stringify(event)}\n\n`) }
+export { normalizeBookingErrorCode as bookingPlannerErrorCode, safeBookingErrorMessage as bookingPlannerErrorMessage } from './error-codes.ts'
+
+function sameCapabilities(a: readonly string[], b: readonly string[]): boolean {
+  return a.length === b.length && [...a].sort().every((kind, index) => kind === [...b].sort()[index])
+}
+function exactKeys(value: Record<string, unknown>, allowed: readonly string[]): boolean {
+  return Object.keys(value).length === allowed.length && Object.keys(value).every((key) => allowed.includes(key))
+}
+
+const SURFACE_ACTION_MATRIX: Record<BookingWorkspaceSnapshotV2['surface'], readonly string[]> = BOOKING_SURFACE_ALLOWED_ACTIONS_V2
+
+function validSurfaceActions(surface: unknown, allowed: unknown): allowed is BookingWorkspaceSnapshotV2['capabilities']['allowedActions'] {
+  if (typeof surface !== 'string' || !Object.prototype.hasOwnProperty.call(SURFACE_ACTION_MATRIX, surface)) return false
+  if (!Array.isArray(allowed) || allowed.length < 1 || new Set(allowed).size !== allowed.length) return false
+  const matrix = SURFACE_ACTION_MATRIX[surface as BookingWorkspaceSnapshotV2['surface']]
+  return allowed.every((action) => typeof action === 'string'
+    && matrix.includes(action)
+    && (BOOKING_READ_ACTION_KINDS_V2 as readonly string[]).includes(action))
+}
+
+function validBoundWorkspaceAuthority(workspace: BookingWorkspaceSnapshotV2): boolean {
+  return workspace.capabilities.surface === workspace.surface
+    && validSurfaceActions(workspace.surface, workspace.capabilities.allowedActions)
+}
+
+function validIngressBinding(binding: unknown, ingress: IngressTurnV2): binding is {
+  taskId: string
+  turnId: string
+  contextRef: string
+  surface: BookingWorkspaceSnapshotV2['surface']
+  allowedActions: BookingWorkspaceSnapshotV2['capabilities']['allowedActions']
+} {
+  if (!binding || typeof binding !== 'object' || Array.isArray(binding)) return false
+  const candidate = binding as Record<string, unknown>
+  if (!exactKeys(candidate, ['taskId', 'turnId', 'contextRef', 'surface', 'allowedActions'])) return false
+  if (typeof candidate.taskId !== 'string' || typeof candidate.turnId !== 'string' || typeof candidate.contextRef !== 'string') return false
+  if (typeof candidate.surface !== 'string' || candidate.surface !== ingress.surfaceHint || !Object.prototype.hasOwnProperty.call(SURFACE_ACTION_MATRIX, candidate.surface)) return false
+  return validSurfaceActions(candidate.surface, candidate.allowedActions)
+}
+
+function fallbackErrorEvent(task: BookingCopilotTaskStateV2, code: string): BookingSurfaceEventV2 {
+  return {
+    schemaVersion: BOOKING_SURFACE_SCHEMA_VERSION_V2,
+    eventId: `error-${task.taskId}-${task.lastSequence + 1}`,
+    taskId: task.taskId,
+    contextRef: task.contextRef,
+    sequence: task.lastSequence + 1,
+    emittedAt: new Date().toISOString(),
+    kind: 'error',
+    error: { code: normalizeBookingErrorCode(code), message: safeBookingErrorMessage(normalizeBookingErrorCode(code)), retryable: false },
+  }
+}
+
+function writeTypedError(res: ServerResponse, adapter: BookingCopilotV2Adapter, task: BookingCopilotTaskStateV2, error: unknown, requestKey?: string, includeSubmitted = false): void {
+  const code = normalizeBookingErrorCode(error)
+  try {
+    const decision = { kind: 'error' as const, error: { code, message: safeBookingErrorMessage(code), retryable: false } }
+    if (requestKey) {
+      const events = adapter.runtime.applyDecisionBatch(task.taskId, requestKey, [decision], includeSubmitted)
+      for (const event of events) write(res, event)
+      return
+    }
+    write(res, adapter.runtime.emitEvent(task.taskId, decision))
+  } catch {
+    // The stream is already committed. Emit a schema-valid, non-durable
+    // typed envelope instead of silently returning an empty HTTP 200 stream.
+    write(res, fallbackErrorEvent(task, code))
+  }
+}
+
+/** Handles one already-authenticated v2 request inside server.ts's sole listener. */
+export async function handleBookingCopilotV2Request(req: IncomingMessage, res: ServerResponse, adapter: BookingCopilotV2Adapter, maxBodyBytes: number): Promise<void> {
+  let turn: Exclude<BookingCopilotTurnV2, IngressTurnV2>
+  let browserRequestKey: string | undefined
+  let requestBinding: BookingIngressRequestBindingInputV2 | undefined
+  try {
+    const parsed = JSON.parse(await readBody(req, maxBodyBytes)) as unknown
+    const valid = validateBookingSurfaceV2(parsed)
+    if (!valid.ok) { send(res, 400, { error: { code: 'invalid_booking_surface_turn', details: valid.errors } }); return }
+    if ((parsed as BookingCopilotTurnV2).kind === 'user.turn.ingress') {
+      const ingress = parsed as IngressTurnV2
+      browserRequestKey = ingress.requestKey
+      if (adapter.ingressMode !== 'bff-ingress-binding' || !adapter.ingressBinding || !adapter.principal) {
+        send(res, 503, { error: { code: 'trusted_ingress_binding_required', mode: adapter.ingressMode ?? 'bff-bound-turn-only', acceptedTurnKinds: [...BOOKING_COPILOT_V2_ACCEPTED_TURN_KINDS] } })
+        return
+      }
+      const binding = await adapter.ingressBinding.bind(ingress, adapter.principal)
+      if (!validIngressBinding(binding, ingress)) { send(res, 502, { error: { code: 'invalid_ingress_binding' } }); return }
+      const boundWorkspace = {
+        ...ingress.workspace,
+        contextRef: binding.contextRef,
+        surface: binding.surface,
+        capabilities: { surface: binding.surface, allowedActions: [...binding.allowedActions] },
+      } as BookingWorkspaceSnapshotV2
+      turn = { schemaVersion: 'booking.surface.v2', kind: 'user.turn', taskId: binding.taskId, turnId: binding.turnId, workspace: boundWorkspace, request: ingress.request }
+      requestBinding = { requestKey: ingress.requestKey, principal: adapter.principal, ...(ingress.taskHandle ? { taskHandle: ingress.taskHandle } : {}) }
+      const boundValid = validateBookingSurfaceV2(turn)
+      if (!boundValid.ok) { send(res, 502, { error: { code: 'invalid_ingress_binding', details: boundValid.errors } }); return }
+    } else {
+      turn = parsed as Exclude<BookingCopilotTurnV2, IngressTurnV2>
+      if (!validBoundWorkspaceAuthority(turn.workspace)) {
+        send(res, 403, { error: { code: 'invalid_bound_turn_authority' } })
+        return
+      }
+    }
+  } catch (error) { const code = normalizeBookingErrorCode(error); send(res, code === 'PAYLOAD_TOO_LARGE' ? 413 : 400, { error: { code } }); return }
+
+  let task: BookingCopilotTaskStateV2; let fresh = false; let replayKey: string | undefined; let replayEvents: BookingSurfaceEventV2[] | null = null; let activeDecisionKey: string | undefined
+  try {
+    fresh = turn.kind === 'action.receipt.continuation' ? false : !turn.taskId || adapter.runtime.resumeTask(turn.taskId) === null
+    if (turn.kind === 'action.receipt.continuation') {
+      replayKey = `receipt:${turn.receipt.actionId}:${adapter.runtime.receiptDigest(turn.receipt)}`
+      task = adapter.runtime.continueWithReceipt(turn)
+      if (task.awaitingApproval) {
+        replayKey = adapter.runtime.approvalPresentationRequestKey(turn.taskId)
+      }
+      replayEvents = adapter.runtime.readDecisionBatch(turn.taskId, replayKey)
+      if (!replayEvents && task.phase === 'terminal') replayEvents = adapter.runtime.terminalDecisionBatch(turn.taskId, replayKey)
+    } else {
+      const existing = turn.taskId ? adapter.runtime.resumeTask(turn.taskId) : null
+      if (requestBinding && turn.kind === 'user.turn') adapter.runtime.assertRequestBinding(browserRequestKey!, turn, requestBinding)
+      const requestReplayKey = existing && browserRequestKey ? `ingress:${existing.taskId}:${browserRequestKey}` : undefined
+      const directReplayKey = existing && turn.kind === 'user.turn' && turn.turnId ? `turn:${existing.taskId}:${turn.turnId}` : undefined
+      const stableReplayKey = requestReplayKey ?? directReplayKey
+      const stableReplay = stableReplayKey ? adapter.runtime.readDecisionBatch(existing!.taskId, stableReplayKey) : null
+      if (stableReplay) {
+        if (existing && turn.kind === 'user.turn' && directReplayKey) adapter.runtime.assertTurnBinding(existing.taskId, turn)
+        task = existing!
+        replayKey = stableReplayKey
+        replayEvents = stableReplay
+      } else if (existing?.phase === 'terminal' || existing?.phase === 'error') {
+        throw new Error('task_terminal')
+      } else if (existing?.phase === 'waiting_receipt') {
+        const workspace = turn.workspace as BookingWorkspaceSnapshotV2
+        if (workspace.contextRef !== existing.contextRef || workspace.surface !== existing.surface || workspace.revision !== existing.revision || workspace.capabilities.surface !== existing.surface || !sameCapabilities(workspace.capabilities.allowedActions, existing.allowedActions)) throw new Error('task_conflict:workspace_mismatch')
+        // A waiting task can only be replayed with the caller's stable turn
+        // identity. Without it, an identical sentence is not distinguishable
+        // from a new user turn and must not receive an old operation batch.
+        if (!turn.turnId || existing.lastTurnId !== turn.turnId) throw new Error('receipt_required')
+        replayKey = browserRequestKey ? `ingress:${existing.taskId}:${browserRequestKey}` : `turn:${existing.taskId}:${existing.lastTurnId ?? existing.userTurnCount}`
+        replayEvents = adapter.runtime.readDecisionBatch(existing.taskId, replayKey)
+        if (!replayEvents) throw new Error('receipt_required')
+        task = existing
+      } else {
+        task = adapter.runtime.startTask(turn, requestBinding)
+        if (turn.kind === 'user.turn' && turn.taskId) {
+          replayKey = browserRequestKey ? `ingress:${task.taskId}:${browserRequestKey}` : `turn:${task.taskId}:${turn.turnId ?? task.userTurnCount}`
+          replayEvents = adapter.runtime.readDecisionBatch(task.taskId, replayKey)
+        }
+      }
+    }
+  } catch (error) { send(res, 409, { error: { code: normalizeBookingErrorCode(error) } }); return }
+
+  res.writeHead(200, { 'content-type': 'text/event-stream; charset=utf-8', 'cache-control': 'no-cache, no-transform', connection: 'keep-alive', 'x-content-type-options': 'nosniff', 'x-booking-surface-version': BOOKING_SURFACE_SCHEMA_VERSION_V2, 'x-booking-surface-schema-sha256': BOOKING_SURFACE_SCHEMA_V2_SHA256 })
+  try {
+    if (replayEvents) {
+      for (const event of replayEvents) write(res, event)
+    } else {
+      const requestKey = replayKey ?? `turn:${task.taskId}:${task.userTurnCount}`
+      activeDecisionKey = requestKey
+      const flightKey = JSON.stringify([task.taskId, requestKey])
+      const decisionEvents = await runDecisionSingleFlight(adapter, flightKey, async () => {
+        if (turn.kind === 'action.receipt.continuation' && task.awaitingApproval) {
+          return adapter.runtime.applyDecisionBatch(task.taskId, requestKey, [adapter.runtime.approvalQuestion(task.taskId)], false)
+        }
+        const sessions = sessionsFor(adapter)
+        const session = sessions.get(task.taskId) ?? adapter.plannerFactory(task)
+        sessions.set(task.taskId, session)
+        const decisions = await session.next({ turn, task: adapter.runtime.resumeTask(task.taskId) ?? task })
+        const plannerDecisions = decisions.length ? decisions : [{ kind: 'error' as const, error: { code: 'PLANNER_NO_DECISION', message: 'Planner returned no typed decision.', retryable: false } }]
+        return adapter.runtime.applyDecisionBatch(task.taskId, requestKey, plannerDecisions, fresh)
+      })
+      for (const event of decisionEvents) write(res, event)
+    }
+  } catch (error) {
+    writeTypedError(res, adapter, task, error, activeDecisionKey, fresh)
+  } finally { res.end() }
+}

package/ts/src/booking-surface/server.ts

@@ -0,0 +1,324 @@
+/**
+ * BFF-only HTTP/SSE seam for the embedded Booking Copilot.
+ *
+ * The browser never calls this server directly. A same-origin HotelByte BFF
+ * authenticates the actor, mints contextRef and sends a strict planner turn
+ * with a deployment-level Bearer key. No portal token field exists here.
+ */
+
+import { timingSafeEqual } from 'node:crypto'
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'
+import {
+  BOOKING_SURFACE_SCHEMA_SHA256,
+  BOOKING_SURFACE_SCHEMA_SHA256_HEADER,
+  BOOKING_SURFACE_SCHEMA_VERSION,
+  BOOKING_SURFACE_VERSION_HEADER,
+  type BookingCopilotTurnV1,
+  type BookingReadActionV1,
+  type BookingSurfaceEventV1,
+} from './contracts.ts'
+import {
+  BookingCopilotTaskRuntime,
+  type BookingCopilotTaskStateV1,
+  type BookingSurfaceEventDraftV1,
+} from './runtime.ts'
+import { validateBookingCopilotTurnV1 } from './validation.ts'
+import { handleBookingCopilotV2Request, type BookingCopilotV2Adapter } from './server-v2.ts'
+import { normalizeBookingErrorCode, safeBookingErrorMessage } from './error-codes.ts'
+import {
+  BOOKING_COPILOT_V2_ACCEPTED_TURN_KINDS,
+  BOOKING_COPILOT_V2_INGRESS_TURN_KIND,
+  BOOKING_COPILOT_V2_INGRESS_MODES,
+  BOOKING_SURFACE_SCHEMA_V2_SHA256,
+  BOOKING_SURFACE_SCHEMA_VERSION_V2,
+  type BookingCopilotV2IngressMode,
+} from './contracts-v2.ts'
+
+export type BookingPlannerDecisionV1 =
+  | { kind: 'operation'; action: BookingReadActionV1 }
+  | BookingSurfaceEventDraftV1
+
+export interface BookingPlannerSessionV1 {
+  next(input: {
+    turn: BookingCopilotTurnV1
+    task: BookingCopilotTaskStateV1
+  }): Promise<readonly BookingPlannerDecisionV1[]>
+}
+
+/** Called once per task in a server process, including once after recovery. */
+export type BookingPlannerSessionFactoryV1 = (
+  initialTask: BookingCopilotTaskStateV1,
+) => BookingPlannerSessionV1
+
+export interface BookingCopilotServerOptionsV1 {
+  /** Deployment credential shared only with the HotelByte BFF. */
+  apiKey: string
+  runtime?: BookingCopilotTaskRuntime
+  plannerFactory?: BookingPlannerSessionFactoryV1
+  host?: string
+  port?: number
+  maxBodyBytes?: number
+  /** GoTry source commit loaded from the root-owned release artifact. */
+  artifactId?: string
+  /** Optional v2 adapter dispatched by the same listener after version/hash selection. */
+  v2?: BookingCopilotV2Adapter
+}
+
+export interface BookingCopilotServerHandleV1 {
+  server: Server
+  port: number
+  close(): Promise<void>
+}
+
+interface BookingCopilotRuntimeIdentityV1 {
+  nodeVersion: string
+  nodeModulesAbi: string
+  releaseTuple: string
+  glibcVersion: string
+}
+
+function runtimeIdentity(): BookingCopilotRuntimeIdentityV1 {
+  const report = process.report?.getReport?.() as { header?: { glibcVersionRuntime?: string } } | undefined
+  const header = report?.header
+  const glibcVersion = header?.glibcVersionRuntime ?? ''
+  return {
+    nodeVersion: process.version,
+    nodeModulesAbi: process.versions.modules ?? '',
+    releaseTuple: `${process.platform}-${process.arch}-${glibcVersion ? 'glibc' : 'unknown'}`,
+    glibcVersion,
+  }
+}
+
+function safeSecretEqual(actual: string, expected: string): boolean {
+  const actualBytes = Buffer.from(actual)
+  const expectedBytes = Buffer.from(expected)
+  return actualBytes.length === expectedBytes.length && timingSafeEqual(actualBytes, expectedBytes)
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown): void {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8' })
+  res.end(JSON.stringify(body))
+}
+
+function readBody(req: IncomingMessage, maxBodyBytes: number): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = []
+    let size = 0
+    let exceeded = false
+    req.on('data', (chunk: Buffer) => {
+      size += chunk.length
+      if (size > maxBodyBytes) {
+        exceeded = true
+        return
+      }
+      chunks.push(chunk)
+    })
+    req.on('end', () => exceeded ? reject(new Error('payload_too_large')) : resolve(Buffer.concat(chunks).toString('utf8')))
+    req.on('error', reject)
+  })
+}
+
+function writeSse(res: ServerResponse, event: BookingSurfaceEventV1): void {
+  res.write(`event: ${event.kind}\ndata: ${JSON.stringify(event)}\n\n`)
+}
+
+export function startBookingCopilotServer(options: BookingCopilotServerOptionsV1): Promise<BookingCopilotServerHandleV1> {
+  if (!options.apiKey) return Promise.reject(new Error('booking_copilot_api_key_required'))
+  if (options.artifactId !== undefined && !/^[0-9a-f]{40}$/.test(options.artifactId)) {
+    return Promise.reject(new Error('booking_copilot_artifact_id_invalid'))
+  }
+  const hasIngressBinding = Boolean(options.v2?.ingressBinding)
+  const hasPrincipal = Boolean(options.v2?.principal)
+  if (options.v2 && hasIngressBinding !== hasPrincipal) {
+    return Promise.reject(new Error('booking_copilot_v2_ingress_binding_pair_required'))
+  }
+  if (options.v2 && hasIngressBinding && (typeof options.v2.ingressBinding?.bind !== 'function'
+    || typeof options.v2.principal?.subject !== 'string' || options.v2.principal.subject.length === 0 || options.v2.principal.subject.length > 256
+    || typeof options.v2.principal?.scope !== 'string' || options.v2.principal.scope.length === 0 || options.v2.principal.scope.length > 256)) {
+    return Promise.reject(new Error('booking_copilot_v2_ingress_binding_invalid'))
+  }
+  const ingressMode: BookingCopilotV2IngressMode | undefined = options.v2
+    ? options.v2.ingressMode ?? (hasIngressBinding ? 'bff-ingress-binding' : 'bff-bound-turn-only')
+    : undefined
+  if (options.v2 && !BOOKING_COPILOT_V2_INGRESS_MODES.includes(ingressMode!)) {
+    return Promise.reject(new Error('booking_copilot_v2_ingress_mode_invalid'))
+  }
+  if (options.v2 && ingressMode === 'bff-ingress-binding' && !hasIngressBinding) {
+    return Promise.reject(new Error('booking_copilot_v2_ingress_binding_required'))
+  }
+  if (options.v2 && ingressMode === 'bff-bound-turn-only' && hasIngressBinding) {
+    return Promise.reject(new Error('booking_copilot_v2_ingress_mode_conflict'))
+  }
+  const v2 = options.v2 ? { ...options.v2, ingressMode } : undefined
+  const v2Only = Boolean(v2 && !options.runtime && !options.plannerFactory)
+  const sessions = new Map<string, BookingPlannerSessionV1>()
+  const maxBodyBytes = options.maxBodyBytes ?? 1_000_000
+  const runningIdentity = runtimeIdentity()
+
+  const server = createServer(async (req, res) => {
+    const isProbe = req.method === 'GET' && (req.url === '/healthz' || req.url === '/status')
+    if (!isProbe && (req.method !== 'POST' || req.url !== '/a2a/booking-copilot/turn')) {
+      sendJson(res, 404, { error: { code: 'not_found' } })
+      return
+    }
+    const auth = String(req.headers.authorization ?? '')
+    if (!safeSecretEqual(auth, `Bearer ${options.apiKey}`)) {
+      sendJson(res, 401, { error: { code: 'unauthorized' } })
+      return
+    }
+    if (isProbe) {
+      const activeV2Only = Boolean(v2 && !options.runtime && !options.plannerFactory)
+      res.setHeader(BOOKING_SURFACE_VERSION_HEADER, activeV2Only ? BOOKING_SURFACE_SCHEMA_VERSION_V2 : BOOKING_SURFACE_SCHEMA_VERSION)
+      res.setHeader(BOOKING_SURFACE_SCHEMA_SHA256_HEADER, activeV2Only ? BOOKING_SURFACE_SCHEMA_V2_SHA256 : BOOKING_SURFACE_SCHEMA_SHA256)
+      if (options.artifactId) res.setHeader('X-GoTry-Artifact-ID', options.artifactId)
+      res.setHeader('X-GoTry-Node-Version', runningIdentity.nodeVersion)
+      res.setHeader('X-GoTry-Node-Modules-ABI', runningIdentity.nodeModulesAbi)
+      res.setHeader('X-GoTry-Release-Tuple', runningIdentity.releaseTuple)
+      if (runningIdentity.glibcVersion) res.setHeader('X-GoTry-Glibc-Version', runningIdentity.glibcVersion)
+      const healthBody: Record<string, unknown> = {
+        schemaVersion: activeV2Only ? BOOKING_SURFACE_SCHEMA_VERSION_V2 : BOOKING_SURFACE_SCHEMA_VERSION,
+        schemaSha256: activeV2Only ? BOOKING_SURFACE_SCHEMA_V2_SHA256 : BOOKING_SURFACE_SCHEMA_SHA256,
+        status: 'ready',
+      }
+      if (activeV2Only || v2) healthBody.supportedSchemaVersions = activeV2Only ? [BOOKING_SURFACE_SCHEMA_VERSION_V2] : [BOOKING_SURFACE_SCHEMA_VERSION, BOOKING_SURFACE_SCHEMA_VERSION_V2]
+      if (v2) {
+        const acceptedTurnKinds = v2.ingressMode === 'bff-ingress-binding'
+          ? [...BOOKING_COPILOT_V2_ACCEPTED_TURN_KINDS, BOOKING_COPILOT_V2_INGRESS_TURN_KIND]
+          : [...BOOKING_COPILOT_V2_ACCEPTED_TURN_KINDS]
+        healthBody.ingressMode = v2.ingressMode
+        healthBody.acceptedTurnKinds = acceptedTurnKinds
+        res.setHeader('X-GoTry-Ingress-Mode', v2.ingressMode!)
+        res.setHeader('X-GoTry-Accepted-Turn-Kinds', acceptedTurnKinds.join(','))
+      }
+      sendJson(res, 200, healthBody)
+      return
+    }
+    const schemaVersion = String(req.headers[BOOKING_SURFACE_VERSION_HEADER] ?? '')
+    const schemaHash = String(req.headers[BOOKING_SURFACE_SCHEMA_SHA256_HEADER] ?? '')
+    if (schemaVersion === BOOKING_SURFACE_SCHEMA_VERSION_V2) {
+      if (!v2 || schemaHash !== BOOKING_SURFACE_SCHEMA_V2_SHA256) {
+        sendJson(res, 409, { error: { code: 'booking_surface_schema_mismatch', expectedVersion: BOOKING_SURFACE_SCHEMA_VERSION_V2, expectedSchemaSha256: BOOKING_SURFACE_SCHEMA_V2_SHA256 } })
+        return
+      }
+      await handleBookingCopilotV2Request(req, res, v2, maxBodyBytes)
+      return
+    }
+    if (schemaVersion !== BOOKING_SURFACE_SCHEMA_VERSION || schemaHash !== BOOKING_SURFACE_SCHEMA_SHA256) {
+      sendJson(res, 409, {
+        error: {
+          code: 'booking_surface_schema_mismatch',
+          expectedVersion: BOOKING_SURFACE_SCHEMA_VERSION,
+          expectedSchemaSha256: BOOKING_SURFACE_SCHEMA_SHA256,
+        },
+      })
+      return
+    }
+    if (!options.runtime || !options.plannerFactory) {
+      sendJson(res, 503, { error: { code: 'booking_surface_v1_not_configured' } })
+      return
+    }
+
+    let turn: BookingCopilotTurnV1
+    try {
+      const raw = await readBody(req, maxBodyBytes)
+      const parsed = JSON.parse(raw) as unknown
+      const validation = validateBookingCopilotTurnV1(parsed)
+      if (!validation.ok) {
+        sendJson(res, 400, { error: { code: 'invalid_booking_surface_turn', details: validation.errors } })
+        return
+      }
+      turn = parsed as BookingCopilotTurnV1
+    } catch (error) {
+      const code = normalizeBookingErrorCode(error)
+      sendJson(res, code === 'PAYLOAD_TOO_LARGE' ? 413 : 400, { error: { code } })
+      return
+    }
+
+    let task: BookingCopilotTaskStateV1
+    let isNewTask = false
+    try {
+      const taskId = turn.taskId
+      if (v2 && taskId && v2.runtime.resumeTask(taskId)) throw new Error('task_conflict:protocol_version')
+      if (turn.kind === 'user.turn') {
+        const suppliedTaskId = turn.taskId
+        isNewTask = !suppliedTaskId || options.runtime.resumeTask(suppliedTaskId) === null
+        task = options.runtime.startTask(turn)
+      } else {
+        task = options.runtime.continueWithReceipt(turn)
+      }
+    } catch (error) {
+      sendJson(res, 409, { error: { code: normalizeBookingErrorCode(error) } })
+      return
+    }
+
+    res.writeHead(200, {
+      'content-type': 'text/event-stream; charset=utf-8',
+      'cache-control': 'no-cache, no-transform',
+      connection: 'keep-alive',
+      'x-content-type-options': 'nosniff',
+      [BOOKING_SURFACE_VERSION_HEADER]: BOOKING_SURFACE_SCHEMA_VERSION,
+      [BOOKING_SURFACE_SCHEMA_SHA256_HEADER]: BOOKING_SURFACE_SCHEMA_SHA256,
+    })
+
+    try {
+      if (isNewTask) writeSse(res, options.runtime.emitEvent(task.taskId, { kind: 'status', status: 'submitted' }))
+      writeSse(res, options.runtime.emitEvent(task.taskId, { kind: 'status', status: 'working' }))
+      task = options.runtime.resumeTask(task.taskId) ?? task
+      let session = sessions.get(task.taskId)
+      if (!session) {
+        session = options.plannerFactory(task)
+        sessions.set(task.taskId, session)
+      }
+      const decisions = await session.next({ turn, task })
+      if (decisions.length === 0) {
+        writeSse(res, options.runtime.emitEvent(task.taskId, {
+          kind: 'error',
+          error: { code: 'PLANNER_NO_DECISION', message: 'Planner returned no typed decision.', retryable: false },
+        }))
+      } else {
+        for (const decision of decisions) {
+          const event = decision.kind === 'operation'
+            ? options.runtime.issueOperation(task.taskId, decision.action)
+            : options.runtime.emitEvent(task.taskId, decision)
+          writeSse(res, event)
+        }
+      }
+    } catch (error) {
+      try {
+        writeSse(res, options.runtime.emitEvent(task.taskId, {
+          kind: 'error',
+          error: { code: normalizeBookingErrorCode(error), message: safeBookingErrorMessage(normalizeBookingErrorCode(error)), retryable: false },
+        }))
+      } catch {
+        // Headers are already committed. Preserve a non-empty typed SSE error
+        // even when the durable event append is unavailable.
+        writeSse(res, {
+          schemaVersion: 'booking.surface.v1',
+          eventId: `error-${task.taskId}-${task.lastSequence + 1}`,
+          taskId: task.taskId,
+          contextRef: task.contextRef,
+          sequence: task.lastSequence + 1,
+          emittedAt: new Date().toISOString(),
+          kind: 'error',
+          error: { code: normalizeBookingErrorCode(error), message: safeBookingErrorMessage(normalizeBookingErrorCode(error)), retryable: false },
+        })
+      }
+    } finally {
+      res.end()
+    }
+  })
+
+  return new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(options.port ?? 0, options.host ?? '127.0.0.1', () => {
+      server.off('error', reject)
+      const address = server.address()
+      const port = typeof address === 'object' && address ? address.port : (options.port ?? 0)
+      resolve({
+        server,
+        port,
+        close: () => new Promise<void>((done, fail) => server.close((error) => error ? fail(error) : done())),
+      })
+    })
+  })
+}