@neurocode-ai/app 1.18.8

package/src/utils/server-errors.ts

@@ -0,0 +1,109 @@
+export type ConfigInvalidError = {
+  name: "ConfigInvalidError"
+  data: {
+    path?: string
+    message?: string
+    issues?: Array<{ message: string; path: string[] }>
+  }
+}
+
+export type ProviderModelNotFoundError = {
+  name: "ProviderModelNotFoundError"
+  data: {
+    providerID: string
+    modelID: string
+    suggestions?: string[]
+  }
+}
+
+type Translator = (key: string, vars?: Record<string, string | number>) => string
+
+function tr(translator: Translator | undefined, key: string, text: string, vars?: Record<string, string | number>) {
+  if (!translator) return text
+  const out = translator(key, vars)
+  if (!out || out === key) return text
+  return out
+}
+
+export function formatServerError(error: unknown, translate?: Translator, fallback?: string) {
+  const unwrapped = unwrapNamedError(error)
+  if (isConfigInvalidErrorLike(unwrapped)) return parseReadableConfigInvalidError(unwrapped, translate)
+  if (isProviderModelNotFoundErrorLike(unwrapped)) return parseReadableProviderModelNotFoundError(unwrapped, translate)
+  if (error instanceof Error && error.message) return error.message
+  if (typeof error === "string" && error) return error
+  if (fallback) return fallback
+  return tr(translate, "error.chain.unknown", "Unknown error")
+}
+
+function unwrapNamedError(error: unknown): unknown {
+  if (error instanceof Error && error.cause && typeof error.cause === "object" && "body" in error.cause) {
+    return (error.cause as Record<string, unknown>).body
+  }
+  return error
+}
+
+// Client-synthesized session not-found errors share one constructor and
+// predicate so the message contract cannot drift between the sync store
+// (server-session.ts), the route lineage (session-lineage.ts), and the
+// not-found fallback matching (session.tsx).
+const sessionNotFoundMessage = (sessionID: string) => `Session not found: ${sessionID}`
+
+export function sessionNotFoundError(sessionID: string) {
+  return new Error(sessionNotFoundMessage(sessionID))
+}
+
+export function isLocalSessionNotFoundError(error: unknown, sessionID: string) {
+  return error instanceof Error && error.message === sessionNotFoundMessage(sessionID)
+}
+
+export function isSessionNotFoundError(error: unknown, sessionID: string) {
+  const unwrapped = unwrapNamedError(error)
+  if (typeof unwrapped !== "object" || unwrapped === null) return false
+  const value = unwrapped as Record<string, unknown>
+  return value._tag === "SessionNotFoundError" && value.sessionID === sessionID
+}
+
+function isConfigInvalidErrorLike(error: unknown): error is ConfigInvalidError {
+  if (typeof error !== "object" || error === null) return false
+  const o = error as Record<string, unknown>
+  return o.name === "ConfigInvalidError" && typeof o.data === "object" && o.data !== null
+}
+
+function isProviderModelNotFoundErrorLike(error: unknown): error is ProviderModelNotFoundError {
+  if (typeof error !== "object" || error === null) return false
+  const o = error as Record<string, unknown>
+  return o.name === "ProviderModelNotFoundError" && typeof o.data === "object" && o.data !== null
+}
+
+export function parseReadableConfigInvalidError(errorInput: ConfigInvalidError, translator?: Translator) {
+  const file = errorInput.data.path && errorInput.data.path !== "config" ? errorInput.data.path : "config"
+  const detail = errorInput.data.message?.trim() ?? ""
+  const issues = (errorInput.data.issues ?? [])
+    .map((issue) => {
+      const msg = issue.message.trim()
+      if (!issue.path.length) return msg
+      return `${issue.path.join(".")}: ${msg}`
+    })
+    .filter(Boolean)
+  const msg = issues.length ? issues.join("\n") : detail
+  if (!msg) return tr(translator, "error.chain.configInvalid", `Config file at ${file} is invalid`, { path: file })
+  return tr(translator, "error.chain.configInvalidWithMessage", `Config file at ${file} is invalid: ${msg}`, {
+    path: file,
+    message: msg,
+  })
+}
+
+function parseReadableProviderModelNotFoundError(errorInput: ProviderModelNotFoundError, translator?: Translator) {
+  const p = errorInput.data.providerID.trim()
+  const m = errorInput.data.modelID.trim()
+  const list = (errorInput.data.suggestions ?? []).map((v) => v.trim()).filter(Boolean)
+  const body = tr(translator, "error.chain.modelNotFound", `Model not found: ${p}/${m}`, { provider: p, model: m })
+  const tail = tr(translator, "error.chain.checkConfig", "Check your config (neurocode.json) provider/model names")
+  if (list.length) {
+    const suggestions = list.slice(0, 5).join(", ")
+    return [body, tr(translator, "error.chain.didYouMean", `Did you mean: ${suggestions}`, { suggestions }), tail].join(
+      "\n",
+    )
+  }
+  return [body, tail].join("\n")
+}

package/src/utils/server-health.test.ts

@@ -0,0 +1,178 @@
+import { describe, expect, test } from "bun:test"
+import type { ServerConnection } from "@/context/server"
+import { checkServerHealth } from "./server-health"
+
+const server: ServerConnection.HttpBase = {
+  url: "http://localhost:4096",
+}
+
+function abortFromInput(input: RequestInfo | URL, init?: RequestInit) {
+  if (init?.signal) return init.signal
+  if (input instanceof Request) return input.signal
+  return undefined
+}
+
+describe("checkServerHealth", () => {
+  test("returns healthy response with version", async () => {
+    let request: URL | undefined
+    const fetch = (async (input: RequestInfo | URL) => {
+      request = input instanceof URL ? input : new URL(input instanceof Request ? input.url : input)
+      return new Response(JSON.stringify({ healthy: true, version: "1.2.3" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      })
+    }) as unknown as typeof globalThis.fetch
+
+    const result = await checkServerHealth(server, fetch)
+
+    expect(result).toEqual({ healthy: true, version: "1.2.3" })
+    expect(request?.pathname).toBe("/api/health")
+  })
+
+  test("falls back to the V1 health endpoint", async () => {
+    const paths: string[] = []
+    const fetch = (async (input: RequestInfo | URL) => {
+      const url = input instanceof URL ? input : new URL(input instanceof Request ? input.url : input)
+      paths.push(url.pathname)
+      if (url.pathname === "/api/health") return new Response(undefined, { status: 404 })
+      return Response.json({ healthy: true, version: "1.18.4" })
+    }) as unknown as typeof globalThis.fetch
+
+    expect(await checkServerHealth(server, fetch)).toEqual({ healthy: true, version: "1.18.4" })
+    expect(paths).toEqual(["/api/health", "/global/health"])
+  })
+
+  test("falls back when the current health response is malformed", async () => {
+    const paths: string[] = []
+    const fetch = (async (input: RequestInfo | URL) => {
+      const url = input instanceof URL ? input : new URL(input instanceof Request ? input.url : input)
+      paths.push(url.pathname)
+      if (url.pathname === "/api/health") return Response.json({})
+      return Response.json({ healthy: true, version: "1.18.4" })
+    }) as unknown as typeof globalThis.fetch
+
+    expect(await checkServerHealth(server, fetch)).toEqual({ healthy: true, version: "1.18.4" })
+    expect(paths).toEqual(["/api/health", "/global/health"])
+  })
+
+  test("allows slow servers thirty seconds by default", async () => {
+    const timeout = Object.getOwnPropertyDescriptor(AbortSignal, "timeout")
+    let timeoutMs = 0
+    Object.defineProperty(AbortSignal, "timeout", {
+      configurable: true,
+      value: (ms: number) => {
+        timeoutMs = ms
+        return new AbortController().signal
+      },
+    })
+
+    const fetch = (async () =>
+      new Response(JSON.stringify({ healthy: true, version: "1.2.3" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      })) as unknown as typeof globalThis.fetch
+
+    await checkServerHealth(server, fetch).finally(() => {
+      if (timeout) Object.defineProperty(AbortSignal, "timeout", timeout)
+      if (!timeout) Reflect.deleteProperty(AbortSignal, "timeout")
+    })
+
+    expect(timeoutMs).toBe(30_000)
+  })
+
+  test("returns unhealthy when request fails", async () => {
+    const fetch = (async () => {
+      throw new Error("network")
+    }) as unknown as typeof globalThis.fetch
+
+    const result = await checkServerHealth(server, fetch)
+
+    expect(result).toEqual({ healthy: false })
+  })
+
+  test("uses timeout fallback when AbortSignal.timeout is unavailable", async () => {
+    const timeout = Object.getOwnPropertyDescriptor(AbortSignal, "timeout")
+    Object.defineProperty(AbortSignal, "timeout", {
+      configurable: true,
+      value: undefined,
+    })
+
+    let aborted = false
+    const fetch = ((input: RequestInfo | URL, init?: RequestInit) =>
+      new Promise<Response>((_resolve, reject) => {
+        const signal = abortFromInput(input, init)
+        signal?.addEventListener(
+          "abort",
+          () => {
+            aborted = true
+            reject(new DOMException("Aborted", "AbortError"))
+          },
+          { once: true },
+        )
+      })) as unknown as typeof globalThis.fetch
+
+    const result = await checkServerHealth(server, fetch, {
+      timeoutMs: 10,
+    }).finally(() => {
+      if (timeout) Object.defineProperty(AbortSignal, "timeout", timeout)
+      if (!timeout) Reflect.deleteProperty(AbortSignal, "timeout")
+    })
+
+    expect(aborted).toBe(true)
+    expect(result).toEqual({ healthy: false })
+  })
+
+  test("uses provided abort signal", async () => {
+    let signal: AbortSignal | undefined
+    const fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      signal = abortFromInput(input, init)
+      return new Response(JSON.stringify({ healthy: true, version: "1.2.3" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      })
+    }) as unknown as typeof globalThis.fetch
+
+    const abort = new AbortController()
+    await checkServerHealth(server, fetch, {
+      signal: abort.signal,
+    })
+
+    expect(signal).toBe(abort.signal)
+  })
+
+  test("retries transient failures and eventually succeeds", async () => {
+    let count = 0
+    const fetch = (async () => {
+      count += 1
+      if (count < 3) throw new TypeError("network")
+      return new Response(JSON.stringify({ healthy: true, version: "1.2.3" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      })
+    }) as unknown as typeof globalThis.fetch
+
+    const result = await checkServerHealth(server, fetch, {
+      retryCount: 2,
+      retryDelayMs: 1,
+    })
+
+    expect(count).toBe(3)
+    expect(result).toEqual({ healthy: true, version: "1.2.3" })
+  })
+
+  test("returns unhealthy when retries are exhausted", async () => {
+    let count = 0
+    const fetch = (async () => {
+      count += 1
+      throw new TypeError("network")
+    }) as unknown as typeof globalThis.fetch
+
+    const result = await checkServerHealth(server, fetch, {
+      retryCount: 2,
+      retryDelayMs: 1,
+    })
+
+    expect(count).toBe(6)
+    expect(result).toEqual({ healthy: false })
+  })
+})

package/src/utils/server-health.ts

@@ -0,0 +1,172 @@
+import { usePlatform } from "@/context/platform"
+import { ServerConnection } from "@/context/server"
+import { authTokenFromCredentials, createSdkForServer } from "./server"
+import { ClientError, NeuroCode } from "@neurocode-ai/client"
+import { Accessor, createEffect, onCleanup } from "solid-js"
+import { createStore, reconcile } from "solid-js/store"
+
+export type ServerHealth = { healthy: boolean; version?: string }
+
+interface CheckServerHealthOptions {
+  timeoutMs?: number
+  signal?: AbortSignal
+  retryCount?: number
+  retryDelayMs?: number
+}
+
+const defaultTimeoutMs = 30_000
+const defaultRetryCount = 2
+const defaultRetryDelayMs = 100
+const cacheMs = 750
+const healthCache = new Map<
+  string,
+  { at: number; done: boolean; fetch: typeof globalThis.fetch; promise: Promise<ServerHealth> }
+>()
+
+function cacheKey(server: ServerConnection.HttpBase) {
+  return `${server.url}\n${server.username ?? ""}\n${server.password ?? ""}`
+}
+
+function timeoutSignal(timeoutMs: number) {
+  const timeout = (AbortSignal as unknown as { timeout?: (ms: number) => AbortSignal }).timeout
+  if (timeout) {
+    try {
+      return {
+        signal: timeout.call(AbortSignal, timeoutMs),
+        clear: undefined as (() => void) | undefined,
+      }
+    } catch {}
+  }
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), timeoutMs)
+  return { signal: controller.signal, clear: () => clearTimeout(timer) }
+}
+
+function wait(ms: number, signal?: AbortSignal) {
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new DOMException("Aborted", "AbortError"))
+      return
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort)
+      resolve()
+    }, ms)
+    const onAbort = () => {
+      clearTimeout(timer)
+      reject(new DOMException("Aborted", "AbortError"))
+    }
+    signal?.addEventListener("abort", onAbort, { once: true })
+  })
+}
+
+function retryable(error: unknown, signal?: AbortSignal) {
+  if (signal?.aborted) return false
+  if (error instanceof ClientError) return error.reason === "Transport"
+  if (!(error instanceof Error)) return false
+  if (error.name === "AbortError" || error.name === "TimeoutError") return false
+  if (error instanceof TypeError) return true
+  return /network|fetch|econnreset|econnrefused|enotfound|timedout/i.test(error.message)
+}
+
+export async function checkServerHealth(
+  server: ServerConnection.HttpBase,
+  fetch: typeof globalThis.fetch,
+  opts?: CheckServerHealthOptions,
+): Promise<ServerHealth> {
+  const timeout = opts?.signal ? undefined : timeoutSignal(opts?.timeoutMs ?? defaultTimeoutMs)
+  const signal = opts?.signal ?? timeout?.signal
+  const retryCount = opts?.retryCount ?? defaultRetryCount
+  const retryDelayMs = opts?.retryDelayMs ?? defaultRetryDelayMs
+  const next = (count: number, error: unknown) => {
+    if (count >= retryCount || !retryable(error, signal)) return Promise.resolve({ healthy: false } as const)
+    return wait(retryDelayMs * (count + 1), signal)
+      .then(() => attempt(count + 1))
+      .catch(() => ({ healthy: false }))
+  }
+  const attempt = async (count: number): Promise<ServerHealth> => {
+    const current = await NeuroCode.make({
+      baseUrl: server.url,
+      fetch,
+      headers: server.password
+        ? {
+            Authorization: `Basic ${authTokenFromCredentials({ username: server.username, password: server.password })}`,
+          }
+        : undefined,
+    })
+      .health.get({ signal })
+      .then((x) =>
+        typeof x.healthy === "boolean"
+          ? { data: { healthy: x.healthy, version: x.version } }
+          : { error: new Error("Invalid health response") },
+      )
+      .catch((error) => ({ error }))
+    if ("data" in current && current.data) return current.data
+    if (signal?.aborted) return { healthy: false }
+
+    return createSdkForServer({ server, fetch, signal })
+      .global.health()
+      .then((x) => (x.error ? next(count, x.error) : { healthy: x.data?.healthy === true, version: x.data?.version }))
+      .catch((error) => next(count, error))
+  }
+  return attempt(0).finally(() => timeout?.clear?.())
+}
+
+const pollMs = 10_000
+
+export function useCheckServerHealth() {
+  const platform = usePlatform()
+  const fetcher = platform.fetch ?? globalThis.fetch
+
+  return (http: ServerConnection.HttpBase) => {
+    const key = cacheKey(http)
+    const hit = healthCache.get(key)
+    const now = Date.now()
+    if (hit && hit.fetch === fetcher && (!hit.done || now - hit.at < cacheMs)) return hit.promise
+    const promise = checkServerHealth(http, fetcher).finally(() => {
+      const next = healthCache.get(key)
+      if (!next || next.promise !== promise) return
+      next.done = true
+      next.at = Date.now()
+    })
+    healthCache.set(key, { at: now, done: false, fetch: fetcher, promise })
+    return promise
+  }
+}
+
+export const useServerHealth = (servers: Accessor<ServerConnection.Any[]>, enabled: Accessor<boolean>) => {
+  const checkServerHealth = useCheckServerHealth()
+  const [status, setStatus] = createStore({} as Record<ServerConnection.Key, ServerHealth | undefined>)
+
+  createEffect(() => {
+    if (!enabled()) {
+      setStatus(reconcile({}))
+      return
+    }
+    const list = servers()
+    let dead = false
+
+    const refresh = async () => {
+      const results: Record<string, ServerHealth> = {}
+      await Promise.all(
+        list.map(async (conn) => {
+          const key = ServerConnection.key(conn)
+          const result = await checkServerHealth(conn.http)
+          results[key] = result
+          if (!dead) setStatus(key, result)
+        }),
+      )
+      if (dead) return
+      setStatus(reconcile(results))
+    }
+
+    void refresh()
+    const id = setInterval(() => void refresh(), pollMs)
+    onCleanup(() => {
+      dead = true
+      clearInterval(id)
+    })
+  })
+
+  return status
+}

package/src/utils/server-protocol.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, test } from "bun:test"
+import { detectServerProtocol } from "./server-protocol"
+
+const server = { url: "http://localhost:4096" }
+const json = (value: unknown, status = 200) =>
+  new Response(JSON.stringify(value), { status, headers: { "content-type": "application/json" } })
+const mockFetch = (run: (input: string | URL | Request) => Promise<Response>) =>
+  Object.assign(run, { preconnect: globalThis.fetch.preconnect })
+
+describe("detectServerProtocol", () => {
+  test("prefers the legacy health endpoint when both API generations exist", async () => {
+    const fetcher = mockFetch((input) => {
+      const path = new URL(input instanceof Request ? input.url : input).pathname
+      if (path === "/global/health") return Promise.resolve(json({ healthy: true, version: "1.18.4" }))
+      return Promise.resolve(json({ healthy: true, version: "2.0.0", pid: 123 }))
+    })
+
+    expect(await detectServerProtocol(server, fetcher)).toBe("v1")
+  })
+
+  test("recognizes V2 health by its process identifier", async () => {
+    const fetcher = mockFetch((input) => {
+      const path = new URL(input instanceof Request ? input.url : input).pathname
+      if (path === "/global/health") return Promise.resolve(json({}, 404))
+      return Promise.resolve(json({ healthy: true, version: "2.0.0", pid: 123 }))
+    })
+
+    expect(await detectServerProtocol(server, fetcher)).toBe("v2")
+  })
+
+  test("recognizes the transitional V1 API health response", async () => {
+    const fetcher = mockFetch((input) => {
+      const path = new URL(input instanceof Request ? input.url : input).pathname
+      if (path === "/global/health") return Promise.resolve(json({}, 404))
+      return Promise.resolve(json({ healthy: true }))
+    })
+
+    expect(await detectServerProtocol(server, fetcher)).toBe("v1")
+  })
+})

package/src/utils/server-protocol.ts

@@ -0,0 +1,35 @@
+import type { ServerConnection } from "@/context/server"
+import { authTokenFromCredentials } from "./server"
+
+export type ServerProtocol = "v1" | "v2"
+
+function headers(server: ServerConnection.HttpBase) {
+  if (!server.password) return
+  return {
+    Authorization: `Basic ${authTokenFromCredentials({ username: server.username, password: server.password })}`,
+  }
+}
+
+async function probe(server: ServerConnection.HttpBase, fetch: typeof globalThis.fetch, path: string) {
+  const response = await fetch(new URL(path, server.url), {
+    headers: headers(server),
+    signal: AbortSignal.timeout(5_000),
+  })
+  if (!response.ok || !response.headers.get("content-type")?.includes("application/json")) return
+  const value: unknown = await response.json()
+  if (!value || typeof value !== "object") return
+  return value
+}
+
+export async function detectServerProtocol(
+  server: ServerConnection.HttpBase,
+  fetch: typeof globalThis.fetch,
+): Promise<ServerProtocol> {
+  const legacy = await probe(server, fetch, "/global/health").catch(() => undefined)
+  if (legacy && "healthy" in legacy && legacy.healthy === true) return "v1"
+
+  const current = await probe(server, fetch, "/api/health").catch(() => undefined)
+  if (current && "pid" in current && typeof current.pid === "number") return "v2"
+  if (current && "healthy" in current && current.healthy === true) return "v1"
+  return "v2"
+}

package/src/utils/server-scope.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, test } from "bun:test"
+import { ScopedKey, ServerScope, SessionRouteKey, SessionStateKey, migrateLegacySessionStateKeys } from "./server-scope"
+
+describe("ServerScope", () => {
+  test("uses a stable local scope for the canonical sidecar", () => {
+    expect(String(ServerScope.fromServerKey("sidecar" as Parameters<typeof ServerScope.fromServerKey>[0]))).toBe(
+      "local",
+    )
+  })
+
+  test("keeps configured loopback servers distinct from the canonical sidecar", () => {
+    expect(
+      String(ServerScope.fromServerKey("http://localhost:4096" as Parameters<typeof ServerScope.fromServerKey>[0])),
+    ).toBe("http://localhost:4096")
+  })
+
+  test("uses a stable local scope for an explicit canonical web server", () => {
+    const key = "http://localhost:4096" as Parameters<typeof ServerScope.fromServerKey>[0]
+    expect(String(ServerScope.fromServerKey(key, key))).toBe("local")
+  })
+})
+
+describe("SessionStateKey", () => {
+  test("combines local and remote scope with route identity", () => {
+    const route = SessionRouteKey.fromRoute("cmVwbw", "session-1")
+    expect(String(SessionStateKey.from(ServerScope.local, route))).toBe("local\0cmVwbw/session-1")
+    expect(String(SessionStateKey.from("https://windows.example" as ServerScope, route))).toBe(
+      "https://windows.example\0cmVwbw/session-1",
+    )
+    expect(SessionStateKey.from("https://debian.example" as ServerScope, route)).not.toBe(
+      SessionStateKey.from("https://windows.example" as ServerScope, route),
+    )
+  })
+
+  test("extracts route keys from scoped and legacy state keys", () => {
+    expect(String(SessionStateKey.route("cmVwbw/session-1"))).toBe("cmVwbw/session-1")
+    expect(String(SessionStateKey.route("local\0cmVwbw/session-1"))).toBe("cmVwbw/session-1")
+    expect(String(SessionStateKey.route("https://debian.example\0cmVwbw/session-1"))).toBe("cmVwbw/session-1")
+  })
+})
+
+describe("migrateLegacySessionStateKeys", () => {
+  test("copies legacy route keys into local scope without overwriting scoped state", () => {
+    expect(
+      migrateLegacySessionStateKeys({
+        "cmVwbw/session-1": { active: "legacy" },
+        "local\0cmVwbw/session-1": { active: "scoped" },
+        "https://debian.example\0cmVwbw/session-1": { active: "remote" },
+      }),
+    ).toEqual({
+      "local\0cmVwbw/session-1": { active: "scoped" },
+      "https://debian.example\0cmVwbw/session-1": { active: "remote" },
+    })
+  })
+
+  test("rejects invalid identity fragments", () => {
+    expect(() => ScopedKey.from(ServerScope.local, "bad\0directory")).toThrow(
+      "Scoped key part cannot contain null bytes",
+    )
+  })
+})

package/src/utils/server-scope.ts

@@ -0,0 +1,73 @@
+import type { ServerConnection } from "@/context/server"
+
+export type ServerScope = string & { readonly __brand: "ServerScope" }
+export type SessionRouteKey = string & { readonly __brand: "SessionRouteKey" }
+export type SessionStateKey = string & { readonly __brand: "SessionStateKey" }
+export type ScopedKey = string & { readonly __brand: "ScopedKey" }
+
+const separator = "\u0000"
+
+function fragment(label: string, value: string) {
+  if (value.includes(separator)) throw new Error(`${label} cannot contain null bytes`)
+  return value
+}
+
+function compose(scope: ServerScope, parts: string[]) {
+  return [fragment("Server scope", scope), ...parts.map((part) => fragment("Scoped key part", part))].join(separator)
+}
+
+export const ServerScope = {
+  local: "local" as ServerScope,
+  fromServerKey(key: ServerConnection.Key, canonicalLocalServer?: ServerConnection.Key) {
+    return fragment(
+      "Server scope",
+      key === "sidecar" || key === canonicalLocalServer ? ServerScope.local : key,
+    ) as ServerScope
+  },
+}
+
+export const SessionRouteKey = {
+  fromRoute(dir: string | undefined, sessionID?: string) {
+    return fragment("Session route", `${dir ?? ""}${sessionID ? "/" + sessionID : ""}`) as SessionRouteKey
+  },
+  fromLegacy(key: string) {
+    return fragment("Legacy session route", key) as SessionRouteKey
+  },
+}
+
+export const SessionStateKey = {
+  from(scope: ServerScope, route: SessionRouteKey) {
+    return compose(scope, [route]) as SessionStateKey
+  },
+  route(key: string) {
+    const split = key.lastIndexOf(separator)
+    return SessionRouteKey.fromLegacy(split === -1 ? key : key.slice(split + 1))
+  },
+  scope(key: string) {
+    const split = key.indexOf(separator)
+    if (split === -1) return ServerScope.local
+    return fragment("Stored server scope", key.slice(0, split)) as ServerScope
+  },
+}
+
+export const ScopedKey = {
+  from(scope: ServerScope, ...parts: string[]) {
+    return compose(scope, parts) as ScopedKey
+  },
+  prefix(scope: ServerScope, ...parts: string[]) {
+    return `${ScopedKey.from(scope, ...parts)}${separator}`
+  },
+}
+
+export function migrateLegacySessionStateKeys(value: unknown) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return value
+  const entries = Object.entries(value)
+  if (entries.every(([key]) => key.includes(separator))) return value
+  const scoped = Object.fromEntries(entries.filter(([key]) => key.includes(separator)))
+  for (const [key, item] of entries) {
+    if (key.includes(separator)) continue
+    const next = SessionStateKey.from(ServerScope.local, SessionRouteKey.fromLegacy(key))
+    if (!(next in scoped)) scoped[next] = item
+  }
+  return scoped
+}