@huynle/hub 0.7.1 → 0.7.3

package/src/central/agent/watch.ts

@@ -1,220 +1,111 @@
-// GET /api/agent/watch (design §4): a lite SSE stream of compact JSON events about one user's sessions, for
-// orchestrator loops. Not the console's /api/events (cookie/device keyed, with replay and streamed text): this one
-// is per actor, has no replay and never carries text deltas.
+// GET /api/agent/watch (design §4; lifecycle design "Events"): a live SSE view of the canonical agent event journal
+// (events.ts), for orchestrator loops. The same events, visibility and filters as GET /api/agent/events, read with
+// the same read() (events-routes.ts), so the two never define events differently. Not the console's /api/events.
 //
-//   ?blocked=1        blocker events only
+//   ?blocked=1        blocker events only (blocker.*)
 //   ?session=<addr>   only that session's tree (an address resolved for the caller; several for a @@role)
+//   ?cursor=… or Last-Event-ID: resume after a cursor this stream (or GET /api/agent/events) gave; a bad one is
+//                     400 invalid_cursor before the stream starts
 //
-// Events (each `data:` line one JSON object with `type` and `at`):
-//   {type: "ready"}                                         first, once subscribed
-//   {type: "state", sessionID, rootID, state, prev?}        a session's own state changed
-//   {type: "blocker.opened", sessionID, rootID, blocker: {kind, id, summary}}
-//   {type: "blocker.closed", sessionID, rootID, id}         answered, cancelled or gone
-//   {type: "session.added", sessionID, title} / {type: "session.removed", sessionID}   catalog changes
-//   {type: "message", id, kind, state, from, to, sessionID?, senderID?, replyTo?, delivery?}   an agent message was
-//     stored (no text): sessionID is the recipient session, senderID the sending one. The user sees all of them,
-//     a session or app (messages:read) only those it sent or received; ?session= matches either session.
-//   {type: "launch", id, state, reason, outcome?, sessionID?, name?, labels}   a launch changed (the user sees all of
-//     theirs, an app or session those it started); ?session= matches its session.
+// Frames (each `data:` line one JSON object; `id:` lines carry the resumable cursor):
+//   {type: "ready", at}                                  first, once subscribed
+//   {id: "evt_…", at, type, subject, data}               a journal event (no free text)
+//   {type: "reset", at, refresh: [...]}                  the cursor was no longer covered: re-read those
+//   event: ping                                          every heartbeat while idle (default 20 s), with the cursor
 // When the hub drains (shutting down), the stream ends with `retry: 2000` (reconnect, to another pod, after it).
-// A `ping` event every heartbeat (default 20 s). Only status messages of the caller's tenant are read; catalog
-// changes are diffed against the caller's own sessions.
-import type { LiveStatus, RegistryMessage } from "../registry"
-import { partyKey } from "./envelope"
-import { addressOf, type Message } from "./messages"
-import type { Launch } from "./launch-store"
-import type { ReadRegistry } from "./read-routes"
+import type { AgentActor } from "./actor"
+import type { AgentEvent } from "./events"
+import { read, RESET_REFRESH, type EventsPage, type EventsRouteDeps } from "./events-routes"
 
 export const WATCH_HEARTBEAT_MS = 20_000
 /** Draining: the `retry:` (ms) an ending watch stream sends. */
 export const WATCH_RETRY_MS = 2_000
 const RETRY = `retry: ${WATCH_RETRY_MS}\n\n`
 const SSE_HEADERS = { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" }
-
-export interface WatchRegistry extends Pick<ReadRegistry, "catalog" | "sessionTenant"> {
-  subscribe(listener: (message: RegistryMessage, tenant?: string) => void): () => void
-}
-
-/** Stored agent messages as they are sent (MessageFeed). */
-export interface MessageSource {
-  subscribe(listener: (userID: string, message: Message) => void): () => void
-}
-
-/** Launch changes as the engine makes them (LaunchFeed). */
-export interface LaunchSource {
-  subscribe(listener: (userID: string, launch: Launch) => void): () => void
-}
-
-/** The compact watch event of a launch change (never its prompt). */
-function launchEvent(launch: Launch): WatchEvent {
-  return {
-    type: "launch",
-    id: launch.id,
-    state: launch.state,
-    reason: launch.reason,
-    ...(launch.outcome !== undefined ? { outcome: launch.outcome } : {}),
-    ...(launch.sessionID !== undefined ? { sessionID: launch.sessionID } : {}),
-    ...(launch.name !== undefined ? { name: launch.name } : {}),
-    labels: launch.spec.labels,
-  }
-}
+const PAGE = 200
 
 export interface WatchOptions {
-  readonly registry: WatchRegistry
+  readonly events: EventsRouteDeps
   readonly userID: string
+  readonly actor: AgentActor
   readonly signal: AbortSignal
-  /** Only blocker events. */
-  readonly blocked?: boolean
+  /** Resume after this cursor (none: from now). */
+  readonly cursor?: string
+  /** Only these event types (exact, or `blocker.*`). */
+  readonly types?: readonly string[]
   /** Only events of these sessions or of trees rooted at them. */
   readonly sessions?: ReadonlySet<string>
-  /** Message events: from this feed, only those of the party key (undefined: all of the user's). */
-  readonly messages?: { readonly feed: MessageSource; readonly party?: string }
-  /** Launch events: from this feed, only those launched by `by` (undefined: all of the user's). */
-  readonly launches?: { readonly feed: LaunchSource; readonly by?: string }
   readonly heartbeatMs?: number
   readonly now?: () => number
   /** Aborted when the hub drains: the stream ends with a `retry:` hint. */
   readonly draining?: AbortSignal
 }
 
-/** The compact watch event of a message (never its text). */
-function messageEvent(message: Message): WatchEvent {
-  const { id, kind, state, from, recipient, replyTo, delivery } = message
-  return {
-    type: "message",
-    id,
-    kind,
-    state,
-    from: addressOf(from),
-    to: message.to,
-    ...(recipient.kind === "session" ? { sessionID: recipient.sessionID } : {}),
-    ...(from.kind === "session" ? { senderID: from.sessionID } : {}),
-    ...(replyTo ? { replyTo } : {}),
-    ...(delivery ? { delivery } : {}),
-  }
-}
-
-interface Known {
-  state: string
-  blockers: Set<string>
-}
-
-type WatchEvent = { type: string; sessionID?: string; rootID?: string; senderID?: string } & Record<string, unknown>
-
-export function watchStream(options: WatchOptions): Response {
+/** The watch stream; throws invalid_cursor (before streaming) for a cursor this hub did not give this user. */
+export async function watchStream(options: WatchOptions): Promise<Response> {
   if (options.draining?.aborted) return new Response(RETRY, { headers: SSE_HEADERS })
-  const { registry, userID } = options
+  const { userID, actor } = options
   const now = options.now ?? Date.now
+  const heartbeatMs = options.heartbeatMs ?? WATCH_HEARTBEAT_MS
+  const filters = { limit: PAGE, types: options.types ?? [], ...(options.sessions ? { sessions: options.sessions } : {}) }
+  const first = await read(options.events, userID, actor, { ...filters, ...(options.cursor ? { cursor: options.cursor } : {}), wait: 0 })
   const encoder = new TextEncoder()
-  /** Per session (roots and subagents): its own state and open blocker IDs. */
-  const known = new Map<string, Known>()
-  /** Catalog sessions of the user, ID → title. */
-  let catalog = new Map<string, string>()
+  const stop = new AbortController()
 
-  const own = () => {
-    const out = new Map<string, { title: string; status: LiveStatus[] }>()
-    for (const machine of registry.catalog()) {
-      for (const process of machine.processes) {
-        for (const s of process.sessions) {
-          if (!out.has(s.id) && registry.sessionTenant(s.id) === userID) out.set(s.id, { title: s.title, status: s.status })
-        }
-      }
-    }
-    return out
-  }
-  const remember = (entry: LiveStatus) => known.set(entry.id, { state: entry.state, blockers: new Set(entry.blockers.map((b) => b.id)) })
-  const seed = () => {
-    const sessions = own()
-    for (const { status } of sessions.values()) for (const entry of status) if (!known.has(entry.id)) remember(entry)
-    return sessions
-  }
-  catalog = new Map([...seed()].map(([id, s]) => [id, s.title]))
-
-  const wanted = (event: WatchEvent) => {
-    if (options.blocked && !event.type.startsWith("blocker.")) return false
-    if (!options.sessions) return true
-    return [event.sessionID, event.rootID, event.senderID].some((id) => id !== undefined && options.sessions!.has(id))
-  }
-
-  /** Events for a status tree (root first), against what was known. */
-  const statusEvents = (rootID: string, sessions: readonly LiveStatus[]): WatchEvent[] => {
-    const out: WatchEvent[] = []
-    for (const entry of sessions) {
-      const before = known.get(entry.id)
-      const open = new Set(entry.blockers.map((b) => b.id))
-      for (const b of entry.blockers) {
-        if (!before?.blockers.has(b.id)) out.push({ type: "blocker.opened", sessionID: entry.id, rootID, blocker: { kind: b.kind, id: b.id, summary: b.summary } })
-      }
-      for (const id of before?.blockers ?? []) if (!open.has(id)) out.push({ type: "blocker.closed", sessionID: entry.id, rootID, id })
-      if (before?.state !== entry.state) out.push({ type: "state", sessionID: entry.id, rootID, state: entry.state, ...(before ? { prev: before.state } : {}) })
-      remember(entry)
-    }
-    return out
-  }
-
-  const catalogEvents = (): WatchEvent[] => {
-    const sessions = seed()
-    const out: WatchEvent[] = []
-    for (const [id, s] of sessions) if (!catalog.has(id)) out.push({ type: "session.added", sessionID: id, title: s.title })
-    for (const id of catalog.keys()) if (!sessions.has(id)) out.push({ type: "session.removed", sessionID: id })
-    catalog = new Map([...sessions].map(([id, s]) => [id, s.title]))
-    return out
-  }
-
-  let cleanup = () => {}
   const stream = new ReadableStream<Uint8Array>({
-    start(controller) {
+    async start(controller) {
+      let open = true
+      const close = () => {
+        if (!open) return
+        open = false
+        stop.abort()
+        try {
+          controller.close()
+        } catch {}
+      }
       const write = (chunk: string) => {
+        if (!open) return
         try {
           controller.enqueue(encoder.encode(chunk))
         } catch {
-          cleanup()
+          close()
         }
       }
-      const send = (event: WatchEvent) => write(`data: ${JSON.stringify({ ...event, at: now() })}\n\n`)
-      const unsubscribe = registry.subscribe((message, tenant) => {
-        let events: WatchEvent[] = []
-        if (message.type === "catalog") events = catalogEvents()
-        else if (message.type === "status" && tenant === userID) events = statusEvents(message.sessionID, message.sessions)
-        for (const event of events) if (wanted(event)) send(event)
-      })
-      const messages = options.messages
-      const unsubscribeMessages = messages?.feed.subscribe((user, message) => {
-        if (user !== userID) return
-        if (messages.party !== undefined && partyKey(message.from) !== messages.party && partyKey(message.recipient) !== messages.party) return
-        const event = messageEvent(message)
-        if (wanted(event)) send(event)
-      })
-      const launches = options.launches
-      const unsubscribeLaunches = launches?.feed.subscribe((user, launch) => {
-        if (user !== userID || (launches.by !== undefined && launch.by !== launches.by)) return
-        const event = launchEvent(launch)
-        if (wanted(event)) send(event)
-      })
-      // A named event (not a comment) so clients can tell a live stream from a dead one.
-      const heartbeat = setInterval(() => write("event: ping\ndata: 0\n\n"), options.heartbeatMs ?? WATCH_HEARTBEAT_MS)
-      cleanup = () => {
-        clearInterval(heartbeat)
-        unsubscribe()
-        unsubscribeMessages?.()
-        unsubscribeLaunches?.()
+      const frame = (data: object, id?: string) => write(`${id ? `id: ${id}\n` : ""}data: ${JSON.stringify(data)}\n\n`)
+      const emit = (page: EventsPage) => {
+        if (page.reset) return frame({ type: "reset", at: now(), refresh: page.refresh ?? RESET_REFRESH }, page.cursor)
+        if (page.events.length === 0) return write(`event: ping\nid: ${page.cursor}\ndata: 0\n\n`)
+        page.events.forEach((event: AgentEvent, i) => frame(event, i === page.events.length - 1 ? page.cursor : undefined))
       }
-      options.signal.addEventListener("abort", () => cleanup(), { once: true })
-      send({ type: "ready" })
+      options.signal.addEventListener("abort", () => close(), { once: true })
       options.draining?.addEventListener(
         "abort",
         () => {
           write(RETRY)
-          cleanup()
-          try {
-            controller.close()
-          } catch {}
+          close()
         },
         { once: true },
       )
+      frame({ type: "ready", at: now() }, options.cursor && !first.reset ? options.cursor : first.cursor)
+      if (first.reset || first.events.length) emit(first)
+      let cursor = first.cursor
+      while (open && !stop.signal.aborted) {
+        let page: EventsPage
+        try {
+          page = await read(options.events, userID, actor, { ...filters, cursor, wait: heartbeatMs / 1000 }, stop.signal)
+        } catch (cause) {
+          console.error(`[hub] agent watch read failed: ${(cause as Error).message}`)
+          write(RETRY)
+          return close()
+        }
+        if (stop.signal.aborted) break
+        emit(page)
+        cursor = page.cursor
+      }
+      close()
     },
     cancel() {
-      cleanup()
+      stop.abort()
     },
   })
   return new Response(stream, { headers: SSE_HEADERS })

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

@@ -13,13 +13,13 @@ import type { Store } from "../store"
 import type { AgentActor } from "./actor"
 import { AgentError } from "./errors"
 import type { AgentRoute } from "./routes"
-import type { WebhookOwner, Webhooks } from "./webhooks"
+import { webhookEventScopes, type WebhookOwner, type Webhooks } from "./webhooks"
 
 // A literal: routes.ts imports this module.
 const PATH = "/api/agent/webhooks"
 const NO_STORE = { "cache-control": "no-store" }
 /** Users; apps with sessions:launch. */
-export const WEBHOOK_SCOPE = "sessions:launch"
+export const WEBHOOK_SCOPE = "events:subscribe"
 const ALLOW = { scope: WEBHOOK_SCOPE } as const
 
 export type RouteWebhooks = Pick<Webhooks, "register" | "list" | "get" | "remove" | "deliveries">
@@ -29,6 +29,13 @@ const ownerOf = (actor: AgentActor): WebhookOwner | undefined => (actor.kind ===
 
 const notFound = (id: string) => new AgentError("not_found", `No webhook ${id}`)
 
+const requireEventScopes = (actor: AgentActor, events: unknown) => {
+  if (actor.kind !== "app") return
+  const patterns = events === undefined ? ["launch.*"] : Array.isArray(events) && events.every((e) => typeof e === "string") ? events : []
+  const missing = webhookEventScopes(patterns).filter((scope) => !actor.scopes.includes(scope))
+  if (missing.length) throw new AgentError("forbidden", `Webhook events need scope ${missing.join(", ")}`)
+}
+
 async function bodyOf(request: Request): Promise<Record<string, unknown>> {
   const raw = JSON.parse(await request.text()) as unknown
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new AgentError("invalid", "Body must be a JSON object")
@@ -43,6 +50,7 @@ export function webhookRoutes(webhooks: RouteWebhooks, store?: Pick<Store, "audi
       allow: ALLOW,
       async handle({ request, actor, user }) {
         const input = await bodyOf(request)
+        requireEventScopes(actor, input.events)
         const result = await webhooks.register(user.id, ownerOf(actor) ?? "user", { url: input.url, events: input.events, label: input.label })
         await store?.audit({ actor: user.id, action: "webhook.create", target: result.webhook.id, detail: new URL(result.webhook.url).host })
         return Response.json(result, { status: 201, headers: NO_STORE })

package/src/central/agent/webhooks.ts

@@ -27,12 +27,20 @@ import {
 import type { Clock, Locks, StateStore, Timers } from "../backend/types"
 import { publicFetch, PublicURLError, publicURLProblem, type ResolveHost } from "../push-target"
 import { AgentError } from "./errors"
+import type { AgentEvent, EventAudience, EventFamily } from "./events"
 import { LAUNCH_STATES, type Launch } from "./launch-store"
 
 export const WEBHOOKS = "webhooks"
 export const WEBHOOK_OUTBOX = "webhook-outbox"
 /** Every event type a webhook can receive (phase 4: launch changes). */
-export const WEBHOOK_EVENT_TYPES: readonly string[] = LAUNCH_STATES.map((state) => `launch.${state}`)
+export const CANONICAL_WEBHOOK_EVENT_TYPES: readonly string[] = [
+  "session.added", "session.removed", "session.changed", "session.archived", "session.named",
+  "session.pinned",
+  "blocker.opened", "blocker.closed", "machine.changed", "role.claimed", "role.released",
+  "message.changed", "launch.changed",
+]
+/** Includes persisted pre-canonical launch registrations for rolling rollback compatibility. */
+export const WEBHOOK_EVENT_TYPES: readonly string[] = [...CANONICAL_WEBHOOK_EVENT_TYPES, ...LAUNCH_STATES.map((state) => `launch.${state}`)]
 export const DEFAULT_WEBHOOK_EVENTS: readonly string[] = ["launch.*"]
 export const MAX_WEBHOOKS = 20
 export const MAX_WEBHOOK_URL = 2048
@@ -133,6 +141,8 @@ export interface WebhooksDeps {
   readonly fetch?: typeof globalThis.fetch
   /** Whether an app token (by its id) may still have webhooks; its registrations are dropped when not. */
   readonly appAlive?: (userID: string, tokenID: string) => boolean
+  /** Current scopes of an app token; absent preserves the legacy liveness-only check. */
+  readonly appScopes?: (userID: string, tokenID: string) => readonly string[] | undefined
   readonly backoffMs?: readonly number[]
   readonly timeoutMs?: number
   readonly maxResponseBytes?: number
@@ -165,14 +175,30 @@ function matches(pattern: string, type: string): boolean {
 function eventsOf(raw: unknown): string[] {
   if (raw === undefined) return [...DEFAULT_WEBHOOK_EVENTS]
   if (!Array.isArray(raw) || raw.length === 0 || raw.length > MAX_WEBHOOK_EVENTS || !raw.every((e): e is string => typeof e === "string")) {
-    throw invalid(`events must be a list of 1 to ${MAX_WEBHOOK_EVENTS} event types`, `e.g. ["launch.*"]`)
+    throw invalid(`events must be a list of 1 to ${MAX_WEBHOOK_EVENTS} event types`, `e.g. ["launch.*", "message.changed"]`)
   }
   for (const pattern of raw) {
-    if (!WEBHOOK_EVENT_TYPES.some((type) => matches(pattern, type))) throw invalid(`Unknown event type ${pattern}`, `Use launch.* or one of ${WEBHOOK_EVENT_TYPES.join(", ")}`)
+    if (!WEBHOOK_EVENT_TYPES.some((type) => matches(pattern, type))) throw invalid(`Unknown event type ${pattern}`, "Use a canonical event type or family wildcard")
   }
   return [...new Set(raw)]
 }
 
+export function webhookEventScopes(patterns: readonly string[]): string[] {
+  const scopes = new Set<string>()
+  if (patterns.some((pattern) => LAUNCH_STATES.some((state) => matches(pattern, `launch.${state}`)))) scopes.add("sessions:launch")
+  for (const pattern of patterns) for (const type of CANONICAL_WEBHOOK_EVENT_TYPES) if (matches(pattern, type)) {
+    if (type === "message.changed") scopes.add("messages:read")
+    else if (type === "launch.changed") scopes.add("sessions:launch")
+    else if (["session.archived", "session.named", "session.pinned", "role.claimed", "role.released"].includes(type)) scopes.add("sessions:manage")
+    else scopes.add("sessions:read")
+  }
+  return [...scopes]
+}
+
+export function canonicalWebhookEvent(source: string, userID: string, event: AgentEvent): WebhookEvent {
+  return { id: event.id, type: event.type, source, subject: event.subject.launchID ?? event.subject.messageID ?? event.subject.sessionID ?? event.subject.machineID ?? event.id, time: new Date(event.at).toISOString(), user: userID, schemaVersion: 1, data: { subject: event.subject, data: event.data } }
+}
+
 const view = ({ secret: _secret, ...rest }: Registration): WebhookView => rest
 
 const deliveryView = (entry: OutboxEntry): DeliveryView => ({
@@ -286,8 +312,9 @@ export class Webhooks {
    * only when `by` (who caused it) is that app. Resolves with how many deliveries were newly queued (an event
    * already queued for a registration is not queued again).
    */
-  async publish(userID: string, event: WebhookEvent, options: { readonly by?: string } = {}): Promise<number> {
-    const targets = (await this.registrations(userID)).filter((r) => (r.by === "user" || r.by === options.by) && r.events.some((p) => matches(p, event.type)))
+  async publish(userID: string, event: WebhookEvent, options: { readonly by?: string; readonly owners?: readonly string[]; readonly matchTypes?: readonly string[] } = {}): Promise<number> {
+    const matchTypes = options.matchTypes ?? [event.type]
+    const targets = (await this.registrations(userID)).filter((r) => (r.by === "user" || r.by === options.by || options.owners?.includes(r.by)) && r.events.some((p) => matchTypes.some((type) => matches(p, type))))
     if (!targets.length) return 0
     const max = this.deps.maxOutbox ?? WEBHOOK_OUTBOX_MAX
     let size = (await this.deps.state.list(userID, WEBHOOK_OUTBOX)).length
@@ -308,6 +335,15 @@ export class Webhooks {
     return queued
   }
 
+  publishCanonical(userID: string, event: AgentEvent, _family: EventFamily, audience?: EventAudience): Promise<number> {
+    const legacyLaunchType = event.type === "launch.changed" && typeof event.data.state === "string" ? `launch.${event.data.state}` : undefined
+    return this.publish(userID, canonicalWebhookEvent(this.deps.source, userID, event), {
+      ...(audience?.by ? { by: audience.by } : {}),
+      ...(audience?.parties ? { owners: audience.parties.filter((party) => party.startsWith("app:")) } : {}),
+      ...(legacyLaunchType ? { matchTypes: [event.type, legacyLaunchType] } : {}),
+    })
+  }
+
   /** A launch change (the LaunchFeed): `data` is the launch as the API shows it. */
   async onLaunch(userID: string, launch: Launch, data: unknown): Promise<number> {
     return this.publish(userID, launchEvent(this.deps.source, launch, data), launch.by !== undefined ? { by: launch.by } : {})
@@ -401,6 +437,14 @@ export class Webhooks {
         await this.remove(userID, registration.id)
         return
       }
+      if (registration.by !== "user" && this.deps.appScopes) {
+        const scopes = this.deps.appScopes(userID, registration.by.slice("app:".length))
+        const required = ["events:subscribe", ...webhookEventScopes(registration.events)]
+        if (!scopes || required.some((scope) => !scopes.includes(scope))) {
+          await this.remove(userID, registration.id)
+          return
+        }
+      }
       const { last, final } = await this.send(registration, entry, now, timeoutMs)
       const attempts = entry.attempts + 1
       const delivered = last.status !== undefined && last.status >= 200 && last.status < 300

package/src/central/auth.ts

@@ -3,11 +3,14 @@
 // - device pairing: short single-use numeric codes, shown in the /hub dialog or logged at startup
 // - login links: long single-use codes opened from the terminal to sign a browser in
 // - app link codes: long single-use codes (QR / hubapp:// deep link) a native app redeems for a device token
+// - CLI login (device-code flow, `hub login`): a terminal asks, a signed-in user approves it as themselves with the
+//   scopes they choose, the terminal polls for the decision (the caller then issues an app token for that user)
 // Pending codes, enrollments and the limiters live in the Kv / Counters backends (process memory by default, so a
 // restart invalidates them; Valkey in a cluster, so a code issued on one pod is redeemed on any). Codes are spent
 // with GETDEL: exactly one redeem wins, on any pod.
 import { randomBytes, randomInt } from "node:crypto"
 import type { EnrollPoll, EnrollStart } from "../protocol"
+import { APP_SCOPES, DEFAULT_CLI_LOGIN_SCOPES } from "./agent/app-tokens"
 import { MemoryCounters } from "./backend/memory-counters"
 import { MemoryKv } from "./backend/memory-kv"
 import type { Counters, Kv } from "./backend/types"
@@ -32,6 +35,7 @@ export const ENROLL_INTERVAL_MS = 2000
 export const PAIR_TTL_MS = 5 * 60_000
 export const LOGIN_TTL_MS = 2 * 60_000
 export const LINK_TTL_MS = 5 * 60_000
+export const CLI_LOGIN_TTL_MS = 10 * 60_000
 /** Longest device public key accepted at link time (characters). */
 export const MAX_PUBLIC_KEY = 4096
 
@@ -63,6 +67,15 @@ function deviceLabel(value: unknown, fallback: string): string {
   return text ? [...text].slice(0, 64).join("").trim() : fallback
 }
 
+/** App token scopes from a client: a list of known scopes (deduplicated, in order); absent is none when `optional`. */
+function scopeList(value: unknown, optional: boolean): string[] {
+  if (value === undefined && optional) return []
+  if (!Array.isArray(value) || !value.every((s): s is string => typeof s === "string")) throw new ValidationError("scopes must be a list of scope names")
+  const unknown = value.find((s) => !APP_SCOPES.includes(s))
+  if (unknown !== undefined) throw new ValidationError(`Unknown scope: ${unknown.slice(0, 64)}`)
+  return [...new Set(value)]
+}
+
 const PEM = /^-----BEGIN PUBLIC KEY-----([\s\S]*)-----END PUBLIC KEY-----$/
 const KEY_BODY = /^[A-Za-z0-9+/_-]{16,}={0,2}$/
 
@@ -87,6 +100,45 @@ interface Enrollment {
   readonly ownerID?: string
 }
 
+interface CliLogin {
+  readonly userCode: string
+  readonly deviceCode: string
+  readonly clientName: string
+  /** The scopes the terminal asked for (shown on the approval page, ticked by default). */
+  readonly scopes: readonly string[]
+  readonly created: number
+  readonly expiresAt: number
+  readonly status: "pending" | "approved" | "denied"
+  /** The approver: the user the app token is issued for. */
+  readonly ownerID?: string
+  /** The scopes the approver chose. */
+  readonly approved?: readonly string[]
+}
+
+/** POST /cli/login → a code to approve in the console (never a credential). */
+export interface CliLoginStart {
+  readonly userCode: string
+  readonly deviceCode: string
+  readonly approveURL: string
+  readonly intervalMs: number
+  readonly expiresAt: number
+  readonly scopes: readonly string[]
+}
+
+/** A pending CLI login as the approval page shows it. */
+export interface PendingCliLogin {
+  readonly userCode: string
+  readonly clientName: string
+  readonly scopes: readonly string[]
+  readonly created: number
+  readonly expiresAt: number
+}
+
+/** The decision on a CLI login, delivered once. `approved` carries who approved it and the scopes they chose. */
+export type CliLoginPoll =
+  | { readonly status: "pending" | "denied" | "expired" }
+  | { readonly status: "approved"; readonly ownerID: string; readonly clientName: string; readonly scopes: readonly string[] }
+
 /** A pending pairing code, login link or app link code and the user its device will belong to. */
 interface Grant {
   readonly expiresAt: number
@@ -135,6 +187,10 @@ const KEYS = {
   enrollSlot: (slot: number) => `auth:enroll-slot:${slot}`,
   enrollSeq: "auth:enroll-seq",
   enrollRate: "auth:enroll-rate",
+  cliLogin: (deviceCode: string) => `auth:cli-login:${deviceCode}`,
+  cliLoginCode: (userCode: string) => `auth:cli-login-code:${userCode}`,
+  cliLoginDecided: (deviceCode: string) => `auth:cli-login-decided:${deviceCode}`,
+  cliLoginRate: "auth:cli-login-rate",
   pairFailures: "auth:pair-failures",
   code: (kind: CodeKind, code: string) => `auth:${kind}:${code}`,
 }
@@ -181,7 +237,8 @@ export class Auth {
     const px = ENROLL_TTL_MS + 1
     const deviceCode = newToken()
     let code = userCode()
-    while (!(await this.kv.set(KEYS.enrollCode(code), deviceCode, { px, nx: true }))) code = userCode()
+    // A user code names one request: never one a CLI login holds.
+    while ((await this.kv.get(KEYS.cliLoginCode(code))) !== undefined || !(await this.kv.set(KEYS.enrollCode(code), deviceCode, { px, nx: true }))) code = userCode()
     const enrollment: Enrollment = { userCode: code, deviceCode, machineName: machine, created, expiresAt, status: "pending" }
     await this.kv.set(KEYS.enroll(deviceCode), JSON.stringify(enrollment), { px })
     const slot = await this.counters.incr(KEYS.enrollSeq, ENROLL_SEQ_TTL_MS)
@@ -256,6 +313,75 @@ export class Auth {
     return expiresAt - this.now() + 1
   }
 
+  // ---------- CLI login ----------
+
+  /**
+   * Starts a CLI login for `clientName` (the terminal's machine name), asking for the default scopes plus
+   * `scopes`. Rate limited like enrollment. The device code is the poller's secret; the user code is what the
+   * approver confirms.
+   */
+  async startCliLogin(clientName: unknown, scopes: unknown): Promise<CliLoginStart> {
+    const client = name(clientName, "client name")
+    const requested = [...new Set([...DEFAULT_CLI_LOGIN_SCOPES, ...scopeList(scopes, true)])]
+    if ((await this.counters.incr(KEYS.cliLoginRate, ENROLL_WINDOW_MS)) > ENROLL_MAX) throw new RateLimitError("Too many login requests; try again in a minute")
+    const created = this.now()
+    const expiresAt = created + CLI_LOGIN_TTL_MS
+    const px = CLI_LOGIN_TTL_MS + 1
+    const deviceCode = newToken()
+    let code = userCode()
+    while ((await this.kv.get(KEYS.enrollCode(code))) !== undefined || !(await this.kv.set(KEYS.cliLoginCode(code), deviceCode, { px, nx: true }))) code = userCode()
+    const login: CliLogin = { userCode: code, deviceCode, clientName: client, scopes: requested, created, expiresAt, status: "pending" }
+    await this.kv.set(KEYS.cliLogin(deviceCode), JSON.stringify(login), { px })
+    return { userCode: code, deviceCode, approveURL: `${this.publicURL}/approve?code=${code}`, intervalMs: ENROLL_INTERVAL_MS, expiresAt, scopes: requested }
+  }
+
+  /** The pending CLI login of a user code, for the approval page; undefined once decided or expired. */
+  async cliLogin(code: string): Promise<PendingCliLogin | undefined> {
+    const login = await this.cliLoginOf(code)
+    if (!login || login.status !== "pending") return undefined
+    const { userCode, clientName, scopes, created, expiresAt } = login
+    return { userCode, clientName, scopes: [...scopes], created, expiresAt }
+  }
+
+  /**
+   * Approves (as `ownerID`, with the `scopes` they chose: at least one known scope) or denies a pending CLI login:
+   * its client name, or undefined when no such code is pending. The first decision wins (SET NX), on any pod.
+   */
+  async decideCliLogin(code: string, status: "approved" | "denied", ownerID: string, scopes?: unknown): Promise<string | undefined> {
+    const approved = status === "approved" ? scopeList(scopes, false) : undefined
+    if (approved && approved.length === 0) throw new ValidationError("Choose at least one scope")
+    const login = await this.cliLoginOf(code)
+    if (!login || login.status !== "pending") return undefined
+    const px = this.remaining(login.expiresAt)
+    if (!(await this.kv.set(KEYS.cliLoginDecided(login.deviceCode), status, { px, nx: true }))) return undefined
+    const decided: CliLogin = { ...login, status, ownerID, ...(approved ? { approved } : {}) }
+    await this.kv.set(KEYS.cliLogin(login.deviceCode), JSON.stringify(decided), { px })
+    return login.clientName
+  }
+
+  /** The decision on a CLI login, delivered once (GETDEL); afterwards the code reads as expired. */
+  async pollCliLogin(deviceCode: unknown): Promise<CliLoginPoll> {
+    const login = typeof deviceCode === "string" && deviceCode ? await this.pendingLogin(deviceCode) : undefined
+    if (!login) return { status: "expired" }
+    if (login.status === "pending") return { status: "pending" }
+    const taken = parse<CliLogin>(await this.kv.getdel(KEYS.cliLogin(login.deviceCode)))
+    if (!taken || taken.status === "pending") return { status: "expired" }
+    await this.kv.del(KEYS.cliLoginCode(taken.userCode))
+    if (taken.status === "denied" || !taken.ownerID || !taken.approved) return { status: "denied" }
+    return { status: "approved", ownerID: taken.ownerID, clientName: taken.clientName, scopes: [...taken.approved] }
+  }
+
+  private async cliLoginOf(code: string): Promise<CliLogin | undefined> {
+    const deviceCode = await this.kv.get(KEYS.cliLoginCode(normalizeUserCode(code)))
+    return deviceCode === undefined ? undefined : await this.pendingLogin(deviceCode)
+  }
+
+  /** The CLI login of a device code, unless it expired. */
+  private async pendingLogin(deviceCode: string): Promise<CliLogin | undefined> {
+    const login = parse<CliLogin>(await this.kv.get(KEYS.cliLogin(deviceCode)))
+    return login && this.remaining(login.expiresAt) > 0 ? login : undefined
+  }
+
   // ---------- device pairing ----------
 
   /** A pairing code; the device it pairs belongs to `ownerID`. */

package/src/central/backend/index.ts

@@ -6,6 +6,7 @@ import { FileStateStore, type FileStateStoreOptions } from "./file-state"
 import { MemoryBus } from "./memory-bus"
 import { MemoryCatalog } from "./memory-catalog"
 import { MemoryCounters, MemoryLocks } from "./memory-counters"
+import { AGENT_EVENTS_AGE_MS, AGENT_EVENTS_MAX } from "../agent/events"
 import { MemoryEventLog } from "./memory-events"
 import { MemoryKv } from "./memory-kv"
 import { MemoryStateStore } from "./memory-state"
@@ -37,6 +38,7 @@ export function memoryBackends(options: MemoryBackendsOptions = {}): Backends {
     state: new MemoryStateStore({ now }),
     bus: new MemoryBus(options.timers ? { timers: options.timers } : {}),
     events: new MemoryEventLog({ now }),
+    agentEvents: new MemoryEventLog({ now, max: AGENT_EVENTS_MAX, maxAgeMs: AGENT_EVENTS_AGE_MS }),
     counters: new MemoryCounters({ now }),
     locks: new MemoryLocks({ now }),
     catalog: new MemoryCatalog({ now }),
@@ -95,6 +97,7 @@ export function clusterBackends(options: ClusterBackendsOptions): Backends {
     state,
     bus,
     events: new ValkeyEventLog(shared, now ? { now } : {}),
+    agentEvents: new ValkeyEventLog(shared, { ...(now ? { now } : {}), max: AGENT_EVENTS_MAX, maxAgeMs: AGENT_EVENTS_AGE_MS, prefix: "hub:agent:" }),
     counters: new ValkeyCounters(shared),
     locks: new ValkeyLocks(shared, now ? { now } : {}),
     catalog: new ValkeyCatalog(shared, now ? { now } : {}),

package/src/central/backend/types.ts

@@ -235,6 +235,8 @@ export interface Backends {
   readonly state: StateStore
   readonly bus: Bus
   readonly events: EventLog
+  /** The canonical agent event journal's log (24 h / 10,000 per user); the hub makes a memory one when absent. */
+  readonly agentEvents?: EventLog
   readonly counters: Counters
   readonly locks: Locks
   readonly catalog: Catalog