Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

38.2 KB
Raw Blame
/**
 * The HMR layer's app assembly.
 *
 * `bootAppDeps(config)` builds the process's core (database, channels, HmrHost), publishes
 * it into the resource registry (see hmr/capabilities.ts), boots the platform — which builds
 * the business surface over what it claims there — and returns the boot. `createApp(boot)`
 * mounts the layer's HTTP surface: the network guards, `/api/hmr`, the platform seam, and
 * static hosting. Neither listens on a port: tests inject requests via `app.request()`, and
 * the startup entry point is index.ts.
 *
 * Every other route is the platform's (http/app.ts, `HttpModule`), assembled at every App
 * creation from `platformImpl.create` (hmr/platform.ts), so it travels with the platform
 * version rather than with this build. Swap semantics for anything the platform holds that
 * is not parked is a HARD STOP: approvals deny, runs abort, the scheduler dies with its App.
 */
import { createHash } from "node:crypto";
import zlib from "node:zlib";
import fs from "node:fs";
import fsp from "node:fs/promises";
import path from "node:path";
import { Hono } from "hono";
import type { Context, MiddlewareHandler } from "hono";
import type { HttpBindings } from "@hono/node-server";
import { bodyLimit } from "hono/body-limit";
import { bodyLimitBytes, toAttachmentLimits } from "./services/attachment-limits.js";
import type { DatabaseSync } from "node:sqlite";
import type { ModuleTree } from "@adelie/core/kernel";
import type { ServerConfig } from "./config.js";
import { applyProxySettings, mergedNoProxy } from "./net/proxy.js";
import {
  HMR_INTERFACES,
  HMR_INTERFACES_RESOURCE_ID,
  HMR_AUTH_STATE_RESOURCE_ID,
  HMR_CHANNELS_RESOURCE_ID,
  HMR_CONFIG_RESOURCE_ID,
  HMR_DB_RESOURCE_ID,
  HMR_DESKTOP_RESOURCE_ID,
  HMR_LIFECYCLE_RESOURCE_ID,
  HMR_HOST_RESOURCE_ID,
  HMR_CONTROL_RESOURCE_ID,
  HMR_OVERRIDES_RESOURCE_ID,
  HMR_TEST_PLUGINS_RESOURCE_ID,
  type Replacements,
  HMR_PROXY_RESOURCE_ID,
  HmrCapabilities,
  ConsoleLog,
  type Log,
  type ProxyControl,
} from "./hmr/capabilities.js";
import { ensureCliShim } from "./services/cli-shim.js";
import { openDatabase } from "./db/database.js";
import { MachinesRepo } from "./db/repos/machines.js";
import { migrate } from "./db/migrations.js";
import { ErrorsRepo } from "./db/repos/errors.js";
import { MessagingBindingsRepo } from "./db/repos/messaging-bindings.js";
import { SchedulesRepo } from "./db/repos/schedules.js";
import { ServerSettingsRepo } from "./db/repos/server-settings.js";
import { SessionsRepo } from "./db/repos/sessions.js";
import { UiPrefsRepo } from "./db/repos/ui-prefs.js";
import { UsersRepo } from "./db/repos/users.js";
import type { UserRow } from "./db/repos/users.js";
import { jsonOnlyWrites } from "./auth/middleware.js";
import { AMSP_PREFIX, amspAllowOrigin } from "./amsp/cors.js";
import { mintApiToken, storeApiToken } from "./auth/api-token.js";
import type { Identity } from "./terminal/identity.js";
import { terminalRoutes } from "./terminal/routes.js";
import type { TerminalManager } from "./terminal/manager.js";
import { PLUGINS_RESOURCE_ID, type PluginHost } from "./plugin/host.js";
import type { AppEnv } from "./auth/middleware.js";
import { AuthService } from "./auth/service.js";
import { newAuthRuntimeState } from "./auth/runtime-state.js";
import { AuthSessionsRepo } from "./db/repos/auth-sessions.js";
import { ensureInstallId } from "./install-id.js";
import { handleError, HttpError, errorBody, normalizeError } from "./http/errors.js";
import { attributedProjectId } from "./http/attribution.js";
import { STREAM_IDLE_MS } from "./http/sse.js";
import { installRoutes } from "./http/routes/install.js";
import { ChannelHub } from "./runtime/channel.js";
import { ErrorRecorder } from "./runtime/error-recorder.js";
import {
  createCoreSessionLoader,
  SessionLoader,
  SessionManager,
} from "./runtime/session-manager.js";
import { SessionSources } from "./runtime/session-sources.js";
import { Scheduler } from "./runtime/scheduler.js";
import { MessagingBridge } from "./runtime/messaging/bridge.js";
import { FeishuConnector } from "./runtime/messaging/feishu-connector.js";
import { createLarkSdk } from "./runtime/messaging/feishu-sdk.js";
import type { FeishuSdk } from "./runtime/messaging/feishu-sdk.js";
import { TelegramConnector } from "./runtime/messaging/telegram-connector.js";
import { createTelegramTransport } from "./runtime/messaging/telegram-api.js";
import type { TelegramTransport } from "./runtime/messaging/telegram-api.js";
import { QQConnector } from "./runtime/messaging/qq-connector.js";
import { createQQTransport } from "./runtime/messaging/qq-api.js";
import type { QQTransport } from "./runtime/messaging/qq-api.js";
import { QQScanService, createQQScanTransport } from "./runtime/messaging/qq-scan.js";
import { WeChatConnector } from "./runtime/messaging/wechat-connector.js";
import { createWeChatTransport } from "./runtime/messaging/wechat-api.js";
import type { WeChatTransport } from "./runtime/messaging/wechat-api.js";
import { WeChatScanService, createWeChatScanTransport } from "./runtime/messaging/wechat-scan.js";
import type { WeChatScanTransport } from "./runtime/messaging/wechat-scan.js";
import type { QQScanTransport } from "./runtime/messaging/qq-scan.js";
import { TitleGenerator, TitleNotifier } from "./runtime/title-generator.js";
import { AdminService } from "./services/admin-service.js";
import { DesktopService } from "./services/desktop-service.js";
import { LifecycleService } from "./services/lifecycle-service.js";
import { AgentConfigService } from "./services/agent-config-service.js";
import { MemoryService } from "./services/memory-service.js";
import { AgentService } from "./services/agent-service.js";
import { BenchmarkService } from "./services/benchmark-service.js";
import { SnapshotService } from "./services/snapshot-service.js";
import { ProjectConfigService } from "./services/project-config-service.js";
import { ModelOAuthService } from "./services/model-oauth-service.js";
import { ProjectService } from "./services/project-service.js";
import { SessionService } from "./services/session-service.js";
import { TraceIndexService } from "./services/trace-index.js";
import { TraceService } from "./services/trace-service.js";
import { UpdateCheckService } from "./services/update-check-service.js";
import { UpdateJobService } from "./services/update-job.js";
import { UsageService } from "./services/usage-service.js";
import { WorkspaceFilesService } from "./services/workspace-files-service.js";
import { HmrHost, hmrControl } from "@adelie/hmr";
import type { Hmr } from "@adelie/hmr";
import type { PlatformApi, ServerHmrHost } from "./hmr/platform.js";
import { packagedPlatform } from "./hmr/platform.js";
import { platformHttpSeam } from "./hmr/http-seam.js";
import {
  createPreviewTokenSigner,
  hostOnly,
  loopbackHostRoles,
  requestAuthority,
} from "./services/preview-token.js";
import type { PreviewTokenSigner } from "./services/preview-token.js";

import type { ControlEnvContext, ProxyEnvPolicy, SpawnConfiner } from "@adelie/core";
import { declined } from "./hmr/hono-seam.js";
import { AgentsRepo } from "./db/repos/agents.js";
import { MembersRepo } from "./db/repos/members.js";
import { ProjectsRepo } from "./db/repos/projects.js";
import { TraceIndexRepo } from "./db/repos/trace-index.js";
import { UsageRepo } from "./db/repos/usage.js";
import { adminUsersRoutes } from "./http/routes/admin.js";
import { adminSettingsRoutes } from "./http/routes/admin-settings.js";
import type { ServerEvent } from "./api/types.js";
import { meRoutes } from "./http/routes/me.js";
import { eventsRoutes, userChannelKey } from "./http/routes/events.js";
import { projectsRoutes } from "./http/routes/projects.js";
import { membersRoutes } from "./http/routes/members.js";
import { modelsRoutes } from "./http/routes/models.js";
import { modelOAuthCallbackRoutes, modelOAuthRoutes } from "./http/routes/model-oauth.js";
import { chatDefaultsRoutes } from "./http/routes/chat-defaults.js";
import { commandPolicyRoutes } from "./http/routes/command-policy.js";
import { vaultRoutes } from "./http/routes/vault.js";
import { memoryRoutes } from "./http/routes/memory.js";
import { scheduleRoutes } from "./http/routes/schedules.js";
import { benchmarksRoutes } from "./http/routes/benchmarks.js";
import { agentSkillsRoutes } from "./http/routes/skills.js";
import { agentHooksRoutes } from "./http/routes/hooks.js";
import { agentPluginsRoutes, pluginLibraryRoutes } from "./http/routes/plugins.js";
import { agentTransferRoutes } from "./http/routes/agent-transfer.js";
import { agentsRoutes } from "./http/routes/agents.js";
import { dirsRoutes } from "./http/routes/dirs.js";
import { directorySkillsRoutes } from "./http/routes/directory-skills.js";
import { agentConfigRoutes } from "./http/routes/agent-config.js";
import { agentTracesRoutes } from "./http/routes/agent-traces.js";
import { usageRoutes } from "./http/routes/usage.js";
import { agentSessionsRoutes, sessionsRoutes } from "./http/routes/sessions.js";
import { sessionMessagingRoutes } from "./http/routes/messaging.js";
import { versionRoutes } from "./http/routes/version.js";
import { machinesRoutes } from "./http/routes/machines.js";
import { UsageRecorder } from "./runtime/usage-recorder.js";
import { previewRoutes } from "./http/routes/preview.js";
import { MachinesService } from "./machines/service.js";
import { wire } from "@adelie/core/kernel";
import type { Settings } from "./mechanisms/settings.js";
import type { Errors } from "./mechanisms/observability.js";
import type { Access } from "./mechanisms/projects.js";
import type { Auth } from "./mechanisms/identity.js";

/**
 * What the runtime process holds after boot: the capabilities it owns for the process
 * lifetime, and the module tree the platform built over them (src/modules). There is no
 * flat bag of services here any more — a module names what it needs in its manifest.
 */
export interface ServerBoot {
  config: ServerConfig;
  db: DatabaseSync;
  channels: ChannelHub;
  hmr: ServerHmrHost;
  /** The frozen operations over `hmr` (packages/hmr's main.ts): the seam and the upgrade route drive it, nothing drives the host directly. */
  control: Hmr<PlatformApi>;
  desktop: DesktopService | null;
  /** Process lifecycle: whether a supervisor relaunches this process, and the restart trigger (the "restart to update" step). */
  lifecycle: LifecycleService;
  tree: ModuleTree;
}

/**
 * Assemble the runtime core, publish its capabilities, boot the platform (which builds
 * the business surface — see app.ts), and return the merged view. Shared
 * by production and tests; tests pass dbPath=":memory:" and a temp root.
 *
 * `plugins` is what index.ts's loadPlugins shim imported — handed in rather than registered
 * by the caller because the platform boots inside this function, and everything it claims has
 * to be in the registry first. The platform builds its own host from the Projects' closure
 * either way (plugin/loader.ts); this only lets it reuse objects already imported, and lets a
 * platform older than that move find a host at all.
 *
 * `testPlugins` is the other half of that: entries a TEST stands up in process, which no
 * closure could name because they were never on disk. Kept apart from the line above so the
 * production path stays "what the Projects ask for, imported", with no way for a fake to
 * enter it.
 */
export async function bootAppDeps(
  config: ServerConfig,
  replacements: Replacements = [],
  plugins?: PluginHost,
  testPlugins?: PluginHost,
  host?: ServerHmrHost,
  control?: Hmr<PlatformApi>,
): Promise<ServerBoot> {
  const db = openDatabase(config.dbPath);

  const usersRepo = wire(UsersRepo, { db: db });

  // Hoisted above the services so its registry can be populated before anything boots
  // against it. index.ts builds both and hands them in (hmrMain owns them there); a test
  // that boots without an entry gets the same pair here.
  const hmr = host ?? new HmrHost<PlatformApi>(config.root, packagedPlatform);
  // The default replace does what index.ts's does: point the boot's tree at the new
  // generation, so what createApp resolves from it is the current generation's.
  let booted: ServerBoot | null = null;
  const ctl =
    control ??
    hmrControl(hmr, (instance) => {
      const next = typeof instance.api.business === "function" ? instance.api.business() : null;
      if (next !== null && booted !== null) booted.tree = next;
    });

  // Channel idle reclamation must skip active Sessions, but "is this session busy" is a
  // business question: the App installs the answer itself via setActivityProbe at every
  // create (see hmr/platform.ts) — ordinary use of the claimed capability, re-installed
  // by each generation. Until the first App boots, nothing is active.
  const channels = new ChannelHub();

  // Authentication itself is business behaviour and is built per App (buildAppDeps), so a
  // change to it ships by push. Only the values that must survive a push live out here.
  const authState = newAuthRuntimeState();

  // Local API token: minted per boot, persisted at <root>/api-token (0600) and published on
  // the runtime auth state, so authMiddleware accepts it as the admin for this process's
  // whole life — across hot swaps too, since the App that verifies it is rebuilt but the
  // file on disk is not rewritten. Local filesystem access to the data root is admin
  // authority (the reset-admin-password rule); see auth/api-token.ts.
  const apiToken = mintApiToken();
  storeApiToken(config.root, apiToken);
  authState.apiToken = apiToken;

  // Install identity: minted here so a root gets its name the first time it is used rather
  // than on the first browser request, which keeps `<root>/install-id` alongside the other
  // files a boot creates and makes the id observable to the CLI and to tests. The return
  // value is deliberately unused — GET /api/install re-reads the file per request (see
  // http/routes/install.ts); this call exists for the minting side effect. Nothing fails
  // when it cannot be persisted: the browser then simply never sweeps.
  ensureInstallId(config.root);

  // The `penguin` an Agent's commands resolve: this harness's own CLI, written into the
  // data root for every Session to put at the front of PATH (see services/cli-shim.ts).
  // Here rather than per App, for the same reason the two above are: it is a fact about
  // this PROCESS's installation, and a hot-pushed platform — compiled somewhere else
  // entirely — has no way to work out where the CLI it should point at lives.
  // Pre-boot, so the Log mechanism is not up yet: a ConsoleLog replacement (the double a
  // test hands the tree) is honoured here too, and the process's own console otherwise.
  const logDouble = replacements.find(([cls]) => cls === ConsoleLog)?.[1] as Log | undefined;
  const shimLog = (line: string): void => (logDouble ?? new ConsoleLog()).line(line);
  const shim = ensureCliShim(config.root, config.cliEntry ?? null);
  if (shim.kind === "written") {
    shimLog(`Agent CLI: ${path.join(shim.dir, "penguin")} -> ${shim.entry}`);
  } else if (shim.kind === "absent") {
    shimLog(
      "Agent CLI: no CLI entry found; commands an Agent runs resolve `penguin` on their own PATH.",
    );
  } else {
    console.warn(`[server] could not write the penguin CLI shim: ${shim.reason}`);
  }

  // What buildAppDeps claims (see hmr/capabilities.ts) — every entry must be in place before
  // ensure() below performs the first boot. The interface descriptor leads: it is what a
  // bundle's handshake reads before trusting any of the rest.
  hmr.resources.register(HMR_INTERFACES_RESOURCE_ID, HMR_INTERFACES);
  hmr.resources.register(HMR_CONFIG_RESOURCE_ID, config);
  hmr.resources.register(HMR_DB_RESOURCE_ID, db);
  hmr.resources.register(HMR_AUTH_STATE_RESOURCE_ID, authState);
  hmr.resources.register(HMR_CHANNELS_RESOURCE_ID, channels);
  hmr.resources.register(HMR_PROXY_RESOURCE_ID, applyProxySettings);
  hmr.resources.register(HMR_HOST_RESOURCE_ID, hmr);
  hmr.resources.register(HMR_CONTROL_RESOURCE_ID, ctl);
  hmr.resources.register(HMR_OVERRIDES_RESOURCE_ID, replacements);
  const desktop = config.desktopToken !== null ? new DesktopService(config.desktopToken) : null;
  hmr.resources.register(HMR_DESKTOP_RESOURCE_ID, desktop);
  const lifecycle = new LifecycleService(config.supervised);
  hmr.resources.register(HMR_LIFECYCLE_RESOURCE_ID, lifecycle);
  // The registry sweep only STARTS plugin disposal (its disposers are sync) — the
  // fallback for exit paths that skip the graceful shutdown. The graceful path awaits
  // host.dispose() itself, bounded (index.ts); dispose is idempotent, so both may fire.
  if (plugins !== undefined) {
    hmr.resources.register(PLUGINS_RESOURCE_ID, plugins, () => void plugins.dispose());
  }
  if (testPlugins !== undefined) {
    hmr.resources.register(HMR_TEST_PLUGINS_RESOURCE_ID, testPlugins);
  }

  // Boot the platform now rather than on the first request: the business surface —
  // services, routes, the scheduler — is assembled inside its create(). The check reads
  // the in-process api member, not a registry entry: the instance IS the current App.
  const instance = await hmr.ensure();
  const tree = instance.api.business();
  if (tree === null) {
    throw new Error("the packaged platform built no business surface");
  }
  // Callers that outlive swaps (index.ts, the runtime app) may only touch the swap-stable
  // members: the runtime singletons published above. The tree is THIS generation's and
  // goes stale at the next push — per-request business dispatch rides the seam.
  booted = { config, db, channels, hmr, control: ctl, desktop, lifecycle, tree };
  return booted;
}

/**
 * The layer's log handle: whichever platform is current writes the line, and the console
 * does before there is one. Resolved per line through the host, so a swap changes where the
 * lines go without the layer holding any generation's object.
 */
export function platformLog(hmr: ServerHmrHost): (line: string) => void {
  return (line) => {
    void hmr
      .ensure()
      .then((instance) => {
        if (typeof instance.api.log === "function") instance.api.log(line);
        else console.log(line);
      })
      .catch(() => console.log(line));
  };
}

/** Assembles the Hono app (does not listen on a port). */
export function createApp(boot: ServerBoot): Hono<AppEnv> {
  // Resolved on use, from the CURRENT generation's tree — the entry's replace hook points
  // `boot.tree` at each new one — so a node is never the first generation's for the life
  // of the process. A generation that has no tree to resolve from (a pushed fixture, a
  // bare kernel, a tree mid-dispose) keeps the last one resolved, as a captured node did.
  const current = <T>(resolve: () => T): (() => T) => {
    let last = resolve();
    return () => {
      try {
        last = resolve();
      } catch {
        // The tree is mid-swap or belongs to a generation without one: the last node stands.
      }
      return last;
    };
  };
  const errors = current(() => boot.tree.api<Errors>("ObservabilityModule", "Errors"));
  const log = platformLog(boot.hmr);
  const settings = current(() => boot.tree.api<Settings>("SettingsModule", "Settings"));
  const access = current(() => boot.tree.api<Access>("ProjectsModule", "Access"));
  const authService = current(() => boot.tree.api<Auth>("IdentityModule", "Auth"));
  const deps = {
    config: boot.config,
    desktop: boot.desktop,
    get authService() {
      return authService();
    },
    hmr: boot.hmr,
    control: boot.control,
    channels: boot.channels,
  };
  const app = new Hono<AppEnv>();

  // Error recording is layered in a lambda wrapping onError: handleError stays a
  // pure function with unchanged behavior (HttpError is mapped as-is, unknown
  // exceptions are logged with a stack trace and collapsed to 500), and recording
  // to the DB is just a side-effect layered on top.
  app.onError((err, c) => {
    const projectId = attributedProjectId(c, { access: access() });
    // Normalize first: response and recording must agree on what this error is (see http/errors.ts).
    const normalized = normalizeError(err);
    errors().record({
      source: "http",
      err: normalized,
      ...(projectId !== undefined ? { ctx: { projectId } } : {}),
    });
    return handleError(normalized, c);
  });
  app.notFound((c) => c.json(errorBody("not_found", "Endpoint does not exist."), 404));

  // Request logging: a minimal one-liner (method path status ms).
  app.use("*", async (c, next) => {
    const start = performance.now();
    await next();
    const ms = Math.round(performance.now() - start);
    log(`${c.req.method} ${c.req.path} ${c.res.status} ${ms}ms`);
  });

  // An event stream's socket that sends nothing for STREAM_IDLE_MS is destroyed (Node lets the
  // first expiry pass while a write is pending, so a stuck write is cut within two). A live
  // stream pings every 20 s; it goes that quiet only when its peer stopped reading and a write
  // never completes, and then only the socket can end it: the stream's own close queues behind
  // that write. The abort runs the stream's teardown. Only the host holds the socket (`c.env`,
  // passed by index.ts), hence here.
  app.use("*", async (c, next) => {
    await next();
    const socket = (c.env as Partial<HttpBindings> | undefined)?.incoming?.socket;
    if (socket && c.res.headers.get("content-type")?.startsWith("text/event-stream")) {
      socket.setTimeout(STREAM_IDLE_MS, () => socket.destroy());
    }
  });

  // Canonical-host guard (loopback binds only): the App is served on one loopback name and
  // previews on its counterpart, but the SAME process answers on both. Without this, Agent-
  // written preview HTML on the preview host could call /api same-origin and — if a session
  // cookie had ever been set on that host — act as the user. So the preview host serves ONLY
  // /preview/*: /api answers 401 (it never sets or honors a cookie there, closing both the
  // login and the stale-cookie paths), and everything else 302s to the canonical App host.
  // Off when ADELIE_PREVIEW_ORIGIN is set: previews then
  // use that origin rather than the loopback counterpart, so 127.0.0.1 is an ordinary App
  // access point and must not be locked down — deployments enforce the equivalent at the
  // reverse proxy (route only /preview/* to the App on the preview origin).
  const previewRoles = deps.config.previewOrigin ? null : loopbackHostRoles(deps.config.host);
  if (previewRoles) {
    app.use("*", async (c, next) => {
      const host = hostOnly(requestAuthority(c.req.url, c.req.header("host"))).toLowerCase();
      if (host === previewRoles.preview && !c.req.path.startsWith("/preview/")) {
        if (c.req.path.startsWith("/api/")) {
          throw new HttpError(401, "unauthorized", "The API is not served on the preview host.");
        }
        const url = new URL(c.req.url);
        url.hostname = previewRoles.app;
        return c.redirect(url.toString(), 302);
      }
      await next();
    });
  }

  // API common defenses: request body size cap (20MB) and write-request Content-Type (one of the CSRF MVP defenses).
  //
  // The cap has to be measured, not read: a chunked request carries no `content-length` at all,
  // so a header check alone passes a body of any size — the sinks behind it (task input images,
  // file attachments, Trace import) then decode whatever arrives. hono's bodyLimit keeps the
  // header fast path when the length is declared and otherwise counts bytes off the stream,
  // aborting the moment the total crosses the cap.
  //
  // The cap is DERIVED from the admin-settable attachment budget rather than fixed, because the
  // two must not disagree in either direction: a cap below the budget would reject a request whose
  // every attachment was individually legal (and with a body-shaped error, not a size-shaped one),
  // while a cap permanently sized for the largest budget an admin *could* set would keep accepting
  // 300MB bodies on a server whose limits were left at 10MB. It is re-derived per request, so an
  // admin's change takes effect immediately; the middleware itself is memoized on the resulting
  // size so the steady state allocates nothing.
  //
  // The Agent API is called from browsers too: its CORS header (amsp/cors.ts) has to reach these
  // two refusals, which answer before its group runs, or a caller reads a CORS failure, not the code.
  app.use(`${AMSP_PREFIX}/*`, amspAllowOrigin);
  let capped: { size: number; mw: MiddlewareHandler } | null = null;
  app.use("/api/*", (c, next) => {
    const size = bodyLimitBytes(settings().getAttachmentLimitsMb());
    if (capped === null || capped.size !== size) {
      capped = {
        size,
        mw: bodyLimit({
          maxSize: size,
          // Its default is a bare text/plain 413; throw the App's own error instead so the
          // response stays the documented `payload_too_large` body that every client handles.
          onError: () => {
            throw new HttpError(
              413,
              "payload_too_large",
              `Request body exceeds the ${Math.floor(size / (1024 * 1024))}MB limit.`,
            );
          },
        }),
      };
    }
    return capped.mw(c, next);
  });
  app.use("/api/*", jsonOnlyWrites);

  // THE seam: every route is one the platform may take over by push — the upgrade channel
  // included, which the platform declares and contributes like any other group
  // (hmr/routes.ts; a generation without it is refused before commit, see packages/hmr's
  // admitsUpgradeRoute). Declining costs one property read and lands on the layer's own
  // tail below, which is what a platform without an `http` handler does.
  app.use("*", platformHttpSeam(deps.control));

  // Every route but /api/hmr is the platform's, served through the seam above. What follows
  // is the layer's own tail: static hosting and the SPA fallback.

  // Static hosting (production): serves the frontend build output with SPA fallback to
  // index.html. The source resolves per request — the hot host can point it at a
  // freshly pushed/restored web dist (in memory) without a restart; when nothing has
  // been pushed, it falls back to the configured webDist. `hmr.ensure()` is awaited
  // FIRST: web is only restored from harness.json as part of the platform+cli+web
  // version's lazy first boot (see HmrHost.restore()), which nothing else here
  // triggers — without this, a request landing right after a restart (before any
  // /api/hmr/* call warms the host up) would miss a restored version entirely and
  // silently fall back to the packaged webDist.
  registerStaticRoutes(app, async () => {
    await deps.hmr.ensure();
    return deps.hmr.resolveWebSource() ?? { kind: "dir", dir: deps.config.webDist };
  });

  return app;
}

const CONTENT_TYPES: Record<string, string> = {
  ".html": "text/html; charset=utf-8",
  ".js": "text/javascript; charset=utf-8",
  // The build emits one ES module worker besides the .js bundles (pdf.js's), and a browser
  // refuses a module script served as anything but a JavaScript type — the fallback below
  // would answer application/octet-stream and the worker would never start.
  ".mjs": "text/javascript; charset=utf-8",
  ".css": "text/css; charset=utf-8",
  ".json": "application/json",
  ".svg": "image/svg+xml",
  ".png": "image/png",
  ".jpg": "image/jpeg",
  ".ico": "image/x-icon",
  ".map": "application/json",
  ".txt": "text/plain; charset=utf-8",
  ".woff2": "font/woff2",
};

/** Where registerStaticRoutes reads a request's bytes from, resolved fresh per request. */
export type WebSource = { kind: "mem"; files: Map<string, Buffer> } | { kind: "dir"; dir: string };

/**
 * The SPA's caching contract, without which a hot-pushed web is invisible to returning
 * clients until they happen to hard-refresh:
 *
 * - Vite's `assets/*` files are content-hashed, so their bytes can never change under
 *   their name → cache forever, never revalidate.
 * - Everything else — `index.html` above all, including every SPA-fallback answer — must
 *   revalidate on each navigation (`no-cache` means "store, but ask first"), and the ETag
 *   makes that ask a 304 instead of a re-download. A web push changes the ETag, so the
 *   very next load anywhere picks the new app up.
 */
function cacheControlFor(servedPath: string): string {
  return servedPath.startsWith("assets/") ? "public, max-age=31536000, immutable" : "no-cache";
}

/** Content ETags for the in-memory dist, computed once per Buffer (pushes swap the Buffers). */
const memEtags = new WeakMap<Buffer, string>();

function etagOfBuffer(content: Buffer): string {
  let etag = memEtags.get(content);
  if (etag === undefined) {
    etag = `"${createHash("sha256").update(content).digest("base64url").slice(0, 16)}"`;
    memEtags.set(content, etag);
  }
  return etag;
}

/**
 * Whether `If-None-Match` claims this exact representation, per RFC 9110's rules rather than
 * by string equality — both of which a real deployment hits:
 *
 * - It is a LIST. A client holding several validators sends `"a", "b"`.
 * - Comparison is WEAK, so `W/"x"` and `"x"` are the same tag. A proxy that re-encodes a
 *   response (nginx's gzip module is the common one) downgrades a strong ETag to weak on the
 *   way out, and the client sends back what it was given.
 *
 * Getting this wrong costs only 304s — the bytes are still correct — which is exactly why it
 * would never be noticed, and why it is worth a few lines rather than a string compare.
 */
function ifNoneMatchHits(header: string | undefined, etag: string): boolean {
  if (header === undefined) return false;
  const bare = (tag: string) => tag.trim().replace(/^W\//, "");
  // `*` means "any current representation": for a resource that exists, that is a match.
  if (header.trim() === "*") return true;
  const want = bare(etag);
  return header.split(",").some((tag) => bare(tag) === want);
}

/**
 * Extensions worth compressing. Everything absent is either already compressed (png, woff2,
 * ico) or too small for the round trip to pay for the CPU — recompressing a PNG spends time
 * to make the response slightly larger.
 */
const COMPRESSIBLE = new Set([".html", ".js", ".css", ".json", ".svg", ".map", ".txt"]);

/**
 * Below this, compression is not worth doing: a few hundred bytes rarely shrink past the
 * gzip header, and the transfer was never the cost at that size.
 */
const COMPRESS_MIN_BYTES = 1024;

/**
 * The best encoding this client accepts, or null for none.
 *
 * Brotli first — on the app bundle it is meaningfully smaller than gzip, and everything that
 * speaks it also speaks gzip, so the fallback is free. Parsed rather than substring-matched
 * because `q=0` means REFUSED: a client that sends `gzip;q=0` is saying "not gzip", and a
 * naive `includes("gzip")` reads that as consent and returns bytes it cannot decode.
 */
function pickEncoding(header: string | undefined): "br" | "gzip" | null {
  if (header === undefined) return null;
  const accepted = new Set<string>();
  for (const part of header.split(",")) {
    const [rawToken, ...params] = part.split(";");
    const token = (rawToken ?? "").trim().toLowerCase();
    const q = params.map((p) => /^\s*q=([0-9.]+)\s*$/i.exec(p)).find((m) => m !== null)?.[1];
    if (q !== undefined && Number.parseFloat(q) === 0) continue;
    accepted.add(token);
  }
  if (accepted.has("br")) return "br";
  if (accepted.has("gzip")) return "gzip";
  return null;
}

/**
 * Compressed bodies, keyed by `<encoding> <etag>` — the ETag already identifies one exact
 * representation, so it is the only key this needs, and it changes when the bytes do.
 *
 * Cached because the alternative is compressing the same 1.2 MB bundle on every page load.
 * Bounded and insertion-ordered (oldest evicted first): a dist is tens of files, but a hot
 * push replaces all of them, and nothing should grow without a ceiling across a long uptime.
 */
const COMPRESSED_CACHE_ENTRIES = 128;
const compressedCache = new Map<string, Buffer>();

function compressedBody(content: Buffer, encoding: "br" | "gzip", etag: string): Buffer {
  const key = `${encoding} ${etag}`;
  const hit = compressedCache.get(key);
  if (hit !== undefined) return hit;
  const body =
    encoding === "br"
      ? zlib.brotliCompressSync(content, {
          params: {
            // Text mode and the real size let brotli pick its window; quality 5 is the knee
            // of the curve — near-max ratio for a fraction of the time of 11, which on a
            // megabyte is the difference between imperceptible and a visible stall.
            [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
            [zlib.constants.BROTLI_PARAM_QUALITY]: 5,
            [zlib.constants.BROTLI_PARAM_SIZE_HINT]: content.byteLength,
          },
        })
      : zlib.gzipSync(content, { level: 6 });
  if (compressedCache.size >= COMPRESSED_CACHE_ENTRIES) {
    const oldest = compressedCache.keys().next();
    if (!oldest.done) compressedCache.delete(oldest.value);
  }
  compressedCache.set(key, body);
  return body;
}

/** The static response for one resolved file: 304 on an ETag match, the bytes otherwise. */
function staticResponse(
  c: Context<AppEnv>,
  content: Buffer,
  servedPath: string,
  etag: string,
): Response {
  const ext = path.extname(servedPath).toLowerCase();
  const mayCompress = COMPRESSIBLE.has(ext) && content.byteLength >= COMPRESS_MIN_BYTES;
  // Chosen BEFORE the 304, because it decides which representation is being talked about —
  // and a 304 has to carry the validator of the one the client would have got.
  const encoding = mayCompress ? pickEncoding(c.req.header("accept-encoding")) : null;
  // Weakened when compressed, as a re-encoding proxy would: those bytes are a different
  // representation of the same thing, and a weak validator is exactly the claim "equivalent,
  // not identical". Revalidation matches either spelling — ifNoneMatchHits compares weakly.
  const responseEtag = encoding !== null && !etag.startsWith("W/") ? `W/${etag}` : etag;
  const headers: Record<string, string> = {
    "Cache-Control": cacheControlFor(servedPath),
    ETag: responseEtag,
  };
  // Announced whenever the answer COULD have varied — on the 304 too, and even when this
  // particular client took no encoding: a shared cache keys on what the header says, so
  // leaving it off is how one client's gzip reaches another that cannot read it.
  if (mayCompress) headers["Vary"] = "Accept-Encoding";
  if (ifNoneMatchHits(c.req.header("if-none-match"), etag)) {
    return new Response(null, { status: 304, headers });
  }
  headers["Content-Type"] = CONTENT_TYPES[ext] ?? "application/octet-stream";
  if (encoding === null) {
    return new Response(new Uint8Array(content), { status: 200, headers });
  }
  headers["Content-Encoding"] = encoding;
  return new Response(new Uint8Array(compressedBody(content, encoding, etag)), {
    status: 200,
    headers,
  });
}

/**
 * Minimal static file server (avoiding an extra dependency): path traversal
 * protection + SPA fallback, over either an in-memory pushed/restored dist (the
 * hot host's primary path — no filesystem at all) or the packaged webDist
 * directory on disk. Serves the caching contract above, so pushes take effect
 * on the next navigation and hashed assets stop re-downloading.
 */
function registerStaticRoutes(app: Hono<AppEnv>, resolveSource: () => Promise<WebSource>): void {
  app.get("*", async (c) => {
    const reqPath = decodeURIComponent(c.req.path);
    if (reqPath.startsWith("/api/")) {
      return c.json(errorBody("not_found", "Endpoint does not exist."), 404);
    }
    const rel = reqPath.replace(/^\/+/, "") || "index.html";
    // Resolved per request: the hot host may retarget it between requests.
    const source = await resolveSource();

    if (source.kind === "mem") {
      // No filesystem involved, so no traversal guard is needed: an unknown
      // key simply isn't in the map, same as a missing file on disk.
      const servedPath = source.files.has(rel) ? rel : "index.html"; // SPA fallback
      const content = source.files.get(servedPath);
      if (content === undefined) {
        return c.json(errorBody("not_found", "Resource does not exist."), 404);
      }
      return staticResponse(c, content, servedPath, etagOfBuffer(content));
    }

    const webDist = source.dir;
    if (!fs.existsSync(webDist)) {
      return c.json(errorBody("not_found", "Resource does not exist."), 404);
    }
    const resolved = path.resolve(webDist, rel);
    // Guard against path traversal: once resolved, it must still be inside webDist.
    const base = path.resolve(webDist);
    const target =
      resolved === base || resolved.startsWith(base + path.sep)
        ? resolved
        : path.join(base, "index.html");
    let file = target;
    try {
      const stat = await fsp.stat(file);
      if (stat.isDirectory()) file = path.join(file, "index.html");
      await fsp.access(file);
    } catch {
      file = path.join(base, "index.html"); // SPA fallback
    }
    let content: Buffer;
    let mtimeMs = 0;
    try {
      // ONE handle for both, not stat-then-read: a handle names an inode, so the validator
      // is guaranteed to describe the bytes being sent. Read and stat as separate lookups
      // can straddle a file replacement and tag old bytes with a new mtime — after which
      // the client revalidates, matches, and keeps the stale copy indefinitely.
      const handle = await fsp.open(file, "r");
      try {
        mtimeMs = (await handle.stat()).mtimeMs;
        content = await handle.readFile();
      } finally {
        await handle.close();
      }
    } catch {
      return c.json(errorBody("not_found", "Resource does not exist."), 404);
    }
    // A weak size+mtime validator, the classic disk-file shape — hashing every
    // response would cost more than the 304s save.
    const etag = `W/"${content.byteLength}-${Math.round(mtimeMs)}"`;
    return staticResponse(c, content, path.relative(base, file).split(path.sep).join("/"), etag);
  });
}

// ---------------------------------------------------------------------------
// The business surface: everything below travels with the platform version.
// Called from hmr/platform.ts's create() at every App creation — see the module doc.
// ---------------------------------------------------------------------------

/**
 * Assembles the business service graph over the claimed runtime capabilities.
 *
 * The db handle, auth service, channel hub, config object and hmr host come from the
 * claim — one live instance per process, shared with the runtime. Everything else is
 * built fresh per App, which is exactly what makes it hot-swappable.
 */