@huynle/hub 0.7.1 → 0.7.2

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

package/src/central/http.ts

@@ -16,6 +16,10 @@ import { authPage, cookieValue, deviceName, OIDC_COOKIE, OidcClient, OidcError }
 import { isNotificationKind, Push, type PushSender } from "./push"
 import { pushEndpointProblem, resolveHost as systemResolveHost, type ResolveHost } from "./push-target"
 import { Webhooks } from "./agent/webhooks"
+import { issueAppToken } from "./agent/app-tokens"
+import { AGENT_EVENTS_AGE_MS, AGENT_EVENTS_MAX, AgentEvents, archiveEvent } from "./agent/events"
+import { EventWriters } from "./agent/event-writers"
+import { MemoryEventLog } from "./backend/memory-events"
 import { WEBHOOK_SCOPE } from "./agent/webhook-routes"
 import { hubBackends, type Backends } from "./backend"
 import { createResolver, type AgentActor, type BearerVerifier, type CredentialMode } from "./agent/actor"
@@ -33,11 +37,12 @@ import type { Launch } from "./agent/launch-store"
 import { decisionStateQuery, MessageFeed } from "./agent/message-routes"
 import { hubDirectory } from "./agent/directory-routes"
 import { agentApi, agentRoutes, agentVerifiers, isAgentPath, wellKnown, type AgentRoute } from "./agent/routes"
+import { MCP_PATH, mcpHttp } from "./mcp-http"
 import { SessionTokens } from "./agent/session-tokens"
 import { SessionTokenPush } from "./session-token-push"
 import { TokenKeys } from "./token-keys"
 import { EventLog } from "./events-log"
-import { BusyError, Registry, type RegistryMessage } from "./registry"
+import { BusyError, Registry } from "./registry"
 import { createActions, type Unsupported, unsupportedMessage } from "./actions"
 import { audioFormat, SpeechError } from "./speech/provider"
 import { SpeechService } from "./speech/service"
@@ -52,9 +57,8 @@ import { randomBytes, randomUUID } from "node:crypto"
 import { LaunchEngine } from "./agent/launch-engine"
 import { LaunchTokens } from "./agent/launch-tokens"
 import { LaunchFeed, launchInfo } from "./agent/launch-routes"
-import type { WatchRegistry } from "./agent/watch"
 import { DRAIN_RETRY_AFTER_MS, DRAIN_TIMEOUT_MS, RequestTimeoutError, RequestTooLargeError, SpokeError, SpokeHub, type DrainOptions, type Notifier, type SpokeHubOptions, type SpokeSocketData } from "./spoke-ws"
-import { ACTIVITY_INTERVAL_MAX, ACTIVITY_INTERVAL_MIN, LOCAL_USER, PUSH_PREF_KEYS, quietHoursInput, Store, VIEW_PREF_KEYS, type DeviceRecord, type LegacyPushPrefs, type PushPrefs, type UserRecord, type ViewPrefs } from "./store"
+import { ACTIVITY_INTERVAL_MAX, ACTIVITY_INTERVAL_MIN, LOCAL_USER, PUSH_PREF_KEYS, quietHoursInput, Store, VIEW_PREF_KEYS, VIEW_PREF_MAX_ARCHIVED, type DeviceRecord, type LegacyPushPrefs, type PushPrefs, type UserRecord, type ViewPrefs } from "./store"
 
 export interface Speech {
   transcribe(audio: Uint8Array, format: string): Promise<string>
@@ -137,6 +141,10 @@ export interface Central {
   readonly launchTokens: LaunchTokens
   /** Webhooks (P4-T10): registrations and the outbox sender; launch changes are published to it. */
   readonly webhooks: Webhooks
+  /** The canonical agent event journal (GET /api/agent/events, MCP events): compact events per user, 24 h / 10,000. */
+  readonly agentEvents: AgentEvents
+  /** The journal's writers (state, blockers, presence, messages, launches); settled() waits for queued appends. */
+  readonly agentEventWriters: EventWriters
   /** The JSON API's route table (method, path, access), for audits and tests. */
   readonly routes: readonly RouteInfo[]
   /**
@@ -232,8 +240,6 @@ const MAX_TITLE_CHARS = 200
 const MAX_HERDR_WORKSPACE_CHARS = 100
 /** View preferences: entries per list and characters per entry. */
 const VIEW_PREF_MAX_ENTRIES = 500
-/** hiddenSessions holds archived sessions (Archive in the console), which add up over time. */
-const VIEW_PREF_MAX_ARCHIVED = 5000
 const VIEW_PREF_MAX_CHARS = 4096
 const DECISIONS = new Set<PermissionDecision>(["once", "always", "reject"])
 /** Longest utterance accepted for conversation mode (characters, after trimming). */
@@ -822,20 +828,33 @@ export function startCentral(options: CentralOptions): Central {
     resolve: options.resolveHost ?? systemResolveHost,
     ...(config.webhooksAllowPrivate ? { allowPrivate: true } : {}),
     appAlive: (userID, tokenID) => store.agentData(userID).appTokens?.some((t) => t.id === tokenID && Array.isArray(t.scopes) && t.scopes.includes(WEBHOOK_SCOPE)) === true,
+    appScopes: (userID, tokenID) => store.agentData(userID).appTokens?.find((t) => t.id === tokenID)?.scopes,
     userAgent: `hub/${options.version ?? "0.0.0"}`,
   })
-  launchFeed.subscribe((userID, launch) => {
-    void webhooks
-      .onLaunch(userID, launch, launchInfo(launch))
-      // Queued here, sent by the webhooks leader (kicked when that is another pod).
-      .then((queued) => (queued && !webhookLeader.isLeader() ? webhookLeader.kick() : undefined))
-      .catch((cause) => console.error(`[hub] webhook queue failed: ${(cause as Error).message}`))
-  }, { origin: true })
   const webhookLeader = leader("webhooks", {
     onElected: () => webhooks.start(),
     onDeposed: () => webhooks.stop(),
     onKick: () => void webhooks.drain().catch((cause) => console.error(`[hub] webhook delivery failed: ${(cause as Error).message}`)),
   })
+  // The canonical agent event journal (lifecycle design, Events): each change appended once across the cluster;
+  // presence by the agent-events leader, everything else where it happens (event-writers.ts).
+  const agentEvents = new AgentEvents({
+    log: backends.agentEvents ?? new MemoryEventLog({ now, max: AGENT_EVENTS_MAX, maxAgeMs: AGENT_EVENTS_AGE_MS }),
+    kv: backends.kv,
+    now,
+    onAppend: (userID, record) => webhooks.publishCanonical(userID, record.event, record.family, record.audience).then((queued) => (queued && !webhookLeader.isLeader() ? webhookLeader.kick() : undefined)),
+  })
+  const agentEventWriters = new EventWriters({
+    events: agentEvents,
+    kv: backends.kv,
+    registry,
+    machineOwner: (machineID) => store.machines().find((m) => m.id === machineID)?.ownerID,
+    users: allUsers,
+    messages: feed,
+    launches: launchFeed,
+  })
+  agentEventWriters.start()
+  leader("agent-events", { onElected: () => agentEventWriters.elected(), onDeposed: () => agentEventWriters.deposed() })
   for (const loop of leaders) void loop.start()
 
   // One credential resolver for every /api request: device cookie, device token, session and app tokens.
@@ -889,26 +908,7 @@ export function startCentral(options: CentralOptions): Central {
     void escalations.closed(tenant, requestID).catch((cause) => console.error(`[hub] escalation close failed: ${(cause as Error).message}`))
   })
   const escalate: Escalate = (escalation) => escalations.escalate(escalation)
-  /** Cluster mode: what GET /api/agent/watch reads; status of sessions on any pod comes from the user's live events. */
-  const watchRegistry = live
-    ? (userID: string): WatchRegistry => ({
-        catalog: () => registry.catalog(),
-        sessionTenant: (sessionID) => registry.sessionTenant(sessionID),
-        subscribe: (listener) => {
-          const offCatalog = registry.subscribe((message) => {
-            if (message.type === "catalog") listener(message)
-          })
-          const subscription = live.subscribe(userID, (event) => {
-            if (event.message.type === "status") listener(event.message as unknown as RegistryMessage, userID)
-          })
-          return () => {
-            offCatalog()
-            subscription.close()
-          }
-        },
-      })
-    : undefined
-  const agentDeps = { draining: drainSignal.signal, store, sessionTokens, directory, registry, spokes, delivery, decisions, feed, heartbeatMs, now, audit, grants, grantRequests, acting, actions, escalate, launches, launchFeed, webhooks, maxPromptChars: MAX_PROMPT_CHARS, ...(watchRegistry ? { watchRegistry } : {}) }
+  const agentDeps = { draining: drainSignal.signal, store, sessionTokens, directory, registry, spokes, delivery, decisions, feed, heartbeatMs, now, audit, grants, grantRequests, acting, actions, escalate, launches, webhooks, agentEvents, eventCursorKeys: tokenKeys, maxPromptChars: MAX_PROMPT_CHARS }
   const resolveActor = createResolver({
     cookieName: COOKIE,
     findDevice: (token) => deviceOfToken(token),
@@ -927,6 +927,16 @@ export function startCentral(options: CentralOptions): Central {
     routes: [...agentRoutes(agentDeps), ...(options.agent?.routes ?? [])],
   })
 
+  // POST /mcp (MCP Streamable HTTP): `hub mcp`'s tools as the bearer's caller; their /api/agent calls are dispatched
+  // to this handler in process.
+  const mcp = mcpHttp({
+    publicURL: () => publicURL,
+    isOwnOrigin: (origin) => origins.has(origin),
+    verify: async (token) => (await resolveActor(new Request(`${url}${MCP_PATH}`, { headers: { authorization: `Bearer ${token}` } }))).ok,
+    dispatch: async (request) => (await handle(request, server)) ?? error(500, "No response"),
+    version: options.version ?? "0.0.0",
+  })
+
   async function handle(request: Request, server: Server<SpokeSocketData>): Promise<Response | undefined> {
     const url = new URL(request.url)
     const { pathname } = url
@@ -963,12 +973,20 @@ export function startCentral(options: CentralOptions): Central {
         if (poll.status === "approved") broadcast({ type: "catalog" })
         return Response.json(poll)
       }
+      // `hub login` without a token (CLI login device code): no credential; the device code is the poller's secret.
+      if (method === "POST" && pathname === "/cli/login") {
+        const input = await body(request)
+        return Response.json(await auth.startCliLogin(input.clientName, input.scopes), { headers: NO_STORE })
+      }
+      if (method === "POST" && pathname === "/cli/login/poll") return await cliLoginPoll((await body(request)).deviceCode)
+      if (method === "GET" && pathname === "/spoke/presence") return await spokePresence(request)
       if (method === "GET" && pathname === "/.well-known/hub") {
         return wellKnown({ publicURL, version: options.version ?? "0.0.0", auth: config.auth.mode === "oidc" ? { mode: "oidc", issuer: config.auth.issuer } : { mode: "pairing" } })
       }
       if (method === "GET" && pathname === "/login") return login(request, url)
       if (oidc && method === "GET" && pathname === "/auth/login") return await authLogin(url)
       if (oidc && method === "GET" && pathname === "/auth/callback") return await authCallback(request, url)
+      if (pathname === MCP_PATH) return await mcp(request)
       if (isAgentPath(pathname)) return await agent.handle(request, url)
       if (pathname.startsWith("/api/")) return await api(request, server, url)
       if (method === "GET") return await staticFile(pathname, request.headers.get("accept-encoding"))
@@ -978,6 +996,31 @@ export function startCentral(options: CentralOptions): Central {
     }
   }
 
+  /**
+   * GET /spoke/presence: which harness spokes of the caller's own machine are connected (machine token only). The
+   * one read-only query a machine credential can make about itself, for `hubctl setup verify` (spoke-connected
+   * readiness): harness, evidence level and features only, never sessions, directories, pids or other machines.
+   */
+  async function spokePresence(request: Request): Promise<Response> {
+    const refused = () => Response.json({ error: "Invalid or revoked machine token" }, { status: 401 })
+    const token = /^Bearer\s+(\S+)$/i.exec(request.headers.get("authorization") ?? "")?.[1]
+    if (!token || token.startsWith("hlt1.")) return refused()
+    const machine = await store.findMachine(token)
+    if (machine) await store.recheck({ users: [machine.ownerID] })
+    const owner = machine && store.user(machine.ownerID)
+    if (!machine || machine.revoked || !owner || owner.disabled) return refused()
+    const processes = registry.catalog().find((m) => m.id === machine.id)?.processes ?? []
+    const seen = new Set<string>()
+    const spokes = processes.flatMap((p) => {
+      const entry = { harness: p.harness, evidence: p.evidence, features: [...p.features] }
+      const key = JSON.stringify(entry)
+      if (seen.has(key)) return []
+      seen.add(key)
+      return [entry]
+    })
+    return Response.json({ machineID: machine.id, spokes })
+  }
+
   async function login(request: Request, url: URL): Promise<Response> {
     const next = url.searchParams.get("next") ?? "/"
     if (!LOGIN_NEXT.test(next)) return error(400, "Invalid next path")
@@ -1060,12 +1103,24 @@ export function startCentral(options: CentralOptions): Central {
     // The phone's session view (hidden/pinned sessions and workspaces), per user, synced to their other devices.
     route("GET", "/api/prefs/view", "user", ({ user }) => Response.json({ prefs: store.viewPrefs(user.id) }, { headers: NO_STORE })),
     route("PUT", "/api/prefs/view", "user", async ({ request, user, device }) => {
+      const before = new Set(store.viewPrefs(user.id).hiddenSessions)
       const prefs = await store.setViewPrefs(user.id, viewPrefsInput(await request.json()))
       // The user's other devices only: never another user, and not the device that made the change.
       toUser(user.id, { type: "prefs", prefs }, device.id)
+      // Archive changes made in the console go to the agent event journal like the agent API's.
+      const after = new Set(prefs.hiddenSessions)
+      const changes = [...[...after].filter((id) => !before.has(id)).map((id) => archiveEvent(id, true)), ...[...before].filter((id) => !after.has(id)).map((id) => archiveEvent(id, false))]
+      for (const change of changes) await agentEvents.append(user.id, change).catch((cause) => console.error(`[hub] archive event failed: ${(cause as Error).message}`))
       return Response.json({ prefs }, { headers: NO_STORE })
     }),
     route("GET", "/api/reads", "user", ({ user }) => Response.json({ reads: store.reads(user.id) }, { headers: NO_STORE })),
+    // A CLI login (`hub login`): the user approves it as themselves, with the scopes they tick, or denies it.
+    route("GET", "/api/cli-logins/:code", "user", async ({ params }) => {
+      const login = await auth.cliLogin(params.code!)
+      return login ? Response.json({ login }, { headers: NO_STORE }) : error(404, "No pending CLI login with that code")
+    }),
+    route("POST", "/api/cli-logins/:code/approve", "user", async ({ request, params, user }) => decideCliLogin(params.code!, "approved", user, (await body(request)).scopes)),
+    route("POST", "/api/cli-logins/:code/deny", "user", ({ params, user }) => decideCliLogin(params.code!, "denied", user)),
     route("POST", "/api/enrollments/:code/approve", "user", ({ params, user }) => decideEnrollment(params.code!, "approved", user)),
     route("POST", "/api/enrollments/:code/deny", "user", ({ params, user }) => decideEnrollment(params.code!, "denied", user)),
     route("GET", "/api/devices", "user", ({ device, user }) =>
@@ -1431,6 +1486,31 @@ export function startCentral(options: CentralOptions): Central {
     return new Response(null, { status: 204 })
   }
 
+  async function decideCliLogin(code: string, status: "approved" | "denied", user: UserRecord, scopes?: unknown): Promise<Response> {
+    const clientName = await auth.decideCliLogin(code, status, user.id, scopes)
+    if (clientName === undefined) return error(404, "No pending CLI login with that code")
+    await store.audit({ actor: user.id, action: status === "approved" ? "cli-login.approve" : "cli-login.deny", detail: clientName })
+    return new Response(null, { status: 204 })
+  }
+
+  /**
+   * The decision on a CLI login, once. Approved: a new app token of the approver (still active) with the scopes
+   * they chose, in this response only (no-store, never logged).
+   */
+  async function cliLoginPoll(deviceCode: unknown): Promise<Response> {
+    const poll = await auth.pollCliLogin(deviceCode)
+    if (poll.status !== "approved") return Response.json({ status: poll.status }, { headers: NO_STORE })
+    const owner = store.user(poll.ownerID)
+    if (!owner || owner.disabled) return Response.json({ status: "denied" }, { headers: NO_STORE })
+    try {
+      const { record, token } = await issueAppToken(store, owner.id, { label: `CLI login: ${poll.clientName}`, scopes: poll.scopes })
+      return Response.json({ status: "approved", token, tokenID: record.id, scopes: record.scopes }, { headers: NO_STORE })
+    } catch (cause) {
+      if (cause instanceof AgentError && cause.code === "rate_limited") return error(429, cause.message, "rate_limited")
+      throw cause
+    }
+  }
+
   async function revokeMachine(id: string, user: UserRecord): Promise<Response> {
     if (!await store.revokeMachine(id)) return error(404, "No such machine")
     await store.bumpMachineEpoch(id)
@@ -1930,6 +2010,8 @@ export function startCentral(options: CentralOptions): Central {
     launchFeed,
     launchTokens,
     webhooks,
+    agentEvents,
+    agentEventWriters,
     routes: [...routes.map(({ method, path, access }) => ({ method, path, access })), ...agent.routes.map(({ method, path }) => ({ method, path, access: "agent" as const }))],
     drain(drainOptions: DrainOptions = {}) {
       draining ??= runDrain(drainOptions)
@@ -1940,6 +2022,7 @@ export function startCentral(options: CentralOptions): Central {
       await Promise.allSettled([...leaders.map((loop) => loop.stop()), recommendations?.stop()])
       launches.shutdown()
       webhooks.stop()
+      agentEventWriters.stop()
       tokenPush.stop()
       delivery.stop()
       decisions.stop()

package/src/central/mcp-http.ts

@@ -0,0 +1,116 @@
+// POST /mcp: the hub's MCP tools over MCP Streamable HTTP, for MCP clients and gateways (Brain decision txznll2f).
+// Stateless: one JSON-RPC message per POST, answered as application/json (no SSE stream, no Mcp-Session-Id);
+// notifications and client responses get 202. Batches are refused (-32600, as in protocol 2025-06-18).
+//
+// Auth: `Authorization: Bearer <token>`, any credential the agent API accepts (app, device, session and act
+// tokens), checked up front with the agent API's resolver: none or invalid → 401 with `WWW-Authenticate: Bearer
+// realm="hub"` (no OAuth resource metadata, so gateways detect plain bearer auth). The tools are `hub mcp`'s
+// (packages/cli/src/mcp.ts) and call /api/agent with the caller's bearer, dispatched in process: scopes, grants,
+// tenancy, kill switches and the audit are exactly the HTTP API's. A browser Origin other than the hub's own is
+// refused (DNS rebinding); requests without one (servers, gateways) are fine. Tokens are never echoed.
+import { createMcpServer, MCP_PROTOCOL_VERSIONS, NOT_FROM_USER, RPC, rpcError, type RpcResponse } from "../../packages/cli/src/mcp"
+import { readCredentials } from "./agent/actor"
+
+export const MCP_PATH = "/mcp"
+
+/** Largest request body (bytes). */
+export const MCP_MAX_BODY_BYTES = 1 << 20
+
+export const MCP_INSTRUCTIONS =
+  "Hub: see and steer your AI agent sessions. Tools read sessions (status, sessions, show, log, who), message them (msg, ask, reply, decline, inbox), act within your grants (approve, deny, answer, prompt, stop) and launch sessions (launch, launches, launch_show, launch_stop), as this bearer token. " +
+  NOT_FROM_USER
+
+export interface McpHttpDeps {
+  /** The hub's public URL (the tools' base URL; requests never leave the process). */
+  publicURL(): string
+  /** Whether a request's Origin is the hub's own. */
+  isOwnOrigin(origin: string): boolean
+  /** Whether the agent API accepts this bearer token. */
+  verify(token: string): Promise<boolean>
+  /** The hub's own request handler (the tools' /api/agent calls). */
+  dispatch(request: Request): Promise<Response>
+  readonly version: string
+  readonly maxBodyBytes?: number
+}
+
+const NO_STORE = { "cache-control": "no-store" }
+
+const failure = (status: number, code: string, message: string, headers: Record<string, string> = {}) =>
+  Response.json({ error: { code, message } }, { status, headers: { ...NO_STORE, ...headers } })
+
+const unauthorized = (message: string) => failure(401, "unauthorized", message, { "www-authenticate": 'Bearer realm="hub"' })
+
+const answer = (response: RpcResponse) =>
+  // A message the server could not take (parse error, not a request, a batch) carries no id: HTTP 400.
+  Response.json(response, { status: response.error && response.id === null ? 400 : 200, headers: NO_STORE })
+
+/** The body as text, or undefined when it is over `max` bytes (read no further). */
+async function readCapped(request: Request, max: number): Promise<string | undefined> {
+  const length = Number(request.headers.get("content-length") ?? "")
+  if (Number.isFinite(length) && length > max) return undefined
+  if (!request.body) return ""
+  const reader = request.body.getReader()
+  const chunks: Uint8Array[] = []
+  let size = 0
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    size += value.byteLength
+    if (size > max) {
+      void reader.cancel().catch(() => {})
+      return undefined
+    }
+    chunks.push(value)
+  }
+  return new TextDecoder().decode(Buffer.concat(chunks))
+}
+
+const acceptsJSON = (accept: string | null) => {
+  if (accept === null || !accept.trim()) return true
+  return accept.split(",").some((part) => {
+    const type = part.split(";")[0]!.trim().toLowerCase()
+    return type === "application/json" || type === "*/*" || type === "application/*"
+  })
+}
+
+/** Answers a request to /mcp (any method). */
+export function mcpHttp(deps: McpHttpDeps): (request: Request) => Promise<Response> {
+  const max = deps.maxBodyBytes ?? MCP_MAX_BODY_BYTES
+  return async (request) => {
+    if (request.method !== "POST") return failure(405, "method_not_allowed", "POST JSON-RPC messages to /mcp (no SSE stream, no sessions)", { allow: "POST" })
+    const origin = request.headers.get("origin")
+    if (origin !== null && !deps.isOwnOrigin(origin)) return failure(403, "forbidden", "Cross-origin request refused")
+    // The bearer only: a cookie never authenticates /mcp.
+    const token = readCredentials(request, "").bearer
+    if (token === undefined) return unauthorized("Send Authorization: Bearer <hub token>")
+    if (!token || !(await deps.verify(token))) return unauthorized("Invalid, expired or revoked token")
+    const version = request.headers.get("mcp-protocol-version")
+    if (version !== null && !MCP_PROTOCOL_VERSIONS.includes(version)) return failure(400, "invalid", `Unsupported MCP-Protocol-Version (supported: ${MCP_PROTOCOL_VERSIONS.join(", ")})`)
+    const type = (request.headers.get("content-type") ?? "").split(";")[0]!.trim().toLowerCase()
+    if (type !== "application/json") return failure(415, "invalid", "Content-Type must be application/json")
+    if (!acceptsJSON(request.headers.get("accept"))) return failure(406, "invalid", "Accept must allow application/json")
+    const text = await readCapped(request, max)
+    if (text === undefined) return failure(413, "invalid", `Request body over ${max} bytes`)
+    let message: unknown
+    try {
+      message = JSON.parse(text)
+    } catch {
+      return answer(rpcError(null, RPC.parse, "parse error: not JSON"))
+    }
+    const server = createMcpServer({
+      credentials: () => ({ url: deps.publicURL(), token, source: "http", fetch: (input, init) => deps.dispatch(new Request(input, init)) }),
+      version: deps.version,
+      instructions: MCP_INSTRUCTIONS,
+    })
+    // The client went away: its tool calls are aborted.
+    const close = () => server.close()
+    request.signal.addEventListener("abort", close, { once: true })
+    try {
+      const response = await server.handle(message)
+      return response ? answer(response) : new Response(null, { status: 202, headers: NO_STORE })
+    } finally {
+      request.signal.removeEventListener("abort", close)
+      server.close()
+    }
+  }
+}