@huynle/hub 0.7.1 → 0.7.3

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

@@ -7,15 +7,30 @@
 //   POST /api/agent/name           {name, session?}
 //   POST /api/agent/roles/claim    {role, exclusive?, project?, session?}
 //   POST /api/agent/roles/release  {role, project?, session?}
+//   PUT  /api/agent/sessions/:addr/archive {archived}
 // `session` is an address (ses_…, ID prefix, @name, …) resolved for the caller; a session token defaults to
-// its own session, a user must name one.
+// its own session, a user or app must name one. Foreign and unknown sessions are both not_found.
+//
+// App tokens (lifecycle design, decision xwzersmm): naming and archiving need sessions:manage; a role claim or
+// release also needs a grant allowing `roles` whose projects cover the (live) session's directory, in the acting
+// order (kill switch → grant → hourly cap → kill switch), with every outcome in the agent audit (verb roles or
+// roles.release). Reserved roles stay the user's to assign. Each change is in the admin audit and the event
+// journal once (session.named, role.claimed, role.released, session.archived); a no-op is neither.
+import type { ActingSwitch } from "./acting-switch"
+import { auditOf } from "./acting"
+import type { AgentAudit, AuditDecision, AuditOutcome } from "./audit"
+import { partyFromActor } from "./envelope"
+import { type AgentEvents, archiveEvent, type EventInput, namedEvent, pinnedEvent, roleEvent } from "./events"
+import type { Grant, Grants } from "./grants"
 import path from "node:path"
-import type { CatalogMachine, RegistryMessage } from "../registry"
+import type { CatalogMachine, Registry, RegistryMessage } from "../registry"
 import type { Store } from "../store"
 import { Directory, type ReportedSession, type SessionSource } from "./directory"
 import { AgentError } from "./errors"
+import { ArchiveInactive, parseInactiveFor } from "./archive-inactive"
 import { slugify } from "./names"
 import { AGENT_PREFIX, type AgentContext, type AgentRoute } from "./routes"
+import type { CursorKeys } from "./event-cursor"
 
 /** What the directory reads from the Registry. */
 export interface DirectoryRegistry {
@@ -127,8 +142,120 @@ function target(directory: Directory, { actor, user }: AgentContext, addr: strin
 const NO_STORE = { "cache-control": "no-store" }
 const ok = (body: unknown) => Response.json(body, { headers: NO_STORE })
 
-export function directoryRoutes(directory: Directory): AgentRoute[] {
+export interface DirectoryRoutesDeps {
+  readonly directory: Directory
+  readonly store: Pick<Store, "setSessionArchived" | "setSessionPinned" | "archiveSessionIfUnpinned" | "viewPrefs" | "agentData" | "audit">
+  readonly events?: Pick<AgentEvents, "append">
+  /** App role writes: the live session (its directory, for the grant's projects). */
+  readonly registry?: Pick<Registry, "sessionTenant" | "session">
+  readonly grants?: Pick<Grants, "usable" | "consume">
+  readonly acting?: Pick<ActingSwitch, "ensureActing">
+  readonly audit?: Pick<AgentAudit, "record">
+  readonly previewKeys?: CursorKeys
+}
+
+const MANAGE = { session: true, scope: "sessions:manage" } as const
+
+export function directoryRoutes(deps: DirectoryRoutesDeps): AgentRoute[] {
+  const { directory, store, events } = deps
+
+  /** The admin audit and the journal, once per change. */
+  async function changed(context: AgentContext, action: string, sessionID: string, event: EventInput): Promise<void> {
+    await store.audit({ actor: context.user.id, action, target: sessionID, detail: context.actor.kind })
+    await events?.append(context.user.id, event).catch((cause) => console.error(`[hub] ${event.type} event failed: ${(cause as Error).message}`))
+  }
+
+  /** A role write: users and sessions as before; an app under a `roles` grant on the session's project, audited. */
+  async function roleWrite<T>(context: AgentContext, verb: "roles" | "roles.release", sessionID: string, run: () => Promise<T>): Promise<T> {
+    const { actor, user } = context
+    if (actor.kind !== "app") return run()
+    const { registry, grants, acting, audit } = deps
+    if (!registry || !grants || !acting || !audit) throw new AgentError("forbidden", "This hub does not let app tokens change roles")
+    let grant: Grant | undefined
+    const record = (decision: AuditDecision, outcome: AuditOutcome, reason?: string) =>
+      audit.record(user.id, { actor: partyFromActor(actor), verb, target: { sessionID }, ...(grant ? { grant: grant.id } : {}), decision, ...(reason ? { reason } : {}), outcome })
+    try {
+      acting.ensureActing(user.id)
+      const live = registry.sessionTenant(sessionID) === user.id ? registry.session(sessionID) : undefined
+      if (!live) throw new AgentError("offline", "No spoke reports this session now, so its project cannot be checked against a grant")
+      const usable = await grants.usable(actor, "roles", { directory: live.directory })
+      if (!usable.length) throw new AgentError("forbidden", "No grant lets this app change roles in this session's project")
+      grant = usable[0]!
+      await grants.consume(grant)
+      acting.ensureActing(user.id)
+      const result = await run()
+      await record("allow", "ok")
+      return result
+    } catch (cause) {
+      const [decision, outcome] = auditOf(cause)
+      await record(decision, outcome, cause instanceof Error ? cause.message : undefined)
+      throw cause
+    }
+  }
+
   return [
+    ...(deps.previewKeys ? [{
+      method: "POST" as const,
+      path: `${AGENT_PREFIX}/sessions/archive-inactive`,
+      allow: { scope: "sessions:manage" },
+      async handle(context: AgentContext) {
+        const inactive = new ArchiveInactive({ secret: deps.previewKeys!.active().secret })
+        const body = await readBody(context.request)
+        const prefs = store.viewPrefs(context.user.id)
+        const entries = (store.agentData(context.user.id).sessions ?? []).map((s) => ({ sessionID: s.sessionID, online: !!deps.registry?.session(s.sessionID), ...(s.lastSeen !== undefined ? { lastSeen: s.lastSeen } : {}), roles: [] }))
+        if (body.preview === true) {
+          const limit = body.limit
+          if (!Number.isInteger(limit) || Number(limit) < 1 || Number(limit) > 200) throw new AgentError("invalid", "limit must be a whole number from 1 to 200")
+          return ok(inactive.preview(context.user.id, entries, { pinned: new Set(prefs.pinnedSessions), archived: new Set(prefs.hiddenSessions), inactiveForMs: parseInactiveFor(body.inactiveFor), limit: Number(limit) }))
+        }
+        if (body.confirm !== true || typeof body.previewToken !== "string") throw new AgentError("invalid", "Use preview:true first, then confirm:true with its previewToken")
+        const open = new Set(entries.filter((s) => deps.registry?.session(s.sessionID)?.open).map((s) => s.sessionID))
+        const active = new Set(entries.filter((s) => { const v = deps.registry?.session(s.sessionID); return !!v && (v.busy || v.status.some((x) => x.state === "working" || x.state === "blocked")) }).map((s) => s.sessionID))
+        const checked = inactive.revalidate(context.user.id, body.previewToken, entries, { pinned: new Set(prefs.pinnedSessions), archived: new Set(prefs.hiddenSessions), open, active })
+        const changedIDs: string[] = []
+        const skipped = [...checked.skipped]
+        for (const sessionID of checked.candidates) {
+          const result = await store.archiveSessionIfUnpinned(context.user.id, sessionID)
+          if (result === "changed") { changedIDs.push(sessionID); await changed(context, "session.archive", sessionID, archiveEvent(sessionID, true)) }
+          else skipped.push({ sessionID, reason: result === "pinned" ? "pinned" : result === "not_found" ? "not_found" : "archived" })
+        }
+        if (changedIDs.length) await directory.sync(context.user.id)
+        return ok({ changed: changedIDs, skipped })
+      },
+    }] : []),
+    {
+      method: "PUT",
+      path: `${AGENT_PREFIX}/sessions/:addr/pin`,
+      allow: { scope: "sessions:manage" },
+      async handle(context) {
+        const body = await readBody(context.request)
+        if (flag(body, "pinned") === undefined) throw new AgentError("invalid", "pinned must be true or false")
+        const sessionID = target(directory, context, context.params.addr)
+        const pinned = body.pinned === true
+        const result = await store.setSessionPinned(context.user.id, sessionID, pinned)
+        if (!result) throw new AgentError("not_found", `No session ${context.params.addr}`)
+        if (result.changed) await changed(context, pinned ? "session.pin" : "session.unpin", sessionID, pinnedEvent(sessionID, pinned))
+        return ok({ sessionID, pinned, changed: result.changed })
+      },
+    },
+    {
+      method: "PUT",
+      path: `${AGENT_PREFIX}/sessions/:addr/archive`,
+      allow: { scope: "sessions:manage" },
+      async handle(context) {
+        const body = await readBody(context.request)
+        if (flag(body, "archived") === undefined) throw new AgentError("invalid", "archived must be true or false")
+        const sessionID = target(directory, context, context.params.addr)
+        const archived = body.archived === true
+        const result = await store.setSessionArchived(context.user.id, sessionID, archived)
+        if (!result) throw new AgentError("invalid", "The archive is full; unarchive a session first")
+        if (result.changed) {
+          await directory.sync(context.user.id)
+          await changed(context, archived ? "session.archive" : "session.unarchive", sessionID, archiveEvent(sessionID, archived))
+        }
+        return ok({ sessionID, archived, changed: result.changed })
+      },
+    },
     {
       method: "GET",
       path: `${AGENT_PREFIX}/who`,
@@ -143,28 +270,39 @@ export function directoryRoutes(directory: Directory): AgentRoute[] {
     {
       method: "POST",
       path: `${AGENT_PREFIX}/name`,
-      allow: { session: true },
+      allow: MANAGE,
       handle: async (context) => {
         const body = await readBody(context.request)
         const name = text(body, "name", true)
         const sessionID = target(directory, context, text(body, "session"))
-        return ok(await directory.setName(context.user.id, sessionID, name))
+        const before = directory.resolveOne(context.user.id, sessionID).name
+        const named = await directory.setName(context.user.id, sessionID, name)
+        if (named.name !== before) await changed(context, "session.name", sessionID, namedEvent(sessionID, named.name))
+        return ok(named)
       },
     },
     {
       method: "POST",
       path: `${AGENT_PREFIX}/roles/claim`,
-      allow: { session: true },
+      allow: MANAGE,
       handle: async (context) => {
         const body = await readBody(context.request)
         const role = text(body, "role", true)
         const exclusive = flag(body, "exclusive")
         const project = text(body, "project")
         const sessionID = target(directory, context, text(body, "session"))
-        const claim = await directory.claimRole(context.user.id, sessionID, role, {
-          ...(exclusive !== undefined ? { exclusive } : {}),
-          ...(project !== undefined ? { project } : {}),
-          byUser: context.actor.kind === "user",
+        const claim = await roleWrite(context, "roles", sessionID, async () => {
+          const before = directory.resolveOne(context.user.id, sessionID).roles
+          const claim = await directory.claimRole(context.user.id, sessionID, role, {
+            ...(exclusive !== undefined ? { exclusive } : {}),
+            ...(project !== undefined ? { project } : {}),
+            byUser: context.actor.kind === "user",
+          })
+          const prev = before.find((r) => r.role === claim.role && r.project === claim.project)
+          if (!prev || prev.generation !== claim.generation || !!prev.exclusive !== !!claim.exclusive) {
+            await changed(context, "role.claim", sessionID, roleEvent(sessionID, true, claim))
+          }
+          return claim
         })
         return ok({ sessionID, ...claim })
       },
@@ -172,13 +310,18 @@ export function directoryRoutes(directory: Directory): AgentRoute[] {
     {
       method: "POST",
       path: `${AGENT_PREFIX}/roles/release`,
-      allow: { session: true },
+      allow: MANAGE,
       handle: async (context) => {
         const body = await readBody(context.request)
         const role = text(body, "role", true)
         const project = text(body, "project")
         const sessionID = target(directory, context, text(body, "session"))
-        return ok({ sessionID, ...(await directory.releaseRole(context.user.id, sessionID, role, project)), released: true })
+        const released = await roleWrite(context, "roles.release", sessionID, async () => {
+          const released = await directory.releaseRole(context.user.id, sessionID, role, project)
+          await changed(context, "role.release", sessionID, roleEvent(sessionID, false, released))
+          return released
+        })
+        return ok({ sessionID, ...released, released: true })
       },
     },
   ]

package/src/central/agent/directory.ts

@@ -207,7 +207,7 @@ export class Directory {
   /**
    * 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…, concierge…) need `byUser`
+   * 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> {

package/src/central/agent/errors.ts

@@ -5,6 +5,8 @@
 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. */

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)
+  }
+}