@huynle/hub 0.6.1 → 0.7.2

package/src/central/agent/directory.ts

@@ -0,0 +1,473 @@
+// The agent directory (design §2, §7): who is who among one user's sessions. Persisted per user in
+// UserRecord.agent (agent-data.ts): session records, @names (with rename aliases) and @@role holders.
+//
+// Every rule is evaluated lazily against the clock when the directory is used (no timers):
+// - A session record is created when a spoke reports the session; lastSeen is saved at minute granularity
+//   while it stays online (LAST_SEEN_STEP_MS), and exactly when it stops being reported.
+// - Archive source: the console's Archive (viewPrefs.hiddenSessions). Spokes never report archived OpenCode
+//   sessions (the listing drops them), so SessionInfo.archived never reaches the hub. archivedAt is the first
+//   time the directory sees the session in that list; unarchiving clears it. deletedAt comes from markDeleted.
+// - Names: derived once (names.ts deriveName), from the first non-placeholder title, for root sessions only; a taken derived name
+//   gets a suffix, an explicit taken one fails (name_taken). A name is released NAME_RELEASE_MS after its
+//   session was archived or deleted; a rename keeps the old name as an alias for ALIAS_MS.
+// - Roles: see claimRole. A holder offline (not reported) for ROLE_OFFLINE_MS loses the role, except during
+//   the RECONNECT_WINDOW_MS after the hub started, while spokes reconnect.
+// - At most SESSION_LIMIT records per user: archived/deleted ones are dropped first, then the least recently
+//   seen, with their names and roles.
+// - Primer (design §2.3): a session record remembers when the identity primer reached it (primed); explicit
+//   names are announced to onNamed listeners (the delivery engine primes on them), derived names never are.
+//
+// Tenancy: everything is per user; another user's sessions, names and roles do not exist here (not_found),
+// and ambiguity candidates only ever list the caller's own sessions.
+// Reads (resolve, who, primed) are synchronous: they evaluate the rules on a copy of the stored data and save
+// nothing. Writes (sync, names, roles, primer and deletion marks) are async: they run inside one store update and
+// resolve once it is saved (their errors reject). Uniqueness holds across pods: on a shared (cluster) store an update
+// that lost a race with another pod's write runs again on the fresh data before it resolves.
+// Cluster mode: the SessionSource reports every pod's sessions (the Registry's cluster view), so a sync on one pod
+// never takes another pod's sessions for offline.
+import { roleKey, type AgentData, type AgentName, type AgentRole, type AgentSession } from "../agent-data"
+import type { Store } from "../store"
+import { AgentError } from "./errors"
+import { deriveName, isPlaceholderTitle, isReservedName, isReservedRole, parseAddress, validName, withSuffix, type Address } from "./names"
+
+const MINUTE = 60_000
+const HOUR = 60 * MINUTE
+const DAY = 24 * HOUR
+
+export const SESSION_LIMIT = 2000
+export const NAME_RELEASE_MS = 7 * DAY
+export const ALIAS_MS = 24 * HOUR
+export const ROLE_OFFLINE_MS = 30 * MINUTE
+export const RECONNECT_WINDOW_MS = 2 * MINUTE
+export const LAST_SEEN_STEP_MS = MINUTE
+/** Most candidates listed in an ambiguous error. */
+const CANDIDATES_MAX = 20
+
+/** A session a spoke of the user reports now. */
+export interface ReportedSession {
+  readonly sessionID: string
+  readonly title: string
+  readonly machineID?: string
+  readonly parentID?: string
+  /** Project name, lowercased (the `.project` scope). */
+  readonly project?: string
+  readonly state?: string
+}
+
+/** What the directory needs to know about the user's live sessions. */
+export interface SessionSource {
+  /** The user's sessions reported now (roots and subagents), only ones the user owns. */
+  reported(userID: string): readonly ReportedSession[]
+  /** IDs of the sessions the user archived. */
+  archived(userID: string): ReadonlySet<string>
+}
+
+export type DirectoryStore = Pick<Store, "updateAgentData" | "agentData" | "user">
+
+export interface DirectoryOptions {
+  readonly store: DirectoryStore
+  readonly source: SessionSource
+  readonly now?: () => number
+}
+
+export interface RoleView {
+  readonly role: string
+  readonly project?: string
+  readonly generation: number
+  readonly exclusive?: boolean
+}
+
+/** One session in directory answers. */
+export interface DirectoryEntry {
+  readonly sessionID: string
+  readonly name?: string
+  readonly aliases?: string[]
+  readonly machineID?: string
+  readonly parentID?: string
+  readonly project?: string
+  readonly title?: string
+  readonly state?: string
+  /** A spoke reports it now. */
+  readonly online: boolean
+  readonly lastSeen?: number
+  readonly archived?: boolean
+  readonly roles: RoleView[]
+}
+
+/** Hears an explicit name change (setName); derived names are never announced. */
+export type NamedListener = (userID: string, sessionID: string, name: string) => void
+
+export interface Resolved {
+  readonly address: Address
+  /** One session for an ID or @name; every live holder for a @@role. */
+  readonly sessions: DirectoryEntry[]
+}
+
+/** The working copy of one user's data inside an update. */
+interface Draft {
+  readonly data: AgentData
+  readonly sessions: AgentSession[]
+  readonly byID: Map<string, AgentSession>
+  readonly reported: Map<string, ReportedSession>
+  names: AgentName[]
+  roles: AgentRole[]
+}
+
+const ended = (s: AgentSession | undefined): number | undefined => {
+  const times = [s?.archivedAt, s?.deletedAt].filter((t): t is number => typeof t === "number")
+  return times.length ? Math.min(...times) : undefined
+}
+
+export class Directory {
+  private readonly store: DirectoryStore
+  private readonly source: SessionSource
+  private readonly now: () => number
+  private readonly startedAt: number
+  /** Per user: the sessions reported at the last update (to stamp lastSeen when they go away). */
+  private readonly online = new Map<string, Set<string>>()
+  private readonly named = new Set<NamedListener>()
+
+  constructor(options: DirectoryOptions) {
+    this.store = options.store
+    this.source = options.source
+    this.now = options.now ?? Date.now
+    this.startedAt = this.now()
+  }
+
+  /** Applies what the spokes report and the clock to the user's records (saves only on change). */
+  sync(userID: string): Promise<void> {
+    return this.update(userID, () => undefined)
+  }
+
+  /** Records that a session was deleted (its name is released NAME_RELEASE_MS later). */
+  markDeleted(userID: string, sessionID: string): Promise<void> {
+    return this.update(userID, (draft) => {
+      const record = draft.byID.get(sessionID)
+      if (record && record.deletedAt === undefined) record.deletedAt = this.now()
+    })
+  }
+
+  // ---------- primer ----------
+
+  /** Whether the identity primer reached the session (false for an unknown one). */
+  primed(userID: string, sessionID: string): boolean {
+    return this.read(userID, (draft) => draft.byID.get(sessionID)?.primed !== undefined)
+  }
+
+  /** Records that the identity primer reached the session (an unknown session is ignored). */
+  markPrimed(userID: string, sessionID: string): Promise<void> {
+    return this.update(userID, (draft) => {
+      const record = draft.byID.get(sessionID)
+      if (record && record.primed === undefined) record.primed = this.now()
+    })
+  }
+
+  /** Listens for explicit names (setName); returns the unsubscribe. */
+  onNamed(listener: NamedListener): () => void {
+    this.named.add(listener)
+    return () => void this.named.delete(listener)
+  }
+
+  // ---------- names ----------
+
+  /** Names a session (explicit: a taken name fails); the previous name stays an alias for ALIAS_MS. Tells onNamed listeners. */
+  async setName(userID: string, sessionID: string, requested: string): Promise<{ sessionID: string; name: string; alias?: string }> {
+    const result = await this.assignName(userID, sessionID, requested)
+    for (const listener of this.named) {
+      try {
+        listener(userID, sessionID, result.name)
+      } catch (cause) {
+        console.error("[hub] name listener failed:", cause)
+      }
+    }
+    return result
+  }
+
+  private async assignName(userID: string, sessionID: string, requested: string): Promise<{ sessionID: string; name: string; alias?: string }> {
+    const name = requested.replace(/^@/, "")
+    if (!validName(name)) throw new AgentError("invalid", "A name is 2–40 characters: a-z, 0-9 and -")
+    if (isReservedName(name)) throw new AgentError("invalid", "@me is reserved: it always means the user")
+    return this.update(userID, (draft) => {
+      const record = this.known(draft, sessionID)
+      const held = draft.names.find((n) => n.name === name)
+      if (held && held.sessionID !== sessionID) throw new AgentError("name_taken", `@${name} is taken`)
+      record.named = true
+      const current = draft.names.find((n) => n.sessionID === sessionID && n.expiresAt === undefined)
+      if (current?.name === name) return { sessionID, name }
+      const t = this.now()
+      if (held) draft.names = draft.names.filter((n) => n !== held)
+      if (current) current.expiresAt = t + ALIAS_MS
+      draft.names.push({ name, sessionID, created: t })
+      return { sessionID, name, ...(current ? { alias: current.name } : {}) }
+    })
+  }
+
+  // ---------- roles ----------
+
+  /**
+   * Claims `role` (or `role.project`) for a session. Each new holder gets the next holder generation of
+   * (role, project). An exclusive claim fails (name_taken) while another live holder exists, and nobody else
+   * can claim while an exclusive holder is live. Reserved roles (orchestrator…) need `byUser`
+   * (grants with `roles` come in phase 3). Exclusivity and generations are per (role, project scope).
+   */
+  async claimRole(userID: string, sessionID: string, requested: string, options: { exclusive?: boolean; project?: string; byUser?: boolean } = {}): Promise<RoleView> {
+    const { role, project } = parseRole(requested, options.project)
+    if (isReservedRole(role) && !options.byUser) throw new AgentError("forbidden", `@@${role} is reserved: only the user can assign it`)
+    return this.update(userID, (draft) => {
+      this.known(draft, sessionID)
+      const same = draft.roles.filter((r) => r.role === role && r.project === project)
+      const mine = same.find((r) => r.sessionID === sessionID)
+      const others = same.filter((r) => r !== mine)
+      if (others.some((r) => r.exclusive) || (options.exclusive && others.length)) {
+        throw new AgentError("name_taken", `@@${scoped(role, project)} is held${others.some((r) => r.exclusive) ? " exclusively" : ""} by another session`)
+      }
+      if (mine) {
+        if (options.exclusive) mine.exclusive = true
+        return roleView(mine)
+      }
+      const key = roleKey(role, project)
+      const generations = { ...(draft.data.generations ?? {}) }
+      const generation = (generations[key] ?? 0) + 1
+      generations[key] = generation
+      draft.data.generations = generations
+      const claim: AgentRole = { role, sessionID, ...(project !== undefined ? { project } : {}), generation, ...(options.exclusive ? { exclusive: true } : {}), claimedAt: this.now() }
+      draft.roles.push(claim)
+      return roleView(claim)
+    })
+  }
+
+  /** Gives a role up; not_found when the session does not hold it. */
+  async releaseRole(userID: string, sessionID: string, requested: string, scope?: string): Promise<{ role: string; project?: string }> {
+    const { role, project } = parseRole(requested, scope)
+    return this.update(userID, (draft) => {
+      const held = draft.roles.find((r) => r.sessionID === sessionID && r.role === role && r.project === project)
+      if (!held) throw new AgentError("not_found", `Not holding @@${scoped(role, project)}`)
+      draft.roles = draft.roles.filter((r) => r !== held)
+      return project !== undefined ? { role, project } : { role }
+    })
+  }
+
+  // ---------- directory ----------
+
+  /** The user's named, role-holding or online sessions (not archived or deleted), by project and role. */
+  who(userID: string, filter: { project?: string; role?: string } = {}): DirectoryEntry[] {
+    const project = filter.project?.toLowerCase()
+    const role = filter.role !== undefined ? parseRole(filter.role, project) : undefined
+    return this.read(userID, (draft) =>
+      draft.sessions
+        .filter((s) => s.archivedAt === undefined && s.deletedAt === undefined)
+        .map((s) => this.entry(draft, s.sessionID))
+        .filter((e) => e.online || e.name !== undefined || e.roles.length > 0)
+        .filter((e) => project === undefined || e.project === project || e.roles.some((r) => r.project === project))
+        .filter((e) => !role || e.roles.some((r) => r.role === role.role && inScope(r.project, e.project, role.project))),
+    )
+  }
+
+  // ---------- resolution ----------
+
+  /**
+   * The sessions an address names, for this user only: `ses_…` (an ID or a unique ID prefix), `@name[.project]`
+   * or `@@role[.project]` (every live holder). Throws invalid (malformed), not_found or ambiguous {candidates}.
+   */
+  resolve(userID: string, addr: string): Resolved {
+    const address = parseAddress(addr)
+    if (!address) throw new AgentError("invalid", `Not an address: use ses_…, @name or @@role`)
+    return this.read(userID, (draft) => ({ address, sessions: this.lookup(draft, address, addr) }))
+  }
+
+  /** Exactly one session; several (a role with several holders) is ambiguous. */
+  resolveOne(userID: string, addr: string): DirectoryEntry {
+    const { sessions } = this.resolve(userID, addr)
+    if (sessions.length > 1) throw ambiguous(addr, sessions)
+    return sessions[0]!
+  }
+
+  private lookup(draft: Draft, address: Address, addr: string): DirectoryEntry[] {
+    const missing = () => new AgentError("not_found", `No session ${addr}`)
+    if (address.kind === "id") {
+      if (draft.byID.has(address.id)) return [this.entry(draft, address.id)]
+      const matches = draft.sessions.filter((s) => s.sessionID.startsWith(address.id)).map((s) => this.entry(draft, s.sessionID))
+      if (matches.length > 1) throw ambiguous(addr, matches)
+      if (!matches.length) throw missing()
+      return matches
+    }
+    if (address.kind === "name") {
+      const held = draft.names.find((n) => n.name === address.name)
+      const entry = held && this.entry(draft, held.sessionID)
+      if (!entry || (address.project !== undefined && entry.project !== address.project)) throw missing()
+      return [entry]
+    }
+    const holders = draft.roles.filter((r) => r.role === address.role && inScope(r.project, draft.byID.get(r.sessionID)?.project, address.project))
+    const ids = [...new Set(holders.map((r) => r.sessionID))]
+    if (!ids.length) throw missing()
+    return ids.map((id) => this.entry(draft, id))
+  }
+
+  // ---------- internals ----------
+
+  private known(draft: Draft, sessionID: string): AgentSession {
+    const record = draft.byID.get(sessionID)
+    if (!record) throw new AgentError("not_found", `No session ${sessionID}`)
+    return record
+  }
+
+  private entry(draft: Draft, sessionID: string): DirectoryEntry {
+    const record = draft.byID.get(sessionID)
+    const live = draft.reported.get(sessionID)
+    const own = draft.names.filter((n) => n.sessionID === sessionID)
+    const name = own.find((n) => n.expiresAt === undefined)?.name
+    const aliases = own.filter((n) => n.expiresAt !== undefined).map((n) => n.name)
+    const roles = draft.roles.filter((r) => r.sessionID === sessionID).map(roleView)
+    return {
+      sessionID,
+      ...(name ? { name } : {}),
+      ...(aliases.length ? { aliases } : {}),
+      ...(record?.machineID ? { machineID: record.machineID } : {}),
+      ...(record?.parentID ? { parentID: record.parentID } : {}),
+      ...(record?.project ? { project: record.project } : {}),
+      ...(record?.title ? { title: record.title } : {}),
+      ...(live?.state ? { state: live.state } : {}),
+      online: live !== undefined,
+      ...(record?.lastSeen !== undefined ? { lastSeen: record.lastSeen } : {}),
+      ...(record?.archivedAt !== undefined ? { archived: true } : {}),
+      roles,
+    }
+  }
+
+  /** Runs `look` on a refreshed copy of the user's data, saving nothing; not_found for an unknown user. */
+  private read<T>(userID: string, look: (draft: Draft) => T): T {
+    if (!this.store.user(userID)) throw new AgentError("not_found", "No such user")
+    const reported = new Map(this.source.reported(userID).map((s) => [s.sessionID, s]))
+    return look(this.refresh(userID, this.store.agentData(userID), reported, this.source.archived(userID)))
+  }
+
+  /**
+   * Runs `change` on the user's refreshed data in one store update and resolves once it is saved; not_found for an
+   * unknown user. On a shared store the change may run again (on fresh data, after another pod's write).
+   */
+  private async update<T>(userID: string, change: (draft: Draft) => T): Promise<T> {
+    const reported = new Map(this.source.reported(userID).map((s) => [s.sessionID, s]))
+    const archived = this.source.archived(userID)
+    let done = false
+    let result: T | undefined
+    await this.store.updateAgentData(userID, (data) => {
+      const draft = this.refresh(userID, data, reported, archived)
+      result = change(draft)
+      this.write(draft)
+      done = true
+    })
+    if (!done) throw new AgentError("not_found", "No such user")
+    this.online.set(userID, new Set(reported.keys()))
+    return result as T
+  }
+
+  private write(draft: Draft): void {
+    const { data } = draft
+    if (draft.sessions.length || data.sessions) data.sessions = draft.sessions
+    if (draft.names.length || data.names) data.names = draft.names
+    if (draft.roles.length || data.roles) data.roles = draft.roles
+  }
+
+  /** Records, archive marks, releases, derivations and the cap, as of now. */
+  private refresh(userID: string, data: AgentData, reported: Map<string, ReportedSession>, archived: ReadonlySet<string>): Draft {
+    const t = this.now()
+    const sessions = data.sessions ?? []
+    const byID = new Map(sessions.map((s) => [s.sessionID, s]))
+    for (const live of reported.values()) {
+      let record = byID.get(live.sessionID)
+      if (!record) {
+        record = { sessionID: live.sessionID, firstSeen: t }
+        sessions.push(record)
+        byID.set(live.sessionID, record)
+      }
+      for (const field of ["machineID", "parentID", "project", "title"] as const) {
+        const value = live[field]
+        if (value !== undefined && value !== "" && record[field] !== value) record[field] = value
+      }
+      if (record.lastSeen === undefined || t - record.lastSeen >= LAST_SEEN_STEP_MS) record.lastSeen = t
+      delete record.deletedAt
+    }
+    for (const id of this.online.get(userID) ?? []) {
+      const record = byID.get(id)
+      if (record && !reported.has(id)) record.lastSeen = t
+    }
+    for (const record of sessions) {
+      if (archived.has(record.sessionID)) record.archivedAt ??= t
+      else delete record.archivedAt
+    }
+
+    const draft: Draft = { data, sessions, byID, reported, names: data.names ?? [], roles: data.roles ?? [] }
+    draft.names = draft.names.filter((n) => !this.nameReleased(n, byID, t))
+    draft.roles = draft.roles.filter((r) => this.holding(draft, r.sessionID, t))
+    this.derive(draft, t)
+    this.cap(draft)
+    return draft
+  }
+
+  private nameReleased(name: AgentName, byID: Map<string, AgentSession>, t: number): boolean {
+    if (name.expiresAt !== undefined && t >= name.expiresAt) return true
+    const end = ended(byID.get(name.sessionID))
+    return end !== undefined && t - end >= NAME_RELEASE_MS
+  }
+
+  /** A holder keeps its roles while reported, or offline for less than ROLE_OFFLINE_MS, or (any) during the reconnect window; never once deleted. */
+  private holding(draft: Draft, sessionID: string, t: number): boolean {
+    const record = draft.byID.get(sessionID)
+    if (record?.deletedAt !== undefined) return false
+    if (draft.reported.has(sessionID) || t - this.startedAt < RECONNECT_WINDOW_MS) return true
+    return record?.lastSeen !== undefined && t - record.lastSeen < ROLE_OFFLINE_MS
+  }
+
+  /** Names root sessions once, from their first non-placeholder title. */
+  private derive(draft: Draft, t: number): void {
+    for (const live of draft.reported.values()) {
+      const record = draft.byID.get(live.sessionID)!
+      if (live.parentID || record.named || isPlaceholderTitle(live.title)) continue
+      record.named = true
+      const slug = deriveName(live.title)
+      if (!slug || draft.names.some((n) => n.sessionID === live.sessionID && n.expiresAt === undefined)) continue
+      const taken = new Set(draft.names.map((n) => n.name))
+      draft.names.push({ name: withSuffix(slug, (n) => taken.has(n) || isReservedName(n)), sessionID: live.sessionID, created: t })
+    }
+  }
+
+  /** Drops records beyond SESSION_LIMIT (never a reported one), with their names and roles. */
+  private cap(draft: Draft): void {
+    const excess = draft.sessions.length - SESSION_LIMIT
+    if (excess <= 0) return
+    const seen = (s: AgentSession) => s.lastSeen ?? s.firstSeen ?? 0
+    const victims = draft.sessions
+      .filter((s) => !draft.reported.has(s.sessionID))
+      .sort((a, b) => Number(ended(b) !== undefined) - Number(ended(a) !== undefined) || seen(a) - seen(b))
+      .slice(0, excess)
+    const gone = new Set(victims.map((s) => s.sessionID))
+    const kept = draft.sessions.filter((s) => !gone.has(s.sessionID))
+    draft.sessions.splice(0, draft.sessions.length, ...kept)
+    for (const id of gone) draft.byID.delete(id)
+    draft.names = draft.names.filter((n) => !gone.has(n.sessionID))
+    draft.roles = draft.roles.filter((r) => !gone.has(r.sessionID))
+  }
+}
+
+/** `role`, `@@role` or `role.project` (an explicit scope wins); invalid when malformed. */
+function parseRole(requested: string, scope?: string): { role: string; project?: string } {
+  const [role = "", inline, ...rest] = requested.replace(/^@@/, "").split(".")
+  const project = (scope ?? inline)?.toLowerCase()
+  if (!validName(role) || rest.length || (project !== undefined && !/^[^./\s]+$/.test(project))) {
+    throw new AgentError("invalid", "A role is 2–40 characters: a-z, 0-9 and -, optionally .project")
+  }
+  return project !== undefined ? { role, project } : { role }
+}
+
+const scoped = (role: string, project?: string) => (project !== undefined ? `${role}.${project}` : role)
+
+/** A claim scoped to `claimProject` (or unscoped, in a session of `sessionProject`) counts for `wanted`. */
+const inScope = (claimProject: string | undefined, sessionProject: string | undefined, wanted: string | undefined) =>
+  wanted === undefined || claimProject === wanted || (claimProject === undefined && sessionProject === wanted)
+
+const roleView = (r: AgentRole): RoleView => ({ role: r.role, ...(r.project !== undefined ? { project: r.project } : {}), generation: r.generation ?? 0, ...(r.exclusive ? { exclusive: true } : {}) })
+
+function ambiguous(addr: string, sessions: readonly DirectoryEntry[]): AgentError {
+  const candidates = sessions.slice(0, CANDIDATES_MAX).map((s) => ({ sessionID: s.sessionID, ...(s.name ? { name: s.name } : {}), ...(s.project ? { project: s.project } : {}) }))
+  return new AgentError("ambiguous", `${addr} matches ${sessions.length} sessions`, { extra: { candidates } })
+}

package/src/central/agent/envelope.ts

@@ -0,0 +1,51 @@
+// The message envelope (design §3.3): the pure renderer and sanitiser live in the SDK (packages/sdk/src/envelope.ts,
+// shared with the plugin's hub tool and `hub mcp`) and are re-exported here; the hub adds the sender derived only
+// from the authenticated actor (partyFromActor) and the party keys of its indexes.
+import type { Party } from "../../../packages/sdk/src/types.ts"
+import { sanitizeLabel } from "../../../packages/sdk/src/envelope.ts"
+import type { AgentActor } from "./actor"
+
+export { LABEL_MAX, partyLabel, renderEnvelope, renderPrimer, sanitizeLabel, sanitizeText, type EnvelopeInput, type EnvelopeKind } from "../../../packages/sdk/src/envelope.ts"
+export type { Party } from "../../../packages/sdk/src/types.ts"
+
+/** Directory facts for a session sender's label (never taken from a request body). */
+export interface PartyInfo {
+  readonly name?: string
+  readonly harness?: string
+  readonly machine?: string
+}
+
+/** The sender of a request, from its actor; session labels come from the hub's directory, sanitised. */
+export function partyFromActor(actor: AgentActor, info: PartyInfo = {}): Party {
+  switch (actor.kind) {
+    case "user":
+      return { kind: "user" }
+    case "app":
+      return { kind: "app", tokenID: actor.tokenID, ...labels({ label: actor.label }) }
+    case "session":
+      return { kind: "session", sessionID: actor.sessionID, ...labels({ name: info.name, harness: info.harness, machine: info.machine }) }
+  }
+}
+
+/** The given labels, sanitised, without empty ones. */
+function labels<T extends Record<string, string | undefined>>(values: T): Partial<Record<keyof T, string>> {
+  const out: Partial<Record<keyof T, string>> = {}
+  for (const [key, value] of Object.entries(values) as [keyof T, string | undefined][]) {
+    const clean = value === undefined ? "" : sanitizeLabel(value)
+    if (clean) out[key] = clean
+  }
+  return out
+}
+
+/** A stable key per party (index and mute keys): `ses:<id>`, `user`, `app:<tokenID>`. */
+export function partyKey(party: Party): string {
+  switch (party.kind) {
+    case "session":
+      return `ses:${party.sessionID}`
+    case "user":
+      return "user"
+    case "app":
+      return `app:${party.tokenID}`
+  }
+}
+

package/src/central/agent/errors.ts

@@ -0,0 +1,74 @@
+// The /api/agent error envelope (design §8, §14.5): {error: {code, message, hint?, ...extra}}. Only /api/agent/*
+// answers this way; the console routes keep their {error: string, code?} envelope (the web app reads it).
+
+/** HTTP status of each agent error code. */
+export const AGENT_ERROR_STATUS = {
+  /** Malformed request (bad JSON, bad fields, cookie and bearer together). */
+  invalid: 400,
+  /** An events cursor this hub did not give this user, or cannot read (start again without one). */
+  invalid_cursor: 400,
+  /** No credential, or an unknown, revoked or disabled one. */
+  unauthorized: 401,
+  /** A session or app token that expired: get a new one. */
+  token_expired: 401,
+  /** Outside the grant; a recommendation was recorded for the user. */
+  needs_user: 403,
+  /** No grant or scope, or a credential not admitted on this route. */
+  forbidden: 403,
+  /** No such thing, or another user's (they answer alike). */
+  not_found: 404,
+  /** The address matches several sessions (`candidates`). */
+  ambiguous: 409,
+  /** Explicit name or exclusive role already held. */
+  name_taken: 409,
+  /** Already answered, expired or ended. */
+  gone: 410,
+  /** The spoke or node lacks the feature or runtime (`feature`, `harness`). */
+  unsupported: 422,
+  /** A kill switch is on. */
+  paused: 423,
+  /** A pair, recipient, user or launch cap (`retryAfter`, seconds). */
+  rate_limited: 429,
+  /** An unexpected failure (details are logged, not sent). */
+  internal: 500,
+  /** The machine is offline (actions only; messages queue instead). */
+  offline: 503,
+} as const satisfies Record<string, number>
+
+export type AgentErrorCode = keyof typeof AGENT_ERROR_STATUS
+
+export interface AgentErrorOptions {
+  readonly hint?: string
+  /** More fields in the envelope, e.g. candidates, retryAfter, feature; never code or message. */
+  readonly extra?: Record<string, unknown>
+}
+
+/** Throw from an agent handler; answered as the envelope with the code's status. */
+export class AgentError extends Error {
+  constructor(
+    readonly code: AgentErrorCode,
+    message: string,
+    readonly options: AgentErrorOptions = {},
+  ) {
+    super(message)
+  }
+}
+
+export function agentError(error: AgentError): Response {
+  const { hint, extra = {} } = error.options
+  const headers: Record<string, string> = { "cache-control": "no-store" }
+  const retryAfter = extra.retryAfter
+  if (typeof retryAfter === "number" && Number.isFinite(retryAfter) && retryAfter >= 0) headers["retry-after"] = String(Math.ceil(retryAfter))
+  return Response.json(
+    { error: { ...extra, code: error.code, message: error.message, ...(hint ? { hint } : {}) } },
+    { status: AGENT_ERROR_STATUS[error.code], headers },
+  )
+}
+
+/** The envelope for anything an agent handler threw. */
+export function agentFailure(cause: unknown): Response {
+  if (cause instanceof AgentError) return agentError(cause)
+  if (cause instanceof SyntaxError) return agentError(new AgentError("invalid", "Invalid JSON"))
+  console.error("[hub] agent request failed:", cause)
+  return agentError(new AgentError("internal", "Internal error"))
+}