@huynle/hub 0.7.4 → 0.8.0

package/src/central/agent/routes.ts

@@ -8,7 +8,7 @@
 // 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 { eventsRoutes, type EventsRouteDeps } from "./events-routes"
 import type { DeviceRecord, Store, UserRecord } from "../store"
 import type { Directory } from "./directory"
 import { directoryRoutes } from "./directory-routes"
@@ -30,6 +30,36 @@ import { actingRoutes } from "./acting-routes"
 import type { Actions } from "../actions"
 import { launchRoutes, type RouteLaunches } from "./launch-routes"
 import { type RouteWebhooks, webhookRoutes } from "./webhook-routes"
+import { pinAuthorizer } from "../profiles/apply"
+import { profileRoutes } from "../profiles/routes"
+import { ProfileUsage } from "../profiles/usage"
+import { usagePorts } from "../profiles/usage-ports"
+import type { ProfileStore } from "../profiles/store"
+import { workspaceRoutes, type WorkspaceRoutesDeps } from "../workspaces/routes"
+import { boardRoutes, registryBoardSessions } from "../workspaces/board"
+import { type CheckpointStore, checkpointRoutes } from "../workspaces/checkpoints"
+import { masterRoutes } from "../workspaces/master"
+import { routePorts, sideChatRoutes } from "../workspaces/sidechats-routes"
+import { type ArtifactRouteDeps, artifactRoutes } from "../artifacts/routes"
+import { artifactJobRoutes, jobPorts } from "../artifacts/jobs-routes"
+import { type ArtifactHostRouteDeps, artifactHostRoutes } from "../artifacts/host"
+import { type GraphRouteDeps, graphRoutes } from "./interaction-graph-routes"
+import type { TeamIntakeService } from "../teams/intake"
+import { intakeRoutes } from "../teams/intake-routes"
+import { eventVisibility, type TeamDiscovery } from "../teams/discovery"
+import { teamRoutes, type TeamRoutesDeps } from "../teams/routes"
+import type { StateStore } from "../backend/types"
+import type { ActivityTracker } from "../concierge/activity"
+import { boardRoutes as conciergeBoardRoutes } from "../concierge/board-routes"
+import type { ResultTracker } from "../concierge/board-results"
+import { type ConciergeIdentity, watchlistRoutes } from "../concierge/watchlist-routes"
+import { conciergeRoutes } from "../concierge/routes"
+import { guardConciergeRoutes } from "../concierge/guard"
+import { isConciergeLaunch } from "../concierge/supervisor"
+import type { ConciergeService } from "../concierge/service"
+import type { SessionIntent } from "../../protocol"
+import type { SessionIntents } from "./intents"
+import { intentRoutes } from "./intent-routes"
 
 export const AGENT_PREFIX = "/api/agent"
 
@@ -90,6 +120,22 @@ export interface AgentDeps {
   readonly launches?: RouteLaunches
   /** Webhooks (P4-T10): the /api/agent/webhooks routes when given. */
   readonly webhooks?: RouteWebhooks
+  /** Profiles (HWA-14): the /api/agent/profiles and /sessions/:addr/profile routes when given with the directory. */
+  readonly profiles?: ProfileStore
+  /** Workspaces (HWA-06): the /api/agent/workspaces routes when given. */
+  readonly workspaces?: Pick<WorkspaceRoutesDeps, "workspaces" | "members" | "supervision" | "lifecycle">
+  /** Supervisor checkpoints (HWA-11): POST/GET /api/agent/workspaces/:id/checkpoints when given. */
+  readonly workspaceCheckpoints?: CheckpointStore
+  /** Team intake (HWA-36): /api/agent/teams/:id/intake when given. */
+  readonly teamIntake?: TeamIntakeService
+  /** Teams (HWA-37): /api/agent/teams definitions, staffing and status when given (the hub's single instances). */
+  readonly teams?: Pick<TeamRoutesDeps, "teams" | "seats" | "staffing">
+  /** Persistent artifacts (HWA-21): /api/agent/artifacts; without a store the routes answer 422 unsupported. */
+  readonly artifacts?: ArtifactRouteDeps
+  /** Isolated artifact host (HWA-26): mint/revoke capability URLs for html/app revisions when given. */
+  readonly artifactHost?: ArtifactHostRouteDeps
+  /** Interaction graph (HWA-31) team overlay; the graph routes are added with the directory, registry and delivery. */
+  readonly graph?: Pick<GraphRouteDeps, "teams">
   /** 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. */
@@ -105,6 +151,32 @@ export interface AgentDeps {
   /** Aborted when the hub drains: watch streams end with a `retry:` hint. */
   readonly draining?: AbortSignal
   readonly now?: () => number
+  /** Team-aware discovery (HWA-40): who and the read routes scope team members to their teams. */
+  readonly teamDiscovery?: TeamDiscovery
+  /**
+   * Concierge (CON-01): the /api/agent/concierge/watchlist routes when given with the directory and registry.
+   * `identity` is the user's current Concierge session (CON-04); without it no session token is admitted.
+   */
+  readonly concierge?: {
+    readonly state: StateStore
+    readonly activity: Pick<ActivityTracker, "list">
+    readonly identity?: ConciergeIdentity
+    readonly results?: Pick<ResultTracker, "many">
+    /** (CON-04) Sessions only the user acts on (the Concierge's): the act verbs refuse agents on them. */
+    readonly protects?: (userID: string, sessionID: string) => Promise<boolean>
+    /** (CON-04) The Concierge service: /api/agent/concierge settings, enable/disable/restart and notes. */
+    readonly service?: ConciergeService
+    /** (CON-06 and later) More Concierge routes (the tiers slot). */
+    readonly routes?: () => AgentRoute[]
+    /** (CON-06) The Decision armed now by the current Concierge (the board's `armed` flag). */
+    readonly armed?: (userID: string) => Promise<string | undefined>
+    /** (CON-10) The user's time zone (Concierge settings): the rendered board's time is local. */
+    readonly timeZone?: (userID: string) => Promise<string | undefined>
+    /** (CON-13) The board's inGrant (board-routes.ts BoardRouteDeps.coverage). */
+    readonly coverage?: (userID: string, conciergeSessionID: string, sessionID: string, requestID: string) => Promise<{ readonly inGrant: boolean; readonly auto: boolean }>
+  }
+  /** (CON-02) Session intents: GET/PUT /api/agent/sessions/:addr/intent with the directory; reads carry `intent`. */
+  readonly intents?: SessionIntents
 }
 
 /**
@@ -125,11 +197,12 @@ const userView = (user: UserRecord) => ({
 /** The built-in /api/agent routes. */
 export function agentRoutes(deps: AgentDeps): AgentRoute[] {
   const feed = deps.feed ?? new MessageFeed()
-  return [
-    ...(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 }) : []),
+  const routes: AgentRoute[] = [
+    ...(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.teamDiscovery ? { discovery: deps.teamDiscovery } : {}), ...intentReads(deps), ...conciergeReads(deps) }) : []),
+    ...(deps.directory && deps.intents ? intentRoutes({ intents: deps.intents, directory: deps.directory, store: deps.store, ...(deps.registry ? { registry: deps.registry } : {}), ...(deps.teamDiscovery ? { discovery: deps.teamDiscovery } : {}) }) : []),
+    ...(deps.directory && deps.agentEvents && deps.eventCursorKeys ? eventsRoutes({ events: deps.agentEvents, keys: deps.eventCursorKeys, directory: deps.directory, ...eventScope(deps) }) : []),
     ...(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.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 } : {}) }) : []),
+    ...(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, ...eventScope(deps) } } : {}), ...(deps.heartbeatMs !== undefined ? { heartbeatMs: deps.heartbeatMs } : {}), ...(deps.now ? { now: deps.now } : {}), ...(deps.draining ? { draining: deps.draining } : {}), ...(deps.teamDiscovery ? { discovery: deps.teamDiscovery } : {}), ...intentReads(deps), ...conciergeReads(deps) }) : []),
     {
       method: "GET",
       path: `${AGENT_PREFIX}/whoami`,
@@ -145,7 +218,83 @@ export function agentRoutes(deps: AgentDeps): AgentRoute[] {
       ? launchRoutes({ launches: deps.launches, grants: deps.grants, acting: deps.acting, audit: deps.audit, ...(deps.directory ? { directory: deps.directory } : {}) })
       : []),
     ...(deps.webhooks ? webhookRoutes(deps.webhooks, deps.store) : []),
+    ...(deps.profiles && deps.directory
+      ? profileRoutes({
+          profiles: deps.profiles,
+          directory: deps.directory,
+          audit: deps.store,
+          ...(deps.agentEvents ? { events: deps.agentEvents } : {}),
+          // HWA-15: an app's pin also needs a usable prompt grant on the session.
+          ...(deps.grants && deps.registry ? { authorizePin: pinAuthorizer({ registry: deps.registry, grants: deps.grants, ...(deps.acting ? { acting: deps.acting } : {}) }) } : {}),
+          // RP-08: where a profile is used (pins, team roles, launches, workspaces).
+          usage: new ProfileUsage({
+            profiles: deps.profiles,
+            ports: usagePorts({
+              directory: deps.directory,
+              ...(deps.registry ? { registry: deps.registry } : {}),
+              ...(deps.teams ? { teams: { teams: deps.teams.teams, seats: deps.teams.seats } } : {}),
+              ...(deps.launches ? { launches: deps.launches } : {}),
+              ...(deps.workspaces ? { workspaces: { workspaces: deps.workspaces.workspaces, members: deps.workspaces.members } } : {}),
+            }),
+          }),
+        })
+      : []),
+    ...(deps.workspaces ? workspaceRoutes({ ...deps.workspaces, audit: deps.store, ...(deps.agentEvents ? { events: deps.agentEvents } : {}) }) : []),
+    ...(deps.workspaces ? boardRoutes({ ...deps.workspaces, ...(deps.directory && deps.registry ? { sessions: registryBoardSessions(deps.directory, deps.registry) } : {}), ...(deps.decisions ? { decisions: deps.decisions } : {}), ...(deps.artifacts?.artifacts ? { artifacts: deps.artifacts.artifacts } : {}), ...(deps.now ? { now: deps.now } : {}) }) : []),
+    ...(deps.workspaceCheckpoints ? checkpointRoutes({ checkpoints: deps.workspaceCheckpoints, audit: deps.store }) : []),
+    ...(deps.workspaces ? masterRoutes({ ...deps.workspaces, audit: deps.store, ...(deps.workspaceCheckpoints ? { checkpoints: deps.workspaceCheckpoints } : {}), ...(deps.launches ? { launches: deps.launches } : {}), ...(deps.agentEvents ? { events: deps.agentEvents } : {}), ...(deps.now ? { now: deps.now } : {}) }) : []),
+    ...artifactRoutes(deps.artifacts ?? {}),
+    ...(deps.artifactHost ? artifactHostRoutes(deps.artifactHost) : []),
+    ...(deps.directory && deps.registry && deps.delivery ? graphRoutes({ store: deps.store, registry: deps.registry, directory: deps.directory, messages: deps.delivery.messages, ...(deps.decisions ? { decisions: deps.decisions } : {}), ...(deps.launches ? { launches: deps.launches } : {}), ...(deps.workspaces ? { workspaces: deps.workspaces } : {}), ...(deps.audit ? { audit: deps.audit } : {}), ...deps.graph, ...(deps.now ? { now: deps.now } : {}), ...conciergeReads(deps), ...conciergeCurrent(deps) }) : []),
+    ...(deps.teamIntake ? intakeRoutes({ intake: deps.teamIntake, audit: deps.store }) : []),
+    ...(deps.teams ? teamRoutes({ ...deps.teams, ...(deps.teamIntake ? { intake: deps.teamIntake } : {}), audit: deps.store, ...(deps.agentEvents ? { events: deps.agentEvents } : {}) }) : []),
+    ...(deps.concierge && deps.directory && deps.registry
+      ? watchlistRoutes({ ...deps.concierge, directory: deps.directory, store: deps.store, registry: deps.registry, ...(deps.decisions ? { decisions: deps.decisions } : {}), ...launchReads(deps), ...(deps.agentEvents ? { events: deps.agentEvents } : {}), ...(deps.now ? { now: deps.now } : {}) })
+      : []),
+    // CON-03: the situation board and the Concierge's Decision reads (users and the current Concierge only).
+    ...(deps.concierge && deps.directory && deps.registry
+      ? conciergeBoardRoutes({ ...deps.concierge, directory: deps.directory, store: deps.store, registry: deps.registry, ...(deps.decisions ? { decisions: deps.decisions } : {}), ...(deps.intents ? { intents: deps.intents } : {}), ...launchReads(deps), ...(deps.now ? { now: deps.now } : {}) })
+      : []),
+    // CON-04: settings, enable/disable/restart and notes; CON-06's routes through the tiers slot.
+    ...(deps.concierge?.service && deps.concierge.identity ? conciergeRoutes({ service: deps.concierge.service, identity: deps.concierge.identity }) : []),
+    ...(deps.concierge?.routes ? deps.concierge.routes() : []),
   ]
+  // HWA-13: side chats read, launch and message through the routes above, as the caller.
+  const { registry } = deps
+  const sourceUpdatedAt = registry ? (userID: string, id: string) => (registry.sessionTenant(id) === userID ? registry.session(id)?.updated : undefined) : undefined
+  // HWA-24: artifact AI jobs start their handler through the launch and message routes above, as the requester.
+  const a = deps.artifacts
+  routes.push(...artifactJobRoutes({ ...(a?.artifacts ? { artifacts: a.artifacts } : {}), ...(a?.state ? { state: a.state } : {}), ports: jobPorts(routes), ...(deps.launches ? { launches: deps.launches } : {}), audit: deps.store, ...(deps.agentEvents ? { events: deps.agentEvents } : {}), ...(deps.now ? { now: deps.now } : {}) }))
+  const all = deps.workspaces ? [...routes, ...sideChatRoutes({ workspaces: deps.workspaces.workspaces, ports: routePorts(routes), ...(deps.launches ? { launches: deps.launches } : {}), ...(sourceUpdatedAt ? { sourceUpdatedAt } : {}), audit: deps.store, ...(deps.agentEvents ? { events: deps.agentEvents } : {}), ...(deps.now ? { now: deps.now } : {}) })] : routes
+  // CON-04: manage paths never touch a Concierge session (concierge/guard.ts).
+  const identity = deps.concierge?.identity
+  const directory = deps.directory
+  const launches = deps.launches
+  return identity && directory
+    ? guardConciergeRoutes(all, {
+        identity,
+        resolve: (userID, addr) => directory.resolve(userID, addr).sessions.map((s) => s.sessionID),
+        ...(launches
+          ? {
+              launch: async (userID: string, id: string) => {
+                const l = await launches.view(userID, id)
+                return l ? { ...(l.sessionID !== undefined ? { sessionID: l.sessionID } : {}), concierge: isConciergeLaunch(l) } : undefined
+              },
+            }
+          : {}),
+      })
+    : all
+}
+
+/** HWA-28/40: unfiltered events and watch read by a team-scoped session leave out what discovery hides from it. */
+function eventScope(deps: AgentDeps): Pick<EventsRouteDeps, "scope" | "resolve"> {
+  const discovery = deps.teamDiscovery
+  return discovery
+    ? {
+        scope: async (userID, actor) => eventVisibility(await discovery.census(userID, actor)),
+        resolve: async (userID, actor, addr) => discovery.resolve(await discovery.census(userID, actor), addr).sessions.map((s) => s.sessionID),
+      }
+    : {}
 }
 
 /** What the read routes show of launches: launched sessions' labels (the latest launch wins). */
@@ -165,6 +314,24 @@ function launchReads(deps: AgentDeps): Pick<ReadDeps, "labels"> {
   }
 }
 
+/** (CON-04) Which sessions reads mark `concierge: true` (the user's current and hidden Concierge sessions). */
+function conciergeReads(deps: AgentDeps): { concierge?: (userID: string) => Promise<readonly string[]> } {
+  const identity = deps.concierge?.identity
+  return identity ? { concierge: async (userID: string) => (await identity.current(userID)).hiddenSessionIDs } : {}
+}
+
+/** (CON-09a) The user's current Concierge session (Watchtower labels it @@concierge). */
+function conciergeCurrent(deps: AgentDeps): { conciergeCurrent?: (userID: string) => Promise<string | undefined> } {
+  const identity = deps.concierge?.identity
+  return identity ? { conciergeCurrent: async (userID: string) => (await identity.current(userID)).sessionID } : {}
+}
+
+/** (CON-02) What reads show of intents: the stored ones of the listed sessions, by session. */
+function intentReads(deps: AgentDeps): { intents?: (userID: string, sessionIDs: readonly string[]) => Promise<Map<string, SessionIntent>> } {
+  const { intents } = deps
+  return intents ? { intents: (userID: string, sessionIDs: readonly string[]) => intents.many(userID, sessionIDs) } : {}
+}
+
 /** The act verbs, when every part they need is given. */
 function actVerbRoutes(deps: AgentDeps): AgentRoute[] {
   const { actions, acting, grants, audit, registry, directory, spokes } = deps
@@ -180,6 +347,7 @@ function actVerbRoutes(deps: AgentDeps): AgentRoute[] {
       audit,
       ...(deps.escalate ? { escalate: deps.escalate } : {}),
       ...(deps.maxPromptChars !== undefined ? { maxPromptChars: deps.maxPromptChars } : {}),
+      ...(deps.concierge?.protects ? { protect: deps.concierge.protects, conciergeActor: deps.concierge.protects } : {}),
     }),
   )
 }
@@ -192,6 +360,8 @@ export interface AgentApiOptions {
   /** Records activity of a resolved caller (device and user lastSeen). */
   touch?(user: UserRecord, device?: DeviceRecord): void
   readonly routes: readonly AgentRoute[]
+  /** Runs for every resolved caller before the route class check (CON-04: the Concierge's route allow-list). */
+  gate?(actor: AgentActor, route: AgentRoute): Promise<void>
 }
 
 export interface AgentApi {
@@ -250,6 +420,7 @@ export function agentApi(options: AgentApiOptions): AgentApi {
       options.touch?.(resolved.user, resolved.device)
       const found = find(method, url.pathname)
       if (!found) throw new AgentError("not_found", "Not found")
+      if (options.gate) await options.gate(resolved.actor, found.route)
       if (!agentAllows(found.route.allow, resolved.actor)) throw new AgentError("forbidden", "This credential cannot use this route")
       const { actor, credential, user, device } = resolved
       return await found.route.handle({ request, url, params: found.params, actor, credential, user, ...(device ? { device } : {}) })

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

@@ -9,6 +9,7 @@
 // scope of the only events so far, launch.*), which see and delete only the registrations they made and get only
 // the events of launches they started. Sessions cannot register webhooks. Another user's registration, or (apps)
 // one the token did not make, is 404 not_found.
+import { boundedJson } from "./body"
 import type { Store } from "../store"
 import type { AgentActor } from "./actor"
 import { AgentError } from "./errors"
@@ -37,7 +38,7 @@ const requireEventScopes = (actor: AgentActor, events: unknown) => {
 }
 
 async function bodyOf(request: Request): Promise<Record<string, unknown>> {
-  const raw = JSON.parse(await request.text()) as unknown
+  const raw = (await boundedJson(request)) as unknown
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new AgentError("invalid", "Body must be a JSON object")
   return raw as Record<string, unknown>
 }

package/src/central/agent-data.ts

@@ -38,6 +38,8 @@ export interface AgentSession {
   /** Project name (lowercased) used by `.project` scopes. */
   project?: string
   title?: string
+  /** The last harness kind a spoke reported it under (offline sessions keep their glyph, RF-02). */
+  harness?: string
   firstSeen?: number
   /** Last time a spoke reported it (ms; persisted at minute granularity while it stays online). */
   lastSeen?: number
@@ -70,6 +72,8 @@ export interface AgentData {
   generations?: Record<string, number>
   /** The user's agent kill switch (agent/acting-switch.ts): every agent action answers paused. */
   actingPaused?: true
+  /** (CON-09a) Sessions unnamed before the directory knew them: their record is never derived a name (≤ 500). */
+  unnamed?: string[]
   [field: string]: unknown
 }
 

package/src/central/artifacts/access.ts

@@ -0,0 +1,44 @@
+// Who may do what with an artifact (HWA-20; contract: Cross-cutting rules, Artifacts). Checked on every access by
+// the artifact store. Tenancy comes first: the store only ever reads the caller's own user's records, so another
+// user's artifact is simply missing. Within a user:
+// - The user (console, app token) owns every artifact: read, revise, manage.
+// - A session reads an artifact only when its visibility is "workspace" and the session is a *current* member of
+//   that workspace (re-checked on every read, so leaving a workspace ends access). It never reads a private one,
+//   even one it created: createdBySessionID is provenance and grants nothing.
+// - A session may create artifacts (they belong to its user). Membership grants no write: revising, metadata,
+//   visibility, archive and delete stay with the user unless an explicit grant-aware policy is passed in (the
+//   routes, HWA-21, may wire the existing grants through `authorize`).
+// Role labels and workspace roles never confer authority here.
+import type { Artifact } from "../../protocol"
+
+export type ArtifactPrincipal = { readonly kind: "user" } | { readonly kind: "session"; readonly sessionID: string }
+
+/** "manage": metadata, visibility, archive/unarchive and delete. */
+export type ArtifactAction = "read" | "create" | "revise" | "manage"
+
+/** The workspace facts access needs (HWA-03/04 provide them; tests use fixtures). */
+export interface ArtifactWorkspaces {
+  exists(userID: string, workspaceID: string): Promise<boolean>
+  isCurrentMember(userID: string, workspaceID: string, sessionID: string): Promise<boolean>
+}
+
+export interface AccessRequest {
+  readonly userID: string
+  readonly principal: ArtifactPrincipal
+  readonly action: ArtifactAction
+  /** Absent for create. */
+  readonly artifact?: Artifact
+  /** Absent when this hub has no workspaces: then no session reads through a workspace. */
+  readonly workspaces?: ArtifactWorkspaces
+}
+
+export type ArtifactAuthorizer = (request: AccessRequest) => Promise<boolean>
+
+/** The contract's default policy (see the header). */
+export const defaultArtifactPolicy: ArtifactAuthorizer = async ({ userID, principal, action, artifact, workspaces }) => {
+  if (principal.kind === "user") return true
+  if (action === "create") return true
+  if (action !== "read" || !artifact) return false
+  if (artifact.visibility !== "workspace" || artifact.workspaceID === undefined || !workspaces) return false
+  return workspaces.isCurrentMember(userID, artifact.workspaceID, principal.sessionID)
+}

package/src/central/artifacts/blob-store.ts

@@ -0,0 +1,113 @@
+// The BlobStore contract (HWA-20; docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md, Artifacts): artifact
+// bytes, content-addressed by sha256 and immutable, stored per user (the tenant key). Implementations: memory
+// (src/central/backend/memory-blobs.ts, tests and the single-process default), files under the hub data directory
+// (HWA-21) and a chunked Postgres table (HWA-22, decision tctkrik8). Every implementation passes the shared suite in
+// test/blob-store-conformance.ts.
+//
+// Rules every implementation keeps:
+// - Tenancy: a blob belongs to one user. Another user's hash answers like a missing one (no existence oracle), and
+//   usage is per user. The same bytes stored by two users are two blobs.
+// - put streams the body: it hashes as it reads, stops reading (and cancels the source) as soon as the body passes
+//   `maxBytes` (default and ceiling ARTIFACT_LIMITS.blobBytes), and stores nothing when the body is too large, its
+//   hash is not `expectedHash`, the media type is not in ARTIFACT_MEDIA_TYPES (never sniffed), or a new blob would
+//   take the user past `quotaBytes` (default ARTIFACT_LIMITS.userBlobBytes). Storing bytes that are already there
+//   stores nothing new, is never refused for quota, and refreshes `touchedAt`.
+// - A blob becomes visible to get/has/stat/list only once all its bytes are durably stored and verified
+//   (write-temp-then-rename, a committed transaction): readers never see a partial blob.
+// - Reference counting lives with the revisions (src/central/artifacts/store.ts), not here: the artifact store
+//   decides a blob is unreferenced and then calls delete with `touchedBefore`. delete refuses (false) a blob touched
+//   at or after that time, atomically with the removal, so a writer that touched a blob after the deleter read the
+//   references keeps it (see the publish protocol in store.ts).
+import type { BlobRef, Page } from "../../protocol"
+
+/** A blob body: whole bytes, a web stream, or any async iterable of chunks (read once). */
+export type BlobBody = Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>
+
+export interface BlobPutOptions {
+  /** `sha256:<hex>` the body must hash to; a mismatch stores nothing (BlobHashMismatchError). */
+  readonly expectedHash?: string
+  /** Largest body accepted (default and ceiling ARTIFACT_LIMITS.blobBytes). */
+  readonly maxBytes?: number
+  /** The user's total stored bytes a new blob may not exceed (default ARTIFACT_LIMITS.userBlobBytes). */
+  readonly quotaBytes?: number
+}
+
+/** A stored blob's facts (no media type: that belongs to the revision's BlobRef). */
+export interface BlobInfo {
+  readonly hash: string
+  readonly bytes: number
+  /** When the bytes were first stored. */
+  readonly storedAt: number
+  /** The latest put or touch of these bytes. */
+  readonly touchedAt: number
+}
+
+/** A blob being read: its facts and its bytes as a stream (read once). */
+export interface BlobRead extends BlobInfo {
+  readonly body: ReadableStream<Uint8Array>
+}
+
+export interface BlobUsage {
+  readonly blobs: number
+  readonly bytes: number
+}
+
+export interface BlobDeleteOptions {
+  /** Delete only when the blob's touchedAt is before this time (checked atomically with the delete). */
+  readonly touchedBefore?: number
+}
+
+export interface BlobListOptions {
+  /** 1–LIST_LIMIT_MAX (default LIST_LIMIT_DEFAULT). */
+  readonly limit?: number
+  /** The cursor of the previous page. */
+  readonly cursor?: string
+}
+
+export interface BlobStore {
+  /** Stores the body (see the rules above) and answers its reference with the given media type. */
+  put(userID: string, body: BlobBody, mediaType: string, options?: BlobPutOptions): Promise<BlobRef>
+  /** The blob's bytes; undefined when missing (or another user's, or a malformed hash). */
+  get(userID: string, hash: string): Promise<BlobRead | undefined>
+  stat(userID: string, hash: string): Promise<BlobInfo | undefined>
+  has(userID: string, hash: string): Promise<boolean>
+  /** Refreshes touchedAt; false when the blob is missing. */
+  touch(userID: string, hash: string): Promise<boolean>
+  /** Removes the blob; false when missing or (touchedBefore) touched at or after that time. */
+  delete(userID: string, hash: string, options?: BlobDeleteOptions): Promise<boolean>
+  usage(userID: string): Promise<BlobUsage>
+  /** The user's blobs by hash, paged (orphan recovery walks it). */
+  list(userID: string, options?: BlobListOptions): Promise<Page<BlobInfo>>
+}
+
+/** A request the store refuses as malformed: a media type, maxBytes, limit or cursor. Maps to 400 invalid. */
+export class BlobInputError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "BlobInputError"
+  }
+}
+
+/** The body passed maxBytes; nothing was stored. Maps to 400 invalid. */
+export class BlobTooLargeError extends Error {
+  constructor(readonly maxBytes: number) {
+    super(`blob is larger than ${maxBytes} bytes`)
+    this.name = "BlobTooLargeError"
+  }
+}
+
+/** The body did not hash to expectedHash; nothing was stored. Maps to 400 invalid. */
+export class BlobHashMismatchError extends Error {
+  constructor(readonly expected: string, readonly actual: string) {
+    super(`blob hashes to ${actual}, not ${expected}`)
+    this.name = "BlobHashMismatchError"
+  }
+}
+
+/** A new blob would take the user past their quota; nothing was stored. Maps to 429 rate_limited (a user cap). */
+export class BlobQuotaError extends Error {
+  constructor(readonly quotaBytes: number, readonly usedBytes: number) {
+    super(`blob storage quota of ${quotaBytes} bytes reached`)
+    this.name = "BlobQuotaError"
+  }
+}

package/src/central/artifacts/blob-support.ts

@@ -0,0 +1,98 @@
+// Helpers every BlobStore implementation shares (memory, files HWA-21, Postgres HWA-22): option checks, the
+// bounded hashing body reader, and the list cursor. Keeping them here keeps the implementations alike.
+import { ARTIFACT_LIMITS, ARTIFACT_MEDIA_TYPES, isBlobHash, LIST_LIMIT_DEFAULT, LIST_LIMIT_MAX } from "../../protocol"
+import { type BlobBody, BlobHashMismatchError, BlobInputError, type BlobListOptions, type BlobPutOptions, BlobTooLargeError } from "./blob-store"
+
+export interface PutLimits {
+  readonly maxBytes: number
+  readonly quotaBytes: number
+  readonly expectedHash?: string
+}
+
+/** Checks put's media type and options (BlobInputError) and answers the limits in force. */
+export function putLimits(mediaType: string, options: BlobPutOptions = {}): PutLimits {
+  if (!(ARTIFACT_MEDIA_TYPES as readonly string[]).includes(mediaType)) throw new BlobInputError("mediaType is not allowed")
+  const maxBytes = options.maxBytes ?? ARTIFACT_LIMITS.blobBytes
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || maxBytes > ARTIFACT_LIMITS.blobBytes) {
+    throw new BlobInputError(`maxBytes must be 0–${ARTIFACT_LIMITS.blobBytes}`)
+  }
+  const quotaBytes = options.quotaBytes ?? ARTIFACT_LIMITS.userBlobBytes
+  if (!Number.isSafeInteger(quotaBytes) || quotaBytes < 0) throw new BlobInputError("quotaBytes must be a non-negative integer")
+  if (options.expectedHash !== undefined && !isBlobHash(options.expectedHash)) throw new BlobInputError("expectedHash must be sha256:<64 hex>")
+  return { maxBytes, quotaBytes, ...(options.expectedHash !== undefined ? { expectedHash: options.expectedHash } : {}) }
+}
+
+/**
+ * Reads the body once, handing each chunk to `sink` as it comes, hashing and counting it. Stops reading and
+ * cancels the source as soon as the body passes maxBytes (BlobTooLargeError), and checks expectedHash at the end
+ * (BlobHashMismatchError). The caller discards what the sink got when this throws.
+ */
+export async function readBlobBody(
+  body: BlobBody,
+  limits: PutLimits,
+  sink: (chunk: Uint8Array) => void | Promise<void>,
+): Promise<{ hash: string; bytes: number }> {
+  const hasher = new Bun.CryptoHasher("sha256")
+  let bytes = 0
+  const take = async (chunk: Uint8Array): Promise<boolean> => {
+    if (!(chunk instanceof Uint8Array)) throw new BlobInputError("blob chunks must be bytes")
+    bytes += chunk.byteLength
+    if (bytes > limits.maxBytes) return false
+    hasher.update(chunk)
+    await sink(chunk)
+    return true
+  }
+  if (body instanceof Uint8Array) {
+    if (!(await take(body))) throw new BlobTooLargeError(limits.maxBytes)
+  } else if (body instanceof ReadableStream) {
+    const reader = body.getReader()
+    try {
+      for (;;) {
+        const { done, value } = await reader.read()
+        if (done) break
+        if (!(await take(value))) {
+          await reader.cancel().catch(() => {})
+          throw new BlobTooLargeError(limits.maxBytes)
+        }
+      }
+    } finally {
+      // Bun 1.3 can throw from releaseLock() on a finished body reader after other I/O (quirk tfxrxuta).
+      try {
+        reader.releaseLock()
+      } catch {
+        // best effort
+      }
+    }
+  } else {
+    const iterator = body[Symbol.asyncIterator]()
+    for (;;) {
+      const { done, value } = await iterator.next()
+      if (done) break
+      if (!(await take(value))) {
+        await iterator.return?.()
+        throw new BlobTooLargeError(limits.maxBytes)
+      }
+    }
+  }
+  const hash = `sha256:${hasher.digest("hex")}`
+  if (limits.expectedHash !== undefined && limits.expectedHash !== hash) throw new BlobHashMismatchError(limits.expectedHash, hash)
+  return { hash, bytes }
+}
+
+/** A list request's limit and the hash after which the page starts (BlobInputError on bad ones). */
+export function listWindow(options: BlobListOptions = {}): { limit: number; after?: string } {
+  const limit = options.limit ?? LIST_LIMIT_DEFAULT
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > LIST_LIMIT_MAX) throw new BlobInputError(`limit must be 1–${LIST_LIMIT_MAX}`)
+  if (options.cursor === undefined) return { limit }
+  let after: string
+  try {
+    after = Buffer.from(options.cursor, "base64url").toString("utf8")
+  } catch {
+    throw new BlobInputError("cursor is not valid")
+  }
+  if (!isBlobHash(after)) throw new BlobInputError("cursor is not valid")
+  return { limit, after }
+}
+
+/** The cursor that continues a list after `hash`. */
+export const listCursor = (hash: string): string => Buffer.from(hash, "utf8").toString("base64url")

package/src/central/artifacts/events.ts

@@ -0,0 +1,27 @@
+// Artifact events for the canonical agent journal (HWA-21; contract: Cross-cutting rules, Events). The store's
+// onEvent hook gives compact events; this maps them to journal input in the `artifact` family (read with
+// artifacts:read). Payloads are IDs, kinds, revisions and counts only: never titles, descriptions or content.
+import type { ArtifactEvent } from "./store"
+
+/** Journal input of an artifact event (an EventInput of family "artifact"). */
+export interface ArtifactJournalInput {
+  readonly type: ArtifactEvent["type"]
+  readonly family: "artifact"
+  readonly subject: { readonly artifactID: string }
+  readonly data: Readonly<Record<string, string | number>>
+}
+
+export function artifactJournalEvent(event: ArtifactEvent): ArtifactJournalInput {
+  return {
+    type: event.type,
+    family: "artifact",
+    subject: { artifactID: event.artifactID },
+    data: {
+      kind: event.kind,
+      revision: event.revision,
+      ...(event.revisionID !== undefined ? { revisionID: event.revisionID } : {}),
+      ...(event.number !== undefined ? { number: event.number } : {}),
+      ...(event.state !== undefined ? { state: event.state } : {}),
+    },
+  }
+}