@huynle/hub 0.7.1 → 0.7.2

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

@@ -19,9 +19,8 @@ import type { Directory, DirectoryEntry, RoleView } from "./directory"
 import type { AgentActor } from "./actor"
 import { AgentError } from "./errors"
 import { AGENT_PREFIX, type AgentRoute } from "./routes"
-import { partyFromActor, partyKey } from "./envelope"
-import { launchedBy } from "./launch-routes"
-import { type LaunchSource, watchStream, type MessageSource, type WatchRegistry } from "./watch"
+import { watchStream } from "./watch"
+import type { EventsRouteDeps } from "./events-routes"
 
 /** Labels per session ID. */
 export type SessionLabels = ReadonlyMap<string, Readonly<Record<string, string>>>
@@ -46,14 +45,10 @@ export interface ReadDeps {
   readonly directory: Directory
   readonly registry: ReadRegistry
   readonly spokes?: SpokeRequester
-  /** Agent messages for the watch stream's message events. */
-  readonly feed?: MessageSource
   /** The labels of the user's launched sessions (none without it). */
   readonly labels?: (userID: string) => Promise<SessionLabels>
-  /** Launch changes for the watch stream's launch events. */
-  readonly launches?: LaunchSource
-  /** What the watch stream of a user reads (cluster mode: status from every pod); the registry when absent. */
-  readonly watchRegistry?: (userID: string) => WatchRegistry
+  /** The journal GET /api/agent/watch streams (no watch route without it). */
+  readonly events?: EventsRouteDeps
   /** Watch stream heartbeat (default WATCH_HEARTBEAT_MS). */
   readonly heartbeatMs?: number
   /** Aborted when the hub drains: watch streams end with a `retry:` hint. */
@@ -358,32 +353,33 @@ export function readRoutes(deps: ReadDeps): AgentRoute[] {
       allow: READ,
       handle: async ({ user, params, url }) => ok(await log(deps, user.id, params.addr!, url.searchParams.get("n"))),
     },
-    {
-      method: "GET",
-      path: `${AGENT_PREFIX}/watch`,
-      allow: READ,
-      handle: ({ user, url, request, actor }) => {
-        const addr = url.searchParams.get("session") || undefined
-        // Message events: the user sees all; a session, or an app with messages:read, those it is a party to.
-        const messageReader = actor.kind === "user" || actor.kind === "session" || actor.scopes.includes("messages:read")
-        const messages = deps.feed && messageReader ? { feed: deps.feed, ...(actor.kind === "user" ? {} : { party: partyKey(partyFromActor(actor)) }) } : undefined
-        const sessions = addr ? new Set(deps.directory.resolve(user.id, addr).sessions.map((s) => s.sessionID)) : undefined
-        const blocked = ["1", "true"].includes(url.searchParams.get("blocked") ?? "")
-        // Launch events: the user sees all; an app or session those it started.
-        const launches = deps.launches ? { feed: deps.launches, ...(actor.kind === "user" ? {} : { by: launchedBy(actor) }) } : undefined
-        return watchStream({
-          registry: deps.watchRegistry?.(user.id) ?? deps.registry,
-          userID: user.id,
-          signal: request.signal,
-          blocked,
-          ...(sessions ? { sessions } : {}),
-          ...(messages ? { messages } : {}),
-          ...(launches ? { launches } : {}),
-          ...(deps.heartbeatMs !== undefined ? { heartbeatMs: deps.heartbeatMs } : {}),
-          ...(deps.now ? { now: deps.now } : {}),
-          ...(deps.draining ? { draining: deps.draining } : {}),
-        })
-      },
-    },
+    ...(deps.events ? [watchRoute(deps, deps.events)] : []),
   ]
 }
+
+/** GET /api/agent/watch: the journal's events live (watch.ts), with the events route's visibility and filters. */
+function watchRoute(deps: ReadDeps, events: EventsRouteDeps): AgentRoute {
+  return {
+    method: "GET",
+    path: `${AGENT_PREFIX}/watch`,
+    allow: READ,
+    handle: ({ user, url, request, actor }) => {
+      const addr = url.searchParams.get("session") || undefined
+      const sessions = addr ? new Set(deps.directory.resolve(user.id, addr).sessions.map((s) => s.sessionID)) : undefined
+      const blocked = ["1", "true"].includes(url.searchParams.get("blocked") ?? "")
+      const cursor = url.searchParams.get("cursor") || request.headers.get("last-event-id") || undefined
+      return watchStream({
+        events,
+        userID: user.id,
+        actor,
+        signal: request.signal,
+        ...(blocked ? { types: ["blocker.*"] } : {}),
+        ...(sessions ? { sessions } : {}),
+        ...(cursor ? { cursor } : {}),
+        ...(deps.heartbeatMs !== undefined ? { heartbeatMs: deps.heartbeatMs } : {}),
+        ...(deps.now ? { now: deps.now } : {}),
+        ...(deps.draining ? { draining: deps.draining } : {}),
+      })
+    },
+  }
+}

package/src/central/agent/routes.ts

@@ -6,6 +6,9 @@
 // requests skip it) → 403 forbidden; credential → 401 unauthorized / token_expired; route → 404 not_found;
 // route class (agentAllows) → 403 forbidden; then the handler, whose throws become the envelope (agentFailure).
 // Path parameters address sessions as `:addr` (resolved per caller), never `:session`.
+import type { AgentEvents } from "./events"
+import type { CursorKeys } from "./event-cursor"
+import { eventsRoutes } from "./events-routes"
 import type { DeviceRecord, Store, UserRecord } from "../store"
 import type { Directory } from "./directory"
 import { directoryRoutes } from "./directory-routes"
@@ -25,7 +28,7 @@ import { type ActingSwitch, actingSwitchRoutes } from "./acting-switch"
 import { Acting, type ActingRegistry, type Escalate } from "./acting"
 import { actingRoutes } from "./acting-routes"
 import type { Actions } from "../actions"
-import { type LaunchFeed, launchRoutes, type RouteLaunches } from "./launch-routes"
+import { launchRoutes, type RouteLaunches } from "./launch-routes"
 import { type RouteWebhooks, webhookRoutes } from "./webhook-routes"
 
 export const AGENT_PREFIX = "/api/agent"
@@ -87,8 +90,10 @@ export interface AgentDeps {
   readonly launches?: RouteLaunches
   /** Webhooks (P4-T10): the /api/agent/webhooks routes when given. */
   readonly webhooks?: RouteWebhooks
-  /** Launch changes: the watch stream's launch events. */
-  readonly launchFeed?: Pick<LaunchFeed, "subscribe">
+  /** The canonical agent event journal: archive changes are appended to it. */
+  readonly agentEvents?: Pick<AgentEvents, "append" | "latest" | "since" | "appended">
+  /** Signing keys of GET /api/agent/events cursors; the events route is served when given with agentEvents. */
+  readonly eventCursorKeys?: CursorKeys
   /** needs_user escalations of the act verbs (P3-T8 opens a Decision); without it needs_user is only answered. */
   readonly escalate?: Escalate
   /** The console's prompt limit, for the user's prompts on the act route. */
@@ -97,8 +102,6 @@ export interface AgentDeps {
   readonly feed?: MessageFeed
   /** Heartbeat of GET /api/agent/watch. */
   readonly heartbeatMs?: number
-  /** What GET /api/agent/watch reads per user (cluster mode); the registry when absent. */
-  readonly watchRegistry?: ReadDeps["watchRegistry"]
   /** Aborted when the hub drains: watch streams end with a `retry:` hint. */
   readonly draining?: AbortSignal
   readonly now?: () => number
@@ -123,9 +126,10 @@ const userView = (user: UserRecord) => ({
 export function agentRoutes(deps: AgentDeps): AgentRoute[] {
   const feed = deps.feed ?? new MessageFeed()
   return [
-    ...(deps.directory ? directoryRoutes(deps.directory) : []),
+    ...(deps.directory ? directoryRoutes({ directory: deps.directory, store: deps.store, ...(deps.agentEvents ? { events: deps.agentEvents } : {}), ...(deps.registry ? { registry: deps.registry } : {}), ...(deps.grants ? { grants: deps.grants } : {}), ...(deps.acting ? { acting: deps.acting } : {}), ...(deps.audit ? { audit: deps.audit } : {}), ...(deps.eventCursorKeys ? { previewKeys: deps.eventCursorKeys } : {}) }) : []),
+    ...(deps.directory && deps.agentEvents && deps.eventCursorKeys ? eventsRoutes({ events: deps.agentEvents, keys: deps.eventCursorKeys, directory: deps.directory }) : []),
     ...(deps.directory && deps.delivery ? messageRoutes({ delivery: deps.delivery, directory: deps.directory, store: deps.store, feed, ...(deps.decisions ? { decisions: deps.decisions } : {}) }) : []),
-    ...(deps.directory && deps.registry ? readRoutes({ store: deps.store, directory: deps.directory, registry: deps.registry, ...(deps.delivery ? { feed } : {}), ...(deps.spokes ? { spokes: deps.spokes } : {}), ...launchReads(deps), ...(deps.watchRegistry ? { watchRegistry: deps.watchRegistry } : {}), ...(deps.heartbeatMs !== undefined ? { heartbeatMs: deps.heartbeatMs } : {}), ...(deps.now ? { now: deps.now } : {}), ...(deps.draining ? { draining: deps.draining } : {}) }) : []),
+    ...(deps.directory && deps.registry ? readRoutes({ store: deps.store, directory: deps.directory, registry: deps.registry, ...(deps.spokes ? { spokes: deps.spokes } : {}), ...launchReads(deps), ...(deps.agentEvents && deps.eventCursorKeys ? { events: { events: deps.agentEvents, keys: deps.eventCursorKeys, directory: deps.directory } } : {}), ...(deps.heartbeatMs !== undefined ? { heartbeatMs: deps.heartbeatMs } : {}), ...(deps.now ? { now: deps.now } : {}), ...(deps.draining ? { draining: deps.draining } : {}) }) : []),
     {
       method: "GET",
       path: `${AGENT_PREFIX}/whoami`,
@@ -144,9 +148,9 @@ export function agentRoutes(deps: AgentDeps): AgentRoute[] {
   ]
 }
 
-/** What the read routes show of launches: launched sessions' labels (the latest launch wins) and launch events. */
-function launchReads(deps: AgentDeps): Pick<ReadDeps, "labels" | "launches"> {
-  const { launches, launchFeed } = deps
+/** What the read routes show of launches: launched sessions' labels (the latest launch wins). */
+function launchReads(deps: AgentDeps): Pick<ReadDeps, "labels"> {
+  const { launches } = deps
   return {
     ...(launches
       ? {
@@ -158,7 +162,6 @@ function launchReads(deps: AgentDeps): Pick<ReadDeps, "labels" | "launches"> {
           },
         }
       : {}),
-    ...(launchFeed ? { launches: launchFeed } : {}),
   }
 }
 

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