@mohou/host 1.0.20

package/src/host/session.ts

@@ -0,0 +1,358 @@
+import { mkdtempSync } from 'node:fs'
+import { mkdir } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { builtinWorkbenchId } from '@mohou/contract'
+import { McpClient } from '@mohou/mcp-client'
+import type { RuntimeProvider } from '@mohou/runtime-provider'
+
+import { createAppRegistry, listedApp, type ListedApp } from '../apps/registry.ts'
+import { ensureRuntimeAppsLayout } from '../apps/startup-seed.ts'
+import { readActivity } from './activity.ts'
+import { historyBounds } from '../history/store.ts'
+import { ensureVendorFiles, vendorOutputDir } from '../compile/build-vendor.ts'
+import { renderRunnerDocument } from '../compile/runner.ts'
+import { bindLoopback } from '../http/bind.ts'
+import { appResource, httpLayout } from '../http/layout.ts'
+import { createOwnerReads, reloadView } from '../owner/read.ts'
+import { resolveFirstPaint } from '../theme/paint.ts'
+import { createThemePins, type AppPin } from '../theme/pin.ts'
+import { createBash } from '../bash/client.ts'
+import { createHttp } from '../http/client.ts'
+import { readMetrics } from '../metrics/read.ts'
+import { createPwsh } from '../pwsh/client.ts'
+import type { CommandPolicy } from '../shell/command.ts'
+import { createAuthorTools, ensureAuthoringToken, readAuthoringToken } from '../tools/author.ts'
+import { startAuthorHttp } from '../tools/http.ts'
+import { emptyCredentials, type CredentialProvider } from '../credentials/provider.ts'
+import type { AuthorMcpLayout } from './author-mcp.ts'
+import type { AuthorSkillLayout } from './author-skill.ts'
+import { ConfigError } from './codes.ts'
+import { probeBrain, resolveHostConfig, writeHostPolicy, type HostPolicy, type HostSeed } from './config.ts'
+import { allocateHostPort, PortInUseError } from './port.ts'
+import { homeThemesDir, hostAppsDir, hostTrashDir } from './layout.ts'
+import { createHostLog, type HostLog } from './log.ts'
+import { loadMcpServers, mcpReferenceSources, type McpLoadFailure } from './mcp.ts'
+import { createAppWorkbench } from './workbench.ts'
+
+/** Command and HTTP bounds for a booted host. Not locked numbers. */
+const commandPolicy: CommandPolicy = { timeoutMs: 30_000, maxOutputBytes: 1_000_000 }
+const httpPolicy = {
+  timeoutMs: { min: 1, max: 60_000, default: 10_000 },
+  maxBodyBytes: 1_000_000,
+}
+
+export interface HostSession {
+  readonly policy: HostPolicy
+  readonly author: ReturnType<typeof createAuthorTools>
+  readonly log: HostLog
+  readonly owner: ReturnType<typeof createOwnerReads> & {
+    reloadView(appId: string): Promise<void>
+    runnerDocument(appId: string): Promise<string>
+    themes: ReturnType<typeof createThemePins>
+    readPolicy(): HostPolicy
+    writePolicy(raw: unknown): Promise<{ policy: HostPolicy; restartRequired: boolean }>
+    probe(id: string): ReturnType<typeof probeBrain>
+    list(): Promise<ListedApp[]>
+    open(appId: string, title?: string): Promise<unknown>
+    deleteApp(appId: string): Promise<void>
+    undeleteApp(appId: string): Promise<unknown>
+    listTrash(): Promise<ListedApp[]>
+    restoreStorage(appId: string): Promise<void>
+  }
+  bindFrame(post: (message: unknown) => void): () => void
+  start(): Promise<{ port: number }>
+  dispose(): Promise<void>
+}
+
+function brainConfig(policy: HostPolicy): NonNullable<HostPolicy['runtimeProvider']['config']> {
+  const config = policy.runtimeProvider.config ?? {}
+  if (policy.llm === null || config.provider !== undefined || config.model !== undefined) return config
+  return { ...config, provider: policy.llm.provider, model: policy.llm.model }
+}
+
+/**
+ * Boot a host without starting it. Create registers no child.
+ * Start opens the authoring listener and the injected brain. A failed start leaves neither running.
+ * @param options - runtime root, seed used only when `host.json` is missing, and the brain Shell selected
+ */
+export async function createHost(options: {
+  readonly runtimeRoot: string
+  readonly seed: HostSeed
+  readonly provider: RuntimeProvider
+  readonly providers?: readonly RuntimeProvider[]
+  readonly credentials?: CredentialProvider
+  readonly env?: NodeJS.ProcessEnv
+  readonly themesDir?: string
+  readonly panel?: { readonly html: string; readonly script: string }
+  readonly mcpImports?: Readonly<Record<string, string>>
+  readonly restart?: () => Promise<void>
+  readonly authorSkill?: AuthorSkillLayout
+  readonly authorMcp?: AuthorMcpLayout
+  /** When false, skip copying skill startup samples (tests). Default true. */
+  readonly seedStartup?: boolean
+}): Promise<HostSession> {
+  await mkdir(options.runtimeRoot, { recursive: true })
+  ensureAuthoringToken(options.runtimeRoot)
+  let policy = await resolveHostConfig(options.runtimeRoot, options.seed)
+  if (options.seedStartup !== false) {
+    await ensureRuntimeAppsLayout(options.runtimeRoot, options.authorSkill?.source)
+  } else {
+    await mkdir(hostAppsDir(options.runtimeRoot), { recursive: true })
+    await mkdir(hostTrashDir(options.runtimeRoot), { recursive: true })
+  }
+  const providers = options.providers ?? [options.provider]
+  const live = providers.find(item => item.id === policy.runtimeProvider.id)
+  if (live === undefined) {
+    throw new ConfigError('config-invalid', `runtime provider is not registered: ${policy.runtimeProvider.id}`)
+  }
+  const credentials = options.credentials ?? emptyCredentials()
+  const mcpSources = mcpReferenceSources(options.env ?? process.env, credentials)
+  const mcpLoaded = await loadMcpServers(options.runtimeRoot, options.env, mcpSources)
+  const mcp = new McpClient(mcpLoaded.servers, options.env)
+  // What the live client left out. Boot sets it, and every write replaces it, so the panel and the
+  // author list never report a boot-time answer about a file that has changed since.
+  let mcpFailures: readonly McpLoadFailure[] = mcpLoaded.failures
+  const readMcpFailures = (): readonly McpLoadFailure[] => mcpFailures
+  const recordMcpFailures = (failures: readonly McpLoadFailure[]): void => { mcpFailures = failures }
+  const bash = createBash(commandPolicy)
+  const pwsh = createPwsh(commandPolicy)
+  const registry = createAppRegistry(options.runtimeRoot)
+  const themesDir = options.themesDir ?? homeThemesDir(homedir())
+  const log = createHostLog(options.runtimeRoot)
+  const listOwnerApps = async () => {
+    const listed = await registry.list()
+    const activity = readActivity(registry.runtimeRoot)
+    return Promise.all(listed.apps.map(async app => listedApp(app, await historyBounds(app.directory), activity.apps[app.id])))
+  }
+  const author = createAuthorTools({
+    registry,
+    mcp,
+    readMcpFailures,
+    recordMcpFailures,
+    ...options.env === undefined ? {} : { env: options.env },
+    onTreeChanged: (appId) => {
+      author.hostEvents.publish({ type: 'app:reload', appId })
+    },
+    ports: {
+      credentials,
+      config: {
+        get theme() { return policy.theme },
+        get palette() { return policy.palette },
+        get locale() { return policy.locale },
+        get chatLanguage() { return policy.chatLanguage },
+        get hostPort() { return policy.hostPort },
+        get llm() { return policy.llm },
+      },
+      log: (appId, ...args) => {
+        log.write(appId, ...args)
+      },
+      push() {},
+      http: createHttp(httpPolicy),
+      bash: command => bash.run(command),
+      pwsh: command => pwsh.run(command),
+      metrics: () => Promise.resolve(readMetrics()),
+      processDirectory: process.cwd(),
+      createTemp: () => mkdtempSync(join(tmpdir(), 'mma-')),
+      provider: live,
+      workbench: createAppWorkbench({
+        listApps: () => listOwnerApps(),
+        openApp: (appId, title) => author.invoke('mini_app_open', {
+          appId,
+          ...title === undefined ? {} : { title },
+        }).then(() => undefined),
+        readDefault: () => policy.defaultWorkbenchId,
+        writeDefault: async (id) => {
+          const { defaultWorkbenchId: _gone, ...rest } = policy
+          void _gone
+          const written = await writeHostPolicy(options.runtimeRoot, policy, id === undefined ? rest : { ...rest, defaultWorkbenchId: id })
+          policy = written.policy
+          author.hostEvents.publish({ type: 'workbench:default', appId: id ?? builtinWorkbenchId })
+        },
+        locale: () => policy.locale,
+      }),
+    },
+  })
+  const themes = createThemePins(registry, themesDir)
+  const owner = {
+    ...createOwnerReads(registry),
+    themes,
+    reloadView: (appId: string) => reloadView(registry, (event) => {
+      author.hostEvents.publish(event)
+    }, appId),
+    runnerDocument: (appId: string) => runnerDocument(registry, themes, policy.palette, policy.theme, policy.locale, themesDir, appId),
+  }
+  let http: { port: number; close: () => Promise<void> } | undefined
+  let started = false
+  return {
+    get policy() {
+      return policy
+    },
+    author,
+    log,
+    owner: {
+      ...owner,
+      readPolicy: () => policy,
+      writePolicy: async (raw: unknown) => {
+        const written = await writeHostPolicy(options.runtimeRoot, policy, raw)
+        policy = written.policy
+        return written
+      },
+      probe: (id: string) => probeBrain(id, providers, live.id),
+      deleteApp: (appId: string) => author.deleteApp(appId),
+      undeleteApp: (appId: string) => author.undeleteApp(appId),
+      listTrash: async () => {
+        const trashed = await registry.listTrash()
+        const activity = readActivity(registry.runtimeRoot)
+        return Promise.all(trashed.map(async app => listedApp(app, await historyBounds(app.directory), activity.apps[app.id])))
+      },
+      restoreStorage: (appId: string) => author.restoreStorage(appId),
+      list: () => listOwnerApps(),
+      open: (appId: string, title?: string) => author.invoke('mini_app_open', {
+        appId,
+        ...title === undefined ? {} : { title },
+      }),
+    },
+    bindFrame(post) {
+      for (const row of author.appEvents.retained()) {
+        if (row.gap !== undefined) post({ type: 'app:gap', appId: row.appId, since: row.gap.since })
+        for (const event of row.events) post({ appId: row.appId, name: event.name, data: event.data, seq: event.seq })
+      }
+      const stopHost = author.hostEvents.subscribe((event) => {
+        if (event.type === 'app:reload' || event.type === 'app:eval') post(event)
+      })
+      const stopAuthor = author.appEvents.observe((appId, event) => {
+        post({ appId, name: event.name, data: event.data, seq: event.seq })
+      })
+      return () => {
+        stopHost()
+        stopAuthor()
+      }
+    },
+    async start() {
+      if (http !== undefined) return { port: http.port }
+      live.configure?.(brainConfig(policy))
+      const preferred = policy.hostPort
+      try {
+        await live.start()
+        started = true
+        const token = await readAuthoringToken(options.runtimeRoot)
+        const vendorDir = vendorOutputDir()
+        await ensureVendorFiles(vendorDir)
+        http = await startAuthorHttp({
+          author,
+          token,
+          port: preferred,
+          diagnostics: {
+            recordError: (appId, raw) => {
+              author.errors.record(appId, raw)
+            },
+            markAlive: (appId) => {
+              author.views.markAlive(appId)
+            },
+            markAbsent: (appId) => {
+              author.views.absent(appId)
+            },
+            answerView: (requestId, appId, raw) => {
+              return author.views.answer(requestId, appId, raw)
+            },
+          },
+          loopback: bindLoopback({
+            author,
+            owner,
+            registry,
+            mcp,
+            policy: () => policy,
+            writePolicy: async (raw) => {
+              const written = await writeHostPolicy(options.runtimeRoot, policy, raw)
+              policy = written.policy
+              return written
+            },
+            probe: id => probeBrain(id, providers, live.id),
+            providers,
+            token,
+            vendorDir,
+            runtimeRoot: options.runtimeRoot,
+            env: options.env ?? process.env,
+            credentials,
+            mcpFailures: readMcpFailures,
+            recordMcpFailures,
+            ...options.mcpImports === undefined ? {} : { mcpImports: options.mcpImports },
+            ...options.restart === undefined ? {} : { restart: options.restart },
+            ...options.authorSkill === undefined ? {} : { authorSkill: options.authorSkill },
+            ...options.authorMcp === undefined ? {} : { authorMcp: options.authorMcp },
+            ...options.panel === undefined ? {} : {
+              panel: {
+                html: options.panel.html,
+                script: options.panel.script,
+                paint: async () => {
+                  const painted = await resolveFirstPaint({
+                    appDir: options.runtimeRoot,
+                    pin: { kind: 'follow-host' },
+                    hostPalette: policy.palette,
+                    themesDir,
+                  })
+                  return { style: painted.style, appearance: policy.theme }
+                },
+              },
+            },
+          }),
+        })
+      } catch (error) {
+        if (started) await live.stop().catch(() => undefined)
+        started = false
+        http = undefined
+        throw await listenError(error, preferred)
+      }
+      return { port: http.port }
+    },
+    async dispose() {
+      const close = http?.close()
+      http = undefined
+      await close?.catch(() => undefined)
+      await author.settle()
+      if (started) await live.stop().catch(() => undefined)
+      started = false
+      await mcp.dispose()
+      await bash.dispose()
+      await pwsh.dispose()
+      author.dispose()
+    },
+  }
+}
+
+async function runnerDocument(
+  registry: { get: (appId: string) => Promise<{ id: string; directory: string }> },
+  themes: { readPin: (appId: string) => Promise<AppPin> },
+  hostPalette: string,
+  appearance: 'system' | 'light' | 'dark',
+  locale: string,
+  themesDir: string,
+  appId: string,
+): Promise<string> {
+  const app = await registry.get(appId)
+  const paint = await resolveFirstPaint({
+    appDir: app.directory,
+    pin: await themes.readPin(app.id),
+    hostPalette,
+    themesDir,
+  })
+  return renderRunnerDocument({
+    appId: app.id,
+    entry: appResource(app.id, httpLayout.ui, httpLayout.entry),
+    style: paint.style,
+    appearance,
+    locale,
+  })
+}
+
+async function listenError(error: unknown, port: number): Promise<unknown> {
+  if (!isCode(error, 'EADDRINUSE')) return error
+  const suggestedPort = await allocateHostPort(port + 1)
+  return new PortInUseError(port, suggestedPort)
+}
+
+function isCode(error: unknown, code: string): boolean {
+  return typeof error === 'object' && error !== null && 'code' in error && error.code === code
+}

package/src/host/workbench.ts

@@ -0,0 +1,38 @@
+import { builtinWorkbenchId, workbenchEntries, type AppListItem, type AppWorkbench } from '@mohou/contract'
+
+/**
+ * Backend desk for one workbench app.
+ * A rejected id does not write. `default` clears the stored id.
+ */
+export function createAppWorkbench(ports: {
+  listApps(): Promise<readonly AppListItem[]>
+  openApp(appId: string, title?: string): Promise<void>
+  readDefault(): string | undefined
+  writeDefault(id: string | undefined): Promise<void>
+  locale(): string
+}): AppWorkbench {
+  return {
+    listApps: () => ports.listApps(),
+    openApp: (appId, title) => title === undefined ? ports.openApp(appId) : ports.openApp(appId, title),
+    async listWorkbenches() {
+      const apps = await ports.listApps()
+      return workbenchEntries(apps, ports.readDefault(), builtinName(ports.locale()))
+    },
+    async setDefaultWorkbench(id: string) {
+      if (id === builtinWorkbenchId) {
+        await ports.writeDefault(undefined)
+        return
+      }
+      const apps = await ports.listApps()
+      const app = apps.find(item => item.id === id)
+      if (app === undefined || app.kind !== 'workbench') {
+        throw new Error('workbench is not available')
+      }
+      await ports.writeDefault(id)
+    },
+  }
+}
+
+function builtinName(locale: string): string {
+  return locale === 'zh-CN' ? '小程序库' : 'Library'
+}

package/src/http/app.ts

@@ -0,0 +1,46 @@
+import { Hono } from 'hono'
+
+import { type createAuthorTools } from '../tools/author.ts'
+import type { DiagnosticPorts } from '../tools/diagnostics.ts'
+import { isLoopbackAddress } from './guard.ts'
+import { mountAuthor } from './author.ts'
+import type { HostEnv } from './env.ts'
+import { mountIframe } from './iframe.ts'
+import { mountOwner } from './owner.ts'
+import type { LoopbackPorts } from './ports.ts'
+
+type AuthorTools = ReturnType<typeof createAuthorTools>
+
+/**
+ * One loopback app. Author, owner, and iframe are separate mounts.
+ * @param options - the tool implementation, the token, and the owner ports when the session has them
+ */
+export function createLoopbackApp(options: {
+  readonly author: AuthorTools
+  readonly token: string
+  readonly diagnostics?: DiagnosticPorts
+  readonly loopback?: LoopbackPorts
+}): Hono<HostEnv> {
+  const app = new Hono<HostEnv>()
+  app.use('*', async (c, next) => {
+    const address = c.env.incoming.socket.remoteAddress
+    if (!isLoopbackAddress(address)) {
+      return c.json({ ok: false, error: { code: 'authoring-loopback', message: 'authoring caller is not loopback' } }, 403)
+    }
+    await next()
+  })
+  mountIframe(app, {
+    ...options.diagnostics === undefined ? {} : { diagnostics: options.diagnostics },
+    ...options.loopback === undefined ? {} : { loopback: options.loopback },
+  })
+  if (options.loopback !== undefined) mountOwner(app, options.loopback)
+  mountAuthor(app, options.author, options.token)
+  app.notFound((c) => {
+    const authorRoute = c.req.path === '/mcp' || c.req.path.startsWith('/api/tools')
+    if (authorRoute) {
+      return c.json({ ok: false, error: { code: 'unknown-tool', message: 'authoring route is not mounted' } }, 404)
+    }
+    return c.json({ ok: false, error: { code: 'not-found', message: 'route is not mounted' } }, 404)
+  })
+  return app
+}

package/src/http/asset.ts

@@ -0,0 +1,49 @@
+import { lstat, readFile, realpath } from 'node:fs/promises'
+import path from 'node:path'
+
+import { appTrees } from '@mohou/contract'
+
+import { admitAssetInner, assetMediaType } from '../compile/asset-path.ts'
+import { RouteError } from './route-codes.ts'
+
+export interface AppAsset {
+  readonly bytes: Uint8Array<ArrayBuffer>
+  readonly type: string
+}
+
+/**
+ * Read one file under `assets/`. Missing, escaped, or illegal paths are `not-found`.
+ * @param appDir - absolute app directory
+ * @param rest - path after `/assets/`
+ */
+export async function readAppAsset(appDir: string, rest: string): Promise<AppAsset> {
+  let inner: string
+  try {
+    inner = admitAssetInner(rest)
+  } catch (error) {
+    throw missing(error)
+  }
+  let root: string
+  try {
+    root = await realpath(path.join(appDir, appTrees.assets))
+  } catch (error) {
+    throw missing(error)
+  }
+  let real: string
+  try {
+    real = await realpath(path.resolve(root, inner))
+  } catch (error) {
+    throw missing(error)
+  }
+  const rel = path.relative(root, real)
+  if (rel.startsWith('..') || path.isAbsolute(rel)) throw missing()
+  const info = await lstat(real).catch(() => undefined)
+  if (info === undefined || !info.isFile()) throw missing()
+  return { bytes: new Uint8Array(await readFile(real)), type: assetMediaType(inner) }
+}
+
+function missing(cause?: unknown): RouteError {
+  return cause === undefined
+    ? new RouteError('not-found', 'asset is missing')
+    : new RouteError('not-found', 'asset is missing', { cause })
+}

package/src/http/author.ts

@@ -0,0 +1,157 @@
+import { randomUUID } from 'node:crypto'
+
+import type { Context, Hono } from 'hono'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js'
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+
+import { isAuthorMcpTool, type createAuthorTools } from '../tools/author.ts'
+import { AuthorError } from '../tools/codes.ts'
+import { authorMcpToolList, authorToolList } from '../tools/schemas.ts'
+import type { HostEnv } from './env.ts'
+import { authoringTokenMatches } from './guard.ts'
+import { httpLayout } from './layout.ts'
+
+type AuthorTools = ReturnType<typeof createAuthorTools>
+
+/** Authoring routes. Every one requires the token. */
+export function mountAuthor(app: Hono<HostEnv>, author: AuthorTools, token: string): void {
+  app.get(httpLayout.tools, (c) => {
+    const denied = rejectToken(c, token)
+    if (denied !== undefined) return denied
+    return c.json({ tools: authorToolList() })
+  })
+  app.post(httpLayout.invoke, async (c) => {
+    const denied = rejectToken(c, token)
+    if (denied !== undefined) return denied
+    try {
+      const body = record(await c.req.json())
+      const result = await author.invoke(requiredString(body, 'name'), body.arguments ?? {})
+      return c.json({ ok: true, result })
+    } catch (error) {
+      const code = typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string'
+        ? error.code
+        : 'tool-args'
+      const message = error instanceof Error ? error.message : 'tool failed'
+      return c.json({ ok: false, error: { code, message } }, 400)
+    }
+  })
+  app.all(httpLayout.mcp, async (c) => {
+    const denied = rejectToken(c, token)
+    if (denied !== undefined) return denied
+    if (c.req.method !== 'POST' && c.req.method !== 'GET' && c.req.method !== 'DELETE') {
+      return c.json({ ok: false, error: { code: 'unknown-tool', message: 'MCP method is not part of the session lifecycle' } }, 405)
+    }
+    return handleMcp(author, c.req.raw)
+  })
+}
+
+function rejectToken(c: Context, token: string): Response | undefined {
+  const header = c.req.header('authorization')
+  const presented = header?.startsWith('Bearer ') === true ? header.slice('Bearer '.length) : undefined
+  if (presented === '' || !authoringTokenMatches(token, presented)) {
+    return c.json({ ok: false, error: { code: 'authoring-token', message: 'authoring token is missing or wrong' } }, 401)
+  }
+  return undefined
+}
+
+type McpSession = {
+  server: McpServer
+  transport: WebStandardStreamableHTTPServerTransport
+}
+
+const mcpSessions = new Map<string, McpSession>()
+
+/** Close every stored MCP session. The HTTP listener calls this on close. */
+export async function closeMcpSessions(): Promise<void> {
+  const open = [...mcpSessions.values()]
+  mcpSessions.clear()
+  await Promise.all(open.map(async (session) => {
+    await session.transport.close()
+    await session.server.close()
+  }))
+}
+
+async function handleMcp(author: AuthorTools, request: Request): Promise<Response> {
+  const sessionId = request.headers.get('mcp-session-id')
+  if (sessionId !== null && sessionId.length > 0) {
+    const found = mcpSessions.get(sessionId)
+    if (found === undefined) {
+      return Response.json({ ok: false, error: { code: 'unknown-tool', message: 'MCP session is not open' } }, { status: 404 })
+    }
+    const response = await found.transport.handleRequest(request)
+    if (request.method === 'DELETE') {
+      mcpSessions.delete(sessionId)
+      await found.transport.close()
+      await found.server.close()
+    }
+    return response
+  }
+  if (request.method !== 'POST') {
+    return Response.json({ ok: false, error: { code: 'unknown-tool', message: 'MCP session is not open' } }, { status: 404 })
+  }
+  const stateful = wantsSession(request)
+  const session = openMcpSession(author, stateful)
+  await session.server.connect(session.transport)
+  const incoming = stateful ? withJsonAccept(request) : request
+  const response = await session.transport.handleRequest(incoming)
+  const opened = response.headers.get('mcp-session-id')
+  if (opened !== null && opened.length > 0) mcpSessions.set(opened, session)
+  else {
+    await session.transport.close()
+    await session.server.close()
+  }
+  return response
+}
+
+/** SSE-only Accept opens a session. A POST that also lists JSON stays stateless. */
+function wantsSession(request: Request): boolean {
+  const accept = request.headers.get('accept') ?? ''
+  return accept.includes('text/event-stream') && !accept.includes('application/json')
+}
+
+/** The SDK POST handler requires both Accept types. Session open still uses SSE. */
+function withJsonAccept(request: Request): Request {
+  const headers = new Headers(request.headers)
+  const accept = headers.get('accept') ?? ''
+  headers.set('accept', accept.length === 0 ? 'application/json, text/event-stream' : `application/json, ${accept}`)
+  return new Request(request, { headers })
+}
+
+function openMcpSession(author: AuthorTools, stateful: boolean): McpSession {
+  const server = new McpServer({ name: 'mini-app', version: '0.0.0' }, { capabilities: { tools: {} } })
+  server.server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: authorMcpToolList() }))
+  server.server.setRequestHandler(CallToolRequestSchema, async (call) => {
+    try {
+      if (!isAuthorMcpTool(call.params.name)) {
+        throw new AuthorError('unknown-tool', `unknown tool: ${call.params.name}. Catalog: ${authorMcpToolList().map(tool => tool.name).join(', ')}`)
+      }
+      const result = await author.invoke(call.params.name, call.params.arguments ?? {})
+      return { content: [{ type: 'text', text: JSON.stringify(result) }] }
+    } catch (error) {
+      const code = typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string'
+        ? error.code
+        : 'tool-args'
+      const message = error instanceof Error ? error.message : 'tool failed'
+      return { isError: true, content: [{ type: 'text', text: JSON.stringify({ code, message }) }] }
+    }
+  })
+  const transport = new WebStandardStreamableHTTPServerTransport({
+    enableJsonResponse: !stateful,
+    ...stateful ? { sessionIdGenerator: () => randomUUID() } : {},
+  })
+  return { server, transport }
+}
+
+function record(value: unknown): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new AuthorError('tool-args', 'tool arguments must be an object')
+  }
+  return value as Record<string, unknown>
+}
+
+function requiredString(args: Record<string, unknown>, key: string): string {
+  const value = args[key]
+  if (typeof value !== 'string' || value.length === 0) throw new AuthorError('tool-args', `${key} is required`)
+  return value
+}