@danceiny/gotry 0.2.0-rc.31 → 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/gotry-web-api.ts

@@ -12,11 +12,16 @@ import {
   removeFlyaiVerification, resolveFlyaiEndpoint, resolveFlyaiKey, saveFlyaiKey,
   sha256Hex, writeFlyaiVerification,
 } from '../capabilities/flyai-config.ts'
+import {
+  hbcliCredentialPath, hbcliSetupStatus, readHbcliCredentials, removeHbcliVerification,
+  verifyHbcliCandidate, withHbcliCredentials, withoutHbcliCredentials, writeHbcliCredentials, writeHbcliVerification,
+} from '../capabilities/hbcli-config.ts'
 
 interface WebOptions {
   stateRoot: string
   homeDir?: string
   env?: NodeJS.ProcessEnv
+  hbcliBin?: string
   workspaceForSession: (sessionId: string) => Promise<string | undefined>
 }
 
@@ -47,6 +52,7 @@ async function readInput(request: Request): Promise<Record<string, unknown> | Re
 export function createGotryWebHandlers(options: WebOptions) {
   const homeDir = options.homeDir ?? homedir(), env = options.env ?? process.env
   const paths = { homeDir, env }, configPath = flyaiConfigPath(homeDir)
+  const hbPaths = { homeDir, env, hbcliBin: options.hbcliBin }
   let mutations: Promise<unknown> = Promise.resolve()
   const status = () => {
     const current = resolveFlyaiKey(paths), endpoint = resolveFlyaiEndpoint(paths), receipt = readFlyaiVerification(homeDir)
@@ -92,7 +98,48 @@ export function createGotryWebHandlers(options: WebOptions) {
     }
     return json(status())
   }
+  async function mutateHbcli(input: Record<string, unknown>, signal: AbortSignal): Promise<Response> {
+    if (signal.aborted) return rejection('操作已取消。', 409)
+    if (!hbcliSetupStatus(hbPaths).writable) return rejection('当前凭证来自环境变量，或本机配置不可安全写入。', 409)
+    const before = readHbcliCredentials(hbPaths)
+    if (!before.ok) return rejection('原配置损坏，已保留原文件，请先修复。', 409)
+    if (input.action === 'clear') {
+      if (!writeHbcliCredentials(withoutHbcliCredentials(before.data), hbPaths)) return rejection('无法清除配置，请检查本机文件及权限。', 409)
+      removeHbcliVerification(homeDir)
+      return json(hbcliSetupStatus(hbPaths))
+    }
+    const appKey = typeof input.appKey === 'string' ? input.appKey.trim() : ''
+    const appSecret = typeof input.appSecret === 'string' ? input.appSecret.trim() : ''
+    if ([appKey, appSecret].some(value => !value || value.length > 2048 || /[\r\n\0]/.test(value))) return rejection('请填写 HotelByte 提供的 App Key 和 App Secret。')
+    const verified = await verifyHbcliCandidate(appKey, appSecret, hbPaths, signal)
+    if (signal.aborted || verified.verdict === 'error' || verified.verdict === 'cancelled') {
+      return json({ ok: false, error: verified.error ?? '验证已取消，旧配置保留。' }, 422)
+    }
+    const current = readHbcliCredentials(hbPaths)
+    if (!hbcliSetupStatus(hbPaths).writable || !current.ok || current.bytes !== before.bytes) return rejection('配置在验证期间发生变化，请重新读取后再试。', 409)
+    const next = withHbcliCredentials(before.data, appKey, appSecret)
+    if (!writeHbcliCredentials(next, hbPaths)) return rejection('安全保存失败，旧配置保留，请检查本机权限。', 409)
+    if (!writeHbcliVerification(next, verified.verdict, hbPaths)) {
+      const restored = before.bytes === undefined
+        ? (() => { try { rmSync(hbcliCredentialPath(hbPaths)); return true } catch { return false } })()
+        : writeHbcliCredentials(before.data, hbPaths)
+      return rejection(restored ? '验证回执保存失败，旧配置已恢复。' : '验证回执保存失败，请检查本机文件。', 409)
+    }
+    return json(hbcliSetupStatus(hbPaths))
+  }
   return {
+    async hbcli(request: Request): Promise<Response> {
+      if (request.method === 'GET') return json(hbcliSetupStatus(hbPaths))
+      if (request.method !== 'POST') return rejection('不支持此操作。', 405)
+      const input = await readInput(request)
+      if (input instanceof Response) return input
+      if (!['save', 'clear'].includes(String(input.action))
+        || Object.keys(input).some(key => !['action', 'appKey', 'appSecret'].includes(key))
+        || (input.action === 'clear' && ('appKey' in input || 'appSecret' in input))) return rejection('请求无效。')
+      const operation = mutations.then(() => mutateHbcli(input, request.signal)).catch(() => rejection('操作失败，未能确认保存，请重新读取状态。', 500))
+      mutations = operation.then(() => undefined)
+      return operation
+    },
     async flyai(request: Request): Promise<Response> {
       if (request.method === 'GET') return json(status())
       if (request.method !== 'POST') return rejection('不支持此操作。', 405)
@@ -121,11 +168,11 @@ export function createGotryWebHandlers(options: WebOptions) {
   }
 }
 
-export function registerGotryWebApi(ctx: Context, stateRoot: string): void {
+export function registerGotryWebApi(ctx: Context, stateRoot: string, hbcliBin?: string): void {
   if (typeof ctx.inject !== 'function') return
   ctx.inject(['connection', 'sessions'], scope => {
     const connection = scope.get('connection') as HostConnectionHandle
-    const handlers = createGotryWebHandlers({ stateRoot, workspaceForSession: async sessionId => {
+    const handlers = createGotryWebHandlers({ stateRoot, hbcliBin, workspaceForSession: async sessionId => {
       const id = sessionId as Parameters<typeof scope.sessions.get>[0]
       const live = scope.sessions.get(id)?.header
       const stored = live ? undefined : await scope.get('sessionPersistence')?.stat(sessionId)
@@ -135,6 +182,8 @@ export function registerGotryWebApi(ctx: Context, stateRoot: string): void {
     // it. Exact routes have one body mode, so reads and bounded writes differ.
     scope.effect(() => connection.fetch.register({ path: '/api/gotry/flyai', methods: ['GET'], requestBody: 'buffered', fetch: handlers.flyai }))
     scope.effect(() => connection.fetch.register({ path: '/api/gotry/flyai/write', methods: ['POST'], requestBody: 'streaming', fetch: handlers.flyai }))
+    scope.effect(() => connection.fetch.register({ path: '/api/gotry/hbcli', methods: ['GET'], requestBody: 'buffered', fetch: handlers.hbcli }))
+    scope.effect(() => connection.fetch.register({ path: '/api/gotry/hbcli/write', methods: ['POST'], requestBody: 'streaming', fetch: handlers.hbcli }))
     scope.effect(() => connection.fetch.register({ path: '/api/gotry/artifacts', methods: ['GET'], requestBody: 'buffered', fetch: handlers.artifacts }))
   })
 }