@lincyaw/server 0.0.0-stage → 1.0.0-rc.1

package/src/focus.ts

@@ -0,0 +1,47 @@
+import { resolveFocus, toFocusReport } from '@lincyaw/mcp'
+import type { McpFocus } from '@lincyaw/mcp'
+import type { FocusReport, IRDocument } from '@lincyaw/kernel'
+
+const MAX_FOCUS = 50
+
+export class FocusStore {
+  readonly #latest = new Map<string, McpFocus>()
+  readonly #watchers = new Set<() => void>()
+
+  find(document?: string): McpFocus | undefined {
+    if (document !== undefined) return this.#latest.get(document)
+    let newest: McpFocus | undefined
+    for (const found of this.#latest.values()) if (!newest || found.at >= newest.at) newest = found
+    return newest
+  }
+
+  report(document: string, doc: IRDocument | undefined, reports: FocusReport[], readWorkspaceFile?: (file: string) => string): McpFocus {
+    const record = { document, focus: reports.map(report => resolveFocus(doc, document, report, undefined, readWorkspaceFile)), at: Date.now() }
+    this.#latest.set(document, record)
+    for (const watcher of this.#watchers) watcher()
+    return record
+  }
+
+  forget(document: string): void {
+    if (this.#latest.delete(document)) for (const watcher of this.#watchers) watcher()
+  }
+
+  watch(listener: () => void): () => void {
+    this.#watchers.add(listener)
+    return () => this.#watchers.delete(listener)
+  }
+}
+
+export function toFocusRequest(body: unknown): { document: string, focus: FocusReport[] } | string {
+  if (!body || typeof body !== 'object') return 'a JSON object { document, focus: [...] }'
+  const { document, focus } = body as { document?: unknown, focus?: unknown }
+  if (typeof document !== 'string') return 'the document directory (relative to the workspace root) as `document`'
+  if (!Array.isArray(focus) || focus.length > MAX_FOCUS) return `focus is a list of at most ${MAX_FOCUS}`
+  const reports: FocusReport[] = []
+  for (const item of focus) {
+    const report = toFocusReport(item)
+    if (typeof report === 'string') return report
+    reports.push(report)
+  }
+  return { document, focus: reports }
+}

package/src/http.ts

@@ -0,0 +1,188 @@
+import { timingSafeEqual } from 'node:crypto'
+import { Agent, createServer } from 'node:http'
+import { Agent as HttpsAgent } from 'node:https'
+import type { IncomingHttpHeaders, IncomingMessage, Server, ServerResponse } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import type { Duplex } from 'node:stream'
+import { getRequestListener } from '@hono/node-server'
+import { jsonResponse } from '@lincyaw/kernel'
+import { bracketIPv6 } from '@lincyaw/kernel/node'
+import { createProxyServer } from 'http-proxy-3'
+
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]'])
+
+export function normalizeHostName(host: string | null | undefined): string {
+  if (!host) return ''
+  const value = host.trim().toLowerCase()
+  if (value.startsWith('[')) return value.slice(0, value.indexOf(']') + 1)
+  if (value.indexOf(':') !== value.lastIndexOf(':')) return `[${value}]`
+  return value.replace(/:\d+$/, '')
+}
+
+export function isLoopback(host: string | null | undefined): boolean {
+  return LOOPBACK.has(normalizeHostName(host))
+}
+
+export function originHost(origin: string | null | undefined): string | undefined {
+  if (origin === null || origin === undefined) return undefined
+  try {
+    return normalizeHostName(new URL(origin).host)
+  } catch {
+    return ''
+  }
+}
+
+export function bearer(value: string | null | undefined): string | undefined {
+  const match = /^Bearer\s+(\S+)$/i.exec(value?.trim() ?? '')
+  return match?.[1]
+}
+
+export function hasBearerToken(request: Request, accessToken: string): boolean {
+  const given = Buffer.from(bearer(request.headers.get('authorization')) ?? '')
+  const own = Buffer.from(accessToken)
+  return given.length === own.length && timingSafeEqual(given, own)
+}
+
+export async function limitBody(request: Request, limit: number): Promise<Request | Response> {
+  const tooLarge = () => jsonResponse({ error: `the request body is larger than this route takes (${limit} bytes)` }, 413)
+  const declared = Number(request.headers.get('content-length') ?? Number.NaN)
+  if (declared > limit) return tooLarge()
+  if (!request.body) return request
+  const chunks: Uint8Array[] = []
+  let size = 0
+  const reader = request.body.getReader()
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    size += value.byteLength
+    if (size > limit) {
+      void drop(reader)
+      return tooLarge()
+    }
+    chunks.push(value)
+  }
+  const body = new Uint8Array(size)
+  let at = 0
+  for (const chunk of chunks) {
+    body.set(chunk, at)
+    at += chunk.byteLength
+  }
+  return new Request(request.url, { method: request.method, headers: request.headers, body, signal: request.signal })
+}
+
+async function drop(reader: ReadableStreamDefaultReader<Uint8Array>): Promise<void> {
+  try {
+    while (!(await reader.read()).done) {}
+  } catch {}
+}
+
+export function header(headers: IncomingHttpHeaders, name: string): string | undefined {
+  const value = headers[name.toLowerCase()]
+  return Array.isArray(value) ? value[0] : value
+}
+
+export async function send(res: ServerResponse, response: Response): Promise<void> {
+  res.writeHead(response.status, Object.fromEntries(response.headers))
+  res.end(Buffer.from(await response.arrayBuffer()))
+}
+
+export function refuseUpgrade(socket: Duplex, status: number): void {
+  socket.end(`HTTP/1.1 ${status} ${status === 401 ? 'Unauthorized' : status === 403 ? 'Forbidden' : 'Not Found'}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`)
+}
+
+export interface ProxyTarget {
+  target: string
+  path: string
+  headers?: Record<string, string>
+}
+
+export function createProxy() {
+  // A page loads hundreds of modules: the connections to the targets are kept and reused, not opened for each.
+  const agents = { http: new Agent({ keepAlive: true, maxSockets: 64 }), https: new HttpsAgent({ keepAlive: true, maxSockets: 64 }) }
+  const agentFor = (target: string) => (target.startsWith('https:') || target.startsWith('wss:') ? agents.https : agents.http)
+  const proxy = createProxyServer({ ws: true, xfwd: false })
+  proxy.on('error', (error: Error, _req: unknown, res: unknown) => {
+    const response = res as ServerResponse | Duplex | undefined
+    if (response && 'writeHead' in response && !response.headersSent) {
+      response.writeHead(502, { 'Content-Type': 'text/plain; charset=utf-8' })
+      response.end(`proxy error: ${error.message}`)
+    } else {
+      response?.destroy?.()
+    }
+  })
+  return {
+    web(req: IncomingMessage, res: ServerResponse, to: ProxyTarget): void {
+      req.url = to.path
+      proxy.web(req, res, { target: to.target, headers: to.headers, agent: agentFor(to.target) })
+    },
+    ws(req: IncomingMessage, socket: Duplex, head: Buffer, to: ProxyTarget): void {
+      req.url = to.path
+      proxy.ws(req, socket, head, { target: to.target, headers: to.headers, agent: agentFor(to.target) })
+    },
+    close: () => {
+      proxy.close()
+      agents.http.destroy()
+      agents.https.destroy()
+    },
+  }
+}
+
+export type Proxy = ReturnType<typeof createProxy>
+
+export type Decision =
+  | { kind: 'fetch' }
+  | { kind: 'proxy', to: ProxyTarget }
+  | { kind: 'answer', response: Response }
+
+export function nodeServer(options: {
+  decide(req: IncomingMessage): Promise<Decision>
+  decideUpgrade(req: IncomingMessage): Promise<{ to?: ProxyTarget, status?: number }>
+  fetch(request: Request, req: IncomingMessage): Promise<Response>
+  proxy: Proxy
+}): { server: Server, close(): Promise<void> } {
+  const listener = getRequestListener((request, env) => options.fetch(request, (env as { incoming: IncomingMessage }).incoming))
+  const upgrades = new Set<Duplex>()
+  const server = createServer((req, res) => {
+    void options.decide(req).then((decision) => {
+      if (res.destroyed) return
+      if (decision.kind === 'fetch') return listener(req, res)
+      if (decision.kind === 'proxy') return options.proxy.web(req, res, decision.to)
+      return send(res, decision.response)
+    }).catch((error: unknown) => {
+      if (!res.headersSent) res.writeHead(500, { 'Content-Type': 'text/plain; charset=utf-8' })
+      res.end(error instanceof Error ? error.message : String(error))
+    })
+  })
+  server.on('upgrade', (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+    upgrades.add(socket)
+    socket.once('close', () => upgrades.delete(socket))
+    void options.decideUpgrade(req).then(({ to, status }) => {
+      if (socket.destroyed) return
+      if (to) options.proxy.ws(req, socket, head, to)
+      else refuseUpgrade(socket, status ?? 404)
+    }, () => refuseUpgrade(socket, 500))
+  })
+  return {
+    server,
+    close: () => new Promise((resolve) => {
+      server.close(() => resolve())
+      server.closeAllConnections()
+      for (const socket of upgrades) socket.destroy()
+    }),
+  }
+}
+
+export function listen(server: Server, port: number, host: string): Promise<number> {
+  return new Promise((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(port, host, () => {
+      server.off('error', reject)
+      resolve((server.address() as AddressInfo).port)
+    })
+  })
+}
+
+export function urlHost(host: string): string {
+  if (host === '0.0.0.0' || host === '::') return '127.0.0.1'
+  return bracketIPv6(host)
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export type { ApprovalPolicy } from './control.ts'
+export { DiagnosticStore } from './diagnostics.ts'
+export { serverConfigKey, servedDocument } from './server-host.ts'
+export type { ServedDocument, ServedPlugin, ServerHost } from './server-host.ts'
+export { isAnyAddress } from './auth.ts'
+export { hasBearerToken, isLoopback } from './http.ts'
+export { startServer } from './server.ts'
+export type { PresmiumServer, ServerOptions } from './server.ts'

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'