@huynle/hub 0.6.1 → 0.7.2

package/src/central/agent/escalation.ts

@@ -0,0 +1,219 @@
+// Escalations (design §5, §12.1; decision wvqeuis0 §7; exploration hcw63slg Security): what the acting engine's
+// needs_user becomes. An agent asked to approve a permission request outside its grant; the user decides.
+//
+// - ONE Decision per (holder, request): the first escalation opens it (options approve [always] / deny (safe), the
+//   agent's recommendation, the tier the hub set on the evaluation, about the asking session); escalating the same
+//   request again updates the open Decision's reason instead (no new push). Concurrent escalations race on a
+//   version-checked reservation: one opens the Decision, the other is rate_limited (retry).
+// - The recommendation also shows on the request's blocker (registry.recommend: catalog, status, the push's
+//   service worker reads it there).
+// - Answering (decisions.ts runs `act` after the answer wins) replies to the permission AS THE USER through the
+//   shared executor: no grant, no kill switch (those bind agents, not the user); tenancy of the tree is checked
+//   again; the reply is in the agent audit as the user's. The request gone → the Decision closes (gone); its spoke
+//   not serving permission → it closes with the unsupported reason (audited unsupported).
+// - The request answered elsewhere, or ended (registry.onPermissionClosed → closed()): every Decision escalating
+//   it closes.
+// - Spam limits: ESCALATIONS_PER_HOLDER_HOUR new Decisions per holder an hour, ESCALATIONS_OPEN_MAX open ones per
+//   user (both rate_limited: the needs_user still stands, without a Decision), and pushes coalesce: a Decision
+//   opened within ESCALATION_PUSH_COALESCE_MS of the user's last escalation push opens quietly (still listed and
+//   live in the console).
+import { type Actions, unsupportedMessage } from "../actions"
+import type { Counters, StateStore } from "../backend/types"
+import type { Registry } from "../registry"
+import type { PermissionDecision } from "../../protocol"
+import type { BlockerRecommendation } from "../../status"
+import type { Escalation } from "./acting"
+import type { AgentActor, UserActor } from "./actor"
+import type { AgentAudit } from "./audit"
+import { type ActOutcome, type Decision, type DecisionActor, type Decisions, WHY_MAX } from "./decisions"
+import { type Party, partyFromActor, partyKey, partyLabel } from "./envelope"
+import { AgentError } from "./errors"
+import type { Message } from "./messages"
+
+/** New escalation Decisions a holder opens an hour (their asks to @me also count in its message pair limit). */
+export const ESCALATIONS_PER_HOLDER_HOUR = 20
+/** Open escalation Decisions per user. */
+export const ESCALATIONS_OPEN_MAX = 20
+/** Escalations opened this soon after the user's last escalation push do not push again. */
+export const ESCALATION_PUSH_COALESCE_MS = 60_000
+/** A reservation older than this (its opener crashed) no longer blocks a new escalation. */
+const RESERVATION_MS = 60_000
+const HOUR_MS = 3_600_000
+/** Characters of the question (the request's resources are listed up to it). */
+const QUESTION_MAX = 2_000
+const CLOSED_REASON = "The request was answered elsewhere or ended"
+
+const COLLECTION = "escalations"
+
+/** (holder, request) → its Decision; without decisionID while it is being opened. */
+interface EscalationRecord {
+  readonly holder: string
+  readonly requestID: string
+  readonly at: number
+  readonly decisionID?: string
+}
+
+export interface EscalationsDeps {
+  readonly state: StateStore
+  readonly counters: Counters
+  readonly decisions: Pick<Decisions, "ask" | "get" | "list" | "close" | "revise">
+  readonly registry: Pick<Registry, "recommend" | "sessionTenant">
+  readonly actions: Pick<Actions, "answerPermission">
+  readonly audit?: Pick<AgentAudit, "record">
+  /** The holder as envelopes name it (a session by its directory name); default: from the actor alone. */
+  readonly describe?: (userID: string, actor: AgentActor) => Party
+  /** The Decision's ask was stored (the console's message feed). */
+  readonly published?: (userID: string, message: Message) => void
+  readonly now?: () => number
+}
+
+const rateLimited = (message: string, retryAfter: number) => new AgentError("rate_limited", message, { extra: { retryAfter } })
+
+export class Escalations {
+  private readonly now: () => number
+
+  constructor(private readonly deps: EscalationsDeps) {
+    this.now = deps.now ?? Date.now
+    this.act = this.act.bind(this)
+  }
+
+  /** The acting engine's escalate hook: opens or updates the holder's Decision about the request. */
+  async escalate(escalation: Escalation): Promise<{ decisionID?: string }> {
+    const { userID } = escalation
+    const holder = this.describe(userID, escalation.actor)
+    const key = `${partyKey(holder)} ${escalation.requestID}`
+    const { state } = this.deps
+    const existing = await state.get<EscalationRecord>(userID, COLLECTION, key)
+    if (existing?.value.decisionID) {
+      const decision = await this.deps.decisions.get(userID, existing.value.decisionID)
+      if (decision?.state === "open") return this.update(escalation, holder, decision)
+    } else if (existing && this.now() - existing.value.at < RESERVATION_MS) {
+      throw rateLimited("An escalation of this request is being opened", 1)
+    }
+    const record: EscalationRecord = { holder: partyKey(holder), requestID: escalation.requestID, at: this.now() }
+    const reserved = await state.put(userID, COLLECTION, key, record, { ifVersion: existing?.version ?? 0 })
+    if (!reserved.ok) throw rateLimited("An escalation of this request is being opened", 1)
+    try {
+      const decision = await this.open(escalation, holder)
+      await state.put(userID, COLLECTION, key, { ...record, decisionID: decision.id }, { ifVersion: reserved.version })
+      return { decisionID: decision.id }
+    } catch (cause) {
+      await state.delete(userID, COLLECTION, key, { ifVersion: reserved.version })
+      throw cause
+    }
+  }
+
+  /** Decisions' action runner: replies to the escalated permission as the answering user. */
+  async act(userID: string, decision: Decision, choice: { readonly option?: string }, by: UserActor): Promise<ActOutcome> {
+    const action = decision.action
+    if (!action || action.kind !== "permission") return "gone"
+    const reply: PermissionDecision = choice.option === "always" ? "always" : choice.option === "approve" ? "once" : "reject"
+    const verb = reply === "reject" ? "deny" : "approve"
+    const owned = this.deps.registry.sessionTenant(action.rootID) === by.userID && by.userID === userID
+    const answered = owned ? await this.deps.actions.answerPermission({ rootID: action.rootID, requestID: action.requestID, decision: reply }) : { outcome: "gone" as const }
+    await this.deps.audit?.record(userID, {
+      actor: { kind: "user" },
+      verb,
+      target: { sessionID: action.sessionID, requestID: action.requestID },
+      decision: "allow",
+      reason: `Decision ${decision.id}`,
+      outcome: answered.outcome === "done" ? "ok" : answered.outcome,
+    })
+    await this.forget(userID, action.requestID)
+    // The spoke holding the request cannot answer permissions: the Decision closes saying so (not "answered elsewhere").
+    if (answered.outcome === "unsupported") return { outcome: "gone", reason: unsupportedMessage(answered) }
+    return answered.outcome === "done" ? "done" : "gone"
+  }
+
+  /** The request went away (answered elsewhere, ended): closes every Decision escalating it. */
+  async closed(userID: string | undefined, requestID: string): Promise<void> {
+    if (userID === undefined) return
+    for (const { key, value } of await this.deps.state.list<EscalationRecord>(userID, COLLECTION)) {
+      if (value.requestID !== requestID) continue
+      if (value.decisionID) await this.deps.decisions.close(userID, value.decisionID, CLOSED_REASON)
+      await this.deps.state.delete(userID, COLLECTION, key)
+    }
+  }
+
+  // ---- internals ----------------------------------------------------------------------------------------
+
+  private describe(userID: string, actor: AgentActor): Party {
+    return this.deps.describe?.(userID, actor) ?? partyFromActor(actor)
+  }
+
+  /** A new Decision, within the spam limits. */
+  private async open(escalation: Escalation, holder: Party): Promise<Decision> {
+    const { userID } = escalation
+    const { decisions, counters } = this.deps
+    const open = (await decisions.list(userID, { state: "open" })).filter((d) => d.action?.kind === "permission").length
+    if (open >= ESCALATIONS_OPEN_MAX) throw rateLimited(`At most ${ESCALATIONS_OPEN_MAX} escalations wait for the user at once`, 60)
+    const opened = await counters.incr(`escalations:${userID}:${partyKey(holder)}`, HOUR_MS)
+    if (opened > ESCALATIONS_PER_HOLDER_HOUR) throw rateLimited(`At most ${ESCALATIONS_PER_HOLDER_HOUR} escalations an hour`, 3600)
+    const pushes = await counters.incr(`escalation-push:${userID}`, ESCALATION_PUSH_COALESCE_MS)
+    const recommend = escalation.always ? "always" : "approve"
+    const why = boundedWhy(escalation.why)
+    const { message, decision } = await decisions.ask(
+      userID,
+      escalation.actor,
+      {
+        question: question(escalation, partyLabel(holder)),
+        options: [
+          ...(escalation.always ? [{ id: "always", label: "Approve always" }] : []),
+          { id: "approve", label: "Approve once" },
+          { id: "deny", label: "Deny", safe: true },
+        ],
+        recommendation: { option: recommend, ...(why ? { why } : {}) },
+        urgency: "high",
+        tier: escalation.evaluation.tier,
+        about: [escalation.sessionID],
+      },
+      {
+        action: { kind: "permission", requestID: escalation.requestID, rootID: escalation.rootID, sessionID: escalation.sessionID, always: escalation.always },
+        quiet: pushes > 1,
+      },
+    )
+    this.deps.published?.(userID, message)
+    this.showOnBlocker(escalation.requestID, holder, decision)
+    return decision
+  }
+
+  /** The same holder escalated the request again: a new reason replaces the recommendation's. */
+  private async update(escalation: Escalation, holder: Party, decision: Decision): Promise<{ decisionID: string }> {
+    const why = boundedWhy(escalation.why)
+    let current = decision
+    if (why && why !== decision.recommendation?.why) {
+      const option = decision.recommendation?.option ?? (escalation.always ? "always" : "approve")
+      current = (await this.deps.decisions.revise(escalation.userID, decision.id, { recommendation: { option, why } })) ?? decision
+    }
+    this.showOnBlocker(escalation.requestID, holder, current)
+    return { decisionID: decision.id }
+  }
+
+  private showOnBlocker(requestID: string, holder: Party, decision: Decision): void {
+    const why = decision.recommendation?.why
+    const recommendation: BlockerRecommendation = { by: partyLabel(holder), recommends: "approve", ...(why ? { why } : {}), decisionID: decision.id }
+    this.deps.registry.recommend(requestID, recommendation)
+  }
+
+  /** Drops the (holder, request) records of an answered request. */
+  private async forget(userID: string, requestID: string): Promise<void> {
+    for (const { key, value } of await this.deps.state.list<EscalationRecord>(userID, COLLECTION)) {
+      if (value.requestID === requestID) await this.deps.state.delete(userID, COLLECTION, key)
+    }
+  }
+}
+
+/** The agent's reason, cut to what a Decision keeps. */
+function boundedWhy(why: string | undefined): string | undefined {
+  const trimmed = why?.trim()
+  return trimmed ? Array.from(trimmed).slice(0, WHY_MAX).join("") : undefined
+}
+
+/** "@orchestrator asks to approve shell: bun test, bun run lint. Outside its grant: …" (bounded). */
+function question(escalation: Escalation, by: string): string {
+  const { request, evaluation } = escalation
+  const what = request ? `${request.action}${request.resources.length ? `: ${request.resources.join(", ")}` : ""}` : "a permission request (details unknown)"
+  const always = escalation.always && request?.save?.length ? ` always (saves ${request.save.join(", ")})` : escalation.always ? " always" : ""
+  const text = `${by} asks to approve${always} ${what}. Outside its grant: ${evaluation.reason}`
+  return text.length > QUESTION_MAX ? `${text.slice(0, QUESTION_MAX - 1)}…` : text
+}

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