@danceiny/gotry 0.2.0-rc.32 → 0.2.0-rc.33

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

@@ -1,5 +1,6 @@
 /** Production composition entry for GoTry's BFF-only Booking Copilot server. */
 
+import { AsyncResource } from 'node:async_hooks'
 import { mkdirSync } from 'node:fs'
 import { isAbsolute, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -12,6 +13,9 @@ import {
 } from './dsh-planner.ts'
 import { BookingCopilotTaskRuntime } from './runtime.ts'
 import { BOOKING_COPILOT_INGRESS_MODES, type BookingCopilotIngressMode, type BookingIngressBinding, type BookingIngressPrincipal } from './contracts.ts'
+import type { BookingTenancy, TenantPlannerProvider } from './tenancy.ts'
+import { assertManagedDshLimitsEnforceable, type ManagedDshResourceLimits } from './managed-dsh-run-port.ts'
+import type { LlmTicketIssuer, LlmTicketOptions, LlmUsageReport } from '../tenant-seam/llm-broker.ts'
 import {
   startBookingCopilotServer,
   type BookingCopilotServerHandle,
@@ -42,6 +46,11 @@ export interface BookingCopilotStartupDependencies {
   /** Optional in-process BFF identity seam; standalone use is bound-turn-only. */
   ingressBinding?: BookingIngressBinding
   principal?: BookingIngressPrincipal
+  /**
+   * The multi-tenant form (AaaS). When present, no shared ledger, runtime, planner or principal is created: every
+   * request is authenticated and placed in its own tenant by the tenancy, which this process then owns and closes.
+   */
+  tenancy?: BookingTenancy
   startServer(options: BookingCopilotServerOptions): Promise<BookingCopilotServerHandle>
 }
 
@@ -97,6 +106,151 @@ export function resolveBookingCopilotStartupConfig(
   }
 }
 
+export interface BookingCopilotTenantStartupConfig {
+  host: string
+  port: number
+  artifactId?: string
+  /** Set only when the environment names a mode explicitly; it must then agree with the tenancy. */
+  ingressMode?: BookingCopilotIngressMode
+}
+
+/** The listener settings of the multi-tenant form. There is no deployment key and no shared state root: the tenancy holds both roles. */
+export function resolveBookingCopilotTenantStartupConfig(
+  env: Record<string, string | undefined> = process.env,
+): BookingCopilotTenantStartupConfig {
+  const artifactId = env.GOTRY_BOOKING_COPILOT_ARTIFACT_ID || undefined
+  if (artifactId !== undefined && !/^[0-9a-f]{40}$/.test(artifactId)) {
+    throw new Error('booking_copilot_artifact_id_invalid')
+  }
+  const rawIngressMode = env.GOTRY_BOOKING_COPILOT_INGRESS_MODE
+  if (rawIngressMode !== undefined && rawIngressMode !== '' && !(BOOKING_COPILOT_INGRESS_MODES as readonly string[]).includes(rawIngressMode)) {
+    throw new Error('booking_copilot_ingress_mode_invalid')
+  }
+  return {
+    host: env.GOTRY_BOOKING_COPILOT_HOST || '127.0.0.1',
+    port: parsePort(env.GOTRY_BOOKING_COPILOT_PORT),
+    ...(artifactId === undefined ? {} : { artifactId }),
+    ...(rawIngressMode === undefined || rawIngressMode === '' ? {} : { ingressMode: rawIngressMode as BookingCopilotIngressMode }),
+  }
+}
+
+/**
+ * Ceilings for each planner process tree in the multi-tenant form (docs/rfc/aaas-rfc.md §4.8, threat S-17). Every
+ * tenant on a replica shares its CPU and memory, so one runaway child must be stopped by a limit and not by the
+ * operating system's OOM killer. These numbers are a ceiling for a runaway, not a budget, and are unreviewed: they sit
+ * well above what an idle booted planner tree costs (see docs/ops/aaas-capacity-baseline.md) and a deployment that
+ * knows better passes its own `resourceLimits`.
+ */
+export const DEFAULT_TENANT_PLANNER_RESOURCE_LIMITS: ManagedDshResourceLimits = Object.freeze({
+  heapMb: 512,
+  maxRssBytes: 1536 * 1024 * 1024,
+  maxCpuSeconds: 120,
+  maxLineChars: 8 * 1024 * 1024,
+})
+
+/**
+ * The sampler is the only thing between a runaway planner child and the replica. If it cannot see the process table, the
+ * limits would silently govern nothing, so this fails first, with a name, before any child starts. Limits that need no
+ * sampler (a heap ceiling, a line cap) have nothing to check.
+ */
+export const assertPlannerLimitsEnforceable: (limits: ManagedDshResourceLimits) => Promise<void> = assertManagedDshLimitsEnforceable
+
+/**
+ * One planner per tenant, each rooted in that tenant's own directory, so planner sessions and working files never sit
+ * beside another tenant's. Planners are created lazily by the dsh adapter (no process starts until a session needs one).
+ * The dsh adapter does not report token usage yet, so until it does every invocation is charged the quota policy's
+ * worst case (`TenantQuotas.chargeUnprovenInvocation`).
+ */
+export function createDshTenantPlannerProvider(
+  base: Omit<DshEmbeddedBookingPlannerOptions, 'stateRoot'>,
+  createPlanner: (options: DshEmbeddedBookingPlannerOptions) => Promise<DshEmbeddedBookingPlannerHandle> = createDshEmbeddedBookingPlanner,
+): TenantPlannerProvider {
+  // The real dsh planner of the tenant form never holds the deployment's LLM credential (docs/rfc/aaas-rfc.md §4.8, S-18):
+  // it is built with a broker that gives each planner process tree a ticket. A planner factory injected by a suite is
+  // the caller's own business and is not asked for one.
+  if (createPlanner === createDshEmbeddedBookingPlanner && base.llmTickets === undefined) {
+    throw new Error('tenant_planner_credential_broker_required')
+  }
+  const handles: DshEmbeddedBookingPlannerHandle[] = []
+  const realPlanner = createPlanner === createDshEmbeddedBookingPlanner
+  let governable = false
+  return {
+    async forTenant(context) {
+      if (realPlanner && !governable) {
+        await assertPlannerLimitsEnforceable(base.resourceLimits ?? DEFAULT_TENANT_PLANNER_RESOURCE_LIMITS)
+        governable = true
+      }
+      // Tickets issued for this tenant report their measured usage to this tenant's meter. The report is bound to the
+      // async context where the ticket is issued, which is inside the planner invocation that needs the port: the broker
+      // answers from its own request context, and the report must still land on the invocation that asked (and on no other).
+      const issuer = base.llmTickets
+      const llmTickets: LlmTicketIssuer | undefined = issuer && {
+        issue: (options: LlmTicketOptions = {}) => issuer.issue({
+          ...options,
+          onUsage: AsyncResource.bind((report: LlmUsageReport) => context.reportUsage(report.model, report.usage)),
+        }),
+      }
+      const handle = await createPlanner({
+        ...base,
+        ...(llmTickets ? { llmTickets } : {}),
+        resourceLimits: base.resourceLimits ?? DEFAULT_TENANT_PLANNER_RESOURCE_LIMITS,
+        // Both come from the tenant, never from the deployment-wide base: a shared label or root would defeat the point.
+        cachePartition: context.cachePartition,
+        stateRoot: context.tenantRoot,
+      })
+      handles.push(handle)
+      return handle.plannerFactory
+    },
+    async close() {
+      const failures: unknown[] = []
+      for (const handle of handles.splice(0)) {
+        try { await handle.close() } catch (error) { failures.push(error) }
+      }
+      if (failures.length === 1) throw failures[0]
+      if (failures.length > 1) throw new AggregateError(failures, 'booking_copilot_planner_shutdown_failed')
+    },
+  }
+}
+
+async function startTenantCopilot(
+  env: Record<string, string | undefined>,
+  dependencies: BookingCopilotStartupDependencies,
+  tenancy: BookingTenancy,
+): Promise<BookingCopilotStartupHandle> {
+  if (dependencies.ingressBinding || dependencies.principal) throw new Error('booking_copilot_tenancy_shared_conflict')
+  const config = resolveBookingCopilotTenantStartupConfig(env)
+  if (config.ingressMode !== undefined && config.ingressMode !== tenancy.ingressMode) throw new Error('booking_copilot_ingress_mode_conflict')
+  let server: BookingCopilotServerHandle
+  try {
+    server = await dependencies.startServer({
+      tenancy,
+      ingressMode: tenancy.ingressMode,
+      host: config.host,
+      port: config.port,
+      ...(config.artifactId === undefined ? {} : { artifactId: config.artifactId }),
+    })
+  } catch (error) {
+    try { await tenancy.close() } catch (cleanupError) {
+      throw new AggregateError([error, cleanupError], 'booking_copilot_startup_and_cleanup_failed')
+    }
+    throw error
+  }
+  let closed = false
+  return {
+    port: server.port,
+    async close() {
+      if (closed) return
+      closed = true
+      const failures: unknown[] = []
+      // Stop taking turns and drain the ones in flight first; then give the tenants back (planners, then leases).
+      try { await server.close() } catch (error) { failures.push(error) }
+      try { await tenancy.close() } catch (error) { failures.push(error) }
+      if (failures.length === 1) throw failures[0]
+      if (failures.length > 1) throw new AggregateError(failures, 'booking_copilot_shutdown_failed')
+    },
+  }
+}
+
 async function closeAll(
   server: BookingCopilotServerHandle | undefined,
   planner: DshEmbeddedBookingPlannerHandle | undefined,
@@ -123,6 +277,7 @@ export async function startBookingCopilotFromEnvironment(
   env: Record<string, string | undefined> = process.env,
   dependencies: BookingCopilotStartupDependencies = DEFAULT_DEPENDENCIES,
 ): Promise<BookingCopilotStartupHandle> {
+  if (dependencies.tenancy) return startTenantCopilot(env, dependencies, dependencies.tenancy)
   const config = resolveBookingCopilotStartupConfig(env)
   const activeDependencies = dependencies
   const hasIngressBinding = Boolean(activeDependencies.ingressBinding)

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

@@ -0,0 +1,242 @@
+/**
+ * Multi-tenant seam of the Booking Copilot surface (AaaS A2, docs/rfc/aaas-rfc.md §4.4; threats S-1 to S-4, S-10, S-13, S-14).
+ *
+ * One request becomes one `TurnScope` here and nowhere else:
+ *
+ *   authenticate -> deriveSeamTenant -> quotas.admitTurn -> router.openTenant -> a runtime over the tenant's guarded ledger
+ *
+ * The tenant comes from the authenticated caller only. The body, the headers, the tool arguments and the model's output
+ * are never inputs to it, and the scope carries no method that takes a tenant. Everything the surface keeps between
+ * requests (planner sessions, single-flight decisions) is keyed by the scope, so two tenants whose task handles and
+ * request keys collide still never meet. The shared, single-ledger form of the surface (today's deployment) does not
+ * use this module and behaves exactly as before.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { MeasuredLlmUsage } from '../llm-price-table.ts'
+import { assertSeamTenant, deriveSeamTenant, InvalidPrincipalError, SeamError, seamTenantKey, UnknownOrganizationError, type AuthenticatedCaller, type CallerAuthenticator, type CallerRequest, type OrganizationKeyring, type SeamTenant } from '../tenant-seam/seam.ts'
+import { QuotaExceededError, type TenantQuotas } from '../tenant-seam/quotas.ts'
+import { InvalidTenantIdError, ReplicaAtCapacityError, RouterClosedError, TenantDrainingError, TenantStateError } from '../tenant-state/errors.ts'
+import { derivePromptCachePartition } from '../tenant-state/ids.ts'
+import type { TenantHandle, TenantRouter } from '../tenant-state/tenant-router.ts'
+import type { BookingCopilotIngressMode, BookingIngressBinding, BookingIngressPrincipal } from './contracts.ts'
+import { BookingCopilotTaskRuntime, type BookingCopilotRuntimeOptions, type BookingPlannerSession, type BookingPlannerSessionFactory } from './runtime.ts'
+
+/** What a deployment gives the planner for one tenant. */
+export interface TenantPlannerContext {
+  /** The tenant's own directory. Planner working files and session state go here, never beside another tenant's. */
+  readonly tenantRoot: string
+  /**
+   * The tenant's prompt cache partition label (`derivePromptCachePartition`). A planner puts it into every prompt ahead
+   * of anything tenant-derived, so a provider's prefix cache is never shared between tenants past the shared instructions.
+   */
+  readonly cachePartition: string
+  /**
+   * Reports the measured usage of the planner invocation in progress, priced against the frozen table. A report from
+   * outside an invocation of this tenant is dropped, never charged to anyone else.
+   */
+  reportUsage(model: string, usage: MeasuredLlmUsage): void
+}
+
+export interface TenantPlannerProvider {
+  /** The planner session factory of one tenant. Called once per tenant and cached. */
+  forTenant(context: TenantPlannerContext): Promise<BookingPlannerSessionFactory>
+  close(): Promise<void>
+}
+
+/** One planner shared by every tenant. Sessions are still keyed by tenant here, but the planner's own files are shared: for fixtures. */
+export function sharedPlannerProvider(factory: BookingPlannerSessionFactory): TenantPlannerProvider {
+  return { forTenant: async () => factory, close: async () => undefined }
+}
+
+export interface BookingTenancyOptions {
+  readonly authenticator: CallerAuthenticator
+  readonly keyring: OrganizationKeyring
+  readonly router: TenantRouter
+  readonly quotas: TenantQuotas
+  readonly planners: TenantPlannerProvider
+  readonly runtime?: BookingCopilotRuntimeOptions
+  /** The in-process BFF identity seam of ADR-23. Absent: ingress turns are refused, as in bound-turn-only. */
+  readonly ingressBinding?: BookingIngressBinding
+}
+
+/** What the surface needs for one request. Built by the tenancy, or by the server for the shared form. */
+export interface TurnScope {
+  /** `<organization>/<hmac tenant>`, or `null` for the shared single-ledger form. */
+  readonly key: string | null
+  readonly runtime: BookingCopilotTaskRuntime
+  readonly plannerFactory: BookingPlannerSessionFactory
+  readonly ingress: { readonly binding: BookingIngressBinding; readonly principal: BookingIngressPrincipal } | null
+  /** Key of a planner session in the composition-wide map. Equal to the task id in the shared form. */
+  sessionKey(taskId: string): string
+  /** Key of a decision flight in the composition-wide map. Unchanged in the shared form. */
+  flightKey(parts: readonly unknown[]): string
+  /** Runs the decision work (the planner await and the ledger write that follows). Tenant form: leased, drained by a handoff, acknowledged only if the lease held. */
+  runDecision<T>(work: () => Promise<T>): Promise<T>
+  /** True for a failure of the tenant's availability (lease, fence, handoff, store) rather than of the request. */
+  isTenantFault(error: unknown): boolean
+  /** Frees the concurrency slot. Call exactly once, when the response is over. */
+  release(): void
+}
+
+/** The handle and the ledger it exposes disagree with the tenant the seam derived: a wiring bug that must never serve a request. */
+export class TenantBindingError extends SeamError {
+  constructor() {
+    super('GOTRY_SEAM_TENANT_MISMATCH', 'the opened ledger does not belong to the derived tenant')
+  }
+}
+
+interface InvocationMeter {
+  readonly tenantKey: string
+  reported: boolean
+}
+
+const invocations = new AsyncLocalStorage<InvocationMeter>()
+
+function ledgerBytes(handle: TenantHandle): number {
+  return handle.run((ledger) => {
+    const pages = ledger.db.pragma('page_count', { simple: true }) as number
+    const size = ledger.db.pragma('page_size', { simple: true }) as number
+    return pages * size
+  })
+}
+
+export class BookingTenancy {
+  readonly ingressMode: BookingCopilotIngressMode
+  private readonly options: BookingTenancyOptions
+  private readonly planners = new Map<string, Promise<BookingPlannerSessionFactory>>()
+
+  constructor(options: BookingTenancyOptions) {
+    if (typeof options.authenticator?.authenticate !== 'function') throw new Error('booking_copilot_tenancy_authenticator_required')
+    if (typeof options.keyring?.keyFor !== 'function') throw new Error('booking_copilot_tenancy_keyring_required')
+    if (!options.router || !options.quotas || !options.planners) throw new Error('booking_copilot_tenancy_incomplete')
+    if (options.ingressBinding !== undefined && typeof options.ingressBinding.bind !== 'function') throw new Error('booking_copilot_ingress_binding_invalid')
+    this.options = options
+    this.ingressMode = options.ingressBinding ? 'bff-ingress-binding' : 'bff-bound-turn-only'
+  }
+
+  /** The authenticated caller of a request, or `null`. The only place a credential is read. */
+  async authenticate(request: CallerRequest): Promise<AuthenticatedCaller | null> {
+    return this.options.authenticator.authenticate(request)
+  }
+
+  /**
+   * Derives the tenant, admits the turn, and opens the tenant's guarded ledger.
+   *
+   * @throws QuotaExceededError before any lease or file is touched, when the turn is over a limit
+   * @throws InvalidTenantIdError | InvalidPrincipalError | UnknownOrganizationError for a caller the seam cannot place
+   * @throws TenantStateError subclasses when the tenant cannot be served here now (owned elsewhere, draining, store down)
+   */
+  async beginTurn(caller: AuthenticatedCaller): Promise<TurnScope> {
+    const { quotas, router } = this.options
+    const tenant = deriveSeamTenant(caller, this.options.keyring)
+    const permit = quotas.admitTurn(tenant)
+    try {
+      const handle = await router.openTenant(tenant.organization, tenant.ledgerTenant)
+      // Defense in depth: the handle, and the ledger inside it, must be exactly the tenant the seam derived.
+      if (handle.organization !== tenant.organization || handle.ledgerTenant !== tenant.ledgerTenant || handle.ledger.tenant !== tenant.ledgerTenant) throw new TenantBindingError()
+      quotas.observeLedgerBytes(tenant, ledgerBytes(handle))
+      const plannerFactory = await this.plannerFor(tenant)
+      const key = seamTenantKey(tenant)
+      const runtime = new BookingCopilotTaskRuntime(handle.ledger, this.options.runtime)
+      const binding = this.options.ingressBinding
+      return {
+        key,
+        runtime,
+        plannerFactory,
+        ingress: binding ? { binding, principal: { subject: caller.subject, scope: caller.scope } } : null,
+        sessionKey: (taskId) => `${key}\u0000${taskId}`,
+        flightKey: (parts) => JSON.stringify([key, ...parts]),
+        runDecision: (work) => handle.runAsync(work),
+        isTenantFault: (error) => error instanceof TenantStateError,
+        release: () => permit.release(),
+      }
+    } catch (error) {
+      permit.release()
+      throw error
+    }
+  }
+
+  /**
+   * Hands every tenant back and stops the planners. The tenancy owns the router and the planner provider it was given:
+   * a graceful handoff per tenant (drain, final snapshot, release), then the planners. Resolves when done; a tenant whose
+   * final snapshot could not be flushed is reported, because its last writes are then only as durable as the last snapshot.
+   */
+  async close(): Promise<void> {
+    const failures: unknown[] = []
+    try { await this.options.planners.close() } catch (error) { failures.push(error) }
+    const unflushed = await this.options.router.close().catch((error: unknown) => { failures.push(error); return [] as string[] })
+    if (unflushed.length > 0) failures.push(new Error(`booking_copilot_tenant_handoff_unflushed:${unflushed.length}`))
+    if (failures.length === 1) throw failures[0]
+    if (failures.length > 1) throw new AggregateError(failures, 'booking_copilot_tenancy_close_failed')
+  }
+
+  private plannerFor(tenant: SeamTenant): Promise<BookingPlannerSessionFactory> {
+    const seam = assertSeamTenant(tenant)
+    const key = seamTenantKey(seam)
+    let planner = this.planners.get(key)
+    if (!planner) {
+      const { quotas, planners, router } = this.options
+      const organizationKey = this.options.keyring.keyFor(seam.organization)
+      if (organizationKey === null) throw new UnknownOrganizationError()
+      planner = planners.forTenant({
+        tenantRoot: router.tenantRootOf(seam.organization, seam.ledgerTenant),
+        cachePartition: derivePromptCachePartition(organizationKey, seam.ledgerTenant),
+        reportUsage: (model, usage) => {
+          const meter = invocations.getStore()
+          if (!meter || meter.tenantKey !== key) return
+          try {
+            quotas.recordLlmUsage(seam, model, usage)
+            meter.reported = true
+          } catch {
+            // An unpriced model or malformed counts leave the invocation unproven: it is charged the worst case below.
+          }
+        },
+      }).then((inner) => (task) => this.metered(inner(task), seam, key))
+      planner.catch(() => this.planners.delete(key))
+      this.planners.set(key, planner)
+    }
+    return planner
+  }
+
+  /** Wraps a planner session so that every invocation is charged: what it reported, or the worst case if it reported nothing. */
+  private metered(session: BookingPlannerSession, tenant: SeamTenant, key: string): BookingPlannerSession {
+    const { quotas } = this.options
+    return {
+      next: async (input) => {
+        const meter: InvocationMeter = { tenantKey: key, reported: false }
+        try {
+          return await invocations.run(meter, () => session.next(input))
+        } finally {
+          if (!meter.reported) quotas.chargeUnprovenInvocation(tenant)
+        }
+      },
+      ...(session.close ? { close: () => session.close!() } : {}),
+    }
+  }
+}
+
+export interface TenantRejection {
+  readonly status: number
+  readonly body: { readonly error: Record<string, unknown> }
+  readonly retryAfterSeconds?: number
+}
+
+/** The typed HTTP answer for a failure raised before the response stream starts. Bodies carry codes, scopes and hints only. */
+export function tenantRejection(error: unknown): TenantRejection {
+  if (error instanceof QuotaExceededError) {
+    return {
+      status: 429,
+      body: { error: { code: 'quota_exceeded', scope: error.scope, dimension: error.dimension, retryAfterSeconds: error.retryAfterSeconds } },
+      retryAfterSeconds: error.retryAfterSeconds,
+    }
+  }
+  if (error instanceof InvalidTenantIdError || error instanceof InvalidPrincipalError) return { status: 403, body: { error: { code: 'invalid_principal' } } }
+  if (error instanceof UnknownOrganizationError) return { status: 403, body: { error: { code: 'organization_not_served' } } }
+  if (error instanceof RouterClosedError) return { status: 503, body: { error: { code: 'booking_copilot_shutting_down' } } }
+  if (error instanceof TenantDrainingError) return { status: 503, body: { error: { code: 'tenant_draining' } }, retryAfterSeconds: 1 }
+  // A full replica frees a slot only when some tenant is handed off, so retrying it soon is not a useful hint; the request belongs on another replica.
+  if (error instanceof ReplicaAtCapacityError) return { status: 503, body: { error: { code: 'tenant_unavailable' } } }
+  if (error instanceof TenantStateError && !(error instanceof SeamError)) return { status: 503, body: { error: { code: 'tenant_unavailable' } }, retryAfterSeconds: 1 }
+  return { status: 500, body: { error: { code: 'tenant_seam_failure' } } }
+}

package/ts/src/index.ts

@@ -1894,13 +1894,15 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
       fromStationTelecode: { type: 'string', description: '出发站三位电报码,仅 kind=train;城市码表外时填(kyfw 查询页 URL 里)' },
       toStationTelecode: { type: 'string', description: '到达站三位电报码,仅 kind=train,同上' },
       backDate: { type: 'string', description: '回程日期 YYYY-MM-DD,仅 kind=flight;存在即往返检索——须 ui=gui(GUI 车道站点表单原生往返;bridge 车道不知往返 URL 形状,不猜)' },
-      ui: { type: 'string', enum: ['bridge', 'gui'], description: 'kind=flight|hotel:bridge(默认,用户登录态被动嗅探)|gui(gotry 隔离匿名窗口驱动 PC 表单——flight 往返/任意城市原生+低价日历;hotel 任意目的地原生(cityId 码表不在主链路);匿名公开价)' },
+      ui: { type: 'string', enum: ['bridge', 'gui'], description: 'kind=flight|hotel:bridge(默认,用户登录态被动嗅探)|gui(gotry 隔离匿名窗口驱动 PC 表单——flight 往返/多程/任意城市原生+低价日历;hotel 任意目的地原生;匿名公开价)' },
+      legs: { type: 'string', description: '多程段 JSON 数组,仅 kind=flight+ui=gui:[{"from":"香港","to":"迪拜","date":"2026-12-06"},{"from":"迪拜","to":"上海","date":"2026-12-10"}](2–3 段)' },
+      interactiveLogin: { type: 'boolean', description: '仅 ui=gui:登录墙命中时窗口停在携程官方登录页,等用户本人在窗口内完成登录(最多 6 分钟)后自动重查,拿登录态真实数据(行程明细/酒店真实价)。gotry 永不经手密码/验证码/cookie 值' },
     },
     output: { schema: { type: 'json' }, render: (_a, v) => [{ type: 'text', text: String((v as { summary?: string }).summary ?? JSON.stringify(v).slice(0, 600)) }] },
     async execute(args, _exec) {
       const selectedKind = resolveSessionSearchKind(args)
       if (!selectedKind.ok) return { ok: false, summary: selectedKind.reason } as const
-      const q = { ...unwrapQuery<{ kind?: string; from?: string; to?: string; date?: string; fromCityCode?: string; toCityCode?: string; cityId?: number | string; country?: string; checkIn?: string; checkOut?: string; adults?: number; fromStationTelecode?: string; toStationTelecode?: string; backDate?: string; ui?: string }>(args), kind: selectedKind.kind }
+      const q = { ...unwrapQuery<{ kind?: string; from?: string; to?: string; date?: string; fromCityCode?: string; toCityCode?: string; cityId?: number | string; country?: string; checkIn?: string; checkOut?: string; adults?: number; fromStationTelecode?: string; toStationTelecode?: string; backDate?: string; ui?: string; legs?: string; interactiveLogin?: boolean }>(args), kind: selectedKind.kind }
       const runSessionEffect = seams.effect ?? interpretEffect
       // ---- Dida 供应商门户(2026-09-09 实装;hotel-be portal integration 迁移线)----
       if (q.kind === 'dida') {
@@ -1974,6 +1976,7 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
           effect: q.ui === 'gui' ? 'SESSION_HOTEL_GUI_SEARCH' : 'SESSION_HOTEL_SEARCH',
           params: {
             to: q.to, country: q.country, cityId: q.cityId, checkIn: q.checkIn, checkOut: q.checkOut, adults: q.adults,
+            ...(q.ui === 'gui' && q.interactiveLogin ? { interactiveLoginMs: 360_000 } : {}),
             auditPath: join(config.stateRoot ?? '.', 'gotry-state', 'session-incidents.jsonl'),
           },
         })
@@ -2007,11 +2010,34 @@ export function apply(ctx: Context, config: Config, seams: ApplyTestSeams = {}):
       if (q.ui !== undefined && q.ui !== 'bridge' && q.ui !== 'gui') {
         return { ok: false, summary: 'kind=flight 的 ui 只接受 bridge(默认,登录态被动嗅探)|gui(隔离匿名窗口驱动表单)' } as const
       }
+      // 多程段(仅 gui;严格形状闸——2–3 段、城市非空、日期 YMD、段内日期递增)
+      let legs: Array<{ from: string; to: string; date: string }> | undefined
+      if (q.legs !== undefined) {
+        if (q.ui !== 'gui') return { ok: false, summary: 'legs(多程)仅支持 ui=gui(GUI 车道驱动多程表单)' } as const
+        try {
+          const parsed = JSON.parse(q.legs) as unknown
+          if (!Array.isArray(parsed) || parsed.length < 2 || parsed.length > 3) throw new Error('段数须 2–3')
+          legs = parsed.map((raw: unknown) => {
+            const leg = raw as { from?: unknown; to?: unknown; date?: unknown }
+            if (typeof leg.from !== 'string' || !leg.from.trim() || typeof leg.to !== 'string' || !leg.to.trim() || typeof leg.date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(leg.date)) {
+              throw new Error('每段须 {from,to,date(YYYY-MM-DD)}')
+            }
+            return { from: leg.from.trim(), to: leg.to.trim(), date: leg.date }
+          })
+          for (let i = 1; i < legs.length; i += 1) {
+            if (legs[i]!.date <= legs[i - 1]!.date) throw new Error('段日期须递增')
+          }
+        } catch (e) {
+          return { ok: false, summary: `legs 形状非法:${(e as Error).message}` } as const
+        }
+      }
       const itp = await runSessionEffect({
         effect: q.ui === 'gui' ? 'SESSION_FLIGHT_GUI_SEARCH' : 'SESSION_FLIGHT_SEARCH',
         params: {
           from: q.from, to: q.to, date: q.date, fromCityCode: q.fromCityCode, toCityCode: q.toCityCode,
           ...(q.backDate ? { backDate: q.backDate } : {}),
+          ...(legs ? { legs } : {}),
+          ...(q.ui === 'gui' && q.interactiveLogin ? { interactiveLoginMs: 360_000 } : {}),
           // ADR-15 收尾:ReadGuard 审计在生产工具路径同样落盘(此前仅测试传隔离 stateRoot 才有 JSONL)
           auditPath: join(config.stateRoot ?? '.', 'gotry-state', 'session-incidents.jsonl'),
         },