@danceiny/gotry 0.0.1-rc.17 → 0.0.1-rc.19

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

@@ -1,247 +0,0 @@
-/** 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/validation-v2.ts

@@ -1,205 +0,0 @@
-import { readFileSync } from 'node:fs'
-import { Ajv2020, type ValidateFunction } from 'ajv/dist/2020.js'
-import { BOOKING_READ_ACTION_KINDS_V2, BOOKING_V2_BLOCKER_CODES, BOOKING_V2_GAP_CODES } from './contracts-v2.ts'
-
-const schema = JSON.parse(readFileSync(new URL('../../../schemas/booking.surface.v2.schema.json', import.meta.url), 'utf8')) as Record<string, unknown>
-const v1 = JSON.parse(readFileSync(new URL('../../../schemas/booking.surface.v1.schema.json', import.meta.url), 'utf8')) as Record<string, unknown>
-const ajv = new Ajv2020({ allErrors: true, strict: true })
-ajv.addSchema(v1)
-ajv.addSchema(schema)
-const validate: ValidateFunction = ajv.compile(schema)
-const validateActionCanonical = ajv.compile({ $ref: `${schema.$id}#/$defs/Action` })
-const validateBlockerCanonical = ajv.compile({ $ref: `${schema.$id}#/$defs/Blocker` })
-const validateApprovalCanonical = ajv.compile({ $ref: `${schema.$id}#/$defs/Approval` })
-const validateEventCanonical = ajv.compile({ $ref: `${schema.$id}#/$defs/Event` })
-const kinds = new Set<string>(BOOKING_READ_ACTION_KINDS_V2)
-const codes = new Set<string>(BOOKING_V2_BLOCKER_CODES)
-const gapCodes = new Set<string>(BOOKING_V2_GAP_CODES)
-const safeOpaque = (value: unknown): value is string => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]*$/.test(value)
-const safeRequestKey = (value: unknown): value is string => typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{7,127}$/.test(value) && !secret.test(value)
-const secret = /(?:Bearer\s+\S|\bsk-(?!ill(?:s)?\b)[A-Za-z0-9_-]{12,}|\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)/i
-// `.example` is reserved for documentation, so these identifiers cannot be a
-// real mailbox. Do not allowlist lookalikes on routable domains.
-const technicalEmail = /^(?:schema|version)@[a-z0-9-]+\.example$/i
-const currencyAmount = /\b(?:[A-Z]{3}\s*\d+(?:\.\d+)?|\d+(?:\.\d+)?\s*[A-Z]{3})\b/
-const rfc3339DateTime = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,9}))?(Z|([+-])(\d{2}):(\d{2}))$/
-
-export function isBookingDateTimeV2(value: unknown): value is string {
-  if (typeof value !== 'string') return false
-  const match = rfc3339DateTime.exec(value)
-  if (!match) return false
-  const [, yearText, monthText, dayText, hourText, minuteText, secondText] = match
-  const year = Number(yearText)
-  const month = Number(monthText)
-  const day = Number(dayText)
-  const hour = Number(hourText)
-  const minute = Number(minuteText)
-  const second = Number(secondText)
-  const offsetHour = match[9] === undefined ? 0 : Number(match[9])
-  const offsetMinute = match[10] === undefined ? 0 : Number(match[10])
-  if (month < 1 || month > 12 || hour > 23 || minute > 59 || second > 59 || offsetHour > 23 || offsetMinute > 59) return false
-  const daysInMonth = new Date(Date.UTC(year, month, 0)).getUTCDate()
-  if (day < 1 || day > daysInMonth) return false
-  return !Number.isNaN(Date.parse(value))
-}
-
-function normalizedWords(value: string): string {
-  return value.normalize('NFKC').replace(/[^\p{L}\p{N}.]+/gu, ' ').trim()
-}
-
-function hasSupplierCost(value: string): boolean {
-  const normalized = normalizedWords(value)
-  const lower = normalized.toLowerCase()
-  return (
-    /\b(?:supplier|vendor|internal)\b/.test(lower) &&
-    /\b(?:cost|rate|price)\b/.test(lower) &&
-    currencyAmount.test(normalized.toUpperCase())
-  )
-}
-
-function hasInternationalPhone(value: string): boolean {
-  const normalized = value.normalize('NFKC')
-  for (const plusIndex of normalized.split('').flatMap((char, index) => char === '+' ? [index] : [])) {
-    let digits = ''
-    for (const char of normalized.slice(plusIndex + 1, plusIndex + 48)) {
-      if (/\d/u.test(char)) digits += char
-      else if (/\p{L}|@/u.test(char)) break
-      if (digits.length > 15) break
-    }
-    if (/^[1-9]\d{7,14}$/.test(digits)) return true
-  }
-  return false
-}
-
-function hasPaymentCard(value: string): boolean {
-  const normalized = value.normalize('NFKC')
-  const candidates = normalized.match(/(?:\d[ -]?){12,18}\d/g) ?? []
-  const explicitlyLabeled = /\b(?:card|payment|visa|mastercard)\b/i.test(normalized)
-  return candidates.some((candidate) => (explicitlyLabeled || /[ -]/.test(candidate)) && luhn(candidate))
-}
-
-function hasSensitiveText(value: string, opts: { allowOpaqueNumericId?: boolean } = {}): boolean {
-  const normalized = value.normalize('NFKC')
-  if (normalized.includes('@') && !technicalEmail.test(normalized.trim())) return true
-  return secret.test(normalized) || hasInternationalPhone(normalized) || hasSupplierCost(normalized) || (!opts.allowOpaqueNumericId && hasPaymentCard(normalized))
-}
-function luhn(value: string): boolean { const digits = value.replaceAll(/\D/g, ''); if (digits.length < 13 || digits.length > 19) return false; let sum = 0; for (let i = digits.length - 1, parity = 0; i >= 0; i--, parity++) { let n = Number(digits[i]); if (parity % 2 === 1) { n *= 2; if (n > 9) n -= 9 } sum += n } return sum % 10 === 0 }
-const opaqueFieldNames = new Set([
-  'eventId', 'taskId', 'contextRef', 'actionId', 'hotelRef', 'offerRef', 'offerVersionRef', 'checkedOfferVersionRef', 'currentOfferVersionRef', 'verifiedOfferRef',
-  'orderRef', 'searchSessionRef', 'handoffRef', 'questionId', 'blockerId', 'approvalId',
-  'sourceActionId', 'targetActionId', 'sourceTurnId', 'turnId', 'requestKey', 'taskHandle',
-  'nonce', 'deliveryNonce', 'optionDigest', 'sourceReceiptDigest', 'valueDigest',
-])
-function isOpaqueFieldPath(path: string): boolean {
-  const clean = path.replace(/\[\]$/g, '')
-  const field = clean.split('.').at(-1)
-  return field ? opaqueFieldNames.has(field) || field.endsWith('Ref') || field.endsWith('Refs') : false
-}
-const scan = (v: unknown, path = '$'): boolean => typeof v === 'string'
-  ? hasSensitiveText(v, { allowOpaqueNumericId: isOpaqueFieldPath(path) })
-  : Array.isArray(v)
-    ? v.some((child) => scan(child, `${path}[]`))
-    : !!v && typeof v === 'object'
-      ? Object.entries(v).some(([k,x]) => /cost|price/i.test(k) ? /supplier|internal|wholesale/i.test(String(x)) : scan(x, `${path}.${k}`))
-      : false
-export function isSafeBookingRequestKeyV2(value: unknown): value is string { return safeRequestKey(value) }
-export type BookingSurfaceV2ValidationResult = { ok: true } | { ok: false; errors: string[] }
-function errors(v: ValidateFunction): string[] { return (v.errors ?? []).map(e => `${e.instancePath || '$'}: ${e.message ?? e.keyword}`) }
-function workspaceErrors(workspace: Record<string, any> | undefined, path: string): string[] {
-  const e: string[] = []
-  if (!workspace || typeof workspace !== 'object' || Array.isArray(workspace)) return e
-  const loadedOffers = Array.isArray(workspace.loadedOffers) ? workspace.loadedOffers : []
-  const offerRefs = loadedOffers.map((offer: any) => offer?.offerRef).filter((ref: unknown): ref is string => typeof ref === 'string')
-  const offerVersionRefs = loadedOffers.map((offer: any) => offer?.offerVersionRef).filter((ref: unknown): ref is string => typeof ref === 'string')
-  if (new Set(offerRefs).size !== offerRefs.length) e.push(`${path}.loadedOffers: duplicate offerRef`)
-  if (new Set(offerVersionRefs).size !== offerVersionRefs.length) e.push(`${path}.loadedOffers: duplicate offerVersionRef`)
-  const verified = workspace.verifiedOffer
-  if (verified !== undefined) {
-    if (!loadedOffers.some((offer: any) => offer?.offerRef === verified.offerRef && offer?.offerVersionRef === verified.offerVersionRef)) e.push(`${path}.verifiedOffer: loaded offer version required`)
-    if (!safeOpaque(verified.verifiedOfferRef) || !isBookingDateTimeV2(verified.expiresAt)) e.push(`${path}.verifiedOffer: safe ref and parseable expiry required`)
-  }
-  return e
-}
-function cross(value: unknown): string[] {
-  const e: string[] = []
-  if (scan(value)) e.push('$: unsafe PII/payment/supplier-cost/credential text')
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return e
-  const x = value as Record<string, any>
-  const semantic = x.kind === 'action.receipt.continuation' ? x.receipt : x
-  if (x.workspace && x.kind !== 'user.turn.ingress') e.push(...workspaceErrors(x.workspace, '$.workspace'))
-  if (x.schemaVersion === 'booking.surface.v2' && Array.isArray(x.loadedOffers)) e.push(...workspaceErrors(x, '$'))
-  if (x.kind === 'user.turn.ingress') {
-    if (!safeRequestKey(x.requestKey)) e.push('$.requestKey: safe opaque request key required')
-    const workspace = x.workspace as Record<string, any> | undefined
-    e.push(...workspaceErrors(workspace, '$.workspace'))
-    const visibleHotels = Array.isArray(workspace?.visibleHotels) ? workspace.visibleHotels : []
-    const loadedOffers = Array.isArray(workspace?.loadedOffers) ? workspace.loadedOffers : []
-    if (workspace?.focusedHotelRef !== undefined && !visibleHotels.some((hotel: any) => hotel?.hotelRef === workspace.focusedHotelRef)) e.push('$.workspace.focusedHotelRef: visible hotel required')
-    const selectedOffer = workspace?.selectedOfferRef === undefined ? undefined : loadedOffers.find((offer: any) => offer?.offerRef === workspace.selectedOfferRef)
-    if (workspace?.selectedOfferRef !== undefined && !selectedOffer) e.push('$.workspace.selectedOfferRef: loaded offer required')
-    if (selectedOffer && !visibleHotels.some((hotel: any) => hotel?.hotelRef === selectedOffer.hotelRef)) e.push('$.workspace.selectedOfferRef: offer hotel must be visible')
-  }
-  if (semantic !== x && semantic?.resultContract?.hardCriteriaMet === true && semantic.resultContract.blockers?.length) e.push('$.receipt.resultContract: hardCriteriaMet cannot coexist with blockers')
-  if (kinds.has(x.kind)) {
-    const allowed: Record<string, string[]> = {
-      'search.patch': ['patch'], 'search.run': [], 'results.view.patch': ['patch'],
-      'hotel.focus': ['hotelRef'], 'hotel.select': ['hotelRef'],
-      'offers.query': ['hotelRefs', 'criteria'], 'offers.view.patch': ['hotelRef', 'criteria'],
-      'offers.compare': ['offerRefs', 'requestedCount'], 'offer.select': ['offerRef', 'offerVersionRef'],
-      'offer.check': ['offerRef', 'offerVersionRef'], 'checkout.prepare': ['offerRef', 'offerVersionRef', 'verifiedOfferRef'], 'order.observe': ['orderRef'],
-    }
-    const input = x.input
-    if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).some(k => !allowed[x.kind].includes(k))) e.push('$.input: closed kind-specific input required')
-  }
-  if (x.kind === 'action.receipt' && x.resultContract?.hardCriteriaMet === true && x.resultContract.blockers?.length) e.push('$.resultContract: hardCriteriaMet cannot coexist with blockers')
-  if (x.kind === 'user.turn' && Array.isArray(x.request?.approval)) e.push('$.request.approval: at most one approval')
-  if (x.kind === 'action.receipt' || x.kind === 'action.receipt.continuation') {
-    const r = x.kind === 'action.receipt.continuation' ? x.receipt : x
-    if (r?.resultContract?.gapCodes?.some((code: unknown) => !gapCodes.has(String(code)))) e.push('$.resultContract.gapCodes: unregistered gap code')
-    const observation = r?.observation
-    if (observation?.kind === 'offer.availability') {
-      if (r.status === 'applied' && (observation.available !== true || !observation.verifiedOfferRef || observation.currentOfferVersionRef !== observation.checkedOfferVersionRef || observation.changedFactRefs?.length || observation.gapCodes?.length)) e.push('$.observation: applied availability requires unchanged checked/current version, verified ref, and no gaps')
-      if (r.status === 'applied' && (r.resultContract?.outcome !== 'complete' || r.resultContract?.hardCriteriaMet !== true || r.resultContract?.gapCodes?.length || r.resultContract?.blockers?.length)) e.push('$.resultContract: applied availability requires complete hard-criteria result without gaps or blockers')
-      if (r.status === 'changed' && (observation.available !== true || !observation.currentOfferVersionRef || observation.currentOfferVersionRef === observation.checkedOfferVersionRef || !observation.changedFactRefs?.length || observation.verifiedOfferRef)) e.push('$.observation: changed availability requires available replacement current version without verified ref')
-      if ((r.status === 'unavailable' || r.status === 'no_match') && (observation.available !== false || observation.currentOfferVersionRef || observation.verifiedOfferRef)) e.push('$.observation: negative availability must not expose current or verified version')
-      if (r.status !== 'applied' && observation.verifiedOfferRef) e.push('$.observation: only applied availability may expose verified ref')
-    }
-  }
-  const blocker = x.blocker ?? x.question?.blocker
-  if (blocker && !/^(searchDraft|results|offers|checkout)(\.[A-Za-z][A-Za-z0-9_]*){0,3}$/.test(blocker.criterionPath ?? '')) e.push('$.blocker.criterionPath: closed criterion path required')
-  if (blocker?.evidence?.factRefs && new Set(blocker.evidence.factRefs).size !== blocker.evidence.factRefs.length) e.push('$.blocker.evidence.factRefs: unique refs required')
-  if (x.kind === 'question' && blocker && Array.isArray(x.question?.approvalOptions)) {
-    for (const [i, option] of x.question.approvalOptions.entries()) {
-      const result = validateApprovalAgainstBlocker(option?.approval, blocker)
-      if (!result.ok) e.push(...result.errors.map(error => `$.question.approvalOptions[${i}].${error.slice(2)}`))
-    }
-  }
-  if (kinds.has(String(x.kind)) && x.relaxationApprovalRef) {
-    const ref = x.relaxationApprovalRef
-    if (ref.contextRef !== x.contextRef) e.push('$.relaxationApprovalRef.contextRef: must match action')
-    if (ref.sourceRevision !== x.expectedRevision) e.push('$.relaxationApprovalRef.sourceRevision: must equal action revision')
-    if (ref.targetActionKind !== x.kind) e.push('$.relaxationApprovalRef.targetActionKind: must match action kind')
-    if (ref.targetActionId !== x.actionId) e.push('$.relaxationApprovalRef.targetActionId: must match action id')
-    // Expiry and one-time consumption are Phase B runtime concerns; Phase A validates only structure/binding.
-    if (!safeOpaque(ref.nonce) || !isBookingDateTimeV2(ref.expiresAt)) e.push('$.relaxationApprovalRef: invalid expiry or nonce')
-  }
-  if (x.kind === 'question' && (!Array.isArray(x.question?.approvalOptions) || x.question.approvalOptions.length < 1 || x.question.approvalOptions.length > 2)) e.push('$.question.approvalOptions: one or two options required')
-  return e
-}
-export function validateBookingSurfaceV2(value: unknown): BookingSurfaceV2ValidationResult { const ok = validate(value); const e = ok ? [] : errors(validate); e.push(...cross(value)); return e.length ? { ok: false, errors: e } : { ok: true } }
-function fromCanonical(fn: ValidateFunction, value: unknown): BookingSurfaceV2ValidationResult { const ok = fn(value); const e = ok ? [] : errors(fn); e.push(...cross(value)); return e.length ? { ok: false, errors: e } : { ok: true } }
-export function validateBookingReadActionV2(value: unknown): BookingSurfaceV2ValidationResult { return fromCanonical(validateActionCanonical, value) }
-export function validateCriterionBlockerV2(value: unknown): BookingSurfaceV2ValidationResult { return fromCanonical(validateBlockerCanonical, value) }
-export function validateRelaxationApprovalV2(value: unknown): BookingSurfaceV2ValidationResult { return fromCanonical(validateApprovalCanonical, value) }
-export function validateBookingSurfaceEventV2(value: unknown): BookingSurfaceV2ValidationResult { return fromCanonical(validateEventCanonical, value) }
-export function validateApprovalAgainstBlocker(approval: unknown, blocker: unknown): BookingSurfaceV2ValidationResult {
-  const a = approval as any
-  const b = blocker as any
-  const blockerResult = validateCriterionBlockerV2(b)
-  if (!blockerResult.ok) return blockerResult
-  const approvalResult = validateRelaxationApprovalV2(a)
-  if (!approvalResult.ok) return approvalResult
-  const fields = ['blockerId', 'sourceActionId', 'sourceReceiptDigest', 'scope', 'code', 'criterionPath', 'valueDigest']
-  const mismatches = fields.filter(field => a[field] !== b?.[field])
-  return mismatches.length ? { ok: false, errors: mismatches.map(field => `$.${field}: approval does not match blocker`) } : { ok: true }
-}

package/ts/src/tool-budget.ts

@@ -1,165 +0,0 @@
-/** Per-agent, per-turn guard for model-driven tool loops. */
-
-import { randomUUID } from 'node:crypto'
-import type { Context } from '@deepseek-ai/cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
-import type { ToolExecutionResult, ToolExecutionToken } from '@deepseek-ai/dsh-tools'
-
-export const TOOL_BUDGET_SOFT_CALL = 16
-export const TOOL_BUDGET_HARD_CALL = 18
-export const TOOL_BUDGET_EXHAUSTED = 'TOOL_BUDGET_EXHAUSTED'
-
-export type ToolBudgetDecision =
-  | { kind: 'allow'; softSignal: boolean; exhaustsBudget: boolean }
-  | { kind: 'deny'; reason: string }
-
-export function toolBudgetDecision(callNumber: number): ToolBudgetDecision {
-  if (callNumber > TOOL_BUDGET_HARD_CALL) {
-    return {
-      kind: 'deny',
-      reason: `${TOOL_BUDGET_EXHAUSTED}: maximum ${TOOL_BUDGET_HARD_CALL} real tool dispatches per agent turn reached; provide a final answer using existing results`,
-    }
-  }
-  return {
-    kind: 'allow',
-    softSignal: callNumber === TOOL_BUDGET_SOFT_CALL,
-    exhaustsBudget: callNumber === TOOL_BUDGET_HARD_CALL,
-  }
-}
-
-export function createToolBudgetState(): {
-  nextCall(): ToolBudgetDecision & { callNumber: number }
-} {
-  let calls = 0
-  return {
-    nextCall() {
-      calls += 1
-      return { ...toolBudgetDecision(calls), callNumber: calls }
-    },
-  }
-}
-
-function convergenceContext(code: 'TOOL_BUDGET_SOFT' | typeof TOOL_BUDGET_EXHAUSTED, text: string) {
-  return {
-    id: randomUUID(),
-    role: 'user' as const,
-    content: [{ type: 'text' as const, text: `${code}: ${text}` }],
-    source: { kind: 'plugin' as const, plugin: 'gotry-tool-budget' },
-  }
-}
-
-function exhaustionResult(reason: string): ToolExecutionResult {
-  return {
-    isError: true,
-    error: {
-      message: reason,
-      info: { name: 'ToolBudgetError', code: TOOL_BUDGET_EXHAUSTED },
-    },
-    content: [{ type: 'text', text: reason }],
-    additionalContexts: [convergenceContext(
-      TOOL_BUDGET_EXHAUSTED,
-      'No more tool dispatches are permitted in this turn. Produce the final answer from existing results.',
-    ) as never],
-  }
-}
-
-type RestrictableTools = {
-  schemas?: () => Array<{ name: string }>
-  restrict?: (filter: { deny: string[] }) => () => void
-}
-
-/**
- * Install the runtime boundary, kept separate from the GoTry tool catalog so
- * the actual Cordis waterfalls can be exercised without booting every tool.
- */
-export function installToolBudget(ctx: Context): void {
-  // Some offline contract tests intentionally provide a registration-only
-  // Context slice. They do not drive an agent loop, so there is no budget hook
-  // to install and no reason to require an event bus.
-  if (typeof (ctx as unknown as { on?: unknown }).on !== 'function') return
-
-  const budgetByAgent = new Map<string, ReturnType<typeof createToolBudgetState>>()
-  const softExecutions = new Map<ToolExecutionToken, string>()
-  const pendingFinalOnly = new Map<string, Agent>()
-  const finalOnlyDisposers = new Map<string, () => void>()
-
-  const clearAgent = (agentId: string) => {
-    budgetByAgent.delete(agentId)
-    for (const [token, owner] of softExecutions) {
-      if (owner === agentId) softExecutions.delete(token)
-    }
-    pendingFinalOnly.delete(agentId)
-    finalOnlyDisposers.get(agentId)?.()
-    finalOnlyDisposers.delete(agentId)
-  }
-
-  const enterFinalOnly = (agent: Agent) => {
-    const agentId = String(agent.id)
-    if (finalOnlyDisposers.has(agentId)) return
-    const globalTools = ctx.tools as unknown as RestrictableTools
-    const scopedTools = agent.ctx?.tools as unknown as RestrictableTools | undefined
-    if (typeof globalTools.schemas !== 'function' || typeof scopedTools?.restrict !== 'function') return
-
-    // GoTry's model-facing tools are inherited globals. Removing their schemas
-    // makes the next native-mode request text-only; the execution wrapper below
-    // still denies any already-prepared same-step call beyond the hard limit.
-    const inheritedNames = globalTools.schemas()
-      .map(schema => schema.name)
-      .filter(name => name !== 'run_code')
-    if (inheritedNames.length === 0) return
-    finalOnlyDisposers.set(agentId, scopedTools.restrict({ deny: inheritedNames }))
-  }
-
-  ctx.on('session/event', (subject, event) => {
-    const agentId = String(subject.id)
-    if (event.type === 'turn/start' || event.type === 'turn/end') {
-      clearAgent(agentId)
-      return
-    }
-    // The live registry re-checks a tool name before starting every call in
-    // one assistant response. Restricting immediately on call 18 would turn an
-    // already-prepared call 19 into an opaque "unknown tool" before the
-    // execute waterfall can return TOOL_BUDGET_EXHAUSTED. step/end is the
-    // exact boundary after that batch settles and before the next prompt is
-    // assembled, so current-step refusals stay structured while the next
-    // native request is text-only.
-    if (event.type === 'step/end') {
-      const agent = pendingFinalOnly.get(agentId)
-      if (agent) {
-        pendingFinalOnly.delete(agentId)
-        enterFinalOnly(agent)
-      }
-    }
-  })
-  ctx.on('session/disposed', subject => clearAgent(String(subject.id)))
-
-  ctx.on('tools/execute', (exec, next) => {
-    // Programmatic/direct calls are not part of a model planner turn.
-    if (!exec.agent) return next()
-    const agentId = String(exec.agent.id)
-    const state = budgetByAgent.get(agentId) ?? createToolBudgetState()
-    budgetByAgent.set(agentId, state)
-    const decision = state.nextCall()
-    if (decision.kind === 'deny') {
-      pendingFinalOnly.set(agentId, exec.agent)
-      return Promise.resolve(exhaustionResult(decision.reason))
-    }
-    if (decision.softSignal) softExecutions.set(exec.token, agentId)
-    if (decision.exhaustsBudget) pendingFinalOnly.set(agentId, exec.agent)
-    return next()
-  })
-
-  ctx.on('tools/post-execute', (exec, _result, next) => {
-    if (!softExecutions.delete(exec.token)) return next()
-    return next().then(decision => ({
-      ...decision,
-      additionalContexts: [
-        ...(decision.additionalContexts ?? []),
-        convergenceContext(
-          'TOOL_BUDGET_SOFT',
-          'Tool call 16 reached. Converge now and produce the final answer from gathered evidence.',
-        ) as never,
-      ],
-    }))
-  })
-}