@mohou/host 1.0.20

package/src/http/bind.ts

@@ -0,0 +1,217 @@
+import type { McpClient } from '@mohou/mcp-client'
+import type { RuntimeProvider } from '@mohou/runtime-provider'
+
+import type { CredentialProvider } from '../credentials/provider.ts'
+
+import { listedApp, type AppSummary } from '../apps/registry.ts'
+import { readActivity } from '../host/activity.ts'
+import { historyBounds } from '../history/store.ts'
+import { cachedUiBundle } from '../compile/autogen.ts'
+import { forwardFrames } from '../events/app-events.ts'
+import { compileAppStylesheet } from '../compile/sheet.ts'
+import { readAppAsset } from './asset.ts'
+import { httpLayout } from './layout.ts'
+import { readVendorFile } from './ports.ts'
+import type { LoopbackPorts } from './ports.ts'
+import { authoringTokenMatches } from './guard.ts'
+import { probeBrain, type HostPolicy } from '../host/config.ts'
+import { checkPackageUpdate, discardUpdateResult, readUpdateResult, stagePackageUpdate } from './updates.ts'
+import { McpError } from '@mohou/mcp-client'
+
+import { admitMcpText } from '../host/mcp-import.ts'
+import { CredentialError } from '../credentials/codes.ts'
+import { mcpReferenceSources, type McpLoadFailure } from '../host/mcp.ts'
+import { checkMcpEditor, readMcpEditor, readMcpImport, writeMcpEditor } from '../host/mcp-editor.ts'
+import { readAuthorMcp, revealAuthorMcp, writeAuthorMcp, type AuthorMcpLayout } from '../host/author-mcp.ts'
+import { readAuthorSkill, revealAuthorSkill, writeAuthorSkill, type AuthorSkillLayout } from '../host/author-skill.ts'
+import type { createAuthorTools } from '../tools/author.ts'
+import type { createOwnerReads } from '../owner/read.ts'
+import type { createThemePins } from '../theme/pin.ts'
+
+type Author = ReturnType<typeof createAuthorTools>
+
+interface OwnerSlice {
+  reloadView: (appId: string) => Promise<void>
+  runnerDocument: (appId: string) => Promise<string>
+  readHistory: ReturnType<typeof createOwnerReads>['readHistory']
+  readCommit: ReturnType<typeof createOwnerReads>['readCommit']
+  readStorage: ReturnType<typeof createOwnerReads>['readStorage']
+  readTable: ReturnType<typeof createOwnerReads>['readTable']
+  themes: ReturnType<typeof createThemePins>
+}
+
+interface RegistrySlice {
+  get: (appId: string) => Promise<AppSummary>
+  list: () => Promise<{ apps: AppSummary[] }>
+  listTrash: () => Promise<AppSummary[]>
+}
+
+/**
+ * Project the live session onto the loopback routes. Does not open a socket.
+ * @param input - the session pieces the routes call
+ */
+export function bindLoopback(input: {
+  readonly author: Author
+  readonly owner: OwnerSlice
+  readonly registry: RegistrySlice
+  /** Live MCP sessions. A written server file is handed to this client, so it takes effect now. */
+  readonly mcp: McpClient
+  readonly policy: () => HostPolicy
+  readonly writePolicy: (raw: unknown) => Promise<{ policy: HostPolicy; restartRequired: boolean }>
+  readonly probe: (id: string) => ReturnType<typeof probeBrain>
+  readonly providers: readonly RuntimeProvider[]
+  readonly token: string
+  readonly vendorDir: string
+  readonly runtimeRoot: string
+  readonly env: NodeJS.ProcessEnv
+  /** The read port Shell injected. Only names and descriptions reach the panel surface. */
+  readonly credentials: CredentialProvider
+  /** Servers the live client left out: boot's list, replaced by every write. */
+  readonly mcpFailures: () => readonly McpLoadFailure[]
+  readonly recordMcpFailures: (failures: readonly McpLoadFailure[]) => void
+  readonly mcpImports?: Readonly<Record<string, string>>
+  readonly panel?: LoopbackPorts['panel']
+  readonly restart?: () => Promise<void>
+  readonly authorSkill?: AuthorSkillLayout
+  readonly authorMcp?: AuthorMcpLayout
+}): LoopbackPorts {
+  const skill = input.authorSkill
+  const mcpAgents = input.authorMcp
+  const authoringLive = (description: string) => ({
+    url: `http://127.0.0.1:${input.policy().hostPort}${httpLayout.mcp}`,
+    token: input.token,
+    description,
+  })
+  return {
+    list: async () => {
+      const listed = await input.registry.list()
+      const activity = readActivity(input.runtimeRoot)
+      return Promise.all(listed.apps.map(async app => ({
+        ...listedApp(app, await historyBounds(app.directory), activity.apps[app.id]),
+        pin: await input.owner.themes.readPin(app.id),
+        appFile: await input.owner.themes.appFile(app.id),
+      })))
+    },
+    listTrash: async () => {
+      const trashed = await input.registry.listTrash()
+      const activity = readActivity(input.runtimeRoot)
+      return Promise.all(trashed.map(async app => listedApp(app, await historyBounds(app.directory), activity.apps[app.id])))
+    },
+    deleteApp: appId => input.author.deleteApp(appId),
+    undeleteApp: appId => input.author.undeleteApp(appId),
+    open: (appId, title) => input.author.invoke('mini_app_open', {
+      appId,
+      ...title === undefined ? {} : { title },
+    }),
+    reload: appId => input.owner.reloadView(appId),
+    call: (appId, method, args, observe) => {
+      if (observe !== undefined) return input.author.callObserved(appId, method, args, observe)
+      return input.author.invoke('mini_app_call', {
+        appId,
+        method,
+        ...args === undefined ? {} : { args },
+      })
+    },
+    readPolicy: () => input.policy(),
+    writePolicy: raw => input.writePolicy(raw),
+    probe: id => input.probe(id),
+    providers: input.providers,
+    listPalettes: () => input.owner.themes.listPalettes(),
+    readPin: appId => input.owner.themes.readPin(appId),
+    setPin: (appId, pin) => input.owner.themes.setPin(appId, pin),
+    appFile: appId => input.owner.themes.appFile(appId),
+    readAppTheme: appId => input.owner.themes.readAppTheme(appId),
+    readHistory: appId => input.owner.readHistory(appId),
+    readCommit: (appId, commitId) => input.owner.readCommit(appId, commitId),
+    readStorage: appId => input.owner.readStorage(appId),
+    readTable: (appId, table) => input.owner.readTable(appId, table),
+    runnerDocument: appId => input.owner.runnerDocument(appId),
+    entryScript: async (appId) => {
+      const app = await input.registry.get(appId)
+      return cachedUiBundle(app.directory)
+    },
+    stylesheet: async (appId) => {
+      const app = await input.registry.get(appId)
+      return compileAppStylesheet(app.directory)
+    },
+    assetFile: async (appId, rest) => {
+      const app = await input.registry.get(appId)
+      return readAppAsset(app.directory, rest)
+    },
+    restoreStorage: appId => input.author.restoreStorage(appId),
+    readErrors: appId => input.author.errors.read(appId),
+    vendorFile: name => readVendorFile(input.vendorDir, name),
+    ...input.panel === undefined ? {} : { panel: input.panel },
+    authoringToken: input.token,
+    authorized: header => authoringTokenMatches(input.token, bearer(header)),
+    subscribeHost: listener => input.author.hostEvents.subscribe(listener),
+    subscribeFrames: listener => forwardFrames(input.author.appEvents, listener),
+    subscribeApp: (appId, since, listener) => input.author.appEvents.subscribe(appId, since, listener),
+    checkUpdate: async () => {
+      const attempt = readUpdateResult(input.runtimeRoot)
+      return {
+        ...await checkPackageUpdate(),
+        ...attempt === undefined ? {} : { lastAttempt: attempt },
+      }
+    },
+    installUpdate: (version) => {
+      stagePackageUpdate(version)
+      if (input.restart === undefined) return Promise.resolve()
+      const restart = input.restart
+      setTimeout(() => {
+        void restart()
+      }, 200)
+      return Promise.resolve()
+    },
+    ackUpdate: (at) => {
+      discardUpdateResult(input.runtimeRoot, at)
+      return Promise.resolve()
+    },
+    ...input.restart === undefined ? {} : { restart: input.restart },
+    ...skill === undefined ? {} : {
+      authorSkill: skill,
+      readAuthorSkill: customDirs => readAuthorSkill(skill, customDirs ?? []),
+      writeAuthorSkill: (agentIds, customDirs) => writeAuthorSkill(skill, agentIds, customDirs),
+      revealAuthorSkill: dest => revealAuthorSkill(skill, dest),
+    },
+    ...mcpAgents === undefined ? {} : {
+      authorMcp: mcpAgents,
+      readAuthorMcp: () => readAuthorMcp(mcpAgents, authoringLive('')),
+      writeAuthorMcp: (agentIds, description) => writeAuthorMcp(mcpAgents, agentIds, authoringLive(description)),
+      revealAuthorMcp: dest => revealAuthorMcp(mcpAgents, dest),
+    },
+    readMcp: async () => {
+      return { servers: await readMcpEditor(input.runtimeRoot, input.env), unresolved: input.mcpFailures() }
+    },
+    writeMcp: async (servers) => {
+      const resolved = await writeMcpEditor(input.runtimeRoot, servers, input.env, mcpReferenceSources(input.env, input.credentials))
+      await input.mcp.setServers(resolved.servers)
+      input.recordMcpFailures(resolved.failures)
+      return { unresolved: resolved.failures }
+    },
+    checkMcp: server => checkMcpEditor(server, input.env, mcpReferenceSources(input.env, input.credentials)),
+    admitMcp: text => admitMcpText(text),
+    importMcp: (source) => {
+      const file = input.mcpImports?.[source]
+      if (file === undefined) return Promise.reject(new McpError('config-invalid', `mcp import is unknown: ${source}`))
+      return readMcpImport(file)
+    },
+    readCredentials: async () => ({ credentials: await input.credentials.list(), writable: input.credentials.writable }),
+    putCredential: async (name, description, secret) => {
+      // A blank field means "keep the stored secret". Host resolves it here: the panel never reads a
+      // secret back, so it has no value to send, and the store stays a store with one write op.
+      const keep = secret === undefined || secret.length === 0 ? await input.credentials.get(name) : secret
+      if (keep === undefined || keep.length === 0) {
+        throw new CredentialError('credential-invalid', `credential has no secret to keep: ${name}`)
+      }
+      await input.credentials.put(name, description, keep)
+    },
+    removeCredential: name => input.credentials.remove(name),
+  }
+}
+
+function bearer(header: string | undefined): string | undefined {
+  if (header === undefined || !header.startsWith('Bearer ')) return undefined
+  const token = header.slice('Bearer '.length)
+  return token.length === 0 ? undefined : token
+}

package/src/http/client.ts

@@ -0,0 +1,175 @@
+import type { AppHttpRequest, AppHttpResponse } from '@mohou/contract'
+
+import { present } from '../kernel/present.ts'
+import { HttpError } from './codes.ts'
+
+/** Injected bounds. The numbers are host policy and are not locked here. */
+export interface HttpPolicy {
+  readonly timeoutMs: {
+    readonly min: number
+    readonly max: number
+    readonly default: number
+  }
+  readonly maxBodyBytes: number
+}
+
+type HttpFn = (url: string | AppHttpRequest, opts?: Omit<AppHttpRequest, 'url'>) => Promise<AppHttpResponse>
+
+/** Identifies our timer so a caller abort is not reported as a timeout. */
+class TimeoutReason extends Error {
+  readonly code = 'http-timeout'
+
+  /**
+   * @param timeoutMs - the deadline that fired
+   */
+  constructor(timeoutMs: number) {
+    super(`request timed out after ${timeoutMs}ms`)
+    this.name = 'TimeoutReason'
+  }
+}
+
+/**
+ * Build `ctx.http` for one call. 4xx and 5xx stay in the result.
+ * Policy failures throw before the socket opens.
+ * @param policy - resolved host bounds
+ * @param callSignal - this call's signal, aborted with any request signal
+ */
+export function createHttp(policy: HttpPolicy, callSignal?: AbortSignal): HttpFn {
+  return (url, opts) => request(policy, callSignal, url, opts)
+}
+
+async function request(
+  policy: HttpPolicy,
+  callSignal: AbortSignal | undefined,
+  url: string | AppHttpRequest,
+  opts?: Omit<AppHttpRequest, 'url'>,
+): Promise<AppHttpResponse> {
+  const input = typeof url === 'string' ? { url, ...opts } : url
+  const target = parseUrl(input)
+  const timeoutMs = resolveTimeout(policy, input.timeout)
+  const body = encodeBody(input.body, input.headers, policy.maxBodyBytes)
+  const timer = new AbortController()
+  const timerId = setTimeout(() => {
+    timer.abort(new TimeoutReason(timeoutMs))
+  }, timeoutMs)
+  const upstream = [callSignal, input.signal].filter((item): item is AbortSignal => item !== undefined)
+  const signal = AbortSignal.any([timer.signal, ...upstream])
+  try {
+    const response = await fetch(target, {
+      signal,
+      ...present('method', input.method),
+      ...present('headers', body.headers),
+      ...present('body', body.payload),
+    })
+    return await readResponse(response, policy.maxBodyBytes, signal)
+  } catch (error) {
+    throw classify(error, signal)
+  } finally {
+    clearTimeout(timerId)
+  }
+}
+
+function parseUrl(input: AppHttpRequest): URL {
+  let target: URL
+  try {
+    target = new URL(input.url)
+  } catch (error) {
+    throw new HttpError('http-scheme', 'URL is not http or https', { cause: error })
+  }
+  if (target.protocol !== 'http:' && target.protocol !== 'https:') {
+    throw new HttpError('http-scheme', 'URL is not http or https')
+  }
+  for (const [key, value] of Object.entries(input.query ?? {})) {
+    if (value === undefined) continue
+    target.searchParams.append(key, String(value))
+  }
+  return target
+}
+
+function resolveTimeout(policy: HttpPolicy, timeout: number | undefined): number {
+  const resolved = timeout ?? policy.timeoutMs.default
+  if (resolved < policy.timeoutMs.min || resolved > policy.timeoutMs.max) {
+    throw new HttpError('http-policy', 'timeout is outside the host policy')
+  }
+  return resolved
+}
+
+function encodeBody(
+  body: unknown,
+  headers: Record<string, string> | undefined,
+  maxBodyBytes: number,
+): { payload?: string; headers?: Record<string, string> } {
+  if (body === undefined) return headers === undefined ? {} : { headers }
+  if (typeof body === 'function' || typeof body === 'symbol') {
+    throw new HttpError('http-policy', 'request body is not admissible')
+  }
+  let payload: string
+  try {
+    payload = typeof body === 'string' ? body : JSON.stringify(body)
+  } catch (error) {
+    throw new HttpError('http-policy', 'request body is not admissible', { cause: error })
+  }
+  if (Buffer.byteLength(payload) > maxBodyBytes) {
+    throw new HttpError('http-too-large', 'request body exceeds the host cap')
+  }
+  if (typeof body === 'string') return headers === undefined ? { payload } : { payload, headers }
+  return {
+    payload,
+    headers: { ...headers, 'content-type': headers?.['content-type'] ?? 'application/json' },
+  }
+}
+
+async function readResponse(response: Response, maxBodyBytes: number, signal: AbortSignal): Promise<AppHttpResponse> {
+  const declared = Number(response.headers.get('content-length'))
+  if (Number.isFinite(declared) && declared > maxBodyBytes) {
+    await response.body?.cancel()
+    throw new HttpError('http-too-large', 'response body exceeds the host cap')
+  }
+  const text = await readText(response, maxBodyBytes, signal)
+  const headers: Record<string, string> = {}
+  response.headers.forEach((value, key) => {
+    headers[key] = value
+  })
+  const type = response.headers.get('content-type') ?? ''
+  let json: unknown = null
+  if (type.includes('json')) {
+    try {
+      json = JSON.parse(text) as unknown
+    } catch {
+      json = null
+    }
+  }
+  return { ok: response.ok, status: response.status, headers, text, json }
+}
+
+async function readText(response: Response, maxBodyBytes: number, signal: AbortSignal): Promise<string> {
+  if (response.body === null) return ''
+  const reader = response.body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  try {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      total += value.byteLength
+      if (total > maxBodyBytes) {
+        throw new HttpError('http-too-large', 'response body exceeds the host cap')
+      }
+      chunks.push(value)
+    }
+  } catch (error) {
+    throw classify(error, signal)
+  } finally {
+    await reader.cancel().catch(() => undefined)
+  }
+  return Buffer.concat(chunks).toString('utf8')
+}
+
+function classify(error: unknown, signal: AbortSignal): HttpError {
+  if (error instanceof HttpError) return error
+  if (signal.reason instanceof TimeoutReason) {
+    return new HttpError('http-timeout', 'request timed out', { cause: error })
+  }
+  if (signal.aborted) return new HttpError('cancelled', 'request was cancelled', { cause: error })
+  return new HttpError('http-network', 'request failed', { cause: error })
+}

package/src/http/codes.ts

@@ -0,0 +1,29 @@
+/** Codes the HTTP call emits. */
+
+export const httpCodes = [
+  'http-timeout',
+  'http-scheme',
+  'http-too-large',
+  'http-network',
+  'http-policy',
+  'cancelled',
+] as const
+
+/** An HTTP failure. Callers match `code`. */
+export type HttpCode = (typeof httpCodes)[number]
+
+/** Failure from `ctx.http`. The message is for a person. */
+export class HttpError extends Error {
+  readonly code: HttpCode
+
+  /**
+   * @param code - one of {@link httpCodes}
+   * @param message - human text; not the match key
+   * @param options - optional `cause`
+   */
+  constructor(code: HttpCode, message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'HttpError'
+    this.code = code
+  }
+}

package/src/http/env.ts

@@ -0,0 +1,3 @@
+import type { HttpBindings } from '@hono/node-server'
+
+export type HostEnv = { Bindings: HttpBindings }

package/src/http/guard.ts

@@ -0,0 +1,20 @@
+import { timingSafeEqual } from 'node:crypto'
+
+/** A caller is loopback only for these addresses. A missing address is refused. */
+export function isLoopbackAddress(address: string | undefined): boolean {
+  if (address === undefined || address.length === 0) return false
+  const host = address.replace(/^::ffff:/, '')
+  return host === '127.0.0.1' || host === '::1' || host === 'localhost'
+}
+
+/** Compare a presented token without leaking the length in the match. */
+export function authoringTokenMatches(expected: string, presented: string | undefined): boolean {
+  if (presented === undefined) return false
+  const left = Buffer.from(expected)
+  const right = Buffer.from(presented)
+  if (left.length !== right.length) {
+    timingSafeEqual(left, left)
+    return false
+  }
+  return timingSafeEqual(left, right)
+}

package/src/http/iframe.ts

@@ -0,0 +1,212 @@
+import { parseAppId } from '@mohou/contract'
+import type { Context, Hono } from 'hono'
+
+import type { HostEnv } from './env.ts'
+import { streamSSE } from 'hono/streaming'
+
+import { platformLayout, platformModules, platformRuntimePath, platformSdkPath, platformVendorPath } from '../compile/allowlist.ts'
+import { acceptDiagnostic, DEFAULT_DIAGNOSTIC_MAX_BYTES, diagnosticLayout, type DiagnosticPorts } from '../tools/diagnostics.ts'
+import { httpLayout } from './layout.ts'
+import type { LoopbackPorts } from './ports.ts'
+import { RouteError } from './route-codes.ts'
+import { authoringDenied, errorBody, isRecord } from './reply.ts'
+
+/** Iframe document, call, platform files, and diagnostic posts. */
+export function mountIframe(app: Hono<HostEnv>, options: {
+  readonly diagnostics?: DiagnosticPorts
+  readonly loopback?: LoopbackPorts
+}): void {
+  if (options.diagnostics !== undefined) mountDiagnostics(app, options.diagnostics)
+  const ports = options.loopback
+  if (ports === undefined) return
+  app.post(httpLayout.call, c => call(c, ports))
+  app.get(platformRuntimePath(), async (c) => {
+    return script(c, await ports.vendorFile('runtime.js'))
+  })
+  app.get(platformSdkPath(), async (c) => {
+    return script(c, await ports.vendorFile('sdk.js'))
+  })
+  app.get(`${platformLayout.root}/${platformLayout.vendors}/:file`, c => vendor(c, ports))
+  app.get(`${httpLayout.runner}/:appId`, c => document(c, ports))
+  app.get(`${diagnosticLayout.root}/:appId/events`, c => events(c, (listener) => {
+    const since = Number(c.req.query('since') ?? '0')
+    return ports.subscribeApp(c.req.param('appId'), Number.isFinite(since) ? since : 0, listener)
+  }))
+  app.get(httpLayout.events, c => events(c, (listener) => {
+    const stopHost = ports.subscribeHost(listener)
+    const stopFrames = ports.subscribeFrames(listener)
+    return () => {
+      stopHost()
+      stopFrames()
+    }
+  }))
+  app.get(`${diagnosticLayout.root}/:appId/${httpLayout.ui}/${httpLayout.sheet}`, (c) => {
+    return text(c, () => ports.stylesheet(c.req.param('appId')), 'text/css; charset=utf-8')
+  })
+  app.get(`${diagnosticLayout.root}/:appId/${httpLayout.ui}/${httpLayout.entry}`, (c) => {
+    return entryModule(c, () => ports.entryScript(c.req.param('appId')))
+  })
+  app.get(`${diagnosticLayout.root}/:appId/${httpLayout.assets}/*`, c => asset(c, ports))
+  app.get(`${diagnosticLayout.root}/:appId/${diagnosticLayout.errors}`, (c) => {
+    if (!ports.authorized(c.req.header('authorization'))) return authoringDenied(c)
+    return c.json(ports.readErrors(c.req.param('appId')))
+  })
+}
+
+function mountDiagnostics(app: Hono<HostEnv>, ports: DiagnosticPorts): void {
+  const max = ports.maxBodyBytes ?? DEFAULT_DIAGNOSTIC_MAX_BYTES
+  const post = (kind: string) => async (c: Context) => {
+    const raw = await c.req.text()
+    const appId = admittedAppId(c.req.param('appId') ?? '')
+    if (appId !== undefined && Buffer.byteLength(raw) <= max) acceptDiagnostic(ports, appId, kind, raw)
+    return c.body(null, 204)
+  }
+  app.post(`${diagnosticLayout.root}/:appId/${diagnosticLayout.errors}`, post(diagnosticLayout.errors))
+  app.post(`${diagnosticLayout.root}/:appId/${diagnosticLayout.alive}`, post(diagnosticLayout.alive))
+  app.post(`${diagnosticLayout.root}/:appId/${diagnosticLayout.absent}`, post(diagnosticLayout.absent))
+  app.post(`${diagnosticLayout.root}/:appId/${diagnosticLayout.viewEval}`, post(diagnosticLayout.viewEval))
+}
+
+function callBody(result: unknown): { ok: true; value: unknown } | { ok: false; error: string } {
+  if (isRecord(result) && result.ok === true && 'value' in result) return { ok: true, value: result.value }
+  if (isRecord(result) && result.ok === false) {
+    const error = result.error
+    const message = isRecord(error) && typeof error.message === 'string'
+      ? error.message
+      : typeof error === 'string' ? error : 'call failed'
+    return { ok: false, error: message }
+  }
+  return { ok: true, value: result }
+}
+
+async function call(c: Context, ports: LoopbackPorts): Promise<Response> {
+  let body: unknown
+  try {
+    body = await c.req.json()
+  } catch {
+    return c.json({ ok: false, error: 'invalid json' }, 400)
+  }
+  if (!isRecord(body) || typeof body.appId !== 'string' || body.appId.length === 0 || typeof body.method !== 'string' || body.method.length === 0) {
+    return c.json({ ok: false, error: 'missing appId or method' }, 400)
+  }
+  const appId = body.appId
+  const method = body.method
+  const args = body.args
+  if (!wantsStream(c.req.header('accept'))) {
+    try {
+      const result = callBody(await ports.call(appId, method, args))
+      return result.ok ? c.json(result) : c.json(result, 400)
+    } catch (error) {
+      return c.json({ ok: false, error: error instanceof Error ? error.message : 'call failed' }, 400)
+    }
+  }
+  return streamSSE(c, async (sse) => {
+    let chain = Promise.resolve()
+    const write = (event: unknown): void => {
+      const next = chain.then(() => sse.writeSSE({ data: JSON.stringify(event) }))
+      chain = next.then(() => undefined, () => undefined)
+    }
+    const result = callBody(await ports.call(appId, method, args, (value) => {
+      write({ value })
+    }))
+    await chain
+    await sse.writeSSE({
+      data: JSON.stringify(result.ok ? { return: result.value } : { error: result.error }),
+    })
+  })
+}
+
+function wantsStream(header: string | undefined): boolean {
+  return (header ?? '').toLowerCase().includes('text/event-stream')
+}
+
+async function asset(c: Context, ports: LoopbackPorts): Promise<Response> {
+  const marker = `/${httpLayout.assets}/`
+  const at = c.req.path.indexOf(marker)
+  const rest = at < 0 ? '' : c.req.path.slice(at + marker.length)
+  try {
+    const file = await ports.assetFile(c.req.param('appId') ?? '', rest)
+    return new Response(file.bytes, {
+      status: 200,
+      headers: {
+        'content-type': file.type,
+        'cache-control': 'no-cache',
+      },
+    })
+  } catch (error) {
+    const status = error instanceof RouteError && error.code === 'not-found' ? 404 : 400
+    return c.json({ ok: false, error: errorBody(error) }, status)
+  }
+}
+
+async function vendor(c: Context, ports: LoopbackPorts): Promise<Response> {
+  const file = c.req.param('file') ?? ''
+  const id = file.replace(/\.js$/, '')
+  if (!platformModules.some(row => row.file === platformVendorPath(id))) {
+    const error = new RouteError('unknown-vendor', `unknown vendor: ${id}`)
+    return c.json({ ok: false, error: { code: error.code, message: error.message } }, 404)
+  }
+  try {
+    return script(c, await ports.vendorFile(file))
+  } catch (error) {
+    return c.json({ ok: false, error: errorBody(error) }, 400)
+  }
+}
+
+async function document(c: Context, ports: LoopbackPorts): Promise<Response> {
+  const appId = c.req.param('appId') ?? ''
+  return text(c, () => ports.runnerDocument(appId), 'text/html; charset=utf-8')
+}
+
+function events(c: Context, subscribe: (listener: (event: unknown) => void) => () => void): Response {
+  return streamSSE(c, async (stream) => {
+    await new Promise<void>((resolve) => {
+      const stop = subscribe((event) => {
+        void stream.writeSSE({ data: JSON.stringify(event) })
+      })
+      stream.onAbort(() => {
+        stop()
+        resolve()
+      })
+    })
+  })
+}
+
+function admittedAppId(value: string): string | undefined {
+  try {
+    return parseAppId(value)
+  } catch {
+    return undefined
+  }
+}
+
+function script(c: Context, code: string): Response {
+  return c.body(code, 200, { 'content-type': 'text/javascript; charset=utf-8' })
+}
+
+async function text(c: Context, work: () => Promise<string>, type: string): Promise<Response> {
+  try {
+    return c.body(await work(), 200, { 'content-type': type })
+  } catch (error) {
+    return c.json({ ok: false, error: errorBody(error) }, 400)
+  }
+}
+
+/**
+ * UI entry must stay a JS module. A JSON 400 makes the browser say only
+ * "Importing a module script failed" and hides the compile message.
+ */
+async function entryModule(c: Context, work: () => Promise<string>): Promise<Response> {
+  try {
+    return script(c, await work())
+  } catch (error) {
+    const { code, message } = errorBody(error)
+    const detail = code === 'failed' ? message : `${code}: ${message}`
+    return script(c, [
+      `const __mmaUiError = ${JSON.stringify(detail)}`,
+      'throw new Error(__mmaUiError)',
+      'export default function BrokenUi() { throw new Error(__mmaUiError) }',
+      '',
+    ].join('\n'))
+  }
+}