@huynle/hub 0.7.4 → 0.8.1

package/src/central/workspaces/sidechats.ts

@@ -0,0 +1,482 @@
+// Context-linked side chats (HWA-13; contract: Workspaces `POST /workspaces/:id/side-chats` in docs/plans/2026-10-30-
+// hub-workspaces-artifacts-contracts.md, protocol SideChat and WORKSPACE_LIMITS). This module is the record store
+// and the pure snapshot logic; sidechats-routes.ts is the HTTP side, which reads the source and launches the
+// side-chat session through the existing /api/agent routes (so their grants, scopes and audits apply unchanged).
+//
+// A side chat is a NEW session launched through the launch API, started with a bounded copy of some of the source
+// session's transcript. The link to the source is this record only: the side-chat session's native
+// parentID/rootID and any supervision are untouched (a launched session is a root session).
+//
+// Snapshot rules (snapshotOf):
+// - Sources are message IDs of the source session's transcript (timeline rows grouped by messageID), at most
+//   sideChatContextItems, read from the newest SNAPSHOT_SCAN_ROWS rows; no sources = the newest messages.
+//   `artifact_revision` sources are not supported in v1 (unsupported, nothing created).
+// - What is stored is exactly what is delivered: the rendered context fits SIDECHAT_DELIVERY_MAX characters (the
+//   launch prompt and message text limits), and its quoted text stays within sideChatContextBytes. When it does
+//   not fit, the oldest items are omitted (counted in `omitted`) and a single oversized item is clipped (`clipped`).
+// - Each item keeps its time and ordering references (`at`, `pos`); the snapshot keeps `takenAt`, its
+//   `generation` (1 at creation, +1 per explicit refresh) and the newest source row time it saw.
+// - Refresh re-reads the same sources (or, for a "recent" snapshot, the newest messages again). An item whose
+//   source message can no longer be read keeps its previous text marked `stale: "missing"`; an item whose text
+//   changed is marked `changed`.
+//
+// Storage (StateStore, tenant = hub user): `workspace-sidechats` (one record per side chat, by ID) and
+// `workspace-sidechat-index` (one aggregate per workspace: the IDs, to cap sideChatsPerWorkspace atomically; a
+// reservation without a record is dropped after RESERVATION_MS). Records survive session and launch expiry.
+// Events are compact and text-free (IDs, revisions, counts).
+import { createHash, randomBytes } from "node:crypto"
+import { ID_PREFIXES, LIST_LIMIT_DEFAULT, LIST_LIMIT_MAX, WORKSPACE_LIMITS, type Page, type SideChat } from "../../protocol"
+import type { Clock, StateStore } from "../backend/types"
+import type { EventInput } from "../agent/events"
+import { AgentError } from "../agent/errors"
+import { PROMPT_MAX } from "../agent/launch-spec"
+import { TEXT_MAX } from "../agent/messages"
+import { updateVersioned } from "../agent/versioned"
+import { RESERVATION_MS } from "./store"
+
+export const WORKSPACE_SIDECHATS = "workspace-sidechats"
+export const WORKSPACE_SIDECHAT_INDEX = "workspace-sidechat-index"
+
+/** The rendered context (launch prompt, refresh message) never exceeds the launch prompt or message text limit. */
+export const SIDECHAT_DELIVERY_MAX = Math.min(PROMPT_MAX, TEXT_MAX)
+/** Newest transcript rows a snapshot looks at (the log route's maximum page). */
+export const SNAPSHOT_SCAN_ROWS = 200
+/** Longest source message ID accepted. */
+export const SOURCE_ID_MAX = 128
+
+export interface SideChatLimits {
+  readonly sideChatsPerWorkspace: number
+  readonly sideChatContextItems: number
+  readonly sideChatContextBytes: number
+  readonly deliveryMax: number
+}
+
+export const SIDECHAT_LIMITS: SideChatLimits = {
+  sideChatsPerWorkspace: WORKSPACE_LIMITS.sideChatsPerWorkspace,
+  sideChatContextItems: WORKSPACE_LIMITS.sideChatContextItems,
+  sideChatContextBytes: WORKSPACE_LIMITS.sideChatContextBytes,
+  deliveryMax: SIDECHAT_DELIVERY_MAX,
+}
+
+export type SnapshotRole = "user" | "assistant" | "message"
+
+export interface SnapshotItem {
+  readonly kind: "message"
+  /** The source message ID. */
+  readonly id: string
+  readonly role: SnapshotRole
+  /** When the source message was written (ms), when the spoke reported it. */
+  readonly at?: number
+  /** The source's ordering position, when reported. */
+  readonly pos?: number
+  readonly text: string
+  /** UTF-8 bytes of `text`. */
+  readonly bytes: number
+  readonly clipped?: true
+  /** Refresh markers: the source message changed since the previous snapshot, or can't be read any more. */
+  readonly changed?: true
+  readonly stale?: "missing"
+}
+
+export interface SideChatSnapshot {
+  readonly generation: number
+  readonly takenAt: number
+  /** selected: the caller named the messages; recent: the newest messages at the time. */
+  readonly mode: "selected" | "recent"
+  readonly items: readonly SnapshotItem[]
+  readonly bytes: number
+  /** Selected or newest messages left out to stay within the bounds. */
+  readonly omitted: number
+  /** The newest source row time seen when the snapshot was taken (the "as of" reference). */
+  readonly sourceNewestAt?: number
+}
+
+/**
+ * The stored record: the frozen SideChat plus additive fields. `sessionID` is set once the launch reports the
+ * side-chat session (absent while it launches, or when the launch never produced one).
+ */
+export interface StoredSideChat extends Omit<SideChat, "sessionID"> {
+  readonly sessionID?: string
+  readonly launchID: string
+  /** Who created it: `user` or `app:<token id>` (as launches record it). */
+  readonly by: string
+  readonly bindingID: string
+  readonly machineID: string
+  readonly harness: string
+  readonly snapshot: SideChatSnapshot
+  readonly updatedAt: number
+}
+
+interface IndexEntry {
+  readonly id: string
+  readonly at: number
+}
+interface IndexRecord {
+  readonly v: 1
+  readonly entries: readonly IndexEntry[]
+}
+
+// ---------- the snapshot (pure) ----------
+
+/** A transcript row as the spoke's timeline reports it (src/spoke/timeline.ts TimelineItem); unknown fields ignored. */
+interface Row {
+  readonly messageID: string
+  readonly kind: string
+  readonly text?: string
+  readonly name?: string
+  readonly state?: string
+  readonly at?: number
+  readonly pos?: number
+}
+
+type Message = Omit<SnapshotItem, "bytes">
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+const num = (v: unknown) => (typeof v === "number" && Number.isFinite(v) ? v : undefined)
+
+function rowOf(raw: unknown): Row | undefined {
+  if (!isObj(raw) || typeof raw.messageID !== "string" || !raw.messageID || typeof raw.kind !== "string") return undefined
+  const at = num(raw.at)
+  const pos = num(raw.pos)
+  return {
+    messageID: raw.messageID,
+    kind: raw.kind,
+    ...(typeof raw.text === "string" ? { text: raw.text } : {}),
+    ...(typeof raw.name === "string" ? { name: raw.name } : {}),
+    ...(typeof raw.state === "string" ? { state: raw.state } : {}),
+    ...(at !== undefined ? { at } : {}),
+    ...(pos !== undefined ? { pos } : {}),
+  }
+}
+
+/** Control characters the launch prompt and message routes refuse (tab, newline and CR stay). */
+const CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f\u2028\u2029]/g
+const clean = (text: string) => text.replace(CONTROL, "")
+const utf8 = (text: string) => Buffer.byteLength(text, "utf8")
+
+/** The first `max` UTF-8 bytes of `text`, never splitting a character. */
+export function clipBytes(text: string, max: number): string {
+  if (utf8(text) <= max) return text
+  return Buffer.from(text, "utf8").subarray(0, Math.max(0, max)).toString("utf8").replace(/\uFFFD+$/, "")
+}
+
+/** Transcript order: by position, else time, else as reported. */
+const byOrder = (a: { pos?: number; at?: number; i: number }, b: { pos?: number; at?: number; i: number }) =>
+  a.pos !== undefined && b.pos !== undefined ? a.pos - b.pos : a.at !== undefined && b.at !== undefined ? a.at - b.at : a.i - b.i
+
+const defined = (values: readonly (number | undefined)[]) => values.filter((v): v is number => v !== undefined)
+
+/** One message's rows as snapshot text: user, assistant and hub-message text; tools as one-line markers. */
+function messageOf(rows: readonly Row[]): Message | undefined {
+  const parts: string[] = []
+  let role: SnapshotRole | undefined
+  for (const row of rows) {
+    if (row.kind === "user" || row.kind === "assistant" || row.kind === "message") {
+      role ??= row.kind
+      if (row.text) parts.push(clean(row.text))
+    } else if (row.kind === "tool") parts.push(`[tool ${clean(row.name ?? "call").slice(0, 80)}${row.state ? ` ${row.state}` : ""}]`)
+    // Reasoning rows stay out of the copy.
+  }
+  if (!role) return undefined
+  const at = defined(rows.map((r) => r.at))
+  const pos = defined(rows.map((r) => r.pos))
+  return {
+    kind: "message",
+    id: rows[0]!.messageID,
+    role,
+    ...(at.length ? { at: Math.min(...at) } : {}),
+    ...(pos.length ? { pos: Math.min(...pos) } : {}),
+    text: parts.join("\n").trim(),
+  }
+}
+
+/** The source's messages in transcript order, and the newest row time. */
+export function messagesOf(rawRows: readonly unknown[]): { messages: Message[]; newestAt?: number } {
+  const rows = rawRows.map(rowOf).filter((r): r is Row => r !== undefined)
+  const ordered = rows.map((row, i) => ({ ...row, i })).sort(byOrder)
+  const byMessage = new Map<string, Row[]>()
+  for (const row of ordered) byMessage.set(row.messageID, [...(byMessage.get(row.messageID) ?? []), row])
+  const messages = [...byMessage.values()].map(messageOf).filter((m): m is Message => m !== undefined)
+  const times = defined(rows.map((r) => r.at))
+  return { messages, ...(times.length ? { newestAt: Math.max(...times) } : {}) }
+}
+
+export interface SnapshotRequest {
+  /** Named source messages (in any order); empty = the newest messages. */
+  readonly ids: readonly string[]
+  readonly limits?: Partial<SideChatLimits>
+  /** For refresh: the previous snapshot (its mode, changed / missing markers). */
+  readonly previous?: SideChatSnapshot
+}
+
+export interface RenderInfo {
+  readonly sideChatID: string
+  readonly workspaceID: string
+  readonly sourceSessionID: string
+}
+
+const isoOf = (ms: number | undefined) => (ms === undefined ? "time unknown" : new Date(ms).toISOString())
+
+/** The context a side-chat session gets (the launch prompt; a refresh's message): exactly the snapshot's items. */
+export function renderContext(info: RenderInfo, snapshot: SideChatSnapshot): string {
+  const intro =
+    snapshot.generation === 1
+      ? `[Hub side chat ${info.sideChatID}] You are a side conversation started from session ${info.sourceSessionID} (hub workspace ${info.workspaceID}). ` +
+        `Below is a read-only copy of ${snapshot.items.length} message(s) from that session, taken ${isoOf(snapshot.takenAt)}. ` +
+        "It does not update by itself and you cannot act in that session from here. Briefly acknowledge the context, then answer the user's questions in this conversation."
+      : `[Hub side chat ${info.sideChatID}] The user refreshed the context from session ${info.sourceSessionID} (${isoOf(snapshot.takenAt)}, refresh ${snapshot.generation - 1}). ` +
+        "It replaces the earlier copy; items marked changed or missing differ from it."
+  const lines = [intro]
+  if (snapshot.omitted > 0) lines.push(`(${snapshot.omitted} older message(s) were left out to stay within the side-chat context bounds.)`)
+  lines.push("--- context ---")
+  snapshot.items.forEach((item, i) => {
+    const marks = [item.clipped ? "clipped" : "", item.changed ? "changed" : "", item.stale === "missing" ? "missing at source (previous copy)" : ""].filter(Boolean)
+    lines.push(`[${i + 1}] ${item.role} · ${isoOf(item.at)} · ${item.id}${marks.length ? ` · ${marks.join(", ")}` : ""}`, item.text, "")
+  })
+  lines.push("--- end of context ---")
+  return lines.join("\n")
+}
+
+/** The messages a snapshot quotes, before bounds: the newest ones, or the named ones (previous copies for missing). */
+function pick(messages: readonly Message[], request: SnapshotRequest, mode: SideChatSnapshot["mode"], items: number): { picked: Message[]; omitted: number } {
+  if (mode === "recent") {
+    const withText = messages.filter((m) => m.text)
+    const picked = withText.slice(-items)
+    return { picked, omitted: withText.length - picked.length }
+  }
+  const byID = new Map(messages.map((m) => [m.id, m]))
+  const before = new Map((request.previous?.items ?? []).map((item) => [item.id, item]))
+  const missing = request.ids.filter((id) => !byID.has(id) && !before.has(id))
+  if (missing.length) {
+    throw new AgentError("invalid", `${missing.length} source message(s) are not among the source session's newest ${SNAPSHOT_SCAN_ROWS} transcript rows`, { extra: { missing: missing.slice(0, 20) } })
+  }
+  const picked: Message[] = request.ids.map((id) => {
+    const found = byID.get(id)
+    if (found) return found
+    const { bytes: _bytes, changed: _changed, ...old } = before.get(id)!
+    return { ...old, stale: "missing" as const }
+  })
+  return { picked: picked.map((m, i) => ({ ...m, i })).sort(byOrder).map(({ i: _i, ...m }) => m), omitted: 0 }
+}
+
+/** Marks items whose text differs from the previous snapshot's (refresh). */
+function marked(picked: readonly Message[], previous: SideChatSnapshot | undefined): Message[] {
+  if (!previous) return [...picked]
+  const before = new Map(previous.items.map((item) => [item.id, item]))
+  return picked.map((item) => {
+    const old = before.get(item.id)
+    const { changed: _changed, ...rest } = item
+    return item.stale !== "missing" && old && old.stale !== "missing" && !old.clipped && old.text !== item.text ? { ...rest, changed: true as const } : rest
+  })
+}
+
+/**
+ * Builds a bounded snapshot from the source rows. Throws invalid when named messages are neither among the rows nor
+ * in the previous snapshot (a refresh keeps the previous copy of a message it can no longer read, marked missing).
+ */
+export function snapshotOf(rawRows: readonly unknown[], request: SnapshotRequest, info: RenderInfo, takenAt: number): SideChatSnapshot {
+  const limits = { ...SIDECHAT_LIMITS, ...request.limits }
+  const { messages, newestAt } = messagesOf(rawRows)
+  const mode: SideChatSnapshot["mode"] = request.previous?.mode ?? (request.ids.length ? "selected" : "recent")
+  const chosen = pick(messages, request, mode, limits.sideChatContextItems)
+  let omitted = chosen.omitted
+  let items: SnapshotItem[] = marked(chosen.picked, request.previous).map((m) => {
+    const text = clipBytes(m.text, limits.sideChatContextBytes)
+    return { ...m, text, bytes: utf8(text), ...(text !== m.text ? { clipped: true as const } : {}) }
+  })
+  const snapshot = (): SideChatSnapshot => ({
+    generation: (request.previous?.generation ?? 0) + 1,
+    takenAt,
+    mode,
+    items,
+    bytes: items.reduce((n, item) => n + item.bytes, 0),
+    omitted,
+    ...(newestAt !== undefined ? { sourceNewestAt: newestAt } : {}),
+  })
+  // The newest items win: drop the oldest until the quoted text and the whole render fit.
+  const tooBig = () => {
+    const s = snapshot()
+    return s.bytes > limits.sideChatContextBytes || renderContext(info, s).length > limits.deliveryMax
+  }
+  while (items.length > 1 && tooBig()) {
+    items = items.slice(1)
+    omitted++
+  }
+  const over = renderContext(info, snapshot()).length - limits.deliveryMax
+  if (items.length === 1 && over > 0) {
+    const only = items[0]!
+    // Characters over the limit, as bytes (≥ 1 byte per character), and a margin for the clipped marker.
+    const text = clipBytes(only.text, Math.max(0, only.bytes - over * 4 - 32))
+    items = [{ ...only, text, bytes: utf8(text), clipped: true }]
+  }
+  return snapshot()
+}
+
+// ---------- events (family manage, text-free) ----------
+
+export const sideChatCreatedEvent = (chat: StoredSideChat): EventInput => ({
+  type: "workspace.sidechat.created",
+  family: "manage",
+  subject: { workspaceID: chat.workspaceID, sideChatID: chat.id, sourceSessionID: chat.sourceSessionID, launchID: chat.launchID, machineID: chat.machineID },
+  data: { revision: chat.revision, generation: chat.snapshot.generation, items: chat.snapshot.items.length, bytes: chat.snapshot.bytes, omitted: chat.snapshot.omitted },
+})
+
+/** The launch reported the side-chat session (linked) or the context was refreshed. */
+export function sideChatChangedEvent(chat: StoredSideChat, change: "sidechat_linked" | "sidechat_refreshed"): EventInput {
+  const items = chat.snapshot.items
+  const counts: Record<string, number> = change === "sidechat_refreshed" ? { generation: chat.snapshot.generation, items: items.length, changed: items.filter((i) => i.changed).length, missing: items.filter((i) => i.stale).length } : {}
+  return {
+    type: "workspace.updated",
+    family: "manage",
+    subject: { workspaceID: chat.workspaceID, sideChatID: chat.id, ...(chat.sessionID ? { sessionID: chat.sessionID } : {}) },
+    data: { change, sideChatRevision: chat.revision, ...counts },
+  }
+}
+
+// ---------- the store ----------
+
+export interface SideChatStoreDeps {
+  readonly state: StateStore
+  readonly now?: Clock
+  readonly limits?: Partial<SideChatLimits>
+}
+
+export interface NewSideChat {
+  readonly id: string
+  readonly workspaceID: string
+  readonly sourceSessionID: string
+  readonly launchID: string
+  readonly sessionID?: string
+  readonly by: string
+  readonly bindingID: string
+  readonly machineID: string
+  readonly harness: string
+  readonly snapshot: SideChatSnapshot
+}
+
+/** A side-chat ID; derived from a seed (an Idempotency-Key) so a retried create reuses the same launch key. */
+export function sideChatID(seed?: string): string {
+  const body = seed === undefined ? randomBytes(12).toString("hex") : createHash("sha256").update(seed).digest("hex").slice(0, 24)
+  return `${ID_PREFIXES.sideChat}_${body}`
+}
+
+const sourcesOf = (snapshot: SideChatSnapshot) => snapshot.items.map((item) => ({ kind: "message" as const, id: item.id }))
+
+export class SideChatStore {
+  readonly state: StateStore
+  readonly limits: SideChatLimits
+  private readonly now: Clock
+
+  constructor(deps: SideChatStoreDeps) {
+    this.state = deps.state
+    this.now = deps.now ?? Date.now
+    this.limits = { ...SIDECHAT_LIMITS, ...deps.limits }
+  }
+
+  /** Reserves a slot for `id` in the workspace (rate_limited at the cap). Reserving an ID again is a no-op. */
+  async reserve(userID: string, workspaceID: string, id: string): Promise<void> {
+    const at = this.now()
+    const stored = await this.storedIDs(userID)
+    let full = false
+    await updateVersioned<IndexRecord>(this.state, userID, WORKSPACE_SIDECHAT_INDEX, workspaceID, (current) => {
+      full = false
+      const entries = (current?.entries ?? []).filter((e) => stored.has(e.id) || at - e.at < RESERVATION_MS)
+      if (entries.some((e) => e.id === id)) return undefined
+      if (entries.length >= this.limits.sideChatsPerWorkspace) {
+        full = true
+        return undefined
+      }
+      return { v: 1, entries: [...entries, { id, at }] }
+    })
+    if (full) throw new AgentError("rate_limited", `A workspace has at most ${this.limits.sideChatsPerWorkspace} side chats`, { extra: { limit: this.limits.sideChatsPerWorkspace, retryAfter: 3600 } })
+  }
+
+  /** Frees a reservation whose create failed before its record was written (a written record keeps its slot). */
+  async release(userID: string, workspaceID: string, id: string): Promise<void> {
+    if (await this.get(userID, id)) return
+    await updateVersioned<IndexRecord>(this.state, userID, WORKSPACE_SIDECHAT_INDEX, workspaceID, (current) =>
+      current?.entries.some((e) => e.id === id) ? { v: 1, entries: current.entries.filter((e) => e.id !== id) } : undefined,
+    )
+  }
+
+  /** Writes the record once (a repeat with the same ID answers the existing one, created false). */
+  async insert(userID: string, input: NewSideChat): Promise<{ sideChat: StoredSideChat; created: boolean }> {
+    const at = this.now()
+    const chat: StoredSideChat = {
+      v: 1,
+      id: input.id,
+      workspaceID: input.workspaceID,
+      sourceSessionID: input.sourceSessionID,
+      ...(input.sessionID ? { sessionID: input.sessionID } : {}),
+      sources: sourcesOf(input.snapshot),
+      launchID: input.launchID,
+      by: input.by,
+      bindingID: input.bindingID,
+      machineID: input.machineID,
+      harness: input.harness,
+      snapshot: input.snapshot,
+      revision: 1,
+      createdAt: at,
+      updatedAt: at,
+    }
+    const put = await this.state.put(userID, WORKSPACE_SIDECHATS, chat.id, chat, { ifVersion: 0 })
+    if (put.ok) return { sideChat: chat, created: true }
+    const existing = await this.get(userID, chat.id)
+    if (!existing) throw new Error(`side chat ${chat.id} could not be written`)
+    return { sideChat: existing, created: false }
+  }
+
+  async get(userID: string, id: string): Promise<StoredSideChat | undefined> {
+    const stored = await this.state.get<StoredSideChat>(userID, WORKSPACE_SIDECHATS, id)
+    return stored?.value.v === 1 ? stored.value : undefined
+  }
+
+  /** The side chat (in that workspace, when named), or not_found (also another user's). */
+  async require(userID: string, workspaceID: string | undefined, id: string): Promise<StoredSideChat> {
+    const chat = await this.get(userID, id)
+    if (!chat || (workspaceID !== undefined && chat.workspaceID !== workspaceID)) throw new AgentError("not_found", `No side chat ${id}`)
+    return chat
+  }
+
+  /** The workspace's side chats, oldest first, paged. */
+  async list(userID: string, workspaceID: string, query: { readonly limit?: number; readonly cursor?: string } = {}): Promise<Page<StoredSideChat>> {
+    const limit = query.limit ?? LIST_LIMIT_DEFAULT
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > LIST_LIMIT_MAX) throw new AgentError("invalid", `limit must be 1–${LIST_LIMIT_MAX}`)
+    const all = (await this.state.list<StoredSideChat>(userID, WORKSPACE_SIDECHATS))
+      .map((e) => e.value)
+      .filter((c) => c.v === 1 && c.workspaceID === workspaceID)
+      .sort((a, b) => a.createdAt - b.createdAt || a.id.localeCompare(b.id))
+    let start = 0
+    if (query.cursor !== undefined) {
+      start = all.findIndex((c) => c.id === query.cursor) + 1
+      if (start === 0) throw new AgentError("invalid", "Unknown cursor")
+    }
+    const items = all.slice(start, start + limit)
+    return start + limit < all.length ? { items, cursor: items[items.length - 1]!.id } : { items }
+  }
+
+  /** Records the side-chat session the launch reported (once; a later, different session is ignored). */
+  async link(userID: string, id: string, sessionID: string): Promise<StoredSideChat | undefined> {
+    return updateVersioned<StoredSideChat>(this.state, userID, WORKSPACE_SIDECHATS, id, (current) =>
+      current && current.sessionID === undefined ? { ...current, sessionID, revision: current.revision + 1, updatedAt: this.now() } : undefined,
+    )
+  }
+
+  /** Replaces the snapshot under the expected revision (409 conflict with currentRevision when stale). */
+  async refresh(userID: string, workspaceID: string, id: string, expectedRevision: number, snapshot: SideChatSnapshot): Promise<StoredSideChat> {
+    let current: StoredSideChat | undefined
+    const next = await updateVersioned<StoredSideChat>(this.state, userID, WORKSPACE_SIDECHATS, id, (value) => {
+      current = value
+      if (!value || value.workspaceID !== workspaceID || value.revision !== expectedRevision) return undefined
+      return { ...value, snapshot, sources: sourcesOf(snapshot), revision: value.revision + 1, updatedAt: this.now() }
+    })
+    if (next) return next
+    if (!current || current.workspaceID !== workspaceID) throw new AgentError("not_found", `No side chat ${id}`)
+    throw new AgentError("conflict", "The side chat changed since you read it", { extra: { currentRevision: current.revision } })
+  }
+
+  /** IDs of every stored side chat of the user (their reservations never expire). */
+  private async storedIDs(userID: string): Promise<Set<string>> {
+    return new Set((await this.state.list<StoredSideChat>(userID, WORKSPACE_SIDECHATS)).map((e) => e.key))
+  }
+}