@huynle/hub 0.7.3 → 0.8.0

package/src/central/teams/routes.ts

@@ -0,0 +1,516 @@
+// Team routes on /api/agent (HWA-37; contract: Teams in docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md
+// and the HWA-33/34/35/36 clarifications). Intake (/teams/:id/intake…) lives in intake-routes.ts (HWA-36).
+//
+//   POST   /teams                                  {name, title, mode, roles, entryRole, edges?, …}  Idempotency-Key  M
+//   GET    /teams?state&tag…&project&metadata=k=v…&paused&limit&cursor                                          R
+//   GET    /teams/:id                              → {team, draft?}   (:id is the team ID or its name)        R
+//   PATCH  /teams/:id                              {expectedRevision, publish?, …spec fields} → draft saved     M
+//   GET    /teams/:id/draft                        → {draft}                                                 R
+//   DELETE /teams/:id/draft?expectedRevision=      discard the draft                                         M
+//   PUT    /teams/:id/draft/roles/:role            {expectedRevision, label?, description?, …} add/replace   M
+//   DELETE /teams/:id/draft/roles/:role?expectedRevision=   (and its edges)                                  M
+//   PUT    /teams/:id/draft/edges                  {expectedRevision, from, to, kinds, direction}            M
+//   DELETE /teams/:id/draft/edges?from&to&expectedRevision=                                                  M
+//   POST   /teams/:id/publish                      {expectedRevision} → {team, published}                    M
+//   POST   /teams/:id/{pause,resume,archive,restore}  {expectedRevision} → {team}                            M
+//   GET    /teams/:id/versions?limit&cursor        retained published versions, newest first                 R
+//   GET    /teams/:id/versions/:version            → {version}  (the frozen spec)                            R
+//   GET    /teams/:id/diff?from&to                 from (default: published) → to (version or draft, default) R
+//   GET    /teams/:id/staffing?ended=1             seats (current; with ended ones on ended=1)               R + S
+//   PUT    /teams/:id/staffing                     {role, sessionID}  Idempotency-Key  → {staffing, workspace?} M + S
+//   POST   /teams/:id/staffing/launch              {role, launch}  Idempotency-Key  → {request, launch}      M + S
+//   POST   /teams/:id/staffing/:staffing/replace   {expectedRevision, sessionID | launch}                    M + S
+//   DELETE /teams/:id/staffing/:staffing?expectedRevision=                                                   M + S
+//   GET    /teams/:id/roster                       → {roster}                                                R + S
+//   GET    /teams/:id/status                       → {team, roster, intake}  (intake: counts only)           R + S
+//   GET    /team-settings                          → {settings: {teamIsolation, revision, updatedAt?}}       users only
+//   PUT    /team-settings                          {teamIsolation, expectedRevision} → {settings}            users only
+//
+// The owner settings (RP-09) live outside /teams/ so a team named `settings` keeps its address; users only: app and
+// session tokens never read or change them (isolation narrows what team members see; a member must not widen it).
+// Who. Users: their own teams (another user's, by ID or name, is not_found). App tokens: R needs teams:read or
+// teams:manage, M needs teams:manage; routes that show or name sessions (S: seats, roster, status, staffing) also
+// need sessions:read (as the workspace routes). No existing token gains anything: the scopes are new. Session
+// tokens: never change definitions (a team member editing its own team's policy would bypass it); they read only
+// the teams they hold a current seat in (others are not_found), and may staff under the existing grants exactly as
+// TeamStaffingService checks them (needs_user when missing; no grant or Decision is created here). Decision
+// answers and grant administration stay console-only: no route here touches them.
+// Every mutation of an existing record requires expectedRevision (409 conflict with currentRevision when stale);
+// creates take Idempotency-Key (store-level: TeamStore and TeamSeatStore keep the key). Changes are audited (IDs
+// only) and journaled with the compact team events (events.ts). Lists page (limit ≤ LIST_LIMIT_MAX); seats are
+// capped per role and the ended ones retained per team.
+import { boundedText } from "../agent/body"
+import { isContractID, isExpectedRevision, isSlug, LIST_LIMIT_MAX } from "../../protocol"
+import type { AgentContext, AgentRoute } from "../agent/routes"
+import type { AgentEvents, EventInput } from "../agent/events"
+import { AgentError } from "../agent/errors"
+import { idempotencyKeyOf, storeAnswer } from "../agent/idempotency"
+import type { Store } from "../store"
+import { removeEdge, removeRole, setEdge, setRole } from "./draft-edits"
+import { teamArchivedEvent, teamCreatedEvent, teamUpdatedEvent } from "./events"
+import type { TeamIntakeService } from "./intake"
+import type { TeamSeatStore } from "./seats"
+import type { TeamStaffingService } from "./staffing"
+import type { Team, TeamListQuery, TeamStore } from "./store"
+import type { TeamSpec } from "./validation"
+
+const PREFIX = "/api/agent/teams"
+const SETTINGS_PATH = "/api/agent/team-settings"
+/** Users only (no app or session token). */
+const USERS = {} as const
+const NO_STORE = { "cache-control": "no-store" }
+/** Request bodies: a full team spec (32 roles, 256 edges, descriptions) stays well below this. */
+export const TEAM_BODY_MAX = 256 * 1024
+const MANAGE = { scope: "teams:manage" } as const
+const READ = { app: true, session: true } as const
+const STAFF = { scope: "teams:manage", session: true } as const
+
+export interface TeamRoutesDeps {
+  readonly teams: TeamStore
+  readonly seats: TeamSeatStore
+  readonly staffing: TeamStaffingService
+  /** Intake counts in team status (HWA-36); omitted when absent. */
+  readonly intake?: Pick<TeamIntakeService, "summary">
+  readonly events?: Pick<AgentEvents, "append">
+  readonly audit?: Pick<Store, "audit">
+}
+
+const ok = (body: unknown) => Response.json(body, { headers: NO_STORE })
+const printable = (v: string) => (/^[A-Za-z0-9_-]{1,64}$/.test(v) ? v : "(unprintable)")
+
+async function bodyOf(request: Request): Promise<Record<string, unknown>> {
+  const declared = Number(request.headers.get("content-length") ?? "0")
+  if (declared > TEAM_BODY_MAX) throw new AgentError("invalid", `Body must be at most ${TEAM_BODY_MAX} bytes`)
+  const text = await boundedText(request, TEAM_BODY_MAX)
+  if (text.length > TEAM_BODY_MAX) throw new AgentError("invalid", `Body must be at most ${TEAM_BODY_MAX} bytes`)
+  let raw: unknown
+  try {
+    raw = JSON.parse(text === "" ? "{}" : text)
+  } catch {
+    throw new AgentError("invalid", "Body must be JSON")
+  }
+  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 team 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
+
+function boolParam(url: URL, name: string): boolean | undefined {
+  const raw = url.searchParams.get(name)
+  if (raw === null || raw === "") return undefined
+  if (raw === "true" || raw === "1") return true
+  if (raw === "false" || raw === "0") return false
+  throw new AgentError("invalid", `${name} must be true or false`)
+}
+
+/** The list query: repeated `tag`, repeated `metadata=key=value`, state, project, paused, limit, cursor. */
+function listQuery(url: URL): TeamListQuery {
+  const tags = url.searchParams.getAll("tag")
+  const pairs = url.searchParams.getAll("metadata")
+  const metadata: Record<string, string> = {}
+  for (const pair of pairs) {
+    const at = pair.indexOf("=")
+    if (at <= 0) throw new AgentError("invalid", "metadata filters are key=value")
+    metadata[pair.slice(0, at)] = pair.slice(at + 1)
+  }
+  const limit = intParam(url, "limit")
+  const paused = boolParam(url, "paused")
+  const state = text(url, "state")
+  const project = text(url, "project")
+  const cursor = text(url, "cursor")
+  return {
+    ...(state ? { state } : {}),
+    ...(tags.length ? { tags } : {}),
+    ...(project ? { project } : {}),
+    ...(pairs.length ? { metadata } : {}),
+    ...(paused !== undefined ? { paused } : {}),
+    ...(limit !== undefined ? { limit } : {}),
+    ...(cursor ? { cursor } : {}),
+  }
+}
+
+/** Apps reading teams need teams:read or teams:manage, plus sessions:read where sessions are shown. */
+function appMayRead(context: AgentContext, sessions: boolean): void {
+  const { actor } = context
+  if (actor.kind !== "app") return
+  if (!actor.scopes.includes("teams:read") && !actor.scopes.includes("teams:manage")) throw new AgentError("forbidden", "Reading teams needs scope teams:read (or teams:manage)")
+  if (sessions && !actor.scopes.includes("sessions:read")) throw new AgentError("forbidden", "Seats, roster, status and staffing also need scope sessions:read")
+}
+
+function appMayStaff(context: AgentContext): void {
+  const { actor } = context
+  if (actor.kind === "app" && !actor.scopes.includes("sessions:read")) throw new AgentError("forbidden", "Staffing also needs scope sessions:read")
+}
+
+export function teamRoutes(deps: TeamRoutesDeps): AgentRoute[] {
+  const { teams, seats, staffing } = deps
+
+  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 })
+    for (const event of events) await deps.events?.append(context.user.id, event)
+  }
+
+  /** The user's team by ID or name (another user's, or none: not_found). */
+  async function resolve(userID: string, raw: string): Promise<Team> {
+    const team = isContractID("team", raw) ? await teams.get(userID, raw) : isSlug(raw) ? await teams.byName(userID, raw) : undefined
+    if (!team) throw new AgentError("not_found", `No team ${printable(raw)}`)
+    return team
+  }
+
+  /** A team the caller may read: sessions only the teams they hold a current seat in. */
+  async function readable(context: AgentContext, sessions = false): Promise<Team> {
+    appMayRead(context, sessions)
+    const team = await resolve(context.user.id, context.params.id!)
+    const { actor } = context
+    if (actor.kind === "session" && !(await seats.seatsOf(context.user.id, actor.sessionID)).some((s) => s.teamID === team.id)) throw new AgentError("not_found", `No team ${printable(context.params.id!)}`)
+    return team
+  }
+
+  const managed = (context: AgentContext) => resolve(context.user.id, context.params.id!)
+
+  /** A status change under expectedRevision; journaled only when it changed something. */
+  const statusRoute = (verb: "pause" | "resume" | "archive" | "restore"): AgentRoute => ({
+    method: "POST",
+    path: `${PREFIX}/:id/${verb}`,
+    allow: MANAGE,
+    async handle(context) {
+      const body = await bodyOf(context.request)
+      only(body, ["expectedRevision"])
+      const revision = expected(body.expectedRevision)
+      const { id } = await managed(context)
+      const team = await teams[verb](context.user.id, id, revision)
+      if (team.revision !== revision) {
+        const event = verb === "archive" || verb === "restore" ? teamArchivedEvent(team) : teamUpdatedEvent(team, verb === "pause" ? "paused" : "resumed")
+        await changed(context, `team.${verb}`, team.id, event)
+      }
+      return ok({ team })
+    },
+  })
+
+  /** Saves a draft edit computed from the current draft (or published) spec, under expectedRevision. */
+  async function draftEdit(context: AgentContext, revision: number, edit: (spec: TeamSpec) => unknown): Promise<Response> {
+    const current = await managed(context)
+    if (current.revision !== revision)
+      throw new AgentError("conflict", `Team ${current.id} changed since you read it (revision ${current.revision} now)`, { hint: "Read it again and retry with its current revision", extra: { currentRevision: current.revision } })
+    const base = (await teams.draft(context.user.id, current.id))?.spec ?? (await teams.version(context.user.id, current.id, current.version))?.spec
+    if (!base) throw new AgentError("internal", `Team ${current.id} has no readable published version`)
+    const team = await teams.saveDraft(context.user.id, current.id, edit(base), revision)
+    await changed(context, "team.draft", team.id, teamUpdatedEvent(team, "draft"))
+    return ok({ team, draft: await teams.draft(context.user.id, team.id) })
+  }
+
+  /** A publish journals `published`, or `draft_discarded` when the draft equalled the published spec. */
+  async function publishedEvent(context: AgentContext, team: Team, published: boolean): Promise<void> {
+    await changed(context, published ? "team.publish" : "team.draft.discard", team.id, teamUpdatedEvent(team, published ? "published" : "draft_discarded"))
+  }
+
+  return [
+    // ---------- owner settings (users only) ----------
+    {
+      method: "GET",
+      path: SETTINGS_PATH,
+      allow: USERS,
+      async handle(context) {
+        return ok({ settings: await teams.settings(context.user.id) })
+      },
+    },
+    {
+      method: "PUT",
+      path: SETTINGS_PATH,
+      allow: USERS,
+      async handle(context) {
+        const { expectedRevision, ...input } = await bodyOf(context.request)
+        const settings = await teams.setSettings(context.user.id, input, expected(expectedRevision))
+        await changed(context, "team.settings", "team-settings")
+        return ok({ settings })
+      },
+    },
+    // ---------- definitions ----------
+    {
+      method: "POST",
+      path: PREFIX,
+      allow: MANAGE,
+      async handle(context) {
+        const body = await bodyOf(context.request)
+        const key = idempotencyKeyOf(context.request)
+        const { team, created } = await teams.create(context.user.id, body, key === undefined ? {} : { idempotencyKey: key })
+        if (created) await changed(context, "team.create", team.id, teamCreatedEvent(team))
+        return storeAnswer(created, { team })
+      },
+    },
+    {
+      method: "GET",
+      path: PREFIX,
+      allow: READ,
+      async handle(context) {
+        appMayRead(context, false)
+        const query = listQuery(context.url)
+        const { actor, user } = context
+        if (actor.kind !== "session") return ok(await teams.list(user.id, query))
+        // Sessions: only the teams they are seated in (a handful), unpaged.
+        const mine = new Set((await seats.seatsOf(user.id, actor.sessionID)).map((s) => s.teamID))
+        const items: Team[] = []
+        let cursor: string | undefined
+        do {
+          const page = await teams.list(user.id, { ...query, limit: LIST_LIMIT_MAX, ...(cursor ? { cursor } : {}) })
+          items.push(...page.items.filter((t) => mine.has(t.id)))
+          cursor = page.cursor
+        } while (cursor)
+        return ok({ items })
+      },
+    },
+    {
+      method: "GET",
+      path: `${PREFIX}/:id`,
+      allow: READ,
+      async handle(context) {
+        const team = await readable(context)
+        const draft = await teams.draft(context.user.id, team.id)
+        return ok({ team, ...(draft ? { draft } : {}) })
+      },
+    },
+    {
+      method: "PATCH",
+      path: `${PREFIX}/:id`,
+      allow: MANAGE,
+      async handle(context) {
+        const { expectedRevision, publish, ...patch } = await bodyOf(context.request)
+        if (publish !== undefined && typeof publish !== "boolean") throw new AgentError("invalid", "publish must be true or false")
+        const revision = expected(expectedRevision)
+        const { id } = await managed(context)
+        const team = await teams.saveDraft(context.user.id, id, patch, revision)
+        await changed(context, "team.draft", team.id, teamUpdatedEvent(team, "draft"))
+        if (publish !== true) return ok({ team })
+        const result = await teams.publish(context.user.id, id, team.revision)
+        await publishedEvent(context, result.team, result.published)
+        return ok(result)
+      },
+    },
+    {
+      method: "GET",
+      path: `${PREFIX}/:id/draft`,
+      allow: READ,
+      async handle(context) {
+        const team = await readable(context)
+        const draft = await teams.draft(context.user.id, team.id)
+        if (!draft) throw new AgentError("not_found", `Team ${team.id} has no draft`)
+        return ok({ draft })
+      },
+    },
+    {
+      method: "DELETE",
+      path: `${PREFIX}/:id/draft`,
+      allow: MANAGE,
+      async handle(context) {
+        const revision = expected(text(context.url, "expectedRevision"))
+        const { id } = await managed(context)
+        const team = await teams.discardDraft(context.user.id, id, revision)
+        await changed(context, "team.draft.discard", team.id, teamUpdatedEvent(team, "draft_discarded"))
+        return ok({ team })
+      },
+    },
+    {
+      method: "PUT",
+      path: `${PREFIX}/:id/draft/roles/:role`,
+      allow: MANAGE,
+      async handle(context) {
+        const { expectedRevision, ...fields } = await bodyOf(context.request)
+        return draftEdit(context, expected(expectedRevision), (spec) => setRole(spec, context.params.role!, fields))
+      },
+    },
+    {
+      method: "DELETE",
+      path: `${PREFIX}/:id/draft/roles/:role`,
+      allow: MANAGE,
+      async handle(context) {
+        return draftEdit(context, expected(text(context.url, "expectedRevision")), (spec) => removeRole(spec, context.params.role!))
+      },
+    },
+    {
+      method: "PUT",
+      path: `${PREFIX}/:id/draft/edges`,
+      allow: MANAGE,
+      async handle(context) {
+        const { expectedRevision, ...edge } = await bodyOf(context.request)
+        return draftEdit(context, expected(expectedRevision), (spec) => setEdge(spec, edge))
+      },
+    },
+    {
+      method: "DELETE",
+      path: `${PREFIX}/:id/draft/edges`,
+      allow: MANAGE,
+      async handle(context) {
+        const from = text(context.url, "from")
+        const to = text(context.url, "to")
+        if (!from || !to) throw new AgentError("invalid", "from and to (role names) are required")
+        return draftEdit(context, expected(text(context.url, "expectedRevision")), (spec) => removeEdge(spec, from, to))
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/:id/publish`,
+      allow: MANAGE,
+      async handle(context) {
+        const body = await bodyOf(context.request)
+        only(body, ["expectedRevision"])
+        const { id } = await managed(context)
+        const result = await teams.publish(context.user.id, id, expected(body.expectedRevision))
+        await publishedEvent(context, result.team, result.published)
+        return ok(result)
+      },
+    },
+    statusRoute("pause"),
+    statusRoute("resume"),
+    statusRoute("archive"),
+    statusRoute("restore"),
+
+    // ---------- history ----------
+    {
+      method: "GET",
+      path: `${PREFIX}/:id/versions`,
+      allow: READ,
+      async handle(context) {
+        const team = await readable(context)
+        const limit = intParam(context.url, "limit")
+        const cursor = text(context.url, "cursor")
+        return ok(await teams.history(context.user.id, team.id, { ...(limit !== undefined ? { limit } : {}), ...(cursor ? { cursor } : {}) }))
+      },
+    },
+    {
+      method: "GET",
+      path: `${PREFIX}/:id/versions/:version`,
+      allow: READ,
+      async handle(context) {
+        const team = await readable(context)
+        const raw = context.params.version!
+        const number = /^[0-9]{1,9}$/.test(raw) ? Number(raw) : Number.NaN
+        if (!Number.isSafeInteger(number) || number < 1) throw new AgentError("invalid", "version must be a version number")
+        const version = await teams.version(context.user.id, team.id, number)
+        if (!version) throw new AgentError("not_found", `Team ${team.id} has no retained version ${number}`)
+        return ok({ version })
+      },
+    },
+    {
+      method: "GET",
+      path: `${PREFIX}/:id/diff`,
+      allow: READ,
+      async handle(context) {
+        const team = await readable(context)
+        const versionOf = (name: string): number | undefined => {
+          const raw = text(context.url, name)
+          if (raw === undefined) return undefined
+          if (!/^[0-9]{1,9}$/.test(raw) || Number(raw) < 1) throw new AgentError("invalid", `${name} must be a version number${name === "to" ? " or draft" : ""}`)
+          return Number(raw)
+        }
+        const from = versionOf("from") ?? team.version
+        const to: number | "draft" = text(context.url, "to") === "draft" ? "draft" : (versionOf("to") ?? "draft")
+        return ok({ from, to, diff: await teams.diff(context.user.id, team.id, from, to) })
+      },
+    },
+
+    // ---------- staffing ----------
+    {
+      method: "GET",
+      path: `${PREFIX}/:id/staffing`,
+      allow: READ,
+      async handle(context) {
+        const team = await readable(context, true)
+        const ended = boolParam(context.url, "ended") === true
+        return ok({ items: await seats.list(context.user.id, team.id, ended ? {} : { current: true }) })
+      },
+    },
+    {
+      method: "PUT",
+      path: `${PREFIX}/:id/staffing`,
+      allow: STAFF,
+      async handle(context) {
+        appMayStaff(context)
+        const body = await bodyOf(context.request)
+        const key = idempotencyKeyOf(context.request)
+        const { id } = await managed(context)
+        const result = await staffing.attach(context.user.id, context.actor, id, body, key === undefined ? {} : { idempotencyKey: key })
+        if (result.created) await deps.audit?.audit({ actor: context.user.id, action: "team.staff", target: result.staffing.id, detail: context.actor.kind })
+        return storeAnswer(result.created, { staffing: result.staffing, ...(result.workspace ? { workspace: result.workspace } : {}) })
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/:id/staffing/launch`,
+      allow: STAFF,
+      async handle(context) {
+        appMayStaff(context)
+        const body = await bodyOf(context.request)
+        const key = idempotencyKeyOf(context.request)
+        const { id } = await managed(context)
+        const result = await staffing.launch(context.user.id, context.actor, id, body, key === undefined ? {} : { idempotencyKey: key })
+        if (result.created) await deps.audit?.audit({ actor: context.user.id, action: "team.staff.launch", target: result.request.id, detail: context.actor.kind })
+        return storeAnswer(result.created, { request: result.request, launch: result.launch })
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/:id/staffing/:staffing/replace`,
+      allow: STAFF,
+      async handle(context) {
+        appMayStaff(context)
+        const body = await bodyOf(context.request)
+        const { id } = await managed(context)
+        const result = await staffing.replace(context.user.id, context.actor, id, context.params.staffing!, body)
+        await deps.audit?.audit({ actor: context.user.id, action: "team.replace", target: result.ended.id, detail: context.actor.kind })
+        return ok(result)
+      },
+    },
+    {
+      method: "DELETE",
+      path: `${PREFIX}/:id/staffing/:staffing`,
+      allow: STAFF,
+      async handle(context) {
+        appMayStaff(context)
+        const revision = expected(text(context.url, "expectedRevision"))
+        const { id } = await managed(context)
+        const ended = await staffing.unstaff(context.user.id, context.actor, id, context.params.staffing!, revision)
+        await deps.audit?.audit({ actor: context.user.id, action: "team.unstaff", target: ended.id, detail: context.actor.kind })
+        return ok({ staffing: ended })
+      },
+    },
+
+    // ---------- roster and status ----------
+    {
+      method: "GET",
+      path: `${PREFIX}/:id/roster`,
+      allow: READ,
+      async handle(context) {
+        const team = await readable(context, true)
+        return ok({ roster: await staffing.roster(context.user.id, team.id) })
+      },
+    },
+    {
+      method: "GET",
+      path: `${PREFIX}/:id/status`,
+      allow: READ,
+      async handle(context) {
+        const team = await readable(context, true)
+        const roster = await staffing.roster(context.user.id, team.id)
+        const intake = await deps.intake?.summary(context.user.id, team.id)
+        return ok({ team, roster, ...(intake ? { intake } : {}) })
+      },
+    },
+  ]
+}