@mohou/host 1.0.20

package/src/http/layout.ts

@@ -0,0 +1,63 @@
+import { appEntries } from '@mohou/contract'
+
+/** Loopback paths. Spell them here. Call sites use these helpers. */
+
+export const httpLayout = {
+  apps: '/api/apps',
+  app: '/api/app',
+  events: '/api/events',
+  call: '/api/call',
+  hostConfig: '/api/host-config',
+  palettes: '/api/palettes',
+  about: '/api/about',
+  updates: '/api/updates',
+  updateInstall: '/api/updates/install',
+  updateAck: '/api/updates/ack',
+  providers: '/api/runtime-providers',
+  activate: '/api/runtime-providers/activate',
+  probe: '/api/runtime-providers/probe',
+  restart: '/api/restart',
+  authorSkill: '/api/author-skill',
+  authorSkillReveal: '/api/author-skill/reveal',
+  authorMcp: '/api/author-mcp',
+  authorMcpReveal: '/api/author-mcp/reveal',
+  mcpServers: '/api/mcp-servers',
+  mcpCheck: '/api/mcp-servers/check',
+  mcpAdmit: '/api/mcp-servers/admit',
+  mcpImport: '/api/mcp-servers/import',
+  credentials: '/api/credentials',
+  credentialRemove: '/api/credentials/remove',
+  tools: '/api/tools',
+  invoke: '/api/tools/invoke',
+  mcp: '/mcp',
+  runner: '/app',
+  trash: '/api/trash',
+  panel: '/',
+  panelScript: '/panel.js',
+  open: 'open',
+  reload: 'reload',
+  restore: 'restore',
+  restoreStorage: 'restore',
+  history: 'history',
+  storage: 'storage',
+  theme: 'theme',
+  ui: 'ui',
+  entry: 'entry.js',
+  sheet: appEntries.stylesheet,
+  assets: 'assets',
+} as const
+
+/** History list bound. Host policy, not a locked number. */
+export const historyListBound = { default: 50, max: 200 } as const
+
+export function runnerPath(appId: string): string {
+  return `${httpLayout.runner}/${encodeURIComponent(appId)}`
+}
+
+export function appResource(appId: string, ...rest: string[]): string {
+  return [httpLayout.app, encodeURIComponent(appId), ...rest.map(encodeURIComponent)].join('/')
+}
+
+export function appsResource(appId: string, ...rest: string[]): string {
+  return [httpLayout.apps, encodeURIComponent(appId), ...rest.map(encodeURIComponent)].join('/')
+}

package/src/http/owner.ts

@@ -0,0 +1,380 @@
+import type { Context, Hono } from 'hono'
+
+import type { HostEnv } from './env.ts'
+
+import type { McpEditorServer } from '../host/mcp-editor.ts'
+import { authorMcpToolList } from '../tools/schemas.ts'
+import { historyListBound, httpLayout } from './layout.ts'
+import { aboutInfo, type LoopbackPorts } from './ports.ts'
+import { authoringDenied, isPin, isRecord, mergePolicy, ok } from './reply.ts'
+
+/** Panel and owner routes. No authoring token. */
+export function mountOwner(app: Hono<HostEnv>, ports: LoopbackPorts): void {
+  if (ports.panel !== undefined) {
+    const panel = ports.panel
+    app.get(httpLayout.panel, async (c) => {
+      if (panel.paint === undefined) return c.html(panel.html)
+      const painted = await panel.paint()
+      return c.html(injectPanelPaint(panel.html, painted))
+    })
+    app.get(httpLayout.panelScript, c => c.body(panel.script, 200, {
+      'content-type': 'text/javascript; charset=utf-8',
+    }))
+  }
+  app.get(httpLayout.apps, async (c) => {
+    return c.json({ apps: await ports.list() })
+  })
+  app.get(httpLayout.trash, async (c) => {
+    return c.json({ apps: await ports.listTrash() })
+  })
+  app.get(httpLayout.palettes, async (c) => {
+    return c.json(await ports.listPalettes())
+  })
+  app.get(httpLayout.hostConfig, c => c.json({ ok: true, policy: ports.readPolicy() }))
+  app.post(httpLayout.hostConfig, (c) => {
+    const denied = rejectWithoutToken(c, ports)
+    if (denied !== undefined) return denied
+    return writeConfig(c, ports)
+  })
+  app.get(httpLayout.about, c => c.json({
+    ok: true,
+    ...aboutInfo(),
+    authoring: {
+      url: `http://127.0.0.1:${ports.readPolicy().hostPort}${httpLayout.mcp}`,
+      token: ports.authoringToken,
+      tools: authorMcpToolList().map(tool => ({ name: tool.name, description: tool.description })),
+    },
+  }))
+  app.get(httpLayout.updates, async (c) => {
+    return c.json({ ok: true, ...await ports.checkUpdate() })
+  })
+  app.post(httpLayout.updateInstall, async (c) => {
+    const denied = rejectWithoutToken(c, ports)
+    if (denied !== undefined) return denied
+    if (ports.installUpdate === undefined) {
+      return c.json({ ok: false, error: { code: 'config-invalid', message: 'update install is not available' } }, 400)
+    }
+    const body = await readBody(c)
+    const version = isRecord(body) && typeof body.version === 'string' ? body.version : ''
+    return ok(c, async () => {
+      if (ports.installUpdate === undefined) throw new Error('update install is not available')
+      if (version.length === 0) throw new Error('update version is missing')
+      await ports.installUpdate(version)
+    })
+  })
+  app.post(httpLayout.updateAck, async (c) => {
+    if (ports.ackUpdate === undefined) {
+      return c.json({ ok: false, error: { code: 'config-invalid', message: 'update acknowledgement is not available' } }, 400)
+    }
+    const body = await readBody(c)
+    const at = isRecord(body) && typeof body.at === 'number' ? body.at : undefined
+    if (at === undefined) {
+      return c.json({ ok: false, error: { code: 'config-invalid', message: 'attempt time is required' } }, 400)
+    }
+    return ok(c, () => {
+      if (ports.ackUpdate === undefined) throw new Error('update acknowledgement is not available')
+      return ports.ackUpdate(at)
+    })
+  })
+  app.get(httpLayout.providers, async c => c.json({ providers: await providerList(ports) }))
+  app.post(httpLayout.activate, (c) => {
+    const denied = rejectWithoutToken(c, ports)
+    if (denied !== undefined) return denied
+    return activate(c, ports)
+  })
+  app.post(httpLayout.probe, (c) => {
+    const denied = rejectWithoutToken(c, ports)
+    if (denied !== undefined) return denied
+    return probe(c, ports)
+  })
+  app.get(httpLayout.authorSkill, (c) => {
+    if (ports.readAuthorSkill === undefined) {
+      return c.json({ ok: false, error: { code: 'config-invalid', message: 'author skill is not available' } }, 400)
+    }
+    const custom = c.req.query('custom') ?? ''
+    const customDirs = custom.length === 0 ? [] : custom.split('\n')
+    return ok(c, async () => {
+      if (ports.readAuthorSkill === undefined) throw new Error('author skill is not available')
+      return ports.readAuthorSkill(customDirs)
+    })
+  })
+  app.post(httpLayout.authorSkill, async (c) => {
+    const denied = rejectWithoutToken(c, ports)
+    if (denied !== undefined) return denied
+    if (ports.writeAuthorSkill === undefined) {
+      return c.json({ ok: false, error: { code: 'config-invalid', message: 'author skill is not available' } }, 400)
+    }
+    const body = await readBody(c)
+    const agentIds = isRecord(body) && Array.isArray(body.agentIds) ? body.agentIds.filter((item): item is string => typeof item === 'string') : []
+    const customDirs = isRecord(body) && Array.isArray(body.customDirs) ? body.customDirs.filter((item): item is string => typeof item === 'string') : []
+    return ok(c, async () => {
+      if (ports.writeAuthorSkill === undefined) throw new Error('author skill is not available')
+      return ports.writeAuthorSkill(agentIds, customDirs)
+    })
+  })
+  app.post(httpLayout.authorSkillReveal, async (c) => {
+    if (ports.revealAuthorSkill === undefined) {
+      return c.json({ ok: false, error: { code: 'config-invalid', message: 'author skill is not available' } }, 400)
+    }
+    const body = await readBody(c)
+    const dest = isRecord(body) && typeof body.dest === 'string' ? body.dest : ''
+    return ok(c, async () => {
+      if (ports.revealAuthorSkill === undefined) throw new Error('author skill is not available')
+      await ports.revealAuthorSkill(dest)
+    })
+  })
+  app.get(httpLayout.authorMcp, (c) => {
+    if (ports.readAuthorMcp === undefined) {
+      return c.json({ ok: false, error: { code: 'config-invalid', message: 'author mcp is not available' } }, 400)
+    }
+    return ok(c, async () => {
+      if (ports.readAuthorMcp === undefined) throw new Error('author mcp is not available')
+      return ports.readAuthorMcp()
+    })
+  })
+  app.post(httpLayout.authorMcp, async (c) => {
+    const denied = rejectWithoutToken(c, ports)
+    if (denied !== undefined) return denied
+    if (ports.writeAuthorMcp === undefined) {
+      return c.json({ ok: false, error: { code: 'config-invalid', message: 'author mcp is not available' } }, 400)
+    }
+    const body = await readBody(c)
+    const agentIds = isRecord(body) && Array.isArray(body.agentIds) ? body.agentIds.filter((item): item is string => typeof item === 'string') : []
+    const description = isRecord(body) && typeof body.description === 'string' ? body.description : ''
+    return ok(c, async () => {
+      if (ports.writeAuthorMcp === undefined) throw new Error('author mcp is not available')
+      return ports.writeAuthorMcp(agentIds, description)
+    })
+  })
+  app.post(httpLayout.authorMcpReveal, async (c) => {
+    if (ports.revealAuthorMcp === undefined) {
+      return c.json({ ok: false, error: { code: 'config-invalid', message: 'author mcp is not available' } }, 400)
+    }
+    const body = await readBody(c)
+    const dest = isRecord(body) && typeof body.dest === 'string' ? body.dest : ''
+    return ok(c, async () => {
+      if (ports.revealAuthorMcp === undefined) throw new Error('author mcp is not available')
+      await ports.revealAuthorMcp(dest)
+    })
+  })
+  app.post(httpLayout.restart, (c) => {
+    const denied = rejectWithoutToken(c, ports)
+    if (denied !== undefined) return denied
+    if (ports.restart === undefined) {
+      return c.json({ ok: false, error: { code: 'config-invalid', message: 'host restart is not available' } }, 400)
+    }
+    // Delay past response flush. Disposing too soon drops the TCP body and the panel hangs on "Restarting…".
+    setTimeout(() => {
+      void ports.restart?.().catch((error: unknown) => {
+        console.error('host restart failed', error)
+      })
+    }, 400)
+    return c.json({ ok: true, result: { restarting: true } })
+  })
+  app.get(httpLayout.mcpServers, c => ok(c, () => ports.readMcp()))
+  app.post(httpLayout.mcpServers, async (c) => {
+    const denied = rejectWithoutToken(c, ports)
+    if (denied !== undefined) return denied
+    const body = await readBody(c)
+    const servers = isRecord(body) ? mcpServers(body.servers) : undefined
+    if (servers === undefined) return c.json({ ok: false, error: { code: 'config-invalid', message: 'servers are invalid' } }, 400)
+    return ok(c, () => ports.writeMcp(servers))
+  })
+  app.post(httpLayout.mcpCheck, async (c) => {
+    const denied = rejectWithoutToken(c, ports)
+    if (denied !== undefined) return denied
+    const body = await readBody(c)
+    const server = mcpServer(body)
+    if (server === undefined) return c.json({ ok: false, error: { code: 'config-invalid', message: 'server is invalid' } }, 400)
+    return ok(c, () => ports.checkMcp(server))
+  })
+  app.post(httpLayout.mcpAdmit, async (c) => {
+    const body = await readBody(c)
+    const text = isRecord(body) && typeof body.text === 'string' ? body.text : undefined
+    if (text === undefined) return c.json({ ok: false, error: { code: 'config-invalid', message: 'mcp import is empty' } }, 400)
+    return ok(c, () => Promise.resolve({ servers: ports.admitMcp(text) }))
+  })
+  app.get(`${httpLayout.mcpImport}/:source`, c => ok(c, () => ports.importMcp(c.req.param('source')).then(servers => ({ servers }))))
+  app.get(httpLayout.credentials, (c) => {
+    if (!ports.authorized(c.req.header('authorization'))) return authoringDenied(c)
+    return ok(c, () => ports.readCredentials())
+  })
+  app.post(httpLayout.credentials, async (c) => {
+    if (!ports.authorized(c.req.header('authorization'))) return authoringDenied(c)
+    const body = await readBody(c)
+    const name = isRecord(body) && typeof body.name === 'string' ? body.name : undefined
+    const secret = isRecord(body) && typeof body.secret === 'string' ? body.secret : undefined
+    const description = isRecord(body) && typeof body.description === 'string' ? body.description : ''
+    if (name === undefined) {
+      return c.json({ ok: false, error: { code: 'credential-invalid', message: 'a credential needs a name' } }, 400)
+    }
+    return ok(c, () => ports.putCredential(name, description, secret))
+  })
+  app.post(httpLayout.credentialRemove, async (c) => {
+    if (!ports.authorized(c.req.header('authorization'))) return authoringDenied(c)
+    const body = await readBody(c)
+    const name = isRecord(body) && typeof body.name === 'string' ? body.name : undefined
+    if (name === undefined) return c.json({ ok: false, error: { code: 'credential-invalid', message: 'credential name is missing' } }, 400)
+    return ok(c, () => ports.removeCredential(name))
+  })
+  app.post(`${httpLayout.apps}/:appId/${httpLayout.open}`, async (c) => {
+    const body = await readBody(c)
+    const title = isRecord(body) && typeof body.title === 'string' ? body.title : undefined
+    return ok(c, () => ports.open(c.req.param('appId'), title))
+  })
+  app.post(`${httpLayout.apps}/:appId/${httpLayout.reload}`, c => ok(c, () => ports.reload(c.req.param('appId'))))
+  app.get(`${httpLayout.apps}/:appId/${httpLayout.history}`, async (c) => {
+    const raw = Number(c.req.query('limit') ?? '')
+    const limit = Math.min(Number.isFinite(raw) && raw > 0 ? raw : historyListBound.default, historyListBound.max)
+    const nodes = await ports.readHistory(c.req.param('appId'))
+    return c.json({ commits: nodes.slice(0, limit) })
+  })
+  app.get(`${httpLayout.apps}/:appId/${httpLayout.history}/:commitId`, (c) => {
+    return ok(c, () => ports.readCommit(c.req.param('appId'), c.req.param('commitId')))
+  })
+  app.post(`${httpLayout.apps}/:appId/${httpLayout.storage}/${httpLayout.restoreStorage}`, (c) => {
+    return ok(c, () => ports.restoreStorage(c.req.param('appId')))
+  })
+  app.get(`${httpLayout.apps}/:appId/${httpLayout.storage}`, c => ok(c, () => ports.readStorage(c.req.param('appId'))))
+  app.get(`${httpLayout.apps}/:appId/${httpLayout.storage}/:table`, (c) => {
+    return ok(c, () => ports.readTable(c.req.param('appId'), c.req.param('table')))
+  })
+  app.get(`${httpLayout.apps}/:appId/${httpLayout.theme}`, c => ok(c, async () => ({
+    pin: await ports.readPin(c.req.param('appId')),
+    appFile: await ports.appFile(c.req.param('appId')),
+    appTheme: await ports.readAppTheme(c.req.param('appId')),
+  })))
+  app.post(`${httpLayout.apps}/:appId/${httpLayout.theme}`, async (c) => {
+    const body = await readBody(c)
+    if (!isPin(body)) {
+      return c.json({ ok: false, error: { code: 'theme-invalid', message: 'pin is invalid' } }, 400)
+    }
+    return ok(c, () => ports.setPin(c.req.param('appId'), body))
+  })
+  app.delete(`${httpLayout.app}/:appId`, c => ok(c, () => ports.deleteApp(c.req.param('appId'))))
+  app.post(`${httpLayout.trash}/:appId/${httpLayout.restore}`, (c) => {
+    return ok(c, () => ports.undeleteApp(c.req.param('appId')))
+  })
+}
+
+async function providerList(ports: LoopbackPorts): Promise<unknown[]> {
+  return Promise.all(ports.providers.map(async (provider) => {
+    const describe = provider.describe?.bind(provider)
+    return {
+      id: provider.id,
+      ...provider.label === undefined ? {} : { label: provider.label },
+      fields: describe?.() ?? [],
+      models: provider.models === undefined ? [] : await provider.models(),
+    }
+  }))
+}
+
+async function writeConfig(c: Context, ports: LoopbackPorts): Promise<Response> {
+  const body = await readBody(c)
+  if (!isRecord(body)) {
+    return c.json({ ok: false, error: { code: 'config-invalid', message: 'invalid json' } }, 400)
+  }
+  return ok(c, () => ports.writePolicy(mergePolicy(ports.readPolicy(), body)))
+}
+
+async function activate(c: Context, ports: LoopbackPorts): Promise<Response> {
+  const body = await readBody(c)
+  if (!isRecord(body) || typeof body.id !== 'string') {
+    return c.json({ ok: false, error: { code: 'config-invalid', message: 'provider id is required' } }, 400)
+  }
+  const current = ports.readPolicy()
+  if (!isRecord(current)) {
+    return c.json({ ok: false, error: { code: 'config-missing', message: 'host config is missing' } }, 400)
+  }
+  return ok(c, () => ports.writePolicy({
+    ...current,
+    runtimeProvider: {
+      id: body.id,
+      ...isRecord(body.config) ? { config: body.config } : {},
+    },
+  }))
+}
+
+async function probe(c: Context, ports: LoopbackPorts): Promise<Response> {
+  const body = await readBody(c)
+  const id = isRecord(body) ? body.id : undefined
+  if (typeof id !== 'string') {
+    return c.json({ ok: false, error: { code: 'provider-missing', message: 'provider id is required' } }, 400)
+  }
+  return ok(c, () => ports.probe(id))
+}
+
+function mcpServers(value: unknown): readonly McpEditorServer[] | undefined {
+  if (!Array.isArray(value)) return undefined
+  const servers: McpEditorServer[] = []
+  for (const item of value) {
+    const server = mcpServer(item)
+    if (server === undefined) return undefined
+    servers.push(server)
+  }
+  return servers
+}
+
+function mcpServer(value: unknown): McpEditorServer | undefined {
+  if (!isRecord(value) || typeof value.id !== 'string' || value.id.trim().length === 0) return undefined
+  const args = stringList(value.args)
+  const env = stringRecord(value.env)
+  const headers = stringRecord(value.headers)
+  const transport = value.transport === 'sse' || value.transport === 'streamable-http' ? value.transport : undefined
+  let server: McpEditorServer = { id: value.id }
+  if (typeof value.description === 'string' && value.description.trim().length > 0) server = { ...server, description: value.description.trim() }
+  if (value.enabled === false || value.disabled === true) server = { ...server, enabled: false }
+  if (typeof value.command === 'string') server = { ...server, command: value.command }
+  if (args !== undefined) server = { ...server, args }
+  if (env !== undefined) server = { ...server, env }
+  if (typeof value.url === 'string') server = { ...server, url: value.url }
+  if (transport !== undefined) server = { ...server, transport }
+  if (headers !== undefined) server = { ...server, headers }
+  return server
+}
+
+function stringList(value: unknown): string[] | undefined {
+  if (!Array.isArray(value) || !value.every(item => typeof item === 'string')) return undefined
+  return value
+}
+
+function stringRecord(value: unknown): Record<string, string> | undefined {
+  if (!isRecord(value)) return undefined
+  const record: Record<string, string> = {}
+  for (const [key, item] of Object.entries(value)) {
+    if (typeof item !== 'string') return undefined
+    record[key] = item
+  }
+  return record
+}
+
+/** A route that changes host configuration or spawns a configured process requires the token. */
+function rejectWithoutToken(c: Context, ports: LoopbackPorts): Response | undefined {
+  return ports.authorized(c.req.header('authorization')) ? undefined : authoringDenied(c)
+}
+
+async function readBody(c: Context): Promise<unknown> {
+  try {
+    return await c.req.json()
+  } catch {
+    return undefined
+  }
+}
+
+/** Bake the host palette into the panel document. Tailwind utilities read these variables. */
+export function injectPanelPaint(
+  html: string,
+  paint: { readonly style: string; readonly appearance: 'system' | 'light' | 'dark' },
+): string {
+  const mode = paint.appearance === 'system' ? '' : ` data-mode="${paint.appearance}"`
+  const script = paint.appearance === 'system'
+    ? `<script>
+const applyMode = () => { document.documentElement.dataset.mode = matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light' }
+applyMode()
+matchMedia('(prefers-color-scheme: dark)').addEventListener('change', applyMode)
+</script>`
+    : ''
+  return html
+    .replace('<html>', `<html${mode}>`)
+    .replace('</head>', `<style id="mma-theme">${paint.style.replaceAll('</', '<\\/')}</style>${script}</head>`)
+}

package/src/http/ports.ts

@@ -0,0 +1,114 @@
+import { readFileSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+
+import type { RuntimeProvider } from '@mohou/runtime-provider'
+
+import type { AuthorMcpLayout, AuthorMcpStatus } from '../host/author-mcp.ts'
+import type { AuthorSkillLayout, AuthorSkillStatus } from '../host/author-skill.ts'
+import { probeBrain, type HostPolicy } from '../host/config.ts'
+import type { CredentialListing } from '../credentials/provider.ts'
+import type { McpCheck, McpEditorServer } from '../host/mcp-editor.ts'
+import type { McpLoadFailure } from '../host/mcp.ts'
+import type { AppPin } from '../theme/pin.ts'
+import type { UpdateCheck } from './updates.ts'
+
+const require = createRequire(import.meta.url)
+
+export interface LoopbackApp {
+  readonly id: string
+  readonly name: string
+  readonly description: string
+  readonly version: string
+  readonly acronym: string
+  readonly tags?: readonly string[]
+  readonly createdAt?: string
+  readonly updatedAt?: string
+  readonly activity?: { readonly openCount: number; readonly lastOpenedAt: string }
+}
+
+/** Owner and iframe calls. Author routes do not use this bag. */
+export interface LoopbackPorts {
+  list(): Promise<ReadonlyArray<LoopbackApp & { pin: AppPin; appFile: boolean }>>
+  listTrash(): Promise<readonly LoopbackApp[]>
+  deleteApp(appId: string): Promise<void>
+  undeleteApp(appId: string): Promise<unknown>
+  open(appId: string, title?: string): Promise<unknown>
+  reload(appId: string): Promise<void>
+  call(appId: string, method: string, args: unknown, publish?: (value: unknown) => Promise<void> | void): Promise<unknown>
+  readPolicy(): HostPolicy
+  writePolicy(raw: unknown): Promise<{ policy: HostPolicy; restartRequired: boolean }>
+  probe(id: string): ReturnType<typeof probeBrain>
+  providers: readonly RuntimeProvider[]
+  listPalettes(): Promise<unknown>
+  readPin(appId: string): Promise<AppPin>
+  setPin(appId: string, pin: AppPin): Promise<AppPin>
+  appFile(appId: string): Promise<boolean>
+  readAppTheme(appId: string): Promise<{ name?: string; nameZh?: string; swatch: string; style: string } | null>
+  readHistory(appId: string): Promise<readonly unknown[]>
+  readCommit(appId: string, commitId: string): Promise<unknown>
+  readStorage(appId: string): Promise<unknown>
+  readTable(appId: string, table: string): Promise<unknown>
+  runnerDocument(appId: string): Promise<string>
+  entryScript(appId: string): Promise<string>
+  stylesheet(appId: string): Promise<string>
+  assetFile(appId: string, rest: string): Promise<{ bytes: Uint8Array<ArrayBuffer>; type: string }>
+  restoreStorage(appId: string): Promise<void>
+  readErrors(appId: string): unknown
+  vendorFile(file: string): Promise<string>
+  panel?: {
+    readonly html: string
+    readonly script: string
+    readonly paint?: () => Promise<{ readonly style: string; readonly appearance: 'system' | 'light' | 'dark' }>
+  }
+  authoringToken: string
+  authorized(header: string | undefined): boolean
+  subscribeHost(listener: (event: unknown) => void): () => void
+  subscribeFrames(listener: (event: unknown) => void): () => void
+  subscribeApp(appId: string, since: number, listener: (event: unknown) => void): () => void
+  checkUpdate(): Promise<UpdateCheck>
+  installUpdate?(version: string): Promise<void>
+  /** The panel showed the launcher's last attempt. The record is dropped, not shown twice. */
+  ackUpdate?(at: number): Promise<void>
+  restart?(): Promise<void>
+  authorSkill?: AuthorSkillLayout
+  readAuthorSkill?(customDirs?: readonly string[]): Promise<AuthorSkillStatus>
+  writeAuthorSkill?(agentIds: readonly string[], customDirs: readonly string[]): Promise<AuthorSkillStatus>
+  revealAuthorSkill?(dest: string): Promise<void>
+  authorMcp?: AuthorMcpLayout
+  readAuthorMcp?(): Promise<AuthorMcpStatus>
+  writeAuthorMcp?(agentIds: readonly string[], description: string): Promise<AuthorMcpStatus>
+  revealAuthorMcp?(dest: string): Promise<void>
+  readMcp(): Promise<{ servers: readonly McpEditorServer[]; unresolved: readonly McpLoadFailure[] }>
+  writeMcp(servers: readonly McpEditorServer[]): Promise<{ unresolved: readonly McpLoadFailure[] }>
+  checkMcp(server: McpEditorServer): Promise<McpCheck>
+  admitMcp(text: string): readonly McpEditorServer[]
+  importMcp(source: string): Promise<readonly McpEditorServer[]>
+  /** Names, descriptions, and whether the store accepts a write. A secret is never on this surface. */
+  readCredentials(): Promise<{ credentials: readonly CredentialListing[]; writable: boolean }>
+  /**
+   * Write one account. An absent or empty secret keeps the stored one, so an owner can fix a
+   * description without pasting a secret they may no longer hold. A name with no account and no
+   * secret has nothing to keep: `credential-invalid`.
+   */
+  putCredential(name: string, description: string, secret: string | undefined): Promise<void>
+  removeCredential(name: string): Promise<void>
+}
+
+export async function readVendorFile(dir: string, name: string): Promise<string> {
+  return readFile(`${dir}/${name}`, 'utf8')
+}
+
+export function aboutInfo(): { name: string; current: string; platform: string; private: boolean } {
+  const parsed = JSON.parse(readFileSync(require.resolve('@mohou/host/package.json'), 'utf8')) as {
+    name?: unknown
+    version?: unknown
+    private?: unknown
+  }
+  return {
+    name: typeof parsed.name === 'string' ? parsed.name : '',
+    current: typeof parsed.version === 'string' ? parsed.version : '',
+    platform: process.platform,
+    private: parsed.private === true,
+  }
+}

package/src/http/reply.ts

@@ -0,0 +1,53 @@
+import type { Context } from 'hono'
+
+import type { AppPin } from '../theme/pin.ts'
+
+export async function ok(c: Context, work: () => Promise<unknown>): Promise<Response> {
+  try {
+    return c.json({ ok: true, result: await work() })
+  } catch (error) {
+    return c.json({ ok: false, error: errorBody(error) }, 400)
+  }
+}
+
+/** The one refusal for a route that requires the authoring token. */
+export function authoringDenied(c: Context): Response {
+  return c.json({ ok: false, error: { code: 'authoring-token', message: 'authoring token is missing or wrong' } }, 401)
+}
+
+export function errorBody(error: unknown): { code: string; message: string } {
+  const code = typeof error === 'object' && error !== null && 'code' in error && typeof error.code === 'string'
+    ? error.code
+    : 'failed'
+  const message = error instanceof Error ? error.message : 'request failed'
+  return { code, message }
+}
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export function mergePolicy(current: unknown, body: Record<string, unknown>): Record<string, unknown> {
+  const base = isRecord(current) ? current : {}
+  const runtimeRoot = typeof base.runtimeRoot === 'string' ? base.runtimeRoot : undefined
+  const provider = isRecord(body.runtimeProvider) ? body.runtimeProvider : undefined
+  const previous = isRecord(base.runtimeProvider) ? base.runtimeProvider : undefined
+  return {
+    ...base,
+    ...body,
+    ...runtimeRoot === undefined ? {} : { runtimeRoot },
+    ...provider === undefined || previous === undefined ? {} : {
+      runtimeProvider: {
+        ...previous,
+        ...provider,
+        ...provider.config === undefined && previous.config !== undefined ? { config: previous.config } : {},
+      },
+    },
+  }
+}
+
+export function isPin(value: unknown): value is AppPin {
+  if (!isRecord(value) || typeof value.kind !== 'string') return false
+  if (value.kind === 'default' || value.kind === 'follow-host' || value.kind === 'app-file') return true
+  return value.kind === 'palette' && typeof value.id === 'string' && value.id.length > 0
+}

package/src/http/route-codes.ts

@@ -0,0 +1,19 @@
+/** Codes the loopback surface emits that are not a tool code. Callers match `code`. */
+
+export const routeCodes = ['not-found', 'unknown-vendor'] as const
+
+export type RouteCode = (typeof routeCodes)[number]
+
+export class RouteError extends Error {
+  readonly code: RouteCode
+
+  /**
+   * @param code - one of {@link routeCodes}
+   * @param message - human text; not the match key
+   */
+  constructor(code: RouteCode, message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = 'RouteError'
+    this.code = code
+  }
+}