Distillation

Date: Sep 16, 2026

• 🔴 (15:32) User stated that CLI and script processes never serve the /doc route, so they should not pay the cost of generating its OpenAPI specification at module load.
• 🟡 (15:32) packages/server/src/routes.ts adds SessionRecovery.node to applicationServices and builds the service layer with AppNodeBuilder.build(applicationServices, [[SessionExecution.node, SessionExecutionLocal.node]]); both regular createRoutes(password?) and unauthenticated createEmbeddedRoutes() use this graph.
• 🟡 (15:32) In packages/server/src/routes.ts, createRoutes(password?) configures username "opencode" and an optional password, while createEmbeddedRoutes() configures username "opencode" with Option.none(); makeRoutes() exposes OpenAPI at /openapi.json and provides handlers, sessionLocationLayer, locationLayer, authorizationLayer, schemaErrorLayer, auth, and the service layer.
• 🟡 (15:32) packages/opencode/src/server/routes/instance/httpapi/server.ts organizes the HTTP route tree into 7 layers in order: 1. rootApiRoutes, 2. eventApiRoutes, 3. ptyConnectApiRoutes, 4. instanceRoutes, 5. serverRoutes, 6. docRoute, 7. uiRoute.
• 🟡 (15:32) /doc generation in packages/opencode/src/server/routes/instance/httpapi/server.ts is deferred through const docResponse = lazy(() => HttpServerResponse.jsonUnsafe(OpenApi.fromApi(PublicApi))); because jsonUnsafe stringifies eagerly, caching the response also caches the serialized Uint8Array, avoiding regeneration and re-stringification on subsequent /doc requests.
• 🟡 (15:32) docRoute registers authenticated GET /doc via authOnlyRouterLayer; uiRoute is an authenticated raw "*"/"/*" fallback that invokes serveUIEffect(request, { fs, client, disableEmbeddedWebUi: flags.disableEmbeddedWebUi }).
• 🟡 (15:32) The opencode server’s createRoutes(corsOptions?) provides SessionV2.node and SessionRecovery.node through AppNodeBuilderV1.build(...), overriding LocationServiceMap.node with locationServiceMapV2 and SessionExecution.node with SessionExecutionLocal.node.
• 🟡 (15:32) The opencode route assembly applies errorLayer, compressionLayer, corsVaryFix, fenceLayer, CORS with maxAge: 86_400, MoveSession.node, and HttpServer.layerServices; Observability.layer must remain last so eagerly forked fibers such as the ModelsDev background refresh do not capture Effect’s default stdout logger and corrupt the TUI (#34730).
• 🟡 (15:32) The opencode webHandler is lazy and calls HttpRouter.toWebHandler(routes, { disableLogger: true, memoMap, middleware: disposeMiddleware }).