@huynle/hub 0.7.4 → 0.8.1

package/src/central/agent/interaction-graph-routes.ts

@@ -0,0 +1,212 @@
+// The Watchtower's read API (HWA-31) over interaction-graph.ts, and the adapters that feed it from the hub's
+// stores (one scan per source per request; no per-edge reads):
+//
+//   GET /api/agent/graph?since=&until=&machine=&harness=&team=&tag=&project=&session=&workspace=&kind=&state=&limit=
+//   GET /api/agent/graph/edges/:id?since=&until=&cursor=&limit=   message summaries of one edge (no text)
+//   GET /api/agent/graph/nodes/:id?since=&until=&cursor=&limit=   message summaries of one node (no text)
+//
+// Users always; session tokens; app tokens with sessions:read (the route class) and messages:read (viewerOf).
+// Full text stays behind GET /api/agent/messages/:id.
+import { LIST_LIMIT_MAX } from "../../protocol"
+import type { Store } from "../store"
+import type { TeamStore } from "../teams/store"
+import type { TeamSeatStore } from "../teams/seats"
+import type { MembershipStore } from "../workspaces/members"
+import type { WorkspaceStore } from "../workspaces/store"
+import type { SupervisionStore } from "../workspaces/supervision"
+import type { AgentAudit } from "./audit"
+import { AUDIT_PAGE_MAX } from "./audit"
+import type { Decisions } from "./decisions"
+import type { Directory } from "./directory"
+import { buildGraph, edgeDetail, type GraphDenial, type GraphLaunch, type GraphMembership, type GraphSeat, type GraphSources, type GraphTeam, nodeDetail, parseGraphQuery, viewerOf } from "./interaction-graph"
+import type { Messages } from "./messages"
+import type { ReadRegistry } from "./read-routes"
+import { AGENT_PREFIX, type AgentRoute } from "./routes"
+
+/** Pages read from a paged store list before giving up (bounded: the stores cap their records). */
+const PAGES_MAX = 50
+
+export interface GraphRouteDeps {
+  readonly store: Pick<Store, "machines" | "agentData">
+  readonly registry: Pick<ReadRegistry, "catalog" | "sessionTenant">
+  readonly directory: Pick<Directory, "who">
+  readonly messages: Pick<Messages, "all" | "retention">
+  readonly decisions?: Pick<Decisions, "list">
+  readonly launches?: { list(userID: string): Promise<readonly GraphLaunch[]> }
+  readonly teams?: { readonly teams: Pick<TeamStore, "list">; readonly seats: Pick<TeamSeatStore, "list"> }
+  readonly workspaces?: { readonly workspaces: Pick<WorkspaceStore, "list">; readonly members: Pick<MembershipStore, "members">; readonly supervision: Pick<SupervisionStore, "graph"> }
+  readonly audit?: Pick<AgentAudit, "list">
+  readonly now?: () => number
+  /** (CON-04) The user's Concierge sessions: their nodes carry `concierge: true`. */
+  readonly concierge?: (userID: string) => Promise<readonly string[]>
+  /** (CON-09a) The user's current Concierge session: labelled @@concierge; the others "@@concierge (previous)", ended. */
+  readonly conciergeCurrent?: (userID: string) => Promise<string | undefined>
+}
+
+interface ConciergeMarks {
+  readonly node: <N extends { id: string; kind: string }>(node: N) => N
+  /** (CON-10) Previous (retired) Concierge sessions: ended for good. */
+  readonly previous: ReadonlySet<string>
+}
+
+/** Moves undelivered counts (pending, queued) to "dropped": they never reach an ended session. */
+function dropUndelivered<D extends Partial<Record<string, number>>>(delivery: D | undefined): D | undefined {
+  if (!delivery) return delivery
+  const { pending = 0, queued = 0, ...rest } = delivery as Record<string, number>
+  const dropped = (rest.dropped ?? 0) + pending + queued
+  return (dropped ? { ...rest, dropped } : rest) as unknown as D
+}
+
+/**
+ * (CON-09a) How Watchtower shows a Concierge session: no auto @name, previous ones ended (not idle sessions).
+ * (CON-10) An ended one has no "last seen" (its spoke may still report it) and is not online, and messages to it
+ * that never reached it (queued, pending) are dropped, never waiting.
+ */
+async function conciergeMarker(deps: GraphRouteDeps, userID: string): Promise<ConciergeMarks> {
+  const concierge = new Set(deps.concierge ? await deps.concierge(userID) : [])
+  if (!concierge.size) return { node: (node) => node, previous: new Set() }
+  const current = deps.conciergeCurrent ? await deps.conciergeCurrent(userID) : undefined
+  const previous = new Set(deps.conciergeCurrent === undefined ? [] : [...concierge].filter((id) => id !== current))
+  return {
+    previous,
+    node: (node) => {
+      if (node.kind !== "session" || !concierge.has(node.id)) return node
+      if (deps.conciergeCurrent === undefined) return { ...node, concierge: true as const }
+      if (node.id === current) return { ...node, concierge: true as const, label: "@@concierge" }
+      const { lastSeen: _lastSeen, ...rest } = node as typeof node & { lastSeen?: number }
+      return { ...rest, concierge: true as const, label: "@@concierge (previous)", status: "ended", online: false } as unknown as typeof node
+    },
+  }
+}
+
+/** (CON-10) Edges into an ended Concierge session: their undelivered messages are dropped. */
+const markEdge = (previous: ReadonlySet<string>) => <E extends { to: string; delivery?: Partial<Record<string, number>> }>(edge: E): E =>
+  previous.has(edge.to) && edge.delivery ? { ...edge, delivery: dropUndelivered(edge.delivery) } : edge
+
+/** (CON-10) A message to an ended Concierge session that never reached it reads "dropped". */
+const markMessage = (previous: ReadonlySet<string>) => <M extends { to: string; delivery?: string }>(m: M): M =>
+  previous.has(m.to) && (m.delivery === "pending" || m.delivery === "queued") ? { ...m, delivery: "dropped" } : m
+
+/** Every page of a cursor-paged list. */
+async function allPages<T>(list: (cursor?: string) => Promise<{ readonly items: readonly T[]; readonly cursor?: string }>): Promise<T[]> {
+  const out: T[] = []
+  let cursor: string | undefined
+  for (let i = 0; i < PAGES_MAX; i++) {
+    const page = await list(cursor)
+    out.push(...page.items)
+    if (!page.cursor) break
+    cursor = page.cursor
+  }
+  return out
+}
+
+/** The projection's sources over the hub's stores. */
+export function graphSources(deps: GraphRouteDeps): GraphSources {
+  const { teams, workspaces, audit, launches } = deps
+  return {
+    now: deps.now ?? Date.now,
+    machines: (userID) => deps.store.machines().filter((m) => !m.revoked && m.ownerID === userID),
+    registry: deps.registry,
+    sessions: (userID) => deps.store.agentData(userID).sessions ?? [],
+    directory: deps.directory,
+    messages: deps.messages,
+    ...(deps.decisions ? { decisions: deps.decisions } : {}),
+    ...(launches ? { launches: (userID: string) => launches.list(userID) } : {}),
+    ...(teams
+      ? {
+          teams: async (userID: string) => {
+            const list = (await allPages((cursor) => teams.teams.list(userID, { state: "active", limit: LIST_LIMIT_MAX, ...(cursor ? { cursor } : {}) }))) as GraphTeam[]
+            const seats: GraphSeat[] = []
+            for (const team of list) {
+              try {
+                for (const seat of await teams.seats.list(userID, team.id, { current: true })) seats.push({ teamID: seat.teamID, role: seat.role, sessionID: seat.sessionID })
+              } catch {
+                // A team this build cannot read shows without seats.
+              }
+            }
+            return { teams: list, seats }
+          },
+        }
+      : {}),
+    ...(workspaces
+      ? {
+          supervision: async (userID: string) => {
+            const out: GraphMembership[] = []
+            for (const workspace of await allPages((cursor) => workspaces.workspaces.list(userID, { state: "active", limit: LIST_LIMIT_MAX, ...(cursor ? { cursor } : {}) }))) {
+              const [members, graph] = await Promise.all([workspaces.members.members(userID, workspace.id), workspaces.supervision.graph(userID, workspace.id)])
+              const sessionOf = new Map(members.filter((m) => m.current).map((m) => [m.member.id, m.member.sessionID]))
+              const supervisorOf = new Map<string, string>()
+              for (const { link, member, supervisor } of graph.links) {
+                const sessionID = sessionOf.get(link.supervisorMemberID)
+                if (member === "current" && supervisor === "current" && sessionID !== undefined) supervisorOf.set(link.memberID, sessionID)
+              }
+              for (const [memberID, sessionID] of sessionOf) {
+                const supervisorSessionID = supervisorOf.get(memberID)
+                out.push({ workspaceID: workspace.id, sessionID, ...(supervisorSessionID !== undefined ? { supervisorSessionID } : {}) })
+              }
+            }
+            return out
+          },
+        }
+      : {}),
+    ...(audit
+      ? {
+          denials: async (userID: string) => {
+            const out: GraphDenial[] = []
+            let before: number | undefined
+            for (let i = 0; i < PAGES_MAX; i++) {
+              const page = await audit.list(userID, { limit: AUDIT_PAGE_MAX, ...(before !== undefined ? { before } : {}) })
+              for (const entry of page.entries) {
+                if (entry.verb !== "team.denied" || entry.actor.kind !== "session") continue
+                out.push({ at: entry.at, senderID: entry.actor.sessionID, ...(entry.target.sessionID !== undefined ? { recipientID: entry.target.sessionID } : {}) })
+              }
+              if (page.next === undefined) break
+              before = page.next
+            }
+            return out
+          },
+        }
+      : {}),
+  }
+}
+
+const NO_STORE = { "cache-control": "no-store" }
+const ok = (body: unknown) => Response.json(body, { headers: NO_STORE })
+const READ = { session: true, scope: "sessions:read" } as const
+
+export function graphRoutes(deps: GraphRouteDeps): AgentRoute[] {
+  const sources = graphSources(deps)
+  return [
+    {
+      method: "GET",
+      path: `${AGENT_PREFIX}/graph`,
+      allow: READ,
+      handle: async ({ user, actor, url }) => {
+        const viewer = viewerOf(actor)
+        const graph = await buildGraph(sources, user.id, viewer, parseGraphQuery(url.searchParams, sources.now()))
+        const mark = await conciergeMarker(deps, user.id)
+        return ok({ ...graph, nodes: graph.nodes.map(mark.node), edges: graph.edges.map(markEdge(mark.previous)) })
+      },
+    },
+    {
+      method: "GET",
+      path: `${AGENT_PREFIX}/graph/edges/:id`,
+      allow: READ,
+      handle: async ({ user, actor, url, params }) => {
+        const detail = await edgeDetail(sources, user.id, viewerOf(actor), params.id!, url.searchParams, sources.now())
+        const { previous } = await conciergeMarker(deps, user.id)
+        return ok({ ...detail, edge: markEdge(previous)(detail.edge), messages: detail.messages.map(markMessage(previous)) })
+      },
+    },
+    {
+      method: "GET",
+      path: `${AGENT_PREFIX}/graph/nodes/:id`,
+      allow: READ,
+      handle: async ({ user, actor, url, params }) => {
+        const detail = await nodeDetail(sources, user.id, viewerOf(actor), params.id!, url.searchParams, sources.now())
+        const mark = await conciergeMarker(deps, user.id)
+        return ok({ ...detail, node: mark.node(detail.node), messages: detail.messages.map(markMessage(mark.previous)) })
+      },
+    },
+  ]
+}