@huynle/hub 0.7.4 → 0.8.1

package/src/central/workspaces/routes.ts

@@ -0,0 +1,354 @@
+// Workspace routes on /api/agent (HWA-06; contract: Workspaces in docs/plans/2026-10-30-hub-workspaces-artifacts-
+// contracts.md and its clarifications from HWA-03/04/05/14):
+//
+//   POST   /workspaces                                   {title, description?, tags?, metadata?}  Idempotency-Key  manage
+//   GET    /workspaces?state=active|archived&limit&cursor                                                      read
+//   GET    /workspaces/:id                               → {workspace, bindings}                               read
+//   PATCH  /workspaces/:id                               {expectedRevision, title?, description?, tags?, metadata?}  manage
+//   POST   /workspaces/:id/archive                       {expectedRevision} → {workspace, departed}            manage
+//   POST   /workspaces/:id/restore                       {expectedRevision}                                    manage
+//   GET    /workspaces/:id/bindings                                                                            read
+//   POST   /workspaces/:id/bindings                      {machineID, repo, label?}  Idempotency-Key            manage
+//   DELETE /workspaces/:id/bindings?bindingID=&expectedRevision=                                               manage
+//   GET    /workspaces/:id/members?includeLeft=1                                                       read + S
+//   POST   /workspaces/:id/members                       {sessionID, role}  Idempotency-Key            manage + S
+//   PATCH  /workspaces/:id/members/:memberID             {role, expectedRevision}                      manage + S
+//   DELETE /workspaces/:id/members/:memberID?expectedRevision=                                         manage + S
+//   GET    /workspaces/:id/assignments?memberID&status&limit&cursor                                    read + S
+//   GET    /workspaces/:id/assignments/:assignmentID                                                   read + S
+//   POST   /workspaces/:id/assignments                   {memberID, title, status?, criteria?, ref?}  Idempotency-Key  manage
+//   PATCH  /workspaces/:id/assignments/:assignmentID     {expectedRevision, status | memberID}         manage
+//   GET    /workspaces/:id/supervision                   → {workspaceID, revision, links}             read
+//   PUT    /workspaces/:id/supervision                   {memberID, supervisorMemberID|null, order?, expectedRevision}  manage
+//
+// Who: users, always (their own records; another user's answer not_found). App tokens by scope workspaces:read /
+// workspaces:manage; routes that show or name sessions (S: members with presence, joins, assignments with
+// presence) also need sessions:read. Session tokens are refused: membership grants nothing, and no session reads
+// or changes workspaces through its own token in v1.
+// Every mutation of an existing record requires expectedRevision (supervision: the graph aggregate's revision);
+// a stale one is 409 conflict with currentRevision. Creates accept Idempotency-Key: workspaces and assignments
+// keep the key in their stores, bindings and members through the shared route helper (their natural keys,
+// machine + repo and session + role, already make repeats return the existing record).
+// Every change is in the admin audit (IDs only) and the journal (compact, text-free events). Reads are bounded:
+// lists page (≤ LIST_LIMIT_MAX), and members, bindings and supervision links are capped per workspace.
+// Not here: the board (HWA-10), checkpoints (HWA-11), master replacement (HWA-12), side chats (HWA-13,
+// sidechats-routes.ts).
+import { isExpectedRevision, WORKSPACE_SCOPES } from "../../protocol"
+import type { AgentContext, AgentRoute } from "../agent/routes"
+import type { AgentEvents, EventInput } from "../agent/events"
+import { AgentError } from "../agent/errors"
+import { idempotencyKeyOf, RouteIdempotency, storeAnswer } from "../agent/idempotency"
+import type { Store } from "../store"
+import { assignmentChangedEvent, bindingEvent, memberJoinedEvent, memberRoleEvent, supervisionSetEvent, workspaceArchivedEvent, workspaceCreatedEvent, workspacePatchedEvent } from "./events"
+import { WorkspaceLifecycle } from "./lifecycle"
+import type { MembershipStore } from "./members"
+import type { WorkspaceStore } from "./store"
+import type { SupervisionStore } from "./supervision"
+import { AGENT_JSON_BODY_MAX, boundedText } from "../agent/body"
+
+const PREFIX = "/api/agent/workspaces"
+/** The shared route helper's records for bindings and members (store-level keys live in workspace-idempotency). */
+export const WORKSPACE_ROUTE_IDEMPOTENCY = "workspace-route-idempotency"
+const NO_STORE = { "cache-control": "no-store" }
+const [READ_SCOPE, MANAGE_SCOPE] = WORKSPACE_SCOPES
+const READ = { scope: READ_SCOPE } as const
+const MANAGE = { scope: MANAGE_SCOPE } as const
+
+export interface WorkspaceRoutesDeps {
+  readonly workspaces: WorkspaceStore
+  readonly members: MembershipStore
+  readonly supervision: SupervisionStore
+  /** Departures with their supervision and events; one over the stores and `events` when absent. */
+  readonly lifecycle?: WorkspaceLifecycle
+  readonly events?: Pick<AgentEvents, "append">
+  readonly audit?: Pick<Store, "audit">
+  /** Idempotent binding and member creates; one over the workspaces' StateStore when absent. */
+  readonly idempotency?: RouteIdempotency
+}
+
+const ok = (body: unknown, status = 200) => Response.json(body, { status, headers: NO_STORE })
+
+async function bodyOf(request: Request): Promise<Record<string, unknown>> {
+  const text = await boundedText(request, AGENT_JSON_BODY_MAX)
+  const raw = JSON.parse(text === "" ? "{}" : text) 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>
+}
+
+function only(body: Record<string, unknown>, allowed: readonly string[]): void {
+  for (const key of Object.keys(body)) if (!allowed.includes(key)) throw new AgentError("invalid", `unknown field ${/^[A-Za-z0-9_-]{1,40}$/.test(key) ? key : "(unprintable)"}`)
+}
+
+/** The required expectedRevision of a mutation (body field or query parameter). */
+function expected(value: unknown): number {
+  const n = typeof value === "string" && /^[0-9]{1,15}$/.test(value) ? Number(value) : value
+  if (n === undefined || n === null || n === "") throw new AgentError("invalid", "expectedRevision is required: the revision you read", { hint: "Read the record and send its revision" })
+  if (!isExpectedRevision(n)) throw new AgentError("invalid", "expectedRevision must be the revision you read")
+  return n as number
+}
+
+function intParam(url: URL, name: string): number | undefined {
+  const raw = url.searchParams.get(name)
+  return raw === null ? undefined : /^-?[0-9]{1,12}$/.test(raw) ? Number(raw) : Number.NaN
+}
+
+const text = (url: URL, name: string) => url.searchParams.get(name) || undefined
+
+/** Apps on routes that show or name sessions also need sessions:read. */
+function sessionsVisible(context: AgentContext): void {
+  const { actor } = context
+  if (actor.kind === "app" && !actor.scopes.includes("sessions:read")) throw new AgentError("forbidden", "Member and assignment routes also need scope sessions:read")
+}
+
+export function workspaceRoutes(deps: WorkspaceRoutesDeps): AgentRoute[] {
+  const { workspaces, members, supervision } = deps
+  const lifecycle = deps.lifecycle ?? new WorkspaceLifecycle({ workspaces, members, supervision, ...(deps.events ? { events: deps.events } : {}) })
+  const idempotency = deps.idempotency ?? new RouteIdempotency({ state: workspaces.state, collection: WORKSPACE_ROUTE_IDEMPOTENCY })
+
+  async function changed(context: AgentContext, action: string, target: string, ...events: EventInput[]): Promise<void> {
+    await deps.audit?.audit({ actor: context.user.id, action, target, detail: context.actor.kind })
+    await lifecycle.emit(context.user.id, ...events)
+  }
+
+  /** A create through the shared helper (it runs `perform` directly when no key is sent). */
+  const keyed = (context: AgentContext, body: Record<string, unknown>, perform: () => Promise<{ status: number; body: unknown }>): Promise<Response> =>
+    idempotency.run(context.user.id, `POST ${context.url.pathname}`, idempotencyKeyOf(context.request) ?? null, body, perform)
+
+  const id = (context: AgentContext) => context.params.id!
+
+  return [
+    // ---------- workspaces ----------
+    {
+      method: "POST",
+      path: PREFIX,
+      allow: MANAGE,
+      async handle(context) {
+        const body = await bodyOf(context.request)
+        const key = idempotencyKeyOf(context.request)
+        const { workspace, created } = await workspaces.create(context.user.id, body, key === undefined ? {} : { idempotencyKey: key })
+        if (created) await changed(context, "workspace.create", workspace.id, workspaceCreatedEvent(workspace))
+        return storeAnswer(created, { workspace })
+      },
+    },
+    {
+      method: "GET",
+      path: PREFIX,
+      allow: READ,
+      async handle({ url, user }) {
+        const limit = intParam(url, "limit")
+        const state = text(url, "state")
+        const cursor = text(url, "cursor")
+        return ok(await workspaces.list(user.id, { ...(limit !== undefined ? { limit } : {}), ...(state ? { state } : {}), ...(cursor ? { cursor } : {}) }))
+      },
+    },
+    {
+      method: "GET",
+      path: `${PREFIX}/:id`,
+      allow: READ,
+      async handle(context) {
+        const workspace = await workspaces.require(context.user.id, id(context))
+        return ok({ workspace, bindings: await workspaces.bindings(context.user.id, workspace.id) })
+      },
+    },
+    {
+      method: "PATCH",
+      path: `${PREFIX}/:id`,
+      allow: MANAGE,
+      async handle(context) {
+        const { expectedRevision, ...patch } = await bodyOf(context.request)
+        const revision = expected(expectedRevision)
+        const workspace = await workspaces.update(context.user.id, id(context), patch, revision)
+        if (workspace.revision !== revision) await changed(context, "workspace.update", workspace.id, workspacePatchedEvent(workspace))
+        return ok({ workspace })
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/:id/archive`,
+      allow: MANAGE,
+      async handle(context) {
+        const body = await bodyOf(context.request)
+        only(body, ["expectedRevision"])
+        const result = await lifecycle.archive(context.user.id, id(context), expected(body.expectedRevision))
+        await deps.audit?.audit({ actor: context.user.id, action: "workspace.archive", target: result.workspace.id, detail: context.actor.kind })
+        return ok(result)
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/:id/restore`,
+      allow: MANAGE,
+      async handle(context) {
+        const body = await bodyOf(context.request)
+        only(body, ["expectedRevision"])
+        const revision = expected(body.expectedRevision)
+        const workspace = await workspaces.restore(context.user.id, id(context), revision)
+        if (workspace.revision !== revision) await changed(context, "workspace.restore", workspace.id, workspaceArchivedEvent(workspace, 0))
+        return ok({ workspace })
+      },
+    },
+
+    // ---------- host repository bindings ----------
+    {
+      method: "GET",
+      path: `${PREFIX}/:id/bindings`,
+      allow: READ,
+      handle: async (context) => ok({ bindings: await workspaces.bindings(context.user.id, id(context)) }),
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/:id/bindings`,
+      allow: MANAGE,
+      async handle(context) {
+        const body = await bodyOf(context.request)
+        only(body, ["machineID", "repo", "label"])
+        return keyed(context, body, async () => {
+          const { binding, created } = await workspaces.bind(context.user.id, id(context), body)
+          if (created) await changed(context, "workspace.bind", id(context), bindingEvent(id(context), binding, "bound"))
+          return { status: created ? 201 : 200, body: { binding, created } }
+        })
+      },
+    },
+    {
+      method: "DELETE",
+      path: `${PREFIX}/:id/bindings`,
+      allow: MANAGE,
+      async handle(context) {
+        const bindingID = text(context.url, "bindingID")
+        if (!bindingID) throw new AgentError("invalid", "bindingID is required")
+        const binding = await workspaces.unbind(context.user.id, id(context), bindingID, expected(context.url.searchParams.get("expectedRevision") ?? undefined))
+        await changed(context, "workspace.unbind", id(context), bindingEvent(id(context), binding, "unbound"))
+        return new Response(null, { status: 204, headers: NO_STORE })
+      },
+    },
+
+    // ---------- members ----------
+    {
+      method: "GET",
+      path: `${PREFIX}/:id/members`,
+      allow: READ,
+      async handle(context) {
+        sessionsVisible(context)
+        const includeLeft = ["1", "true"].includes(context.url.searchParams.get("includeLeft") ?? "")
+        return ok({ members: await members.members(context.user.id, id(context), { includeLeft }) })
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/:id/members`,
+      allow: MANAGE,
+      async handle(context) {
+        sessionsVisible(context)
+        const body = await bodyOf(context.request)
+        only(body, ["sessionID", "role"])
+        return keyed(context, body, async () => {
+          const { member, created } = await members.join(context.user.id, id(context), body)
+          if (created) await changed(context, "workspace.member.join", member.id, memberJoinedEvent(member))
+          return { status: created ? 201 : 200, body: { member, created } }
+        })
+      },
+    },
+    {
+      method: "PATCH",
+      path: `${PREFIX}/:id/members/:member`,
+      allow: MANAGE,
+      async handle(context) {
+        sessionsVisible(context)
+        const body = await bodyOf(context.request)
+        only(body, ["role", "expectedRevision"])
+        const revision = expected(body.expectedRevision)
+        const member = await members.setRole(context.user.id, id(context), context.params.member!, body.role, revision)
+        if (member.revision !== revision) await changed(context, "workspace.member.role", member.id, memberRoleEvent(member))
+        return ok({ member })
+      },
+    },
+    {
+      method: "DELETE",
+      path: `${PREFIX}/:id/members/:member`,
+      allow: MANAGE,
+      async handle(context) {
+        sessionsVisible(context)
+        const revision = expected(context.url.searchParams.get("expectedRevision") ?? undefined)
+        const departure = await lifecycle.leave(context.user.id, id(context), context.params.member!, revision)
+        await deps.audit?.audit({ actor: context.user.id, action: "workspace.member.leave", target: departure.member.id, detail: context.actor.kind })
+        return ok(departure)
+      },
+    },
+
+    // ---------- assignments ----------
+    {
+      method: "GET",
+      path: `${PREFIX}/:id/assignments`,
+      allow: READ,
+      async handle(context) {
+        sessionsVisible(context)
+        const { url } = context
+        const limit = intParam(url, "limit")
+        const query = { ...(limit !== undefined ? { limit } : {}), ...Object.fromEntries(["memberID", "status", "cursor"].flatMap((k) => (text(url, k) ? [[k, text(url, k)!]] : []))) }
+        return ok(await members.assignments(context.user.id, id(context), query))
+      },
+    },
+    {
+      method: "GET",
+      path: `${PREFIX}/:id/assignments/:assignment`,
+      allow: READ,
+      async handle(context) {
+        sessionsVisible(context)
+        return ok({ assignment: await members.assignment(context.user.id, id(context), context.params.assignment!) })
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/:id/assignments`,
+      allow: MANAGE,
+      async handle(context) {
+        const body = await bodyOf(context.request)
+        const key = idempotencyKeyOf(context.request)
+        const { assignment, created } = await members.assign(context.user.id, id(context), body, key === undefined ? {} : { idempotencyKey: key })
+        if (created) await changed(context, "workspace.assignment.create", assignment.id, assignmentChangedEvent(assignment, "created"))
+        return storeAnswer(created, { assignment })
+      },
+    },
+    {
+      method: "PATCH",
+      path: `${PREFIX}/:id/assignments/:assignment`,
+      allow: MANAGE,
+      async handle(context) {
+        const body = await bodyOf(context.request)
+        only(body, ["status", "memberID", "expectedRevision"])
+        const revision = expected(body.expectedRevision)
+        if ((body.status === undefined) === (body.memberID === undefined)) throw new AgentError("invalid", "Send exactly one of status or memberID")
+        const assignmentID = context.params.assignment!
+        const change = body.status !== undefined ? "status" : "reassigned"
+        const assignment =
+          change === "status"
+            ? await members.setStatus(context.user.id, id(context), assignmentID, body.status, revision)
+            : await members.reassign(context.user.id, id(context), assignmentID, body.memberID, revision)
+        if (assignment.revision !== revision) await changed(context, `workspace.assignment.${change}`, assignment.id, assignmentChangedEvent(assignment, change))
+        return ok({ assignment })
+      },
+    },
+
+    // ---------- supervision ----------
+    {
+      method: "GET",
+      path: `${PREFIX}/:id/supervision`,
+      allow: READ,
+      handle: async (context) => ok(await supervision.graph(context.user.id, id(context))),
+    },
+    {
+      method: "PUT",
+      path: `${PREFIX}/:id/supervision`,
+      allow: MANAGE,
+      async handle(context) {
+        const body = await bodyOf(context.request)
+        only(body, ["memberID", "supervisorMemberID", "order", "expectedRevision"])
+        expected(body.expectedRevision)
+        const result = await supervision.set(context.user.id, id(context), body)
+        if (result.change !== "unchanged" || result.pruned > 0)
+          await changed(context, "workspace.supervision", id(context), supervisionSetEvent(body.memberID as string, result, result.link))
+        return ok(result)
+      },
+    },
+  ]
+}