@huynle/hub 0.7.3 → 0.8.0

package/packages/sdk/src/teams.ts

@@ -0,0 +1,346 @@
+// hub.teams (HWA-37) over /api/agent/teams: assemble and operate persistent teams — definitions (create, list with
+// tag/project/metadata filters, show, draft edits incl. role and policy-edge editing, publish, history and diff,
+// pause/resume, archive/restore), staffing (attach a session, launch a member, replace, unstaff) and status (roster
+// plus intake counts). The intake verbs (submit, intake, intakes, setIntakeStatus) are HWA-36's (team-intake.ts)
+// and part of the same object. `team` is the team's ID (team_…) or its name.
+//
+// Who: users; app tokens with teams:read (reads) or teams:manage (changes) — seats, roster, status and staffing also
+// need sessions:read; staffing by an app or session still needs the user's grants (needs_user otherwise). Session
+// tokens read only the teams they are seated in and never change definitions. Team roles and labels confer no
+// authority. Every change of an existing record sends the revision you read (expectedRevision); creates take an
+// Idempotency-Key. The wire types mirror the hub's records (the SDK imports nothing outside its package; the hub's
+// tests keep them in step).
+import { type TeamIntakeApi, type TeamIntakeTransport, teamIntakeApi } from "./team-intake.ts"
+import type { LaunchSpec, LaunchView } from "./types.ts"
+
+interface Signal {
+  readonly signal?: AbortSignal
+}
+interface Keyed extends Signal {
+  readonly idempotencyKey?: string
+}
+
+export type TeamMode = "open" | "restricted"
+export type TeamMessageKind = "msg" | "ask"
+
+export interface TeamRole {
+  readonly name: string
+  readonly label?: string
+  readonly description?: string
+  /** Holders may contact sessions outside all their teams. */
+  readonly externalContact?: boolean
+  readonly responsibilities?: readonly string[]
+  /** The profile its members should run (staffing reports whether they do; it never pins it). */
+  readonly profile?: { readonly profileID: string; readonly version?: number }
+  /** Placement preferences for staffing launches (advisory). */
+  readonly prefs?: { readonly harness?: string; readonly model?: string; readonly machineID?: string }
+  readonly minMembers?: number
+  readonly maxMembers?: number
+}
+
+/** A communication path: `from` may contact `to` with these kinds (two-way: also back). Restricted mode only. */
+export interface TeamEdge {
+  readonly from: string
+  readonly to: string
+  readonly kinds: readonly TeamMessageKind[]
+  readonly direction: "one-way" | "two-way"
+}
+
+/** The publishable content of a team. */
+export interface TeamSpec {
+  /** Slug used in addresses (`@@role#name`); never changes. */
+  readonly name: string
+  readonly title: string
+  readonly description?: string
+  readonly mode: TeamMode
+  readonly roles: readonly TeamRole[]
+  /** The intake role (e.g. the project manager): receives submitted work and supervises members. */
+  readonly entryRole: string
+  readonly edges: readonly TeamEdge[]
+  readonly tags?: readonly string[]
+  readonly metadata?: Readonly<Record<string, string>>
+  readonly projects?: readonly string[]
+}
+
+/** A team: the published spec plus its record fields. */
+export interface Team extends TeamSpec {
+  readonly v: 1
+  readonly id: string
+  readonly state: "active" | "archived"
+  /** Present while paused: intake and new staffing stop; the policy still applies. */
+  readonly paused?: true
+  /** The published version (1 on create, +1 per publish). */
+  readonly version: number
+  readonly revision: number
+  /** A pending draft (edits are published explicitly). */
+  readonly draft?: { readonly baseVersion: number; readonly digest: string; readonly savedAt: number }
+  readonly createdAt: number
+  readonly publishedAt: number
+  readonly updatedAt: number
+}
+
+export interface TeamDraft {
+  readonly baseVersion: number
+  readonly spec: TeamSpec
+  readonly digest: string
+  readonly savedAt: number
+}
+
+export interface TeamVersionEntry {
+  readonly version: number
+  readonly digest: string
+  readonly publishedAt: number
+}
+
+export interface TeamVersion extends TeamVersionEntry {
+  readonly v: 1
+  readonly teamID: string
+  readonly spec: TeamSpec
+}
+
+/** What changed (names and keys only). Edge keys are `from>to` as drawn. */
+export interface TeamDiff {
+  readonly fields: readonly string[]
+  readonly roles: { readonly added: readonly string[]; readonly removed: readonly string[]; readonly changed: readonly string[] }
+  readonly edges: { readonly added: readonly string[]; readonly removed: readonly string[]; readonly changed: readonly string[] }
+  readonly tags: { readonly added: readonly string[]; readonly removed: readonly string[] }
+  readonly metadata: { readonly added: readonly string[]; readonly removed: readonly string[]; readonly changed: readonly string[] }
+  readonly projects: { readonly added: readonly string[]; readonly removed: readonly string[] }
+}
+
+/** A session staffed in a role; a replacement is the slot's next generation. */
+export interface TeamStaffing {
+  readonly v: 1
+  readonly id: string
+  readonly teamID: string
+  readonly role: string
+  readonly sessionID: string
+  readonly generation: number
+  readonly since: number
+  readonly until?: number
+  readonly revision: number
+  /** The published version it was staffed under. */
+  readonly teamVersion: number
+}
+
+export type TeamSessionPresence = "online" | "offline" | "archived" | "deleted" | "unknown"
+
+export interface TeamStaffingRequest {
+  readonly id: string
+  readonly teamID: string
+  readonly role: string
+  readonly state: "launching" | "staffed" | "failed"
+  readonly by: string
+  readonly launchID?: string
+  readonly replaces?: { readonly staffingID: string; readonly generation: number }
+  readonly sessionID?: string
+  readonly machineID?: string
+  readonly staffingID?: string
+  readonly reason?: string
+  readonly createdAt: number
+  readonly updatedAt: number
+}
+
+export interface TeamWorkspaceLink {
+  readonly id: string
+  readonly state: "active" | "archived" | "missing"
+}
+
+export interface TeamRosterSeat {
+  readonly staffing: TeamStaffing
+  readonly presence: TeamSessionPresence
+  readonly memberID?: string
+  readonly supervisorMemberID?: string
+  readonly profile?: {
+    readonly requested: { readonly profileID: string; readonly version?: number }
+    readonly assigned?: { readonly profileID: string; readonly version: number }
+    readonly status: string
+    readonly matches: boolean
+  }
+}
+
+export interface TeamRosterRole {
+  readonly role: string
+  readonly entry: boolean
+  readonly minMembers: number
+  readonly maxMembers: number
+  readonly seats: readonly TeamRosterSeat[]
+  readonly launching: number
+  readonly online: number
+  readonly offline: number
+  readonly vacant: boolean
+  readonly understaffed: boolean
+}
+
+export interface TeamRoster {
+  readonly teamID: string
+  readonly version: number
+  readonly state: "active" | "archived"
+  readonly paused: boolean
+  readonly workspace?: TeamWorkspaceLink
+  readonly roles: readonly TeamRosterRole[]
+  readonly requests: readonly TeamStaffingRequest[]
+}
+
+/** Intake counts (no text): by status, and routed items by progress. Closed items count while retained. */
+export interface TeamIntakeSummary {
+  readonly queued: number
+  readonly routed: number
+  readonly done: number
+  readonly cancelled: number
+  readonly failed: number
+  readonly open: number
+  readonly inProgress: number
+  readonly blocked: number
+  readonly oldestQueuedAt?: number
+}
+
+export interface TeamStatus {
+  readonly team: Team
+  readonly roster: TeamRoster
+  readonly intake?: TeamIntakeSummary
+}
+
+/** The owner's team settings (users only; app and session tokens are refused). */
+export interface TeamSettings {
+  /** On: team members see only the sessions of their teams (non-team sessions are hidden from them). */
+  readonly teamIsolation: boolean
+  /** 0 while never set; send it back as expectedRevision. */
+  readonly revision: number
+  readonly updatedAt?: number
+}
+
+export interface TeamListFilter extends Signal {
+  /** active (default), archived or all. */
+  readonly state?: "active" | "archived" | "all"
+  /** Teams carrying every one of these tags. */
+  readonly tags?: readonly string[]
+  readonly project?: string
+  /** Teams whose metadata has every one of these pairs. */
+  readonly metadata?: Readonly<Record<string, string>>
+  readonly paused?: boolean
+  readonly limit?: number
+  readonly cursor?: string
+}
+
+/** Spec fields a draft edit may change (the name never changes; null clears an optional field). */
+export type TeamPatch = { readonly [K in Exclude<keyof TeamSpec, "name">]?: TeamSpec[K] | null }
+
+export interface Page<T> {
+  readonly items: readonly T[]
+  readonly cursor?: string
+}
+
+export interface Teams extends TeamIntakeApi {
+  create(spec: TeamSpec, options?: Keyed): Promise<{ team: Team; created: boolean }>
+  list(filter?: TeamListFilter): Promise<Page<Team>>
+  get(team: string, options?: Signal): Promise<{ team: Team; draft?: TeamDraft }>
+  /** Saves edits as the draft; with `publish: true` publishes it at once. */
+  update(team: string, patch: TeamPatch, expectedRevision: number, options?: Signal & { readonly publish?: boolean }): Promise<{ team: Team; published?: boolean }>
+  draft(team: string, options?: Signal): Promise<{ draft: TeamDraft }>
+  discardDraft(team: string, expectedRevision: number, options?: Signal): Promise<{ team: Team }>
+  /** Adds the role to the draft, or replaces the role of that name. */
+  setRole(team: string, role: TeamRole, expectedRevision: number, options?: Signal): Promise<{ team: Team; draft: TeamDraft }>
+  /** Removes a role (not the entry role) and its edges from the draft. */
+  removeRole(team: string, role: string, expectedRevision: number, options?: Signal): Promise<{ team: Team; draft: TeamDraft }>
+  /** Draws (or replaces) the edge from → to in the draft. */
+  setEdge(team: string, edge: TeamEdge, expectedRevision: number, options?: Signal): Promise<{ team: Team; draft: TeamDraft }>
+  removeEdge(team: string, from: string, to: string, expectedRevision: number, options?: Signal): Promise<{ team: Team; draft: TeamDraft }>
+  /** Publishes the draft as the next version (published false: it equalled the published spec). */
+  publish(team: string, expectedRevision: number, options?: Signal): Promise<{ team: Team; published: boolean }>
+  pause(team: string, expectedRevision: number, options?: Signal): Promise<{ team: Team }>
+  resume(team: string, expectedRevision: number, options?: Signal): Promise<{ team: Team }>
+  archive(team: string, expectedRevision: number, options?: Signal): Promise<{ team: Team }>
+  restore(team: string, expectedRevision: number, options?: Signal): Promise<{ team: Team }>
+  versions(team: string, options?: Signal & { readonly limit?: number; readonly cursor?: string }): Promise<Page<TeamVersionEntry>>
+  version(team: string, version: number, options?: Signal): Promise<{ version: TeamVersion }>
+  /** From a version (default: the published one) to another version or the draft (default). */
+  diff(team: string, options?: Signal & { readonly from?: number; readonly to?: number | "draft" }): Promise<{ from: number; to: number | "draft"; diff: TeamDiff }>
+  /** Current seats (with ended ones on `ended`). */
+  staffing(team: string, options?: Signal & { readonly ended?: boolean }): Promise<{ items: readonly TeamStaffing[] }>
+  /** Staffs an existing session in a role (the same role and session again: its seat, created false). */
+  staff(team: string, input: { readonly role: string; readonly sessionID: string }, options?: Keyed): Promise<{ staffing: TeamStaffing; workspace?: TeamWorkspaceLink; created: boolean }>
+  /** Launches a new member for a role through the launch API; the running session is staffed. */
+  launchMember(team: string, input: { readonly role: string; readonly launch: LaunchSpec }, options?: Keyed): Promise<{ request: TeamStaffingRequest; launch: LaunchView; created: boolean }>
+  /** Replaces a seat by an existing session or a launch; the old seat ends at once. */
+  replace(
+    team: string,
+    staffingID: string,
+    input: { readonly expectedRevision: number } & ({ readonly sessionID: string; readonly launch?: never } | { readonly launch: LaunchSpec; readonly sessionID?: never }),
+    options?: Signal,
+  ): Promise<{ ended: TeamStaffing; staffing?: TeamStaffing; request?: TeamStaffingRequest; launch?: LaunchView }>
+  unstaff(team: string, staffingID: string, expectedRevision: number, options?: Signal): Promise<{ staffing: TeamStaffing }>
+  roster(team: string, options?: Signal): Promise<{ roster: TeamRoster }>
+  /** The team, its roster and intake counts. */
+  status(team: string, options?: Signal): Promise<TeamStatus>
+  /** The owner's team settings (GET /api/agent/team-settings; users only). */
+  settings(options?: Signal): Promise<{ settings: TeamSettings }>
+  /** Changes them under CAS (expectedRevision 0 when never set). */
+  setSettings(input: { readonly teamIsolation: boolean }, expectedRevision: number, options?: Signal): Promise<{ settings: TeamSettings }>
+}
+
+type Query = Readonly<Record<string, string | number | readonly string[] | undefined>>
+
+/** What hub.teams needs from the client (HubClient's request and call); queries may repeat a key (arrays). */
+export interface TeamsTransport extends TeamIntakeTransport {
+  request(method: string, pathname: string, options?: { readonly query?: Query; readonly body?: unknown; readonly headers?: Readonly<Record<string, string>>; readonly signal?: AbortSignal }): Promise<Response>
+  call<T>(method: string, pathname: string, options?: { readonly query?: Query; readonly body?: unknown; readonly signal?: AbortSignal }): Promise<T>
+}
+
+const seg = (value: string) => encodeURIComponent(value)
+const sig = (options: Signal = {}) => (options.signal ? { signal: options.signal } : {})
+const key = (options: Keyed = {}) => (options.idempotencyKey ? { headers: { "idempotency-key": options.idempotencyKey } } : {})
+const base = (team: string) => `/api/agent/teams/${seg(team)}`
+
+export function teamsApi(hub: TeamsTransport): Teams {
+  const created = async <T>(method: string, pathname: string, body: unknown, options: Keyed = {}): Promise<T & { created: boolean }> => {
+    const response = await hub.request(method, pathname, { body, ...key(options), ...sig(options) })
+    return { ...((await response.json()) as T), created: response.status === 201 }
+  }
+  const revised = (verb: string) => (team: string, expectedRevision: number, options?: Signal) => hub.call<{ team: Team }>("POST", `${base(team)}/${verb}`, { body: { expectedRevision }, ...sig(options) })
+  return {
+    ...teamIntakeApi(hub),
+    create: (spec, options) => created("POST", "/api/agent/teams", spec, options),
+    list: (filter = {}) =>
+      hub.call("GET", "/api/agent/teams", {
+        query: {
+          state: filter.state,
+          tag: filter.tags,
+          project: filter.project,
+          metadata: filter.metadata ? Object.entries(filter.metadata).map(([k, v]) => `${k}=${v}`) : undefined,
+          paused: filter.paused === undefined ? undefined : String(filter.paused),
+          limit: filter.limit,
+          cursor: filter.cursor,
+        },
+        ...sig(filter),
+      }),
+    get: (team, options) => hub.call("GET", base(team), sig(options)),
+    update: (team, patch, expectedRevision, options = {}) => hub.call("PATCH", base(team), { body: { ...patch, expectedRevision, ...(options.publish ? { publish: true } : {}) }, ...sig(options) }),
+    draft: (team, options) => hub.call("GET", `${base(team)}/draft`, sig(options)),
+    discardDraft: (team, expectedRevision, options) => hub.call("DELETE", `${base(team)}/draft`, { query: { expectedRevision }, ...sig(options) }),
+    setRole: (team, role, expectedRevision, options) => {
+      const { name, ...fields } = role
+      return hub.call("PUT", `${base(team)}/draft/roles/${seg(name)}`, { body: { ...fields, expectedRevision }, ...sig(options) })
+    },
+    removeRole: (team, role, expectedRevision, options) => hub.call("DELETE", `${base(team)}/draft/roles/${seg(role)}`, { query: { expectedRevision }, ...sig(options) }),
+    setEdge: (team, edge, expectedRevision, options) => hub.call("PUT", `${base(team)}/draft/edges`, { body: { ...edge, expectedRevision }, ...sig(options) }),
+    removeEdge: (team, from, to, expectedRevision, options) => hub.call("DELETE", `${base(team)}/draft/edges`, { query: { from, to, expectedRevision }, ...sig(options) }),
+    publish: (team, expectedRevision, options) => hub.call("POST", `${base(team)}/publish`, { body: { expectedRevision }, ...sig(options) }),
+    pause: revised("pause"),
+    resume: revised("resume"),
+    archive: revised("archive"),
+    restore: revised("restore"),
+    versions: (team, options = {}) => hub.call("GET", `${base(team)}/versions`, { query: { limit: options.limit, cursor: options.cursor }, ...sig(options) }),
+    version: (team, version, options) => hub.call("GET", `${base(team)}/versions/${version}`, sig(options)),
+    diff: (team, options = {}) => hub.call("GET", `${base(team)}/diff`, { query: { from: options.from, to: options.to }, ...sig(options) }),
+    staffing: (team, options = {}) => hub.call("GET", `${base(team)}/staffing`, { query: { ended: options.ended ? 1 : undefined }, ...sig(options) }),
+    staff: (team, input, options) => created("PUT", `${base(team)}/staffing`, input, options),
+    launchMember: (team, input, options) => created("POST", `${base(team)}/staffing/launch`, input, options),
+    replace: (team, staffingID, input, options) => hub.call("POST", `${base(team)}/staffing/${seg(staffingID)}/replace`, { body: input, ...sig(options) }),
+    unstaff: (team, staffingID, expectedRevision, options) => hub.call("DELETE", `${base(team)}/staffing/${seg(staffingID)}`, { query: { expectedRevision }, ...sig(options) }),
+    roster: (team, options) => hub.call("GET", `${base(team)}/roster`, sig(options)),
+    status: (team, options) => hub.call("GET", `${base(team)}/status`, sig(options)),
+    settings: (options) => hub.call("GET", "/api/agent/team-settings", sig(options)),
+    setSettings: (input, expectedRevision, options) => hub.call("PUT", "/api/agent/team-settings", { body: { teamIsolation: input.teamIsolation, expectedRevision }, ...sig(options) }),
+  }
+}