@huynle/hub 0.7.1 → 0.7.3

package/src/central/agent/events.ts

@@ -0,0 +1,277 @@
+// The canonical agent event journal (lifecycle design: Events; decision xwzersmm). One bounded journal per user of
+// compact events that GET /api/agent/events, MCP `events` and /api/agent/watch read:
+//
+//   {id: "evt_…", at, type, subject: {sessionID?, rootID?, messageID?, senderID?, launchID?, machineID?}, data}
+//
+// Payloads are built from allowlists here and nowhere else: never prompts, message bodies, titles, blocker
+// summaries, launch reasons or labels, credentials, or connection/pod/spoke IDs. Each record also keeps, for the
+// reader only, its scope family (session, manage, message, launch) and its audience (the parties of a message, who
+// started a launch), so an app or session token sees only what its scopes and identity allow.
+//
+// Storage is an EventLog (a Valkey stream per user in a cluster, process memory otherwise) bounded to
+// AGENT_EVENTS_MAX events and AGENT_EVENTS_AGE_MS. An event id is assigned once, before any cross-pod fan-out;
+// append claims it in the Kv first (SET NX), so appending the same id twice stores it once.
+import { randomBytes } from "node:crypto"
+import type { Clock, EventLog, Kv } from "../backend/types"
+import type { LiveStatus } from "../registry"
+import { partyKey } from "./envelope"
+import type { Launch } from "./launch-store"
+import { addressOf, type Message } from "./messages"
+
+export const AGENT_EVENTS_MAX = 10_000
+export const AGENT_EVENTS_AGE_MS = 86_400_000
+/** Record format version (readers reject others rather than skip them). */
+export const AGENT_EVENT_VERSION = 1
+
+/** The scope family a reader needs: sessions:read, sessions:manage, messages:read, sessions:launch. */
+export type EventFamily = "session" | "manage" | "message" | "launch"
+
+export type EventSubject = Readonly<Record<string, string>>
+export type EventData = Readonly<Record<string, string | number | boolean>>
+
+/** An event as readers receive it. */
+export interface AgentEvent {
+  readonly id: string
+  readonly at: number
+  readonly type: string
+  readonly subject: EventSubject
+  readonly data: EventData
+}
+
+/** Who else may read an event beyond the user: the party keys of a message, who started a launch. */
+export interface EventAudience {
+  readonly parties?: readonly string[]
+  readonly by?: string
+}
+
+/** What a writer appends. */
+export interface EventInput {
+  /** A stable id (assigned before fan-out); a new one when absent. */
+  readonly id?: string
+  readonly type: string
+  readonly family: EventFamily
+  readonly subject: EventSubject
+  readonly data: EventData
+  readonly audience?: EventAudience
+}
+
+/** A journal record: the event, its reader-only scope fields, and its position in the user's log. */
+export interface EventRecord {
+  readonly position: string
+  readonly event: AgentEvent
+  readonly family: EventFamily
+  readonly audience?: EventAudience
+}
+
+/** Records after a position, or `reset` when the journal no longer covers it (expired, trimmed, restarted). */
+export type EventsSince = { readonly records: EventRecord[] } | { readonly reset: true }
+
+const FAMILIES: ReadonlySet<string> = new Set<EventFamily>(["session", "manage", "message", "launch"])
+const EVENT_ID = /^evt_[0-9a-f]{20}$/
+
+export const newEventID = (): string => `evt_${randomBytes(10).toString("hex")}`
+
+export interface AgentEventsOptions {
+  readonly log: EventLog
+  readonly kv: Kv
+  readonly now?: Clock
+  readonly onAppend?: (userID: string, record: Pick<EventRecord, "event" | "family" | "audience">) => void | Promise<void>
+}
+
+export class AgentEvents {
+  private readonly log: EventLog
+  private readonly kv: Kv
+  private readonly now: Clock
+  private readonly onAppend?: AgentEventsOptions["onAppend"]
+  /** Readers waiting for this process's next append, per user (long polling; other pods' appends are rechecked). */
+  private readonly waiters = new Map<string, Set<() => void>>()
+
+  constructor(options: AgentEventsOptions) {
+    this.log = options.log
+    this.kv = options.kv
+    this.now = options.now ?? Date.now
+    this.onAppend = options.onAppend
+  }
+
+  /** Stores an event once per id; returns its id. */
+  async append(userID: string, input: EventInput): Promise<string> {
+    const id = input.id ?? newEventID()
+    if (!EVENT_ID.test(id)) throw new Error("Invalid event id")
+    const claim = `aev:${userID}:${id}`
+    if (!(await this.kv.set(claim, "1", { nx: true, px: AGENT_EVENTS_AGE_MS }))) return id
+    const record = {
+      type: input.type,
+      v: AGENT_EVENT_VERSION,
+      id,
+      at: this.now(),
+      family: input.family,
+      subject: input.subject,
+      data: input.data,
+      ...(input.audience ? { audience: input.audience } : {}),
+    }
+    try {
+      await this.log.append(userID, record)
+    } catch (cause) {
+      // Not stored: a retry with the same id must be able to store it.
+      await this.kv.del(claim).catch(() => {})
+      throw cause
+    }
+    await this.onAppend?.(userID, {
+      event: { id, at: record.at, type: input.type, subject: input.subject, data: input.data },
+      family: input.family,
+      ...(input.audience ? { audience: input.audience } : {}),
+    })
+    const waiting = this.waiters.get(userID)
+    if (waiting) for (const wake of [...waiting]) wake()
+    return id
+  }
+
+  /** Resolves on this process's next append for the user, after `ms`, or when `signal` aborts. */
+  appended(userID: string, ms: number, signal?: AbortSignal): Promise<void> {
+    return new Promise((resolve) => {
+      let set = this.waiters.get(userID)
+      if (!set) this.waiters.set(userID, (set = new Set()))
+      const done = () => {
+        clearTimeout(timer)
+        signal?.removeEventListener("abort", done)
+        set!.delete(done)
+        if (set!.size === 0 && this.waiters.get(userID) === set) this.waiters.delete(userID)
+        resolve()
+      }
+      const timer = setTimeout(done, ms)
+      set.add(done)
+      if (signal?.aborted) done()
+      else signal?.addEventListener("abort", done, { once: true })
+    })
+  }
+
+  /** The position of the user's latest record; a reader holding it gets every later one. */
+  latest(userID: string): Promise<string> {
+    return this.log.latest(userID)
+  }
+
+  async since(userID: string, position: string): Promise<EventsSince> {
+    const result = await this.log.since(userID, position)
+    if ("resync" in result) return { reset: true }
+    const records: EventRecord[] = []
+    for (const logged of result.events) {
+      const m = logged.message as Record<string, unknown>
+      // A record this version cannot read is a reset, never a silent skip.
+      if (m.v !== AGENT_EVENT_VERSION || typeof m.id !== "string" || typeof m.at !== "number" || !FAMILIES.has(m.family as string)) return { reset: true }
+      records.push({
+        position: logged.id,
+        event: { id: m.id, at: m.at, type: String(m.type), subject: (m.subject ?? {}) as EventSubject, data: (m.data ?? {}) as EventData },
+        family: m.family as EventFamily,
+        ...(m.audience ? { audience: m.audience as EventAudience } : {}),
+      })
+    }
+    return { records }
+  }
+}
+
+// ---- Compact builders (allowlists) ------------------------------------------------------------------------
+
+/** A stored agent message changed (sent, delivered, answered…): never its text. */
+export function messageEvent(message: Message): EventInput {
+  const { id, kind, state, from, recipient, replyTo, delivery } = message
+  return {
+    type: "message.changed",
+    family: "message",
+    subject: {
+      messageID: id,
+      ...(recipient.kind === "session" ? { sessionID: recipient.sessionID } : {}),
+      ...(from.kind === "session" ? { senderID: from.sessionID } : {}),
+    },
+    data: { kind, state, from: addressOf(from), to: message.to, ...(replyTo ? { replyTo } : {}), ...(delivery ? { delivery } : {}) },
+    audience: { parties: [partyKey(from), partyKey(recipient)] },
+  }
+}
+
+/** A launch changed: never its prompt, reason or labels. */
+export function launchEvent(launch: Launch): EventInput {
+  return {
+    type: "launch.changed",
+    family: "launch",
+    subject: { launchID: launch.id, ...(launch.sessionID !== undefined ? { sessionID: launch.sessionID } : {}) },
+    data: { state: launch.state, ...(launch.outcome !== undefined ? { outcome: launch.outcome } : {}), ...(launch.name !== undefined ? { name: launch.name } : {}) },
+    ...(launch.by !== undefined ? { audience: { by: launch.by } } : {}),
+  }
+}
+
+/** A session's archive state changed. */
+export const archiveEvent = (sessionID: string, archived: boolean): EventInput => ({ type: "session.archived", family: "manage", subject: { sessionID }, data: { archived } })
+
+export const pinnedEvent = (sessionID: string, pinned: boolean): EventInput => ({ type: "session.pinned", family: "manage", subject: { sessionID }, data: { pinned } })
+
+/** A session was explicitly named (names are validated slugs: a-z, 0-9 and -). */
+export const namedEvent = (sessionID: string, name: string): EventInput => ({ type: "session.named", family: "manage", subject: { sessionID }, data: { name } })
+
+/** A session claimed (held) or released a role; role and project are validated slugs. */
+export function roleEvent(sessionID: string, held: boolean, role: { role: string; project?: string; generation?: number; exclusive?: boolean }): EventInput {
+  return {
+    type: held ? "role.claimed" : "role.released",
+    family: "manage",
+    subject: { sessionID },
+    data: {
+      role: role.role,
+      ...(role.project !== undefined ? { project: role.project } : {}),
+      ...(held && role.generation !== undefined ? { generation: role.generation } : {}),
+      ...(held && role.exclusive ? { exclusive: true } : {}),
+    },
+  }
+}
+
+interface Known {
+  state: string
+  blockers: Set<string>
+}
+
+/**
+ * State and blocker changes of status trees, against what was seen before (one per writer). Bounded by the live
+ * trees: a tree's entry is replaced by each status of it and dropped by forget().
+ */
+export class StatusDiff {
+  private readonly trees = new Map<string, Map<string, Known>>()
+
+  events(rootID: string, sessions: readonly LiveStatus[]): EventInput[] {
+    const before = this.trees.get(rootID) ?? new Map<string, Known>()
+    const after = new Map<string, Known>()
+    const out: EventInput[] = []
+    for (const entry of sessions) {
+      const known = before.get(entry.id)
+      const subject = { sessionID: entry.id, rootID }
+      const open = new Set(entry.blockers.map((b) => b.id))
+      for (const b of entry.blockers) if (!known?.blockers.has(b.id)) out.push({ type: "blocker.opened", family: "session", subject, data: { blockerID: b.id, kind: b.kind } })
+      for (const id of known?.blockers ?? []) if (!open.has(id)) out.push({ type: "blocker.closed", family: "session", subject, data: { blockerID: id } })
+      if (known?.state !== entry.state) out.push({ type: "session.changed", family: "session", subject, data: { state: entry.state, ...(known ? { prev: known.state } : {}) } })
+      after.set(entry.id, { state: entry.state, blockers: open })
+    }
+    this.trees.set(rootID, after)
+    return out
+  }
+
+  /** Drops a tree that is gone. */
+  forget(rootID: string): void {
+    this.trees.delete(rootID)
+  }
+
+  roots(): string[] {
+    return [...this.trees.keys()]
+  }
+}
+
+/** Presence per user (sessions and machines) diffed against the previous view (the catalog writer's). */
+export interface PresenceView {
+  readonly sessions: ReadonlySet<string>
+  /** Machine id → name, for the machines with a connected process. */
+  readonly machines: ReadonlyMap<string, string>
+}
+
+export function presenceEvents(before: PresenceView, after: PresenceView): EventInput[] {
+  const out: EventInput[] = []
+  for (const id of after.sessions) if (!before.sessions.has(id)) out.push({ type: "session.added", family: "session", subject: { sessionID: id }, data: {} })
+  for (const id of before.sessions) if (!after.sessions.has(id)) out.push({ type: "session.removed", family: "session", subject: { sessionID: id }, data: {} })
+  for (const [id, name] of after.machines) if (!before.machines.has(id)) out.push({ type: "machine.changed", family: "session", subject: { machineID: id }, data: { name, online: true } })
+  for (const [id, name] of before.machines) if (!after.machines.has(id)) out.push({ type: "machine.changed", family: "session", subject: { machineID: id }, data: { name, online: false } })
+  return out
+}

package/src/central/agent/names.ts

@@ -43,7 +43,7 @@ export function withSuffix(base: string, taken: (name: string) => boolean): stri
 export const isReservedName = (name: string): boolean => name === "me"
 
 /** Roles only the user may claim in phase 1 (grants including `roles` come in phase 3). */
-const RESERVED_ROLES = ["orchestrator", "concierge"]
+const RESERVED_ROLES = ["orchestrator"]
 
 export const isReservedRole = (role: string): boolean => RESERVED_ROLES.some((prefix) => role.startsWith(prefix))
 

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 } : {}),
   }
 }