@miaws/miaw 1.18.3 → 1.18.5

package/src/server/routes/instance/httpapi/server.ts

@@ -0,0 +1,298 @@
+import { Config as EffectConfig, Context, Effect, Layer } from "effect"
+import { HttpApiBuilder, OpenApi } from "effect/unstable/httpapi"
+import { HttpClient, HttpMiddleware, HttpRouter, HttpServer, HttpServerResponse } from "effect/unstable/http"
+import * as Socket from "effect/unstable/socket/Socket"
+import { FSUtil } from "@miaw/core/fs-util"
+import * as Observability from "@miaw/core/observability"
+import { Account } from "@/account/account"
+import { Agent } from "@/agent/agent"
+import { Auth } from "@/auth"
+import { BackgroundJob } from "@/background/job"
+import { Command } from "@/command"
+import { Config } from "@/config/config"
+import { Workspace } from "@/control-plane/workspace"
+import { Env } from "@/env"
+import { EventV2Bridge } from "@/event-v2-bridge"
+import { Format } from "@/format"
+import { Git } from "@/git"
+import { Installation } from "@/installation"
+import { LSP } from "@/lsp/lsp"
+import { MCP } from "@/mcp"
+import { McpAuth } from "@/mcp/auth"
+import { Permission } from "@/permission"
+import { Plugin } from "@/plugin"
+import { PluginPtyEnvironment } from "@/plugin/pty-environment"
+import { InstanceStore } from "@/project/instance-store"
+import { Project } from "@/project/project"
+import { Vcs } from "@/project/vcs"
+import { ProviderAuth } from "@/provider/auth"
+import { Provider } from "@/provider/provider"
+import { Question } from "@/question"
+import { SessionCompaction } from "@/session/compaction"
+import { Instruction } from "@/session/instruction"
+import { LLM } from "@/session/llm"
+import { SessionProcessor } from "@/session/processor"
+import { SessionPrompt } from "@/session/prompt"
+import { SessionRevert } from "@/session/revert"
+import { SessionRunState } from "@/session/run-state"
+import { Session } from "@/session/session"
+import { SessionStatus } from "@/session/status"
+import { SessionSummary } from "@/session/summary"
+import { Todo } from "@/session/todo"
+import { SessionShare } from "@/share/session"
+import { ShareNext } from "@/share/share-next"
+import { Skill } from "@/skill"
+import { Discovery } from "@/skill/discovery"
+import { Snapshot } from "@/snapshot"
+import { Storage } from "@/storage/storage"
+import { ToolRegistry } from "@/tool/registry"
+import { Truncate } from "@/tool/truncate"
+import { Worktree } from "@/worktree"
+import { RuntimeFlags } from "@/effect/runtime-flags"
+import { MoveSession } from "@miaw/core/control-plane/move-session"
+import { Database } from "@miaw/core/database/database"
+import { LayerNode } from "@miaw/core/effect/layer-node"
+import { httpClient } from "@miaw/core/effect/layer-node-platform"
+import { EventV2 } from "@miaw/core/event"
+import { ModelsDev } from "@miaw/core/models-dev"
+import { Npm } from "@miaw/core/npm"
+import { ProjectV2 } from "@miaw/core/project"
+import { ProjectCopy } from "@miaw/core/project/copy"
+import { PtyTicket } from "@miaw/core/pty/ticket"
+import { Ripgrep } from "@miaw/core/ripgrep"
+import { SessionProjector } from "@miaw/core/session/projector"
+import { lazy } from "@/util/lazy"
+import { CorsConfig, isAllowedCorsOrigin, type CorsOptions } from "@miaw/server/cors"
+import { serveUIEffect } from "@/server/shared/ui"
+import { ServerAuth } from "@/server/auth"
+import { InstanceHttpApi, RootHttpApi } from "./api"
+import { Api } from "@miaw/server/api"
+import { PublicApi } from "./public"
+import {
+  authorizationLayer,
+  authorizationRouterMiddleware,
+  ptyConnectAuthorizationLayer,
+  serverAuthorizationLayer,
+} from "./middleware/authorization"
+import { EventApi } from "./groups/event"
+import { PtyConnectApi } from "./groups/pty"
+import { eventHandlers } from "./handlers/event"
+import { configHandlers } from "./handlers/config"
+import { controlHandlers } from "./handlers/control"
+import { controlPlaneHandlers } from "./handlers/control-plane"
+import { experimentalHandlers } from "./handlers/experimental"
+import { fileHandlers } from "./handlers/file"
+import { globalHandlers } from "./handlers/global"
+import { instanceHandlers } from "./handlers/instance"
+import { mcpHandlers } from "./handlers/mcp"
+import { permissionHandlers } from "./handlers/permission"
+import { projectHandlers } from "./handlers/project"
+import { projectCopyHandlers } from "./handlers/project-copy"
+import { providerHandlers } from "./handlers/provider"
+import { ptyConnectHandlers, ptyHandlers } from "./handlers/pty"
+import { questionHandlers } from "./handlers/question"
+import { sessionHandlers } from "./handlers/session"
+import { syncHandlers } from "./handlers/sync"
+import { tuiHandlers } from "./handlers/tui"
+import { handlers } from "@miaw/server/handlers"
+import { schemaErrorLayer as v2SchemaErrorLayer } from "@miaw/server/middleware/schema-error"
+import { workspaceHandlers } from "./handlers/workspace"
+import { instanceContextLayer } from "./middleware/instance-context"
+import { workspaceRoutingLayer } from "./middleware/workspace-routing"
+import { disposeMiddleware } from "./lifecycle"
+import { memoMap } from "@miaw/core/effect/memo-map"
+import { compressionLayer } from "./middleware/compression"
+import { corsVaryFix } from "./middleware/cors-vary"
+import { errorLayer } from "./middleware/error"
+import { fenceLayer } from "./middleware/fence"
+import { schemaErrorLayer } from "./middleware/schema-error"
+
+export const context = Context.makeUnsafe<unknown>(new Map())
+
+const cors = (corsOptions?: CorsOptions) =>
+  HttpRouter.middleware(
+    HttpMiddleware.cors({
+      allowedOrigins: (origin) => isAllowedCorsOrigin(origin, corsOptions),
+      maxAge: 86_400,
+    }),
+    { global: true },
+  )
+
+// Route tree:
+// - rootApiRoutes: typed /global/* and control routes; auth is declared by RootHttpApi.
+// - eventApiRoutes: typed SSE route with instance routing context and its existing API contract.
+// - ptyConnectApiRoutes: typed WebSocket upgrade route with ticket-aware auth.
+// - instanceApiRoutes: remaining typed instance routes.
+// - uiRoute: raw catch-all fallback; auth is router middleware so public static assets can bypass it.
+const authOnlyRouterLayer = authorizationRouterMiddleware.layer.pipe(Layer.provide(ServerAuth.Config.defaultLayer))
+const httpApiAuthLayer = authorizationLayer.pipe(Layer.provide(ServerAuth.Config.defaultLayer))
+const ptyConnectHttpApiAuthLayer = ptyConnectAuthorizationLayer.pipe(Layer.provide(ServerAuth.Config.defaultLayer))
+const serverHttpApiAuthLayer = serverAuthorizationLayer.pipe(Layer.provide(ServerAuth.Config.defaultLayer))
+const workspaceRoutingLive = workspaceRoutingLayer.pipe(Layer.provide(Socket.layerWebSocketConstructorGlobal))
+const rootApiRoutes = HttpApiBuilder.layer(RootHttpApi).pipe(
+  Layer.provide([controlHandlers, controlPlaneHandlers, globalHandlers]),
+  Layer.provide(schemaErrorLayer),
+  Layer.provide(httpApiAuthLayer),
+)
+const eventApiRoutes = HttpApiBuilder.layer(EventApi).pipe(
+  Layer.provide(eventHandlers),
+  Layer.provide([httpApiAuthLayer, workspaceRoutingLive, instanceContextLayer]),
+)
+const ptyConnectApiRoutes = HttpApiBuilder.layer(PtyConnectApi).pipe(
+  Layer.provide(ptyConnectHandlers),
+  Layer.provide([ptyConnectHttpApiAuthLayer, workspaceRoutingLive, instanceContextLayer]),
+)
+const instanceApiRoutes = HttpApiBuilder.layer(InstanceHttpApi).pipe(
+  Layer.provide([
+    configHandlers,
+    experimentalHandlers,
+    fileHandlers,
+    instanceHandlers,
+    mcpHandlers,
+    projectHandlers,
+    projectCopyHandlers,
+    ptyHandlers,
+    questionHandlers,
+    permissionHandlers,
+    providerHandlers,
+    sessionHandlers,
+    syncHandlers,
+    tuiHandlers,
+    workspaceHandlers,
+  ]),
+)
+
+const instanceRoutes = instanceApiRoutes.pipe(
+  Layer.provide([httpApiAuthLayer, workspaceRoutingLive, instanceContextLayer, schemaErrorLayer]),
+)
+const serverRoutes = HttpApiBuilder.layer(Api).pipe(
+  Layer.provide(handlers),
+  Layer.provide(PluginPtyEnvironment.layer),
+  Layer.provide([serverHttpApiAuthLayer, v2SchemaErrorLayer]),
+)
+
+// `OpenApi.fromApi` is non-trivial; defer until /doc is actually hit so
+// processes that never serve it (CLI, scripts) don't pay at module load.
+// `HttpServerResponse.jsonUnsafe` runs JSON.stringify eagerly, so caching
+// the response also caches the serialized body — every /doc request reuses
+// the same Uint8Array instead of re-stringifying the spec.
+const docResponse = lazy(() => HttpServerResponse.jsonUnsafe(OpenApi.fromApi(PublicApi)))
+
+const docRoute = HttpRouter.use((router) => router.add("GET", "/doc", () => Effect.succeed(docResponse()))).pipe(
+  Layer.provide(authOnlyRouterLayer),
+)
+
+const uiRoute = HttpRouter.use((router) =>
+  Effect.gen(function* () {
+    const fs = yield* FSUtil.Service
+    const client = yield* HttpClient.HttpClient
+    const flags = yield* RuntimeFlags.Service
+    yield* router.add("*", "/*", (request) =>
+      serveUIEffect(request, { fs, client, disableEmbeddedWebUi: flags.disableEmbeddedWebUi }),
+    )
+  }),
+).pipe(Layer.provide(authOnlyRouterLayer))
+
+type RouteRequirements =
+  | HttpRouter.HttpRouter
+  | HttpRouter.Request<"Error", unknown>
+  | HttpRouter.Request<"GlobalError", unknown>
+  | HttpRouter.Request<"Requires", unknown>
+  | HttpRouter.Request<"GlobalRequires", never>
+
+const app = LayerNode.group([
+  Npm.node,
+  FSUtil.node,
+  Database.node,
+  Auth.node,
+  Account.node,
+  Config.node,
+  Env.node,
+  Git.node,
+  Ripgrep.node,
+  Storage.node,
+  Snapshot.node,
+  Plugin.node,
+  ModelsDev.node,
+  Provider.node,
+  ProviderAuth.node,
+  Agent.node,
+  Skill.node,
+  Discovery.node,
+  Question.node,
+  Permission.node,
+  Todo.node,
+  Session.node,
+  SessionProjector.node,
+  SessionStatus.node,
+  BackgroundJob.node,
+  RuntimeFlags.node,
+  EventV2Bridge.node,
+  SessionRunState.node,
+  SessionProcessor.node,
+  SessionCompaction.node,
+  SessionRevert.node,
+  SessionSummary.node,
+  SessionPrompt.node,
+  Instruction.node,
+  LLM.node,
+  LSP.node,
+  MCP.node,
+  McpAuth.node,
+  Command.node,
+  Truncate.node,
+  ToolRegistry.node,
+  Format.node,
+  Project.node,
+  Vcs.node,
+  Workspace.node,
+  Worktree.node,
+  Installation.node,
+  ShareNext.node,
+  SessionShare.node,
+  InstanceStore.node,
+  httpClient,
+  EventV2.node,
+  ProjectV2.node,
+  ProjectCopy.node,
+  PtyTicket.node,
+])
+
+export function createRoutes(
+  corsOptions?: CorsOptions,
+): Layer.Layer<never, EffectConfig.ConfigError, RouteRequirements> {
+  return Layer.mergeAll(
+    rootApiRoutes,
+    eventApiRoutes,
+    ptyConnectApiRoutes,
+    instanceRoutes,
+    serverRoutes,
+    docRoute,
+    uiRoute,
+  ).pipe(
+    Layer.provide([
+      errorLayer,
+      compressionLayer,
+      corsVaryFix,
+      fenceLayer,
+      cors(corsOptions),
+      MoveSession.defaultLayer,
+      HttpServer.layerServices,
+    ]),
+    Layer.provide(LayerNode.buildLayer(app)),
+    Layer.provide(Layer.succeed(CorsConfig)(corsOptions)),
+    Layer.provide(Observability.layer),
+  )
+}
+
+export const routes = createRoutes()
+
+export const webHandler = lazy(() =>
+  HttpRouter.toWebHandler(routes, {
+    disableLogger: true,
+    memoMap,
+    middleware: disposeMiddleware,
+  }),
+)
+
+export * as HttpApiApp from "./server"

package/src/server/routes/instance/httpapi/websocket-tracker.ts

@@ -0,0 +1,57 @@
+import { Context, Effect, Layer, Option } from "effect"
+import * as Socket from "effect/unstable/socket/Socket"
+
+export const SERVER_CLOSING_EVENT = () => new Socket.CloseEvent(1001, "server closing")
+
+type Close = Effect.Effect<void, unknown>
+
+export interface Interface {
+  readonly add: (close: Close) => Effect.Effect<boolean>
+  readonly remove: (close: Close) => Effect.Effect<void>
+  readonly closeAll: Effect.Effect<void>
+}
+
+export class Service extends Context.Service<Service, Interface>()("@miaw/HttpApiWebSocketTracker") {}
+
+export const layer = Layer.sync(Service)(() => {
+  const sockets = new Set<Close>()
+  let closing = false
+  return Service.of({
+    add: (close) =>
+      Effect.gen(function* () {
+        if (closing) return false
+        sockets.add(close)
+        return true
+      }),
+    remove: (close) =>
+      Effect.sync(() => {
+        sockets.delete(close)
+      }),
+    closeAll: Effect.gen(function* () {
+      closing = true
+      const active = Array.from(sockets)
+      sockets.clear()
+      yield* Effect.all(
+        active.map((close) =>
+          close.pipe(
+            Effect.timeout("1 second"),
+            Effect.catch(() => Effect.void),
+          ),
+        ),
+        { concurrency: "unbounded", discard: true },
+      )
+    }),
+  })
+})
+
+export const register = (close: Close) =>
+  Effect.gen(function* () {
+    const tracker = yield* Effect.serviceOption(Service)
+    if (Option.isNone(tracker)) return true
+    const registered = yield* tracker.value.add(close)
+    if (!registered) return false
+    yield* Effect.addFinalizer(() => tracker.value.remove(close))
+    return true
+  })
+
+export * as WebSocketTracker from "./websocket-tracker"

package/src/server/server.ts

@@ -0,0 +1,217 @@
+import "./init-projectors"
+
+import { NodeHttpServer } from "@effect/platform-node"
+import { ConfigProvider, Context, Effect, Exit, Layer, Scope } from "effect"
+import { HttpRouter, HttpServer } from "effect/unstable/http"
+import { OpenApi } from "effect/unstable/httpapi"
+import { createServer } from "node:http"
+import { MDNS } from "./mdns"
+import { HttpApiApp } from "./routes/instance/httpapi/server"
+import { disposeMiddleware } from "./routes/instance/httpapi/lifecycle"
+import { WebSocketTracker } from "./routes/instance/httpapi/websocket-tracker"
+import { PublicApi } from "./routes/instance/httpapi/public"
+import type { CorsOptions } from "@miaw/server/cors"
+import { lazy } from "@/util/lazy"
+
+// @ts-ignore This global is needed to prevent ai-sdk from logging warnings to stdout https://github.com/vercel/ai/blob/2dc67e0ef538307f21368db32d5a12345d98831b/packages/ai/src/logger/log-warnings.ts#L85
+globalThis.AI_SDK_LOG_WARNINGS = false
+
+export type Listener = {
+  hostname: string
+  port: number
+  url: URL
+  stop: (close?: boolean) => Promise<void>
+}
+
+type ServerApp = {
+  fetch(request: Request): Response | Promise<Response>
+  request(input: string | URL | Request, init?: RequestInit): Response | Promise<Response>
+}
+
+type ListenOptions = CorsOptions & {
+  port: number
+  hostname: string
+  mdns?: boolean
+  mdnsDomain?: string
+}
+type ListenerState = {
+  scope: Scope.Scope
+  server: Context.Service.Shape<typeof HttpServer.HttpServer>
+  http: ListenerServer
+  websockets: WebSocketTracker.Interface
+}
+type EffectListener = Omit<Listener, "stop"> & {
+  stop: (close?: boolean) => Effect.Effect<void>
+}
+
+interface ListenerServer {
+  readonly closeAll: Effect.Effect<void>
+}
+
+class ListenerServerService extends Context.Service<ListenerServerService, ListenerServer>()(
+  "@miaw/ListenerServer",
+) {}
+
+export const Default = lazy(() => {
+  const handler = HttpApiApp.webHandler().handler
+  const app: ServerApp = {
+    fetch: (request: Request) => handler(request, HttpApiApp.context),
+    request(input, init) {
+      return app.fetch(input instanceof Request ? input : new Request(new URL(input, "http://localhost"), init))
+    },
+  }
+  return { app }
+})
+
+export async function openapi() {
+  return OpenApi.fromApi(PublicApi)
+}
+
+export let url: URL
+
+export async function listen(opts: ListenOptions): Promise<Listener> {
+  const listener = await Effect.runPromise(listenEffect(opts))
+  return {
+    hostname: listener.hostname,
+    port: listener.port,
+    url: listener.url,
+    stop: (close?: boolean) => Effect.runPromiseExit(listener.stop(close)).then(() => undefined),
+  }
+}
+
+const listenEffect: (opts: ListenOptions) => Effect.Effect<EffectListener, unknown> = Effect.fn("Server.listen")(
+  function* (opts: ListenOptions) {
+    const state = yield* startWithPortFallback(opts)
+    const address = yield* tcpAddress(state)
+    const listenerUrl = makeURL(opts.hostname, address.port)
+    url = listenerUrl
+
+    const unpublishMdns = yield* setupMdns(opts, address.port, state.scope)
+
+    return {
+      hostname: opts.hostname,
+      port: address.port,
+      url: listenerUrl,
+      stop: yield* makeStop(state, unpublishMdns),
+    }
+  },
+)
+
+function listenerLayer(opts: ListenOptions, port: number) {
+  return HttpRouter.serve(HttpApiApp.createRoutes(opts), {
+    middleware: disposeMiddleware,
+    disableLogger: true,
+    disableListenLog: true,
+  }).pipe(
+    Layer.provideMerge(WebSocketTracker.layer),
+    Layer.provideMerge(serverLayer({ port, hostname: opts.hostname })),
+    // Install a fresh `ConfigProvider` per listener so `Config.string(...)`
+    // reads reflect the current `process.env`. Effect's default
+    // `ConfigProvider` snapshots `process.env` on first read and caches the
+    // result on a module-singleton Reference; without overriding it here,
+    // every later `Server.listen()` keeps observing that initial snapshot.
+    Layer.provide(ConfigProvider.layer(ConfigProvider.fromEnv())),
+  )
+}
+
+function startWithPortFallback(opts: ListenOptions) {
+  if (opts.port !== 0) return startListener(opts, opts.port)
+  // Match the legacy listener port-resolution behavior: explicit `0` prefers
+  // 4096 first, then any free port.
+  return startListener(opts, 4096).pipe(Effect.catch(() => startListener(opts, 0)))
+}
+
+function startListener(opts: ListenOptions, port: number) {
+  const scope = Scope.makeUnsafe()
+  return Layer.buildWithMemoMap(listenerLayer(opts, port), Layer.makeMemoMapUnsafe(), scope).pipe(
+    Effect.provide(HttpApiApp.context),
+    Effect.onError(() => Scope.close(scope, Exit.void).pipe(Effect.ignore)),
+    Effect.map(
+      (ctx): ListenerState => ({
+        scope,
+        server: Context.get(ctx, HttpServer.HttpServer),
+        http: Context.get(ctx, ListenerServerService),
+        websockets: Context.get(ctx, WebSocketTracker.Service),
+      }),
+    ),
+  )
+}
+
+function tcpAddress(state: ListenerState) {
+  return Effect.gen(function* () {
+    if (state.server.address._tag === "TcpAddress") return state.server.address
+    yield* Scope.close(state.scope, Exit.void).pipe(Effect.ignore)
+    return yield* Effect.die(new Error(`Unexpected HttpServer address tag: ${state.server.address._tag}`))
+  })
+}
+
+function makeURL(hostname: string, port: number) {
+  const result = new URL("http://localhost")
+  result.hostname = hostname
+  result.port = String(port)
+  return result
+}
+
+function setupMdns(opts: ListenOptions, port: number, scope: Scope.Scope) {
+  return Effect.gen(function* () {
+    const publish =
+      opts.mdns && port && opts.hostname !== "127.0.0.1" && opts.hostname !== "localhost" && opts.hostname !== "::1"
+    if (publish) {
+      const unpublish = yield* Effect.cached(Effect.sync(() => MDNS.unpublish()))
+      yield* Effect.sync(() => MDNS.publish(port, opts.mdnsDomain))
+      yield* Scope.addFinalizer(scope, unpublish)
+      return unpublish
+    }
+    if (opts.mdns) {
+      yield* Effect.logWarning("mDNS enabled but hostname is loopback; skipping mDNS publish")
+    }
+    return Effect.void
+  })
+}
+
+function makeStop(state: ListenerState, unpublishMdns: Effect.Effect<void>) {
+  return Effect.gen(function* () {
+    const forceCloseOnce = yield* Effect.cached(forceClose(state).pipe(Effect.ignore))
+    const closeScopeOnce = yield* Effect.cached(Scope.close(state.scope, Exit.void).pipe(Effect.ignore))
+
+    return (close?: boolean) =>
+      Effect.gen(function* () {
+        yield* unpublishMdns
+        if (close) yield* forceCloseOnce
+        yield* closeScopeOnce
+      })
+  })
+}
+
+function forceClose(state: ListenerState) {
+  return Effect.all([state.http.closeAll, state.websockets.closeAll], { concurrency: "unbounded", discard: true })
+}
+
+function serverLayer(opts: { port: number; hostname: string }) {
+  const server = createServer()
+  const serverRef = { closeStarted: false, forceStop: false }
+  const close = server.close.bind(server)
+  // Keep shutdown owned by NodeHttpServer, but honor listener.stop(true) by
+  // force-closing active HTTP sockets when its finalizer calls server.close().
+  // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion -- Node's overloads don't preserve a monkey-patched method assignment.
+  server.close = ((callback?: Parameters<typeof server.close>[0]) => {
+    serverRef.closeStarted = true
+    const result = close(callback)
+    if (serverRef.forceStop) server.closeAllConnections()
+    return result
+  }) as typeof server.close
+
+  return Layer.mergeAll(
+    NodeHttpServer.layer(() => server, { port: opts.port, host: opts.hostname, gracefulShutdownTimeout: "1 second" }),
+    Layer.succeed(ListenerServerService)(
+      ListenerServerService.of({
+        closeAll: Effect.sync(() => {
+          serverRef.forceStop = true
+          if (serverRef.closeStarted) server.closeAllConnections()
+        }),
+      }),
+    ),
+  )
+}
+
+export * as Server from "./server"

package/src/server/shared/fence.ts

@@ -0,0 +1,60 @@
+import { Database } from "@miaw/core/database/database"
+import { inArray } from "drizzle-orm"
+import { EventSequenceTable } from "@miaw/core/event/sql"
+import { Workspace } from "@/control-plane/workspace"
+import type { WorkspaceV2 } from "@miaw/core/workspace"
+import { Effect } from "effect"
+
+export const HEADER = "x-miaw-sync"
+export type State = Record<string, number>
+
+export function load(db: Database.Interface["db"], ids?: string[]) {
+  return Effect.gen(function* () {
+    const rows = yield* (
+      ids?.length
+        ? db.select().from(EventSequenceTable).where(inArray(EventSequenceTable.aggregate_id, ids)).all()
+        : db.select().from(EventSequenceTable).all()
+    ).pipe(Effect.orDie)
+
+    return Object.fromEntries(rows.map((row) => [row.aggregate_id, row.seq]))
+  })
+}
+
+export function diff(prev: State, next: State) {
+  const ids = new Set([...Object.keys(prev), ...Object.keys(next)])
+  return Object.fromEntries(
+    [...ids]
+      .map((id) => [id, next[id] ?? -1] as const)
+      .filter(([id, seq]) => {
+        return (prev[id] ?? -1) !== seq
+      }),
+  )
+}
+
+export function parse(headers: Headers): State | undefined {
+  const raw = headers.get(HEADER)
+  if (!raw) return
+
+  let data
+  try {
+    data = JSON.parse(raw)
+  } catch {
+    return
+  }
+
+  if (!data || typeof data !== "object") return
+
+  return Object.fromEntries(
+    Object.entries(data).filter((entry): entry is [string, number] => {
+      return typeof entry[0] === "string" && Number.isInteger(entry[1])
+    }),
+  )
+}
+
+export function wait(workspaceID: WorkspaceV2.ID, state: State, signal?: AbortSignal) {
+  return Effect.gen(function* () {
+    yield* Effect.logInfo("waiting for state", { workspaceID, state })
+    yield* Workspace.Service.use((workspace) => workspace.waitForSync(workspaceID, state, signal))
+    yield* Effect.logInfo("state fully synced", { workspaceID, state })
+  })
+}

package/src/server/shared/pty-ticket.ts

@@ -0,0 +1,15 @@
+export const PTY_CONNECT_TICKET_QUERY = "ticket"
+export const PTY_CONNECT_TOKEN_HEADER = "x-miaw-ticket"
+export const PTY_CONNECT_TOKEN_HEADER_VALUE = "1"
+
+const PTY_CONNECT_PATH = /^\/pty\/[^/]+\/connect$/
+
+// Auth middleware skips Basic Auth when this matches; the PTY connect handler
+// is then responsible for validating the ticket.
+export function isPtyConnectPath(pathname: string) {
+  return PTY_CONNECT_PATH.test(pathname)
+}
+
+export function hasPtyConnectTicketURL(url: URL) {
+  return isPtyConnectPath(url.pathname) && !!url.searchParams.get(PTY_CONNECT_TICKET_QUERY)
+}

package/src/server/shared/public-ui.ts

@@ -0,0 +1,12 @@
+// Static UI assets the browser fetches without app-managed credentials, e.g.
+// the manifest link in <head>. These bypass auth so the page can install/render
+// the manifest icons even when a server password is configured.
+export const PUBLIC_UI_PATHS = new Set<string>([
+  "/site.webmanifest",
+  "/web-app-manifest-192x192.png",
+  "/web-app-manifest-512x512.png",
+])
+
+export function isPublicUIPath(method: string, pathname: string) {
+  return method === "GET" && PUBLIC_UI_PATHS.has(pathname)
+}

package/src/server/shared/tui-control.ts

@@ -0,0 +1,28 @@
+import { AsyncQueue } from "@/util/queue"
+import { Schema } from "effect"
+
+export const TuiRequest = Schema.Struct({
+  path: Schema.String,
+  body: Schema.Unknown,
+})
+
+export type TuiRequest = Schema.Schema.Type<typeof TuiRequest>
+
+const request = new AsyncQueue<TuiRequest>()
+const response = new AsyncQueue<unknown>()
+
+export function nextTuiRequest() {
+  return request.next()
+}
+
+export function submitTuiRequest(body: TuiRequest) {
+  request.push(body)
+}
+
+export function submitTuiResponse(body: unknown) {
+  response.push(body)
+}
+
+export function nextTuiResponse() {
+  return response.next()
+}