@lincyaw/server 1.0.0-rc.0 → 1.0.0-rc.1

package/src/mcp-access.ts

@@ -0,0 +1,76 @@
+import { randomBytes } from 'node:crypto'
+import { LOCAL_AUTHOR } from '@lincyaw/kernel'
+import type { McpEndpoint, McpGrant } from '@lincyaw/kernel'
+import type { McpCaller } from '@lincyaw/mcp'
+
+function endedBy(response: Response, signal: AbortSignal, done: () => void): Response {
+  if (!response.body) {
+    done()
+    return response
+  }
+  const { readable, writable } = new TransformStream<Uint8Array, Uint8Array>()
+  void response.body.pipeTo(writable, { signal, preventAbort: true })
+    .catch(() => writable.close().catch(() => undefined))
+    .finally(done)
+  return new Response(readable, { status: response.status, statusText: response.statusText, headers: response.headers })
+}
+
+/**
+ * The tokens that open /mcp: this process's own (written to its state file), the grants MCP_ENDPOINT issues,
+ * and the grants the launcher asks for its agent sessions. Revoking a grant ends the event streams it opened.
+ */
+export class McpTokens {
+  readonly processMcpToken = randomBytes(24).toString('base64url')
+  readonly endpoint: McpEndpoint
+  readonly #callers = new Map<string, McpCaller>()
+  readonly #streams = new Map<string, Set<AbortController>>()
+  readonly #agentSessionGrants = new Map<string, McpGrant>()
+
+  constructor(serverUrl: () => string) {
+    this.endpoint = {
+      issue: (member, mode, issued = {}) => {
+        const mcpToken = randomBytes(24).toString('base64url')
+        this.#callers.set(mcpToken, { member, mode, ...issued.confirmed ? { confirmed: true } : {}, ...issued.document !== undefined ? { document: issued.document } : {} })
+        return { url: `${serverUrl()}/mcp`, token: mcpToken, revoke: () => this.#revoke(mcpToken) }
+      },
+    }
+  }
+
+  callerOf(mcpToken: string | undefined): McpCaller | undefined {
+    if (mcpToken === undefined) return undefined
+    return mcpToken === this.processMcpToken ? { member: LOCAL_AUTHOR, mode: 'author' } : this.#callers.get(mcpToken)
+  }
+
+  /** Ties an event stream to the grant that opened it, so that revoking the grant ends the stream. */
+  tieToGrant(mcpToken: string, response: Response): Response {
+    if (mcpToken === this.processMcpToken || !response.headers.get('content-type')?.startsWith('text/event-stream')) return response
+    if (!this.#callers.has(mcpToken)) return endedBy(response, AbortSignal.abort(), () => {})
+    const stream = new AbortController()
+    const open = this.#streams.get(mcpToken) ?? new Set()
+    this.#streams.set(mcpToken, open.add(stream))
+    return endedBy(response, stream.signal, () => open.delete(stream))
+  }
+
+  grantAgentSession(session: string, document: string): McpGrant {
+    this.#agentSessionGrants.get(session)?.revoke()
+    const grant = this.endpoint.issue(LOCAL_AUTHOR, 'author', { confirmed: true, document })
+    this.#agentSessionGrants.set(session, grant)
+    return grant
+  }
+
+  /** Revokes the grant of one agent session, or of every one; returns how many it revoked. */
+  revokeAgentSessions(session?: string): number {
+    const revoked = session === undefined ? [...this.#agentSessionGrants.keys()] : this.#agentSessionGrants.has(session) ? [session] : []
+    for (const id of revoked) {
+      this.#agentSessionGrants.get(id)!.revoke()
+      this.#agentSessionGrants.delete(id)
+    }
+    return revoked.length
+  }
+
+  #revoke(mcpToken: string): void {
+    this.#callers.delete(mcpToken)
+    for (const stream of this.#streams.get(mcpToken) ?? []) stream.abort()
+    this.#streams.delete(mcpToken)
+  }
+}

package/src/mcp-host.ts

@@ -0,0 +1,96 @@
+import { dirname } from 'node:path'
+import { isPresentingRole } from '@lincyaw/kernel'
+import type { AgentTool, Member, ServiceToken } from '@lincyaw/kernel'
+import type { McpHost, McpPluginTools, McpPosition } from '@lincyaw/mcp'
+import type { ControlChannel } from './control.ts'
+import type { FocusStore } from './focus.ts'
+import type { DiagnosticStore } from './diagnostics.ts'
+import type { ServedDocument, ServerHost } from './server-host.ts'
+
+export interface McpHostOptions {
+  serverHost?: ServerHost
+  control: ControlChannel
+  command: 'dev' | 'serve'
+  mount(document: string): Promise<ServedDocument | undefined>
+  mounted(): Promise<ServedDocument[]>
+  service<T>(token: ServiceToken<T>): T | undefined
+  focus: FocusStore
+  diagnostics: DiagnosticStore
+}
+
+function toolsOf(documents: ServedDocument[], own: McpHostOptions['service']): McpPluginTools {
+  const tools = new Map<string, AgentTool>()
+  for (const doc of documents) {
+    for (const { plugin } of doc.plugins) for (const tool of plugin.tools ?? []) if (!tools.has(tool.name)) tools.set(tool.name, tool)
+  }
+  const doc = documents[0]
+  return { tools: [...tools.values()], service: <T>(token: ServiceToken<T>) => own(token) ?? doc?.service(token) }
+}
+
+export function serverMcpHost(options: McpHostOptions): McpHost {
+  const { control } = options
+  const host = (): ServerHost => {
+    if (!options.serverHost) throw new Error('this server has no host operations')
+    return options.serverHost
+  }
+  const position = (entry: ReturnType<ControlChannel['positions']>[number]): McpPosition => {
+    const { report } = entry
+    const { slide, step, view, section, trail } = report.position!
+    return { document: entry.document, member: entry.member, slide, step, view, ...section === undefined ? {} : { section }, ...trail ? { trail } : {}, role: report.role, at: report.at }
+  }
+  return {
+    process: { command: options.command },
+    get projectAuthoring() { return options.serverHost?.projectAuthoring },
+    get authoring() { return options.serverHost?.authoring },
+    get documentHistory() { return options.serverHost?.documentHistory },
+    get authoringClients() { return options.serverHost?.authoringClients },
+    get audioAuthoring() { return options.serverHost?.audioAuthoring },
+    get imageAuthoring() { return options.serverHost?.imageAuthoring },
+    get voiceAuthoring() { return options.serverHost?.voiceAuthoring },
+    get transcriptions() { return options.serverHost?.transcriptions },
+    get transcriptionAdoption() { return options.serverHost?.transcriptionAdoption },
+    readyTools: document => options.serverHost?.agentTools?.(document) ?? { tools: [], service: options.service },
+    watchTools: listener => options.serverHost?.watchAgentTools?.(listener) ?? (() => {}),
+    documents: () => host().documents(),
+    compile: document => host().compile(document),
+    async check(document) {
+      const { doc } = await host().compile(document)
+      const irRevision = options.diagnostics.irRevision(document)
+      const findings = await host().check(document)
+      if (irRevision === options.diagnostics.irRevision(document)) {
+        const compiled = new Set(doc.diagnostics.map(finding => JSON.stringify(finding)))
+        options.diagnostics.replace({ document, origin: 'check' }, findings.filter(finding => !compiled.has(JSON.stringify(finding))), { root: host().workspaceRoot ?? dirname(doc.meta.entry), irRevision })
+      }
+      return findings
+    },
+    build: (document, build) => host().build(document, build),
+    get jobs() {
+      return options.serverHost?.jobs
+    },
+    run: (document, target, signal) => host().run(document, target, signal),
+    approve: (request, signal) => control.approvals.request(request, signal),
+    offers: kind => control.policy(kind) !== 'off',
+    approval: kind => control.policy(kind),
+    async tools(document) {
+      if (document === undefined) return toolsOf(await options.mounted(), options.service)
+      const doc = await options.mount(document)
+      return toolsOf(doc ? [doc] : [], options.service)
+    },
+    positions(document: string | undefined, member: Member) {
+      const all = control.positions({ document, viewer: member })
+      const presenting = (w: typeof all[number]) => w.member === member.id && isPresentingRole(w.report.role)
+      return [...all.filter(presenting), ...all.filter(w => !presenting(w))].map(position)
+    },
+    watchPositions: listener => control.watch(listener),
+    focus: document => options.focus.find(document),
+    watchFocus: listener => options.focus.watch(listener),
+    async diagnostics(document) {
+      return options.diagnostics.snapshot(document)
+    },
+    watchDiagnostics: listener => options.diagnostics.watch(listener),
+    classroomStatus: document => control.status(document),
+    runtime: document => control.runtime(document).map(({ window, report }) => ({ window, role: report.role, position: report.position, reported: new Date(report.at).toISOString(), status: report.status ?? {} })),
+    navigate: (document, to, member) => control.go(to, { member, document }),
+    setClassroom: (document, action, name, member) => control.setClassroom(action, name, { document, member }),
+  }
+}

package/src/mounts.ts

@@ -0,0 +1,118 @@
+import { errorMessage, prefixedLogger } from '@lincyaw/kernel'
+import type { Logger, ServerContext, ServerContribution, ServiceToken } from '@lincyaw/kernel'
+import { operatorSpeechSecrets } from '@lincyaw/kernel/node'
+import type { DiagnosticStore } from './diagnostics.ts'
+import type { ServedDocument } from './server-host.ts'
+
+export interface Mounted {
+  doc: ServedDocument
+  contributions: Map<string, ServerContribution>
+}
+
+export interface MountsOptions {
+  document(dir: string): Promise<ServedDocument | undefined>
+  ownService<T>(token: ServiceToken<T>): T | undefined
+  settings?: Record<string, Record<string, unknown>>
+  operatorDir?: string
+  env: NodeJS.ProcessEnv
+  diagnostics: DiagnosticStore
+  log: Logger
+}
+
+/** The plugins' server contributions of each document, made when a request first names the document. */
+export class Mounts {
+  readonly #options: MountsOptions
+  readonly #mounted = new Map<string, Promise<Mounted | undefined>>()
+  readonly #tearingDown = new Map<string, Promise<void>>()
+  #stopped = false
+
+  constructor(options: MountsOptions) {
+    this.#options = options
+  }
+
+  mount(dir: string): Promise<Mounted | undefined> {
+    if (this.#stopped) return Promise.resolve(undefined)
+    const known = this.#mounted.get(dir)
+    if (known) return known
+    const loading = this.#load(dir, this.#tearingDown.get(dir))
+    loading.then((found) => {
+      if (!found && this.#mounted.get(dir) === loading) this.#mounted.delete(dir)
+    }, () => {
+      if (this.#mounted.get(dir) === loading) this.#mounted.delete(dir)
+    })
+    this.#mounted.set(dir, loading)
+    return loading
+  }
+
+  async documents(): Promise<ServedDocument[]> {
+    return (await Promise.all([...this.#mounted.values()].map(known => known.catch(() => undefined)))).flatMap(m => (m ? [m.doc] : []))
+  }
+
+  async unmount(dir: string): Promise<void> {
+    const known = this.#mounted.get(dir)
+    this.#mounted.delete(dir)
+    if (!known) return this.#tearingDown.get(dir)
+    this.#options.log.debug(`unmounting the server contributions of ${dir || 'the deck'}`)
+    const stopped = this.#takeDown(known).finally(() => this.#options.diagnostics.clear(dir, 'server'))
+    this.#tearingDown.set(dir, stopped)
+    try {
+      await stopped
+    } finally {
+      if (this.#tearingDown.get(dir) === stopped) this.#tearingDown.delete(dir)
+    }
+  }
+
+  /** Mounts nothing more: every later request for a document finds none. */
+  stop(): void {
+    this.#stopped = true
+  }
+
+  async close(): Promise<void> {
+    this.stop()
+    await Promise.all([...this.#mounted.keys()].map(dir => this.unmount(dir)))
+    await Promise.all(this.#tearingDown.values())
+  }
+
+  async #load(dir: string, previous: Promise<void> | undefined): Promise<Mounted | undefined> {
+    const { diagnostics, env, log } = this.#options
+    await previous
+    const doc = await this.#options.document(dir)
+    if (!doc) return undefined
+    log.debug(`mounting the server contributions of ${dir || 'the deck'}: ${doc.plugins.filter(p => p.plugin.server).map(p => p.id).join(', ') || 'none'}`)
+    const contributions = new Map<string, ServerContribution>()
+    for (const { id, plugin, config } of doc.plugins) {
+      if (!plugin.server) continue
+      const operatorDir = this.#options.operatorDir ?? doc.operatorDir
+      const ctx: ServerContext = {
+        deckDir: doc.deckDir,
+        workspaceRoot: doc.workspaceRoot,
+        config,
+        settings: (this.#options.settings ?? doc.settings)?.[id] ?? {},
+        lang: doc.lang,
+        service: <T>(token: ServiceToken<T>) => this.#options.ownService(token) ?? doc.service(token),
+        secret: operatorSpeechSecrets(operatorDir, name => env[name]),
+        ...operatorDir ? { operatorDir } : {},
+        ...doc.home ? { home: true } : {},
+        log: prefixedLogger(log, id),
+      }
+      try {
+        contributions.set(id, await plugin.server.call(plugin, ctx))
+        diagnostics.replace({ document: dir, origin: 'server', instance: id }, [])
+      } catch (error) {
+        log.error(`plugin ${id} failed to make its server contribution: ${errorMessage(error)}`)
+        diagnostics.replace({ document: dir, origin: 'server', instance: id }, [{ checkId: id, severity: 'error', message: `plugin ${id} failed to make its server contribution: ${errorMessage(error)}` }])
+      }
+    }
+    return { doc, contributions }
+  }
+
+  async #takeDown(known: Promise<Mounted | undefined>): Promise<void> {
+    for (const [id, contribution] of (await known.catch(() => undefined))?.contributions ?? []) {
+      try {
+        await contribution.close?.()
+      } catch (error) {
+        this.#options.log.error(`the contribution of ${id} failed to close: ${errorMessage(error)}`)
+      }
+    }
+  }
+}

package/src/server-host.ts

@@ -0,0 +1,75 @@
+import type { ProjectAuthoring, DocumentHistory } from '@lincyaw/kernel'
+import type { Compilation } from '@lincyaw/compiler'
+import { pluginId } from '@lincyaw/compiler'
+import type { DocumentSummary, Finding, IRDocument, Member, OutputJobs, PresmiumNodePlugin, RunResult, ServiceToken } from '@lincyaw/kernel'
+import type { AgentTool, DocumentAuthoring, DocumentAudioAuthoring, DocumentImageAuthoring, DocumentVoiceAuthoring, DocumentTranscriptionAdoption, DocumentTranscriptions, Route } from '@lincyaw/kernel'
+
+export interface ServedPlugin {
+  id: string
+  plugin: PresmiumNodePlugin
+  config: Record<string, unknown>
+}
+
+export interface ServedDocument {
+  deckDir: string
+  workspaceRoot: string
+  lang?: string
+  plugins: ServedPlugin[]
+  service<T>(token: ServiceToken<T>): T | undefined
+  settings?: Record<string, Record<string, unknown>>
+  operatorDir?: string
+  home?: boolean
+}
+
+/** What the server contributions of a compilation depend on, as a key that changes when they must be made again. */
+export function serverConfigKey(compilation: Pick<Compilation, 'doc' | 'plugins'>): string {
+  return JSON.stringify([
+    compilation.doc.meta.lang,
+    compilation.plugins.filter(loaded => loaded.plugin).map(loaded => [pluginId(loaded), loaded.dir, loaded.entry]),
+    compilation.doc.config.presmium,
+  ])
+}
+
+export function servedDocument(compilation: Compilation): ServedDocument {
+  const { presmium } = compilation.doc.config
+  return {
+    deckDir: compilation.deckDir,
+    workspaceRoot: compilation.workspaceRoot,
+    lang: compilation.doc.meta.lang,
+    plugins: compilation.plugins.flatMap((loaded) => {
+      if (!loaded.plugin) return []
+      const config = presmium[pluginId(loaded)]
+      return [{ id: pluginId(loaded), plugin: loaded.plugin, config: config !== null && typeof config === 'object' && !Array.isArray(config) ? config as Record<string, unknown> : {} }]
+    }),
+    service: compilation.service,
+    settings: compilation.settings,
+    ...compilation.operatorDir ? { operatorDir: compilation.operatorDir } : {},
+  }
+}
+
+export interface ServerHost {
+  projectAuthoring?: ProjectAuthoring
+  authoring?: DocumentAuthoring
+  documentHistory?: DocumentHistory
+  authoringClients?: AuthoringClients
+  audioAuthoring?: DocumentAudioAuthoring
+  imageAuthoring?: DocumentImageAuthoring
+  voiceAuthoring?: DocumentVoiceAuthoring
+  transcriptions?: DocumentTranscriptions
+  transcriptionAdoption?: DocumentTranscriptionAdoption
+  /** Host-owned routes are available before a document's compiled plugin contributions. */
+  routes?: Record<string, Record<string, Route>>
+  /** Only already compiled plugin tools. This snapshot must never start or wait for compilation. */
+  agentTools?(document?: string): { tools: AgentTool[], service<T>(token: ServiceToken<T>): T | undefined }
+  watchAgentTools?(listener: (document: string) => void): () => void
+  readSource?(path: string, member: Member): Promise<{ content: string }>
+  workspaceRoot?: string
+  documents(): Promise<DocumentSummary[]>
+  compile(document: string): Promise<{ doc: IRDocument, diagnostics: Finding[] }>
+  check(document: string): Promise<Finding[]>
+  build(document: string, options?: { to?: string[] }): Promise<{ outputs: { renderer: string, outDir: string }[], findings: Finding[] }>
+  run(document: string, target: { section: string, block: string }, signal?: AbortSignal): Promise<RunResult>
+  /** The documents' builds and exports as jobs, where the host runs them so (the workspace service). */
+  jobs?: OutputJobs
+}
+import type { AuthoringClients } from '@lincyaw/kernel'

package/src/server-routes.ts

@@ -0,0 +1,203 @@
+import { randomUUID } from 'node:crypto'
+import type { IncomingMessage } from 'node:http'
+import { errorMessage, hasRole, isRecord, jsonResponse, MAX_BODY, problemResponse, sseResponse } from '@lincyaw/kernel'
+import type { AuthoringDiagnostics, CanonicalSource, Finding, Member, PreviewDiagnostics } from '@lincyaw/kernel'
+import type { McpHost } from '@lincyaw/mcp'
+import type { ControlChannel, WindowPosition } from './control.ts'
+import type { DiagnosticStore } from './diagnostics.ts'
+import { toFocusRequest } from './focus.ts'
+import type { FocusStore } from './focus.ts'
+import { hasBearerToken, limitBody } from './http.ts'
+import type { McpTokens } from './mcp-access.ts'
+import type { ServerHost } from './server-host.ts'
+
+export const SERVER_PATH = '/__presmium/presmium.server'
+
+export interface ServerRoutesOptions {
+  control: ControlChannel
+  mcpTokens: McpTokens
+  focus: FocusStore
+  diagnostics: DiagnosticStore
+  mcpHost: McpHost
+  serverHost?: ServerHost
+  launcherToken?: string
+}
+
+export interface ServerRouteContext {
+  member: Member
+  document: string
+  req: IncomingMessage
+}
+
+/** The server's own routes under SERVER_PATH: hello, control, tokens, focus and diagnostics. */
+export function createServerRouteHandler(options: ServerRoutesOptions): (request: Request, route: string, ctx: ServerRouteContext) => Promise<Response> {
+  const { control, mcpTokens, focus, diagnostics, launcherToken } = options
+  const isFromLauncher = (request: Request) => launcherToken !== undefined && hasBearerToken(request, launcherToken)
+  const hasDocument = async (serverHost: ServerHost, document: string) => (await serverHost.documents()).some(doc => doc.dir === document)
+
+  const controlRoute = async (request: Request, { member, document, req }: ServerRouteContext): Promise<Response> => {
+    if (request.method === 'GET') {
+      const query = new URL(request.url).searchParams
+      const window = query.get('window') || randomUUID()
+      const stream = control.open(window, member, document, { observer: query.get('observe') === 'approvals' })
+      req.once('close', () => stream.end())
+      return sseResponse(stream, request.signal)
+    }
+    if (request.method !== 'POST') return problemResponse(405, 'GET or POST')
+    const limited = await limitBody(request, MAX_BODY)
+    if (limited instanceof Response) return limited
+    const body: unknown = await limited.json().catch(() => undefined)
+    if (!isRecord(body)) return problemResponse(400, 'a JSON object')
+    if (body.type === 'answer' && typeof body.id === 'string') {
+      const status = control.answer(body.id, body.allow === true, member)
+      return status === 200 ? jsonResponse({ ok: true }) : problemResponse(status, status === 404 ? 'no such approval' : 'this member may not answer this approval')
+    }
+    if (body.type === 'report' && typeof body.window === 'string') {
+      const position = toWindowPosition(body.position)
+      const ok = control.report(body.window, member, { position, role: typeof body.role === 'string' ? body.role : undefined, status: isRecord(body.status) ? body.status : undefined })
+      return ok ? jsonResponse({ ok: true }) : problemResponse(404, 'unknown window')
+    }
+    return problemResponse(400, 'unknown message')
+  }
+
+  const tokensRoute = async (request: Request): Promise<Response> => {
+    if (!launcherToken) return problemResponse(403, 'session tokens are issued only to the host that started this service (PRESMIUM_SERVICE_TOKEN)')
+    if (!isFromLauncher(request)) return problemResponse(401, 'session tokens need Authorization: Bearer <the service token>')
+    const limited = await limitBody(request, MAX_BODY)
+    if (limited instanceof Response) return limited
+    const body: unknown = await limited.json().catch(() => ({}))
+    const session = isRecord(body) && typeof body.session === 'string' && body.session !== '' ? body.session : undefined
+    if (request.method === 'DELETE') return jsonResponse({ revoked: mcpTokens.revokeAgentSessions(session) })
+    if (request.method !== 'POST') return problemResponse(405, 'POST or DELETE')
+    if (!isRecord(body) || typeof body.document !== 'string' || session === undefined) return problemResponse(400, '{ document, session }')
+    const document = body.document
+    if (options.serverHost && !(await hasDocument(options.serverHost, document))) return problemResponse(404, `no document ${JSON.stringify(document)}`)
+    const grant = mcpTokens.grantAgentSession(session, document)
+    return jsonResponse({ url: grant.url, token: grant.token, document }, 201)
+  }
+
+  const focusRoute = async (request: Request, member: Member): Promise<Response> => {
+    if (request.method === 'GET') {
+      const params = new URL(request.url).searchParams
+      const found = focus.find(params.has('document') ? params.get('document')! : undefined)
+      return jsonResponse(found ? { document: found.document, focus: found.focus, reported: new Date(found.at).toISOString() } : { focus: null })
+    }
+    if (request.method !== 'POST') return problemResponse(405, 'GET or POST')
+    if (launcherToken && !isFromLauncher(request)) return problemResponse(401, 'a focus report needs Authorization: Bearer <the service token>')
+    const { serverHost } = options
+    if (!serverHost) return problemResponse(409, 'this server compiles no document')
+    const limited = await limitBody(request, MAX_BODY)
+    if (limited instanceof Response) return limited
+    const body = toFocusRequest(await limited.json().catch(() => undefined))
+    if (typeof body === 'string') return problemResponse(400, body)
+    const workspaceFocus = body.focus.filter(report => report.scope === 'workspace')
+    if (workspaceFocus.length && !hasRole(member, 'owner')) return problemResponse(403, 'workspace source selections need the owner role')
+    if (workspaceFocus.length && !serverHost.readSource) return problemResponse(400, 'this host does not read workspace source selections')
+    if (!(await hasDocument(serverHost, body.document))) return problemResponse(404, `no document ${JSON.stringify(body.document)}`)
+    try {
+      const doc = body.focus.some(report => report.scope !== 'workspace') ? (await serverHost.compile(body.document)).doc : undefined
+      const sources = new Map(await Promise.all(workspaceFocus.map(async (report) => {
+        const path = report.source!.file
+        return [path, (await serverHost.readSource!(path, member)).content] as const
+      })))
+      const record = focus.report(body.document, doc, body.focus, path => sources.get(path)!)
+      return jsonResponse({ document: record.document, focus: record.focus, reported: new Date(record.at).toISOString() })
+    } catch (error) {
+      return problemResponse(400, errorMessage(error))
+    }
+  }
+
+  const diagnosticsRoute = async (request: Request, stream: boolean, req: IncomingMessage): Promise<Response> => {
+    if (launcherToken && !isFromLauncher(request)) return problemResponse(401, 'diagnostics need Authorization: Bearer <the service token>')
+    const { serverHost } = options
+    if (!serverHost) return problemResponse(409, 'this server compiles no document')
+    const params = new URL(request.url).searchParams
+    if (request.method === 'GET') {
+      const document = params.has('document') ? params.get('document')! : undefined
+      if (document !== undefined) {
+        if (!(await hasDocument(serverHost, document))) return problemResponse(404, `no document ${JSON.stringify(document)}`)
+        await options.mcpHost.diagnostics!(document)
+      }
+      if (!stream) return jsonResponse(diagnostics.snapshot(document))
+      const connection = new AbortController()
+      req.once('close', () => connection.abort())
+      return sseResponse(diagnostics.events(document, AbortSignal.any([connection.signal, request.signal])), request.signal)
+    }
+    if (request.method !== 'POST' || stream) return problemResponse(405, stream ? 'GET' : 'GET or POST')
+    const limited = await limitBody(request, MAX_BODY)
+    if (limited instanceof Response) return limited
+    const body: unknown = await limited.json().catch(() => undefined)
+    const report = toPreviewDiagnostics(body)
+    if (typeof report === 'string') return problemResponse(400, report)
+    if (!(await hasDocument(serverHost, report.document))) return problemResponse(404, `no document ${JSON.stringify(report.document)}`)
+    return jsonResponse({ accepted: diagnostics.report(report) })
+  }
+
+  return async (request, route, ctx) => {
+    if (route === 'hello') return jsonResponse({ member: ctx.member, document: ctx.document })
+    if (route === 'control') return await controlRoute(request, ctx)
+    if (route === 'tokens') return await tokensRoute(request)
+    if (route === 'focus') return await focusRoute(request, ctx.member)
+    if (route === 'diagnostics/authoring') {
+      if (launcherToken && !isFromLauncher(request)) return problemResponse(401, 'authoring diagnostics need the service token')
+      if (!hasRole(ctx.member, 'editor')) return problemResponse(403, 'authoring diagnostics need the role editor')
+      if (request.method !== 'POST') return problemResponse(405, 'POST')
+      if (!options.serverHost?.authoring) return problemResponse(409, 'authoring diagnostics are unavailable')
+      const limited = await limitBody(request, 64 << 10)
+      if (limited instanceof Response) return limited
+      const report = toAuthoringDiagnostics(await limited.json().catch(() => undefined))
+      if (typeof report === 'string') return problemResponse(400, report)
+      if (!(await hasDocument(options.serverHost, report.document))) return problemResponse(404, 'no such authoring document')
+      diagnostics.reportAuthoring(report, ctx.member.id)
+      return jsonResponse({ accepted: true })
+    }
+    if (route === 'diagnostics' || route === 'diagnostics/events') return await diagnosticsRoute(request, route === 'diagnostics/events', ctx.req)
+    return problemResponse(404, 'not found')
+  }
+}
+
+function toAuthoringDiagnostics(body: unknown): AuthoringDiagnostics | string {
+  if (!isRecord(body) || Object.keys(body).some(key => !['document', 'instance', 'findings'].includes(key))
+    || typeof body.document !== 'string' || body.document.length > 1024 || typeof body.instance !== 'string' || !/^workbench:[a-zA-Z0-9.-]{1,80}$/.test(body.instance)
+    || !Array.isArray(body.findings) || body.findings.length > 20) return 'authoring diagnostics need document, workbench instance and at most 20 findings'
+  const findings: AuthoringDiagnostics['findings'] = []
+  for (const item of body.findings) {
+    if (!isRecord(item) || Object.keys(item).some(key => !['checkId', 'severity', 'message', 'authoringSource'].includes(key))
+      || typeof item.checkId !== 'string' || !item.checkId.startsWith('presmium.workbench.') || item.checkId.length > 100
+      || item.severity !== 'error' || typeof item.message !== 'string' || item.message.length > 600) return 'invalid authoring diagnostic'
+    let source: CanonicalSource | undefined
+    if (item.authoringSource !== undefined) {
+      const value = item.authoringSource
+      if (!isRecord(value) || Object.keys(value).some(key => !['documentId', 'version', 'fingerprint'].includes(key))
+        || !['documentId', 'version'].every(key => typeof value[key] === 'string' && (value[key] as string).length > 0 && (value[key] as string).length <= 200)
+        || typeof value.fingerprint !== 'string' || !/^[a-f\d]{16}$/.test(value.fingerprint)) return 'invalid authoring diagnostic source'
+      source = { documentId: value.documentId as string, version: value.version as string, fingerprint: value.fingerprint }
+    }
+    findings.push({ checkId: item.checkId, severity: 'error', message: item.message, ...source ? { authoringSource: source } : {} })
+  }
+  return { document: body.document, instance: body.instance, findings }
+}
+
+function toPreviewDiagnostics(body: unknown): PreviewDiagnostics | string {
+  if (!isRecord(body) || typeof body.document !== 'string' || (body.renderer !== 'web' && body.renderer !== 'slides') || typeof body.instance !== 'string' || !body.instance || typeof body.revision !== 'string' || !Array.isArray(body.findings)) return 'a preview diagnostic report needs document, renderer, instance, revision and findings'
+  const findings: Finding[] = []
+  for (const item of body.findings) {
+    if (!isRecord(item) || typeof item.checkId !== 'string' || typeof item.message !== 'string' || !['error', 'warning', 'info'].includes(String(item.severity))) return 'each diagnostic needs checkId, severity and message'
+    if (item.hint !== undefined && typeof item.hint !== 'string') return 'a diagnostic hint must be text'
+    if (item.source !== undefined && (!isRecord(item.source) || typeof item.source.file !== 'string' || (item.source.line !== undefined && (!Number.isInteger(item.source.line) || Number(item.source.line) < 1)))) return 'a diagnostic source needs a file and an optional positive line'
+    findings.push({ checkId: item.checkId, severity: item.severity as Finding['severity'], message: item.message, ...item.hint ? { hint: item.hint as string } : {}, ...item.source ? { source: item.source as Finding['source'] } : {} })
+  }
+  return { document: body.document, renderer: body.renderer, instance: body.instance, revision: body.revision, findings }
+}
+
+function toWindowPosition(value: unknown): WindowPosition | undefined {
+  if (!isRecord(value) || typeof value.slide !== 'number' || typeof value.step !== 'number') return undefined
+  const { trail } = value
+  return {
+    slide: value.slide,
+    step: value.step,
+    ...typeof value.view === 'string' ? { view: value.view } : {},
+    ...typeof value.section === 'string' ? { section: value.section } : {},
+    ...Array.isArray(trail) && trail.length <= 10_000 && trail.every(key => typeof key === 'string') ? { trail: trail as string[] } : {},
+  }
+}