@frontera-sdk/cli 1.46.6 → 1.46.7

package/src/forge/server.ts

@@ -0,0 +1,655 @@
+import {
+  type ForgeChatRequest,
+  type ForgeCreateTerminalInput,
+  type ForgeCreateThreadInput,
+  type ForgeHostId,
+  type ForgeTerminalClientMessage,
+  type ForgeWellKnown,
+} from '@frontera-sdk/forge-contracts'
+import { createUIMessageStream, createUIMessageStreamResponse, type UIMessageChunk } from 'ai'
+
+import { KIT } from '../kit'
+import type { AdapterFactory } from './adapter'
+import { ClaudeAdapter } from './claude-adapter'
+import { CodexAdapter } from './codex-adapter'
+import {
+  HOSTS,
+  type Exec,
+  defaultEffortFor,
+  firstInstalledHostId,
+  isHostId,
+  isHostMode,
+  listHosts,
+  modeIdsFor,
+} from './hosts'
+import { ForgeHttpError, badRequest, errorBody, json, notFound, okBody, readJson } from './http'
+import type { Logger } from './log'
+import { forgePath } from './env'
+import { FORGE_HEADERS, FORGE_WELL_KNOWN_PATH } from './protocol'
+import { commandsFor } from './claude-commands'
+import { skillsFor } from './claude-skills'
+import { normalizeTurnText } from './turn-text'
+import { ensureWorkspaceProject, inspectRoot, listFiles, readChanges } from './projects'
+import { RunManager } from './runs'
+import { sessionView } from './sessions'
+import { ForgeStore, type StoredThread, type ThreadPatch } from './store'
+import { TerminalManager, type TerminalClient } from './terminals'
+
+/**
+ * The daemon's HTTP surface: the Forge routes and the platform-compatible
+ * chat/session routes, documented in packages/forge-contracts/README.md.
+ *
+ * Loopback only, one bearer token, one allowed browser origin. There is no
+ * multi-tenancy to model — the process belongs to the developer who started
+ * it — so the checks are a token compare and an origin compare, nothing more.
+ */
+
+export interface ForgeServerOptions {
+  port: number
+  token: string
+  /** Browser origin allowed by CORS. Null: no browser may call (curl still can). */
+  origin: string | null
+  /** Platform API origin, for the MCP injection. '' when unknown. */
+  apiUrl: string
+  version: string
+  /** Path of the sqlite file, or ':memory:'. */
+  storePath: string
+  log: Logger
+  adapters?: AdapterFactory
+  /**
+   * How host binaries are probed. Defaults to spawning them. A test supplies
+   * its own so which harnesses happen to be installed on the machine running
+   * it cannot change the answer.
+   */
+  hostExec?: Exec
+}
+
+export interface ForgeServer {
+  port: number
+  stop(): Promise<void>
+}
+
+const ALLOW_HEADERS = 'authorization, content-type, x-workspace-id, x-org-id'
+const ALLOW_METHODS = 'GET, POST, PATCH, DELETE, OPTIONS'
+const EXPOSE_HEADERS = [FORGE_HEADERS.conversationId, FORGE_HEADERS.runId, FORGE_HEADERS.agentRuntime].join(', ')
+
+/** Under Bun's 255s ceiling and well over the 15s keepalive. */
+const IDLE_TIMEOUT_S = 255
+const KEEPALIVE_MS = 15_000
+const PING = new TextEncoder().encode(': ping\n\n')
+
+type Params = Record<string, string>
+type Handler = (req: Request, params: Params, url: URL) => Promise<Response> | Response
+
+interface Route {
+  method: string
+  segments: string[]
+  handler: Handler
+}
+
+interface WsData {
+  terminalId: string
+  client: TerminalClient | null
+}
+
+function segmentsOf(path: string): string[] {
+  return path.split('/').filter((s) => s !== '')
+}
+
+function matchRoute(route: Route, method: string, segments: string[]): Params | null {
+  if (route.method !== method || route.segments.length !== segments.length) return null
+  const params: Params = {}
+  for (let i = 0; i < segments.length; i += 1) {
+    const want = route.segments[i]!
+    const got = segments[i]!
+    if (want.startsWith(':')) params[want.slice(1)] = decodeURIComponent(got)
+    else if (want !== got) return null
+  }
+  return params
+}
+
+function withHeaders(res: Response, headers: Record<string, string>): Response {
+  const merged = new Headers(res.headers)
+  for (const [k, v] of Object.entries(headers)) merged.set(k, v)
+  return new Response(res.body, { status: res.status, statusText: res.statusText, headers: merged })
+}
+
+/**
+ * Interleave SSE comment pings so a silent tool run never trips an idle
+ * timeout — the same shape as the platform's `withSseKeepalive`. Pump-based,
+ * because pings must flow on wall time rather than on downstream demand.
+ */
+function withKeepalive(body: ReadableStream<Uint8Array>, intervalMs = KEEPALIVE_MS): ReadableStream<Uint8Array> {
+  const reader = body.getReader()
+  let timer: ReturnType<typeof setInterval> | null = null
+  const stop = () => {
+    if (timer) clearInterval(timer)
+    timer = null
+  }
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      timer = setInterval(() => {
+        try {
+          controller.enqueue(PING)
+        } catch {
+          stop()
+        }
+      }, intervalMs)
+      void (async () => {
+        try {
+          for (;;) {
+            const { done, value } = await reader.read()
+            if (done) break
+            controller.enqueue(value)
+          }
+          stop()
+          controller.close()
+        } catch (err) {
+          stop()
+          try {
+            controller.error(err)
+          } catch {
+            // Already closed.
+          }
+        }
+      })()
+    },
+    cancel(reason) {
+      stop()
+      return reader.cancel(reason)
+    },
+  })
+}
+
+/**
+ * A mode is only meaningful against the host that declared it — Claude Code's
+ * `acceptEdits` means nothing to Codex — so validation always carries a host.
+ */
+function requireHostMode(host: ForgeHostId, value: unknown): string {
+  if (!isHostMode(host, value)) {
+    throw badRequest(`mode must be one of: ${modeIdsFor(host).join(', ')}`)
+  }
+  return value
+}
+
+function optionalString(value: unknown, field: string): string | null | undefined {
+  if (value === undefined) return undefined
+  if (value === null) return null
+  if (typeof value !== 'string') throw badRequest(`${field} must be a string`)
+  return value
+}
+
+export function defaultAdapters(log: Logger): AdapterFactory {
+  return (host) => (host === 'claude' ? new ClaudeAdapter({ log }) : new CodexAdapter())
+}
+
+export function startForgeServer(opts: ForgeServerOptions): ForgeServer {
+  const { log } = opts
+  const store = new ForgeStore(opts.storePath)
+  const reaped = store.reapOrphanRuns()
+  if (reaped > 0) log.warn(`${reaped} run(s) from a previous daemon marked interrupted`)
+  const runs = new RunManager(store, opts.adapters ?? defaultAdapters(log), log, opts.apiUrl)
+  const terminals = new TerminalManager(log)
+
+  const corsHeaders = (): Record<string, string> =>
+    opts.origin
+      ? {
+          'Access-Control-Allow-Origin': opts.origin,
+          'Access-Control-Allow-Headers': ALLOW_HEADERS,
+          'Access-Control-Allow-Methods': ALLOW_METHODS,
+          'Access-Control-Expose-Headers': EXPOSE_HEADERS,
+          Vary: 'Origin',
+        }
+      : {}
+
+  const ok = <T>(data: T, headers: Record<string, string> = {}): Response => json(okBody(data), { headers })
+  const fail = (status: number, message: string, code: string): Response => json(errorBody(message, code), { status })
+
+  const requireProject = (id: string) => {
+    const project = store.getProject(id)
+    if (!project) throw notFound('project')
+    return project
+  }
+  const requireThread = (id: string) => {
+    const thread = store.getThread(id)
+    if (!thread) throw notFound('thread')
+    return thread
+  }
+
+  const routes: Route[] = []
+  const route = (method: string, path: string, handler: Handler) => {
+    routes.push({ method, segments: segmentsOf(path), handler })
+  }
+
+  // -- readiness ------------------------------------------------------------
+
+  route('GET', FORGE_WELL_KNOWN_PATH, () => {
+    const body: ForgeWellKnown = {
+      service: 'frontera-forge',
+      version: opts.version,
+      kitVersion: KIT.kitVersion ?? null,
+      pid: process.pid,
+    }
+    return ok(body)
+  })
+
+  route('GET', '/v1/forge/hosts', () => ok(listHosts(opts.hostExec)))
+
+  // -- projects -------------------------------------------------------------
+
+  route('GET', '/v1/forge/projects', () => ok(store.listProjects()))
+
+  route('POST', '/v1/forge/projects', async (req) => {
+    const body = await readJson<{ root?: unknown }>(req)
+    const detected = inspectRoot(typeof body.root === 'string' ? body.root : '')
+    const existing = store.projectByRoot(detected.root)
+    if (existing) return ok(store.refreshProject(existing.id, detected))
+    const project = store.insertProject(detected)
+    log.info(`project ${project.id} opened at ${project.root}`)
+    return ok(project)
+  })
+
+  // The managed folder for the workspace the developer is in — no picker.
+  route('POST', '/v1/forge/projects/workspace', async (req) => {
+    const body = await readJson<{ workspaceId?: unknown; workspaceSlug?: unknown; workspaceName?: unknown }>(req)
+    if (typeof body.workspaceId !== 'string' || !body.workspaceId) throw badRequest('workspaceId is required')
+    if (typeof body.workspaceSlug !== 'string' || !body.workspaceSlug) throw badRequest('workspaceSlug is required')
+    const detected = ensureWorkspaceProject(
+      {
+        workspaceId: body.workspaceId,
+        workspaceSlug: body.workspaceSlug,
+        ...(typeof body.workspaceName === 'string' ? { workspaceName: body.workspaceName } : {}),
+      },
+      opts.apiUrl || null,
+      (message) => log.warn(message),
+    )
+    const existing = store.projectByWorkspace(body.workspaceId) ?? store.projectByRoot(detected.root)
+    if (existing) return ok(store.refreshProject(existing.id, detected))
+    const project = store.insertProject(detected)
+    log.info(`workspace project ${project.id} at ${project.root}`)
+    return ok(project)
+  })
+
+  route('DELETE', '/v1/forge/projects/:id', async (_req, params) => {
+    const id = params.id!
+    requireProject(id)
+    for (const thread of store.listThreads(id)) {
+      const active = runs.activeRunFor(thread.id)
+      if (active) await runs.cancel(active)
+    }
+    store.deleteProject(id)
+    return ok({ id })
+  })
+
+  route('GET', '/v1/forge/projects/:id/threads', (_req, params) =>
+    ok(store.listThreads(params.id!).map(({ archived: _archived, ...thread }) => thread)))
+
+  route('GET', '/v1/forge/projects/:id/files', (_req, params, url) => {
+    const project = requireProject(params.id!)
+    return ok(listFiles(project.root, url.searchParams.get('path') ?? ''))
+  })
+
+  // What the composer's `/` menu lists: the skills the host would load for a
+  // session in this folder, read from the same directories the CLI reads.
+  route('GET', '/v1/forge/projects/:id/skills', (_req, params) => {
+    const project = requireProject(params.id!)
+    return ok(skillsFor(project.root))
+  })
+
+  // The host's own slash commands, from its initialization handshake.
+  route('GET', '/v1/forge/projects/:id/commands', (_req, params) => {
+    const project = requireProject(params.id!)
+    const which = (bin: string) => Bun.which(bin, { PATH: forgePath() })
+    return ok(commandsFor(project.root, which('claude'), log))
+  })
+
+  route('GET', '/v1/forge/projects/:id/changes', (_req, params) => {
+    const project = requireProject(params.id!)
+    return ok(readChanges(project.root))
+  })
+
+  // -- threads --------------------------------------------------------------
+
+  route('POST', '/v1/forge/threads', async (req) => {
+    const body = await readJson<Partial<ForgeCreateThreadInput>>(req)
+    if (typeof body.projectId !== 'string') throw badRequest('projectId is required')
+    requireProject(body.projectId)
+    if (!isHostId(body.host)) throw badRequest(`host must be one of: ${Object.keys(HOSTS).join(', ')}`)
+    const host = HOSTS[body.host]
+    const mode = body.mode === undefined ? host.defaultMode : requireHostMode(body.host, body.mode)
+    const model = optionalString(body.model, 'model') ?? host.defaultModel
+    const effort = optionalString(body.effort, 'effort')
+    const title = optionalString(body.title, 'title')
+    const { archived: _archived, ...thread } = store.insertThread({
+      projectId: body.projectId,
+      host: body.host,
+      model,
+      mode,
+      effort: effort ?? defaultEffortFor(body.host, model),
+      title: title ?? null,
+    })
+    return ok(thread)
+  })
+
+  route('GET', '/v1/forge/threads/:id', (_req, params) => {
+    const { archived: _archived, ...thread } = requireThread(params.id!)
+    return ok(thread)
+  })
+
+  route('PATCH', '/v1/forge/threads/:id', async (req, params) => {
+    const existing = requireThread(params.id!)
+    const body = await readJson<{ title?: unknown; model?: unknown; mode?: unknown; effort?: unknown }>(req)
+    const mode = body.mode === undefined ? undefined : requireHostMode(existing.host, body.mode)
+    const title = optionalString(body.title, 'title')
+    const model = optionalString(body.model, 'model')
+    const effort = optionalString(body.effort, 'effort')
+    const { archived: _archived, ...thread } = store.updateThread(params.id!, {
+      ...(title !== undefined ? { title } : {}),
+      ...(model !== undefined ? { model } : {}),
+      ...(mode !== undefined ? { mode } : {}),
+      ...(effort !== undefined ? { effort } : {}),
+    })
+    return ok(thread)
+  })
+
+  const deleteThread = async (id: string): Promise<Response> => {
+    requireThread(id)
+    const active = runs.activeRunFor(id)
+    if (active) await runs.cancel(active)
+    store.deleteThread(id)
+    return ok({ id })
+  }
+  route('DELETE', '/v1/forge/threads/:id', (_req, params) => deleteThread(params.id!))
+
+  // -- terminals ------------------------------------------------------------
+
+  // `?threadId=` is how the surface lists one session's tabs; unfiltered is
+  // every terminal the daemon owns, in the order they were opened.
+  route('GET', '/v1/forge/terminals', (_req, _params, url) => ok(terminals.list(url.searchParams.get('threadId'))))
+
+  route('POST', '/v1/forge/terminals', async (req) => {
+    const body = await readJson<Partial<ForgeCreateTerminalInput>>(req)
+    if (typeof body.projectId !== 'string') throw badRequest('projectId is required')
+    const project = requireProject(body.projectId)
+    if (body.threadId !== undefined && typeof body.threadId !== 'string') throw badRequest('threadId must be a string')
+    const title = optionalString(body.title, 'title')
+    return ok(
+      terminals.create({ ...body, projectId: body.projectId, ...(title ? { title } : {}) }, project),
+    )
+  })
+
+  route('PATCH', '/v1/forge/terminals/:id', async (req, params) => {
+    const body = await readJson<{ title?: unknown }>(req)
+    const title = optionalString(body.title, 'title')
+    if (!title) throw badRequest('title is required')
+    const renamed = terminals.rename(params.id!, title)
+    if (!renamed) throw notFound('terminal')
+    return ok(renamed)
+  })
+
+  route('DELETE', '/v1/forge/terminals/:id', (_req, params) => {
+    if (!terminals.kill(params.id!)) throw notFound('terminal')
+    return ok({ id: params.id! })
+  })
+
+  // -- chat (platform-compatible) ------------------------------------------
+
+  const sseResponse = (stream: ReadableStream<UIMessageChunk>, headers: Record<string, string>): Response => {
+    const res = createUIMessageStreamResponse({
+      stream: createUIMessageStream({
+        execute: ({ writer }) => {
+          writer.merge(stream)
+        },
+      }),
+      headers,
+    })
+    if (!res.body) return res
+    return new Response(withKeepalive(res.body), { status: res.status, headers: res.headers })
+  }
+
+  route('POST', '/v1/chat', async (req) => {
+    const body = await readJson<Partial<ForgeChatRequest>>(req)
+    /**
+     * A session is created by SENDING, not by opening a composer.
+     *
+     * The platform's chat works this way — `conversationId: 'new'` and the id
+     * comes back on the response header — and Forge matches it so the surface
+     * can reuse the same components and so an abandoned composer leaves no
+     * empty session in the list.
+     */
+    const isNew =
+      body.conversationId === undefined || body.conversationId === '' || body.conversationId === 'new'
+    let thread: StoredThread
+    if (isNew) {
+      if (typeof body.projectId !== 'string') throw badRequest('projectId is required to open a session')
+      requireProject(body.projectId)
+      const hostId = isHostId(body.host) ? body.host : firstInstalledHostId(opts.hostExec)
+      if (!hostId) throw new ForgeHttpError(409, 'no coding harness is installed — install Claude Code or Codex')
+      const host = HOSTS[hostId]
+      const model = optionalString(body.modelMode, 'modelMode') ?? host.defaultModel
+      thread = store.insertThread({
+        projectId: body.projectId,
+        host: hostId,
+        model,
+        mode: body.forgeMode === undefined ? host.defaultMode : requireHostMode(hostId, body.forgeMode),
+        effort: optionalString(body.reasoningEffort, 'reasoningEffort') ?? defaultEffortFor(hostId, model),
+        title: null,
+      })
+    } else {
+      thread = requireThread(body.conversationId as string)
+    }
+    const project = requireProject(thread.projectId)
+    if (runs.activeRunFor(thread.id)) throw new ForgeHttpError(409, 'a turn is already running on this thread')
+
+    const messages = Array.isArray(body.messages) ? body.messages : []
+    const lastUser = [...messages].reverse().find((m) => m && m.role === 'user')
+    if (!lastUser) throw badRequest('messages must contain a user message')
+    const rawText = (Array.isArray(lastUser.parts) ? lastUser.parts : [])
+      .filter((p) => p && p.type === 'text' && typeof p.text === 'string')
+      .map((p) => p.text as string)
+      .join('\n')
+      .trim()
+    const text = normalizeTurnText(rawText)
+    if (!text) throw badRequest('the user message has no text')
+
+    // The composer is the source of truth for model, effort and mode: what it
+    // sends applies to this turn AND sticks to the thread, exactly as the
+    // platform chat treats `modelMode`.
+    const patch: ThreadPatch = {}
+    if (typeof body.modelMode === 'string' && body.modelMode && body.modelMode !== thread.model) {
+      patch.model = body.modelMode
+    }
+    if (typeof body.reasoningEffort === 'string' && body.reasoningEffort && body.reasoningEffort !== thread.effort) {
+      patch.effort = body.reasoningEffort
+    }
+    if (body.forgeMode !== undefined) {
+      const mode = requireHostMode(thread.host, body.forgeMode)
+      if (mode !== thread.mode) patch.mode = mode
+    }
+    if (Object.keys(patch).length > 0) thread = store.updateThread(thread.id, patch)
+
+    const { runId, stream } = runs.start(thread, project, text)
+    return sseResponse(stream, {
+      [FORGE_HEADERS.conversationId]: thread.id,
+      [FORGE_HEADERS.runId]: runId,
+      [FORGE_HEADERS.agentRuntime]: 'wdk',
+    })
+  })
+
+  route('GET', '/v1/chat/:runId/stream', (_req, params, url) => {
+    const runId = params.runId!
+    const startIndex = Number(url.searchParams.get('startIndex') ?? '0')
+    const stream = runs.subscribe(runId, Number.isFinite(startIndex) ? startIndex : 0)
+    if (!stream) {
+      const stored = store.getRun(runId)
+      if (!stored) throw notFound('run')
+      // Finished before this daemon, or journal already released: nothing to replay.
+      throw new ForgeHttpError(410, 'this run is no longer streaming', 'RUN_FINISHED')
+    }
+    const run = store.getRun(runId)
+    return sseResponse(stream, {
+      ...(run ? { [FORGE_HEADERS.conversationId]: run.threadId } : {}),
+      [FORGE_HEADERS.runId]: runId,
+      [FORGE_HEADERS.agentRuntime]: 'wdk',
+    })
+  })
+
+  route('POST', '/v1/chat/:runId/cancel', async (_req, params) => {
+    const cancelled = await runs.cancel(params.runId!)
+    if (!cancelled) throw notFound('live run')
+    return ok({ runId: params.runId!, cancelled: true })
+  })
+
+  // -- sessions (platform-compatible) --------------------------------------
+
+  route('GET', '/v1/sessions/:id', (_req, params) => {
+    const thread = requireThread(params.id!)
+    return ok(sessionView(thread, runs.activeRunFor(thread.id)))
+  })
+
+  route('PATCH', '/v1/sessions/:id', async (req, params) => {
+    const id = params.id!
+    const existing = requireThread(id)
+    const body = await readJson<{
+      title?: unknown
+      modelMode?: unknown
+      status?: unknown
+      mode?: unknown
+      reasoningEffort?: unknown
+    }>(req)
+    const title = optionalString(body.title, 'title')
+    const modelMode = optionalString(body.modelMode, 'modelMode')
+    const effort = optionalString(body.reasoningEffort, 'reasoningEffort')
+    if (body.status !== undefined && body.status !== 'active' && body.status !== 'archived') {
+      throw badRequest('status must be active or archived')
+    }
+    const mode = body.mode === undefined ? undefined : requireHostMode(existing.host, body.mode)
+    const thread = store.updateThread(id, {
+      ...(title !== undefined ? { title } : {}),
+      ...(modelMode !== undefined ? { model: modelMode } : {}),
+      ...(effort !== undefined ? { effort } : {}),
+      ...(body.status !== undefined ? { archived: body.status === 'archived' } : {}),
+      ...(mode !== undefined ? { mode } : {}),
+    })
+    return ok(sessionView(thread, runs.activeRunFor(thread.id)))
+  })
+
+  route('DELETE', '/v1/sessions/:id', (_req, params) => deleteThread(params.id!))
+
+  route('GET', '/v1/sessions/:id/messages', (_req, params) => {
+    requireThread(params.id!)
+    return ok(store.listMessages(params.id!))
+  })
+
+  route('GET', '/v1/sessions/:id/pending', (_req, params) => {
+    requireThread(params.id!)
+    return ok([])
+  })
+
+  route('POST', '/v1/sessions/:id/approvals/:approvalId', async (req, params) => {
+    requireThread(params.id!)
+    const body = await readJson<{ decision?: unknown }>(req)
+    if (body.decision !== 'approve' && body.decision !== 'deny') throw badRequest('decision must be approve or deny')
+    if (!runs.respondApproval(params.id!, params.approvalId!, body.decision)) throw notFound('pending approval')
+    return ok({ approvalId: params.approvalId!, decision: body.decision })
+  })
+
+  route('GET', '/v1/follow-ups', () => ok([]))
+
+  // -- dispatch -------------------------------------------------------------
+
+  const authorized = (req: Request, url: URL): boolean => {
+    const header = req.headers.get('authorization')
+    if (header) return header === `Bearer ${opts.token}`
+    return url.searchParams.get('token') === opts.token
+  }
+
+  const server = Bun.serve<WsData>({
+    hostname: '127.0.0.1',
+    port: opts.port,
+    idleTimeout: IDLE_TIMEOUT_S,
+    async fetch(req, srv) {
+      const url = new URL(req.url)
+      const cors = corsHeaders()
+      const origin = req.headers.get('origin')
+      if (origin && origin !== opts.origin) {
+        return withHeaders(fail(403, 'origin not allowed', 'FORBIDDEN'), {})
+      }
+      if (req.method === 'OPTIONS') return new Response(null, { status: 204, headers: cors })
+
+      const segments = segmentsOf(url.pathname)
+
+      if (url.pathname !== FORGE_WELL_KNOWN_PATH && !authorized(req, url)) {
+        return withHeaders(fail(401, 'missing or invalid bearer token', 'UNAUTHORIZED'), cors)
+      }
+
+      // Terminal socket: /v1/forge/terminals/:id/ws
+      if (
+        segments.length === 5
+        && segments[0] === 'v1' && segments[1] === 'forge' && segments[2] === 'terminals' && segments[4] === 'ws'
+      ) {
+        const terminalId = decodeURIComponent(segments[3]!)
+        if (!terminals.get(terminalId)) return withHeaders(fail(404, 'terminal not found', 'NOT_FOUND'), cors)
+        const upgraded = srv.upgrade(req, { data: { terminalId, client: null } })
+        if (upgraded) return undefined as unknown as Response
+        return withHeaders(fail(400, 'expected a WebSocket upgrade', 'BAD_REQUEST'), cors)
+      }
+
+      for (const r of routes) {
+        const params = matchRoute(r, req.method, segments)
+        if (!params) continue
+        try {
+          return withHeaders(await r.handler(req, params, url), cors)
+        } catch (err) {
+          if (err instanceof ForgeHttpError) return withHeaders(fail(err.status, err.message, err.code), cors)
+          const message = err instanceof Error ? err.message : String(err)
+          log.error(`${req.method} ${url.pathname}: ${message}`)
+          return withHeaders(fail(500, message, 'INTERNAL_ERROR'), cors)
+        }
+      }
+      return withHeaders(fail(404, `no route for ${req.method} ${url.pathname}`, 'NOT_FOUND'), cors)
+    },
+    websocket: {
+      open(ws) {
+        const client: TerminalClient = {
+          sendBytes: (bytes) => ws.send(bytes),
+          sendJson: (message) => ws.send(JSON.stringify(message)),
+        }
+        ws.data.client = client
+        if (!terminals.attach(ws.data.terminalId, client)) ws.close(4004, 'terminal not found')
+      },
+      message(ws, message) {
+        const id = ws.data.terminalId
+        if (typeof message === 'string') {
+          let parsed: ForgeTerminalClientMessage
+          try {
+            parsed = JSON.parse(message) as ForgeTerminalClientMessage
+          } catch {
+            return
+          }
+          if (parsed.type === 'input' && typeof parsed.data === 'string') terminals.write(id, parsed.data)
+          else if (parsed.type === 'resize') terminals.resize(id, Number(parsed.cols), Number(parsed.rows))
+          return
+        }
+        terminals.write(id, new Uint8Array(message))
+      },
+      close(ws) {
+        if (ws.data.client) terminals.detach(ws.data.terminalId, ws.data.client)
+      },
+    },
+  })
+
+  // Optional in Bun's types because a unix-socket server has none; ours is TCP.
+  const port = server.port ?? opts.port
+  log.info(`listening on http://127.0.0.1:${port}`)
+
+  return {
+    port,
+    async stop() {
+      await runs.stopAll()
+      terminals.killAll()
+      server.stop(true)
+      store.close()
+    },
+  }
+}