@huynle/hub 0.7.1 → 0.7.2

package/src/central/agent/event-cursor.ts

@@ -0,0 +1,49 @@
+// Cursors of GET /api/agent/events (lifecycle design, frozen "Events route and tool"): opaque, versioned,
+// authenticated, tenant-bound strings over a journal position (`<epoch>.<n>`).
+//
+//   hev1_<base64url(kid "\n" position)>.<base64url(mac)>
+//
+// mac is HMAC-SHA256 under the token signing key `kid` (token-keys.ts) of a domain-separated string that also binds
+// the user, truncated to 16 bytes; another user's cursor, a changed byte, an unknown key or another version all fail
+// to decode (400 invalid_cursor), never reset. The user never appears in the cursor itself.
+import { createHmac, timingSafeEqual } from "node:crypto"
+
+export const CURSOR_PREFIX = "hev1_"
+const DOMAIN = "hub-agent-events-cursor/v1"
+const MAC_BYTES = 16
+const POSITION = /^([a-z0-9]{1,40})\.(\d{1,15})$/
+const KID = /^[A-Za-z0-9_-]{1,64}$/
+const B64URL = /^[A-Za-z0-9_-]+$/
+
+export interface CursorKeys {
+  active(): { kid: string; secret: Buffer }
+  key(kid: string): Buffer | undefined
+}
+
+/** A journal position: its epoch and n. */
+export function parsePosition(position: string): { epoch: string; n: number } | undefined {
+  const match = POSITION.exec(position)
+  return match ? { epoch: match[1]!, n: Number(match[2]) } : undefined
+}
+
+const mac = (secret: Buffer, userID: string, kid: string, position: string) => createHmac("sha256", secret).update(`${DOMAIN}\n${userID}\n${kid}\n${position}`).digest().subarray(0, MAC_BYTES)
+
+export function encodeCursor(keys: CursorKeys, userID: string, position: string): string {
+  const { kid, secret } = keys.active()
+  const body = Buffer.from(`${kid}\n${position}`).toString("base64url")
+  return `${CURSOR_PREFIX}${body}.${mac(secret, userID, kid, position).toString("base64url")}`
+}
+
+/** The position of a cursor this hub gave this user; undefined for anything else. */
+export function decodeCursor(keys: CursorKeys, userID: string, cursor: string): string | undefined {
+  if (cursor.length > 300 || !cursor.startsWith(CURSOR_PREFIX)) return undefined
+  const [body, tag, ...rest] = cursor.slice(CURSOR_PREFIX.length).split(".")
+  if (rest.length || !body || !tag || !B64URL.test(body) || !B64URL.test(tag)) return undefined
+  const [kid, position, ...extra] = Buffer.from(body, "base64url").toString("utf8").split("\n")
+  if (extra.length || !kid || !position || !KID.test(kid) || !parsePosition(position)) return undefined
+  const secret = keys.key(kid)
+  if (!secret) return undefined
+  const given = Buffer.from(tag, "base64url")
+  const expected = mac(secret, userID, kid, position)
+  return given.length === expected.length && timingSafeEqual(given, expected) ? position : undefined
+}

package/src/central/agent/event-writers.ts

@@ -0,0 +1,181 @@
+// Writers of the canonical agent event journal (events.ts; lifecycle design, Event rollout stage 1). Each change
+// is appended exactly once across a cluster, by the one place that sees it first:
+//
+// - state and blockers: the pod holding the spoke (the registry's status messages are local to it), diffed per tree;
+// - session and machine presence: the "agent-events" leader, diffing the cluster-wide catalog per user against a
+//   snapshot it keeps in the Kv, so a new leader continues where the last one stopped (none: everything present
+//   is new);
+// - messages and launches: the pod that published them (Feed origin listeners);
+// - archive changes: the route that made them (directory-routes).
+//
+// Appends of one writer are serialized, so a user's events keep their order. Failures are reported, never thrown.
+import type { Kv } from "../backend/types"
+import type { CatalogMachine, RegistryMessage } from "../registry"
+import { AGENT_EVENTS_AGE_MS, type AgentEvents, type EventInput, launchEvent, messageEvent, presenceEvents, type PresenceView, StatusDiff } from "./events"
+import type { Launch } from "./launch-store"
+import type { Message } from "./messages"
+
+interface Subscribable<T> {
+  subscribe(listener: (userID: string, item: T) => void, options?: { readonly origin?: boolean }): () => void
+}
+
+export interface EventWriterRegistry {
+  subscribe(listener: (message: RegistryMessage, tenant?: string) => void): () => void
+  catalog(): CatalogMachine[]
+  sessionTenant(sessionID: string): string | undefined
+}
+
+export interface PresenceLeader {
+  isLeader(): boolean
+}
+
+export interface EventWritersOptions {
+  readonly events: AgentEvents
+  readonly kv: Kv
+  readonly registry: EventWriterRegistry
+  /** The owner of a stored machine (undefined: not stored, e.g. the local machine). */
+  readonly machineOwner: (machineID: string) => string | undefined
+  /** Every stored user (a new leader loads their presence snapshots). */
+  readonly users: () => Promise<string[]>
+  readonly messages?: Subscribable<Message>
+  readonly launches?: Subscribable<Launch>
+  readonly report?: (cause: unknown) => void
+}
+
+const snapshotKey = (userID: string) => `aev:presence:${userID}`
+
+const EMPTY: PresenceView = { sessions: new Set(), machines: new Map() }
+
+/** Presence of every user in a catalog. */
+export function presenceOf(machines: readonly CatalogMachine[], tenant: (sessionID: string) => string | undefined, owner: (machineID: string) => string | undefined): Map<string, PresenceView> {
+  const out = new Map<string, { sessions: Set<string>; machines: Map<string, string> }>()
+  const view = (userID: string) => {
+    let v = out.get(userID)
+    if (!v) out.set(userID, (v = { sessions: new Set(), machines: new Map() }))
+    return v
+  }
+  for (const machine of machines) {
+    const users = new Set<string>()
+    const stored = owner(machine.id)
+    if (stored !== undefined) users.add(stored)
+    for (const process of machine.processes) {
+      for (const s of process.sessions) {
+        const userID = tenant(s.id)
+        if (userID === undefined) continue
+        view(userID).sessions.add(s.id)
+        if (stored === undefined) users.add(userID)
+      }
+    }
+    if (machine.processes.length > 0) for (const userID of users) view(userID).machines.set(machine.id, machine.name)
+  }
+  return out
+}
+
+export class EventWriters {
+  private readonly options: EventWritersOptions
+  private readonly diff = new StatusDiff()
+  private readonly report: (cause: unknown) => void
+  private queue: Promise<void> = Promise.resolve()
+  /** Presence as last journaled, per user (leader only; undefined when not leading). */
+  private presence: Map<string, PresenceView> | undefined
+  private readonly offs: (() => void)[] = []
+
+  constructor(options: EventWritersOptions) {
+    this.options = options
+    this.report = options.report ?? ((cause) => console.error(`[hub] agent event write failed: ${cause instanceof Error ? cause.message : String(cause)}`))
+  }
+
+  start(): void {
+    const { registry, messages, launches } = this.options
+    this.offs.push(
+      registry.subscribe((message, tenant) => {
+        if (message.type === "status" && tenant !== undefined) this.write(tenant, this.diff.events(message.sessionID, message.sessions))
+        else if (message.type === "catalog") {
+          this.forgetGone()
+          if (this.presence) this.enqueue(() => this.presenceChanged())
+        }
+      }),
+    )
+    if (messages) this.offs.push(messages.subscribe((userID, message) => this.write(userID, [messageEvent(message)]), { origin: true }))
+    if (launches) this.offs.push(launches.subscribe((userID, launch) => this.write(userID, [launchEvent(launch)]), { origin: true }))
+  }
+
+  stop(): void {
+    for (const off of this.offs.splice(0)) off()
+    this.presence = undefined
+  }
+
+  /** Became the presence leader: load the last leader's snapshots, then journal what changed since. */
+  elected(): void {
+    this.enqueue(async () => {
+      const presence = new Map<string, PresenceView>()
+      for (const userID of await this.options.users()) {
+        const raw = await this.options.kv.get(snapshotKey(userID))
+        if (raw) presence.set(userID, parseSnapshot(raw))
+      }
+      this.presence = presence
+      await this.presenceChanged()
+    })
+  }
+
+  deposed(): void {
+    this.enqueue(async () => {
+      this.presence = undefined
+    })
+  }
+
+  /** Resolves once every queued append is done (tests, drain). */
+  settled(): Promise<void> {
+    return this.queue
+  }
+
+  private write(userID: string, events: readonly EventInput[]): void {
+    if (events.length === 0) return
+    this.enqueue(async () => {
+      for (const event of events) await this.options.events.append(userID, event)
+    })
+  }
+
+  private enqueue(job: () => Promise<void>): void {
+    this.queue = this.queue.then(job).catch(this.report)
+  }
+
+  private async presenceChanged(): Promise<void> {
+    const before = this.presence
+    if (!before) return
+    const { registry, machineOwner, events, kv } = this.options
+    const after = presenceOf(registry.catalog(), (id) => registry.sessionTenant(id), machineOwner)
+    for (const userID of new Set([...before.keys(), ...after.keys()])) {
+      const prev = before.get(userID) ?? EMPTY
+      const next = after.get(userID) ?? EMPTY
+      const changes = presenceEvents(prev, next)
+      if (changes.length === 0) continue
+      for (const event of changes) await events.append(userID, event)
+      if (next.sessions.size === 0 && next.machines.size === 0) {
+        before.delete(userID)
+        await kv.del(snapshotKey(userID))
+      } else {
+        before.set(userID, next)
+        await kv.set(snapshotKey(userID), JSON.stringify({ sessions: [...next.sessions], machines: [...next.machines] }), { px: AGENT_EVENTS_AGE_MS })
+      }
+    }
+  }
+
+  /** Drops the status diffs of trees no longer in the catalog. */
+  private forgetGone(): void {
+    const present = new Set<string>()
+    for (const machine of this.options.registry.catalog()) for (const process of machine.processes) for (const s of process.sessions) present.add(s.id)
+    for (const rootID of this.diff.roots()) if (!present.has(rootID)) this.diff.forget(rootID)
+  }
+}
+
+function parseSnapshot(raw: string): PresenceView {
+  try {
+    const value = JSON.parse(raw) as { sessions?: unknown; machines?: unknown }
+    const sessions = Array.isArray(value.sessions) ? value.sessions.filter((id): id is string => typeof id === "string") : []
+    const machines = Array.isArray(value.machines) ? value.machines.filter((m): m is [string, string] => Array.isArray(m) && typeof m[0] === "string" && typeof m[1] === "string") : []
+    return { sessions: new Set(sessions), machines: new Map(machines) }
+  } catch {
+    return EMPTY
+  }
+}

package/src/central/agent/events-routes.ts

@@ -0,0 +1,148 @@
+// GET /api/agent/events?cursor=&wait=&limit=&type=&session= (lifecycle design, frozen "Events route and tool"):
+// the canonical journal (events.ts) read with an opaque cursor (event-cursor.ts).
+//
+// - No cursor: no events and a cursor at the latest record (a long poll then waits for what comes next).
+// - wait: seconds 0–60 to hold the request while nothing matches (local appends wake it at once; appends on other
+//   pods are rechecked every RECHECK_MS). limit: 1–200 (default 50). type and session may repeat (≤ 20 each);
+//   a type ending in `.*` matches a family of types.
+// - At most INSPECT_MAX records are inspected per request. Filters advance the cursor over every inspected record;
+//   `more` means records remain unread, matching or not.
+// - A cursor the journal no longer covers (expired, trimmed, another epoch after a restart) answers a typed reset
+//   with a fresh cursor and the reads to refresh; a malformed, forged, future, unsupported-version or another
+//   user's cursor answers 400 invalid_cursor.
+//
+// Who sees what: the user everything. App tokens need events:subscribe for the route and, per family, sessions:read
+// (session), sessions:manage (manage), messages:read and being a party (message), sessions:launch and having started
+// it (launch). Session tokens see session and manage events, messages they are a party to and launches they started.
+// Reader-only fields (family, audience, position) never leave the hub.
+import type { AgentActor } from "./actor"
+import type { Directory } from "./directory"
+import { decodeCursor, encodeCursor, parsePosition, type CursorKeys } from "./event-cursor"
+import type { AgentEvent, AgentEvents, EventRecord } from "./events"
+import { partyFromActor, partyKey } from "./envelope"
+import { AgentError } from "./errors"
+import { launchedBy } from "./launch-routes"
+import { AGENT_PREFIX, type AgentRoute } from "./routes"
+
+export const EVENTS_WAIT_MAX_S = 60
+export const EVENTS_LIMIT_MAX = 200
+export const EVENTS_LIMIT_DEFAULT = 50
+export const INSPECT_MAX = 1000
+export const RECHECK_MS = 1000
+export const RESET_REFRESH = ["status", "sessions", "inbox", "decisions", "launches"] as const
+const FILTER_MAX = 20
+const TYPE = /^[a-z][a-z0-9_]*(\.[a-z0-9_]+)*(\.\*)?$/
+
+const NO_STORE = { "cache-control": "no-store" }
+
+export interface EventsRouteDeps {
+  readonly events: Pick<AgentEvents, "latest" | "since" | "appended">
+  readonly keys: CursorKeys
+  readonly directory: Pick<Directory, "resolve">
+}
+
+export interface EventsPage {
+  readonly events: AgentEvent[]
+  readonly cursor: string
+  readonly more: boolean
+  readonly reset: boolean
+  readonly refresh?: readonly string[]
+}
+
+const invalid = (message: string) => new AgentError("invalid", message)
+const badCursor = () => new AgentError("invalid_cursor", "This cursor is not valid here: start again without one", { hint: `GET ${AGENT_PREFIX}/events without cursor` })
+
+function intParam(url: URL, key: string, min: number, max: number, fallback: number): number {
+  const raw = url.searchParams.get(key)
+  if (raw === null || raw === "") return fallback
+  if (!/^\d+$/.test(raw) || Number(raw) < min || Number(raw) > max) throw invalid(`${key} must be a whole number from ${min} to ${max}`)
+  return Number(raw)
+}
+
+/** Whether an actor may read a record. */
+export function visible(record: EventRecord, actor: AgentActor): boolean {
+  if (actor.kind === "user") return true
+  const party = partyKey(partyFromActor(actor))
+  const has = (scope: string) => actor.kind === "session" || actor.scopes.includes(scope)
+  switch (record.family) {
+    case "session":
+      return has("sessions:read")
+    case "manage":
+      return has("sessions:manage")
+    case "message":
+      return has("messages:read") && (record.audience?.parties ?? []).includes(party)
+    case "launch":
+      return has("sessions:launch") && record.audience?.by === launchedBy(actor)
+  }
+}
+
+export function eventsRoutes(deps: EventsRouteDeps): AgentRoute[] {
+  return [
+    {
+      method: "GET",
+      path: `${AGENT_PREFIX}/events`,
+      allow: { session: true, scope: "events:subscribe" },
+      handle: async ({ user, url, actor, request }) => {
+        const wait = intParam(url, "wait", 0, EVENTS_WAIT_MAX_S, 0)
+        const limit = intParam(url, "limit", 1, EVENTS_LIMIT_MAX, EVENTS_LIMIT_DEFAULT)
+        const types = url.searchParams.getAll("type").filter(Boolean)
+        const addrs = url.searchParams.getAll("session").filter(Boolean)
+        if (types.length > FILTER_MAX || addrs.length > FILTER_MAX) throw invalid(`At most ${FILTER_MAX} type and ${FILTER_MAX} session filters`)
+        if (types.some((t) => t.length > 100 || !TYPE.test(t))) throw invalid("type must be an event type such as session.changed or launch.*")
+        const sessions = addrs.length ? new Set(addrs.flatMap((addr) => deps.directory.resolve(user.id, addr).sessions.map((s) => s.sessionID))) : undefined
+        const page = await read(deps, user.id, actor, { cursor: url.searchParams.get("cursor") ?? undefined, wait, limit, types, sessions }, request.signal)
+        return Response.json(page, { headers: NO_STORE })
+      },
+    },
+  ]
+}
+
+interface ReadOptions {
+  readonly cursor?: string
+  readonly wait: number
+  readonly limit: number
+  readonly types: readonly string[]
+  readonly sessions?: ReadonlySet<string>
+}
+
+const typeMatches = (types: readonly string[], type: string) => types.length === 0 || types.some((t) => (t.endsWith(".*") ? type.startsWith(t.slice(0, -1)) : t === type))
+
+const sessionMatches = (sessions: ReadonlySet<string> | undefined, event: AgentEvent) =>
+  !sessions || [event.subject.sessionID, event.subject.rootID, event.subject.senderID].some((id) => id !== undefined && sessions.has(id))
+
+export async function read(deps: EventsRouteDeps, userID: string, actor: AgentActor, options: ReadOptions, signal?: AbortSignal): Promise<EventsPage> {
+  const { events, keys } = deps
+  const page = (position: string, found: AgentEvent[], more: boolean): EventsPage => ({ events: found, cursor: encodeCursor(keys, userID, position), more, reset: false })
+  let position: string
+  if (options.cursor === undefined || options.cursor === "") {
+    position = await events.latest(userID)
+    if (options.wait === 0) return page(position, [], false)
+  } else {
+    const decoded = decodeCursor(keys, userID, options.cursor)
+    const held = decoded ? parsePosition(decoded) : undefined
+    if (!decoded || !held) throw badCursor()
+    const latest = parsePosition(await events.latest(userID))
+    if (latest && latest.epoch === held.epoch && held.n > latest.n) throw badCursor()
+    position = decoded
+  }
+  const deadline = performance.now() + options.wait * 1000
+  for (;;) {
+    const result = await events.since(userID, position)
+    if ("reset" in result) return { events: [], cursor: encodeCursor(keys, userID, await events.latest(userID)), more: false, reset: true, refresh: RESET_REFRESH }
+    const found: AgentEvent[] = []
+    let more = result.records.length > INSPECT_MAX
+    for (const record of result.records.slice(0, INSPECT_MAX)) {
+      if (visible(record, actor) && typeMatches(options.types, record.event.type) && sessionMatches(options.sessions, record.event)) {
+        if (found.length === options.limit) {
+          more = true
+          break
+        }
+        found.push(record.event)
+      }
+      position = record.position
+    }
+    const left = deadline - performance.now()
+    if (found.length > 0 || more || left <= 0 || signal?.aborted) return page(position, found, more)
+    await events.appended(userID, Math.min(RECHECK_MS, left), signal)
+  }
+}

package/src/central/agent/events.ts

@@ -0,0 +1,277 @@
+// The canonical agent event journal (lifecycle design: Events; decision xwzersmm). One bounded journal per user of
+// compact events that GET /api/agent/events, MCP `events` and /api/agent/watch read:
+//
+//   {id: "evt_…", at, type, subject: {sessionID?, rootID?, messageID?, senderID?, launchID?, machineID?}, data}
+//
+// Payloads are built from allowlists here and nowhere else: never prompts, message bodies, titles, blocker
+// summaries, launch reasons or labels, credentials, or connection/pod/spoke IDs. Each record also keeps, for the
+// reader only, its scope family (session, manage, message, launch) and its audience (the parties of a message, who
+// started a launch), so an app or session token sees only what its scopes and identity allow.
+//
+// Storage is an EventLog (a Valkey stream per user in a cluster, process memory otherwise) bounded to
+// AGENT_EVENTS_MAX events and AGENT_EVENTS_AGE_MS. An event id is assigned once, before any cross-pod fan-out;
+// append claims it in the Kv first (SET NX), so appending the same id twice stores it once.
+import { randomBytes } from "node:crypto"
+import type { Clock, EventLog, Kv } from "../backend/types"
+import type { LiveStatus } from "../registry"
+import { partyKey } from "./envelope"
+import type { Launch } from "./launch-store"
+import { addressOf, type Message } from "./messages"
+
+export const AGENT_EVENTS_MAX = 10_000
+export const AGENT_EVENTS_AGE_MS = 86_400_000
+/** Record format version (readers reject others rather than skip them). */
+export const AGENT_EVENT_VERSION = 1
+
+/** The scope family a reader needs: sessions:read, sessions:manage, messages:read, sessions:launch. */
+export type EventFamily = "session" | "manage" | "message" | "launch"
+
+export type EventSubject = Readonly<Record<string, string>>
+export type EventData = Readonly<Record<string, string | number | boolean>>
+
+/** An event as readers receive it. */
+export interface AgentEvent {
+  readonly id: string
+  readonly at: number
+  readonly type: string
+  readonly subject: EventSubject
+  readonly data: EventData
+}
+
+/** Who else may read an event beyond the user: the party keys of a message, who started a launch. */
+export interface EventAudience {
+  readonly parties?: readonly string[]
+  readonly by?: string
+}
+
+/** What a writer appends. */
+export interface EventInput {
+  /** A stable id (assigned before fan-out); a new one when absent. */
+  readonly id?: string
+  readonly type: string
+  readonly family: EventFamily
+  readonly subject: EventSubject
+  readonly data: EventData
+  readonly audience?: EventAudience
+}
+
+/** A journal record: the event, its reader-only scope fields, and its position in the user's log. */
+export interface EventRecord {
+  readonly position: string
+  readonly event: AgentEvent
+  readonly family: EventFamily
+  readonly audience?: EventAudience
+}
+
+/** Records after a position, or `reset` when the journal no longer covers it (expired, trimmed, restarted). */
+export type EventsSince = { readonly records: EventRecord[] } | { readonly reset: true }
+
+const FAMILIES: ReadonlySet<string> = new Set<EventFamily>(["session", "manage", "message", "launch"])
+const EVENT_ID = /^evt_[0-9a-f]{20}$/
+
+export const newEventID = (): string => `evt_${randomBytes(10).toString("hex")}`
+
+export interface AgentEventsOptions {
+  readonly log: EventLog
+  readonly kv: Kv
+  readonly now?: Clock
+  readonly onAppend?: (userID: string, record: Pick<EventRecord, "event" | "family" | "audience">) => void | Promise<void>
+}
+
+export class AgentEvents {
+  private readonly log: EventLog
+  private readonly kv: Kv
+  private readonly now: Clock
+  private readonly onAppend?: AgentEventsOptions["onAppend"]
+  /** Readers waiting for this process's next append, per user (long polling; other pods' appends are rechecked). */
+  private readonly waiters = new Map<string, Set<() => void>>()
+
+  constructor(options: AgentEventsOptions) {
+    this.log = options.log
+    this.kv = options.kv
+    this.now = options.now ?? Date.now
+    this.onAppend = options.onAppend
+  }
+
+  /** Stores an event once per id; returns its id. */
+  async append(userID: string, input: EventInput): Promise<string> {
+    const id = input.id ?? newEventID()
+    if (!EVENT_ID.test(id)) throw new Error("Invalid event id")
+    const claim = `aev:${userID}:${id}`
+    if (!(await this.kv.set(claim, "1", { nx: true, px: AGENT_EVENTS_AGE_MS }))) return id
+    const record = {
+      type: input.type,
+      v: AGENT_EVENT_VERSION,
+      id,
+      at: this.now(),
+      family: input.family,
+      subject: input.subject,
+      data: input.data,
+      ...(input.audience ? { audience: input.audience } : {}),
+    }
+    try {
+      await this.log.append(userID, record)
+    } catch (cause) {
+      // Not stored: a retry with the same id must be able to store it.
+      await this.kv.del(claim).catch(() => {})
+      throw cause
+    }
+    await this.onAppend?.(userID, {
+      event: { id, at: record.at, type: input.type, subject: input.subject, data: input.data },
+      family: input.family,
+      ...(input.audience ? { audience: input.audience } : {}),
+    })
+    const waiting = this.waiters.get(userID)
+    if (waiting) for (const wake of [...waiting]) wake()
+    return id
+  }
+
+  /** Resolves on this process's next append for the user, after `ms`, or when `signal` aborts. */
+  appended(userID: string, ms: number, signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve) => {
+      let set = this.waiters.get(userID)
+      if (!set) this.waiters.set(userID, (set = new Set()))
+      const done = () => {
+        clearTimeout(timer)
+        signal?.removeEventListener("abort", done)
+        set!.delete(done)
+        if (set!.size === 0 && this.waiters.get(userID) === set) this.waiters.delete(userID)
+        resolve()
+      }
+      const timer = setTimeout(done, ms)
+      set.add(done)
+      if (signal?.aborted) done()
+      else signal?.addEventListener("abort", done, { once: true })
+    })
+  }
+
+  /** The position of the user's latest record; a reader holding it gets every later one. */
+  latest(userID: string): Promise<string> {
+    return this.log.latest(userID)
+  }
+
+  async since(userID: string, position: string): Promise<EventsSince> {
+    const result = await this.log.since(userID, position)
+    if ("resync" in result) return { reset: true }
+    const records: EventRecord[] = []
+    for (const logged of result.events) {
+      const m = logged.message as Record<string, unknown>
+      // A record this version cannot read is a reset, never a silent skip.
+      if (m.v !== AGENT_EVENT_VERSION || typeof m.id !== "string" || typeof m.at !== "number" || !FAMILIES.has(m.family as string)) return { reset: true }
+      records.push({
+        position: logged.id,
+        event: { id: m.id, at: m.at, type: String(m.type), subject: (m.subject ?? {}) as EventSubject, data: (m.data ?? {}) as EventData },
+        family: m.family as EventFamily,
+        ...(m.audience ? { audience: m.audience as EventAudience } : {}),
+      })
+    }
+    return { records }
+  }
+}
+
+// ---- Compact builders (allowlists) ------------------------------------------------------------------------
+
+/** A stored agent message changed (sent, delivered, answered…): never its text. */
+export function messageEvent(message: Message): EventInput {
+  const { id, kind, state, from, recipient, replyTo, delivery } = message
+  return {
+    type: "message.changed",
+    family: "message",
+    subject: {
+      messageID: id,
+      ...(recipient.kind === "session" ? { sessionID: recipient.sessionID } : {}),
+      ...(from.kind === "session" ? { senderID: from.sessionID } : {}),
+    },
+    data: { kind, state, from: addressOf(from), to: message.to, ...(replyTo ? { replyTo } : {}), ...(delivery ? { delivery } : {}) },
+    audience: { parties: [partyKey(from), partyKey(recipient)] },
+  }
+}
+
+/** A launch changed: never its prompt, reason or labels. */
+export function launchEvent(launch: Launch): EventInput {
+  return {
+    type: "launch.changed",
+    family: "launch",
+    subject: { launchID: launch.id, ...(launch.sessionID !== undefined ? { sessionID: launch.sessionID } : {}) },
+    data: { state: launch.state, ...(launch.outcome !== undefined ? { outcome: launch.outcome } : {}), ...(launch.name !== undefined ? { name: launch.name } : {}) },
+    ...(launch.by !== undefined ? { audience: { by: launch.by } } : {}),
+  }
+}
+
+/** A session's archive state changed. */
+export const archiveEvent = (sessionID: string, archived: boolean): EventInput => ({ type: "session.archived", family: "manage", subject: { sessionID }, data: { archived } })
+
+export const pinnedEvent = (sessionID: string, pinned: boolean): EventInput => ({ type: "session.pinned", family: "manage", subject: { sessionID }, data: { pinned } })
+
+/** A session was explicitly named (names are validated slugs: a-z, 0-9 and -). */
+export const namedEvent = (sessionID: string, name: string): EventInput => ({ type: "session.named", family: "manage", subject: { sessionID }, data: { name } })
+
+/** A session claimed (held) or released a role; role and project are validated slugs. */
+export function roleEvent(sessionID: string, held: boolean, role: { role: string; project?: string; generation?: number; exclusive?: boolean }): EventInput {
+  return {
+    type: held ? "role.claimed" : "role.released",
+    family: "manage",
+    subject: { sessionID },
+    data: {
+      role: role.role,
+      ...(role.project !== undefined ? { project: role.project } : {}),
+      ...(held && role.generation !== undefined ? { generation: role.generation } : {}),
+      ...(held && role.exclusive ? { exclusive: true } : {}),
+    },
+  }
+}
+
+interface Known {
+  state: string
+  blockers: Set<string>
+}
+
+/**
+ * State and blocker changes of status trees, against what was seen before (one per writer). Bounded by the live
+ * trees: a tree's entry is replaced by each status of it and dropped by forget().
+ */
+export class StatusDiff {
+  private readonly trees = new Map<string, Map<string, Known>>()
+
+  events(rootID: string, sessions: readonly LiveStatus[]): EventInput[] {
+    const before = this.trees.get(rootID) ?? new Map<string, Known>()
+    const after = new Map<string, Known>()
+    const out: EventInput[] = []
+    for (const entry of sessions) {
+      const known = before.get(entry.id)
+      const subject = { sessionID: entry.id, rootID }
+      const open = new Set(entry.blockers.map((b) => b.id))
+      for (const b of entry.blockers) if (!known?.blockers.has(b.id)) out.push({ type: "blocker.opened", family: "session", subject, data: { blockerID: b.id, kind: b.kind } })
+      for (const id of known?.blockers ?? []) if (!open.has(id)) out.push({ type: "blocker.closed", family: "session", subject, data: { blockerID: id } })
+      if (known?.state !== entry.state) out.push({ type: "session.changed", family: "session", subject, data: { state: entry.state, ...(known ? { prev: known.state } : {}) } })
+      after.set(entry.id, { state: entry.state, blockers: open })
+    }
+    this.trees.set(rootID, after)
+    return out
+  }
+
+  /** Drops a tree that is gone. */
+  forget(rootID: string): void {
+    this.trees.delete(rootID)
+  }
+
+  roots(): string[] {
+    return [...this.trees.keys()]
+  }
+}
+
+/** Presence per user (sessions and machines) diffed against the previous view (the catalog writer's). */
+export interface PresenceView {
+  readonly sessions: ReadonlySet<string>
+  /** Machine id → name, for the machines with a connected process. */
+  readonly machines: ReadonlyMap<string, string>
+}
+
+export function presenceEvents(before: PresenceView, after: PresenceView): EventInput[] {
+  const out: EventInput[] = []
+  for (const id of after.sessions) if (!before.sessions.has(id)) out.push({ type: "session.added", family: "session", subject: { sessionID: id }, data: {} })
+  for (const id of before.sessions) if (!after.sessions.has(id)) out.push({ type: "session.removed", family: "session", subject: { sessionID: id }, data: {} })
+  for (const [id, name] of after.machines) if (!before.machines.has(id)) out.push({ type: "machine.changed", family: "session", subject: { machineID: id }, data: { name, online: true } })
+  for (const [id, name] of before.machines) if (!after.machines.has(id)) out.push({ type: "machine.changed", family: "session", subject: { machineID: id }, data: { name, online: false } })
+  return out
+}

package/src/central/agent/names.ts

@@ -43,7 +43,7 @@ export function withSuffix(base: string, taken: (name: string) => boolean): stri
 export const isReservedName = (name: string): boolean => name === "me"
 
 /** Roles only the user may claim in phase 1 (grants including `roles` come in phase 3). */
-const RESERVED_ROLES = ["orchestrator", "concierge"]
+const RESERVED_ROLES = ["orchestrator"]
 
 export const isReservedRole = (role: string): boolean => RESERVED_ROLES.some((prefix) => role.startsWith(prefix))