@huynle/hub 0.7.3 → 0.8.0

package/src/central/store.ts

@@ -126,6 +126,8 @@ export interface PushPrefs {
    * (once per run), or a retry for a quota, free-tier or auth error. Replaces the root's "failed" for that failure.
    */
   providerError: boolean
+  /** (CON-04) The Concierge needs you: its questions, permissions, Decisions, messages and spoken replies (opens /concierge). */
+  concierge: boolean
 }
 
 export const PUSH_PREF_KEYS = [
@@ -147,6 +149,7 @@ export const PUSH_PREF_KEYS = [
   "decision",
   "message",
   "providerError",
+  "concierge",
 ] as const satisfies readonly (keyof PushPrefs)[]
 
 /** Defaults: anything that needs you, all done, failed, hand-offs and spoken replies; the finer kinds are opt-in. */
@@ -170,6 +173,7 @@ export const DEFAULT_PUSH_PREFS: Readonly<PushPrefs> = Object.freeze({
   decision: true,
   message: true,
   providerError: true,
+  concierge: true,
 })
 
 /** Default and allowed range of a device's activity update interval, in minutes. */

package/src/central/teams/collections.ts

@@ -0,0 +1,34 @@
+// Shared storage shapes of the team modules (HWA-33): the staffing aggregate is read by the definition store (a
+// publish must not drop a staffed role) and owned by seats.ts.
+import { CONTRACT_VERSION, type TeamStaffing } from "../../protocol"
+import { AgentError } from "../agent/errors"
+
+/** One aggregate per team (key: team ID): its staffing records, current and ended, and the staffing Idempotency-Keys. */
+export const TEAM_SEATS = "team-seats"
+
+export interface SeatKey {
+  readonly staffingID: string
+  readonly digest: string
+  readonly at: number
+}
+
+export interface SeatsDoc {
+  readonly v: 1
+  readonly teamID: string
+  readonly seats: readonly TeamStaffing[]
+  readonly keys: Readonly<Record<string, SeatKey>>
+}
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/** The stored staffing aggregate (undefined when missing); newer versions are unsupported, malformed ones internal. */
+export function readSeatsDoc(raw: unknown, teamID: string): SeatsDoc | undefined {
+  if (raw === undefined) return undefined
+  if (isObj(raw) && typeof raw.v === "number" && raw.v > CONTRACT_VERSION)
+    throw new AgentError("unsupported", `The staffing of team ${teamID} was written by a newer hub`, { hint: "Upgrade this hub", extra: { feature: "team-staffing" } })
+  if (!isObj(raw) || raw.v !== CONTRACT_VERSION || raw.teamID !== teamID || !Array.isArray(raw.seats)) throw new AgentError("internal", `Stored staffing of team ${teamID} is malformed`)
+  return { v: 1, teamID, seats: raw.seats as TeamStaffing[], keys: isObj(raw.keys) ? (raw.keys as Record<string, SeatKey>) : {} }
+}
+
+/** Current seats (not ended). */
+export const currentSeats = (doc: SeatsDoc | undefined): TeamStaffing[] => (doc?.seats ?? []).filter((s) => s.until === undefined)

package/src/central/teams/discovery.ts

@@ -0,0 +1,346 @@
+// Team-aware discovery (HWA-40; contract docs/plans/2026-10-30-hub-workspaces-artifacts-contracts.md, Teams
+// "Discovery (HWA-40)"; decisions zltiwb4s 2026-10-28 addition, r3vv4eon (+correction), 5etngvgm, qxzrdc6c).
+//
+// Who sees whom, for who / status / sessions / show / log / watch (with or without ?session=) and events:
+// - A session caller holding a seat in at least one ACTIVE team (paused teams count; archived ones do not — the same
+//   rule teamDeliveryVerdict uses) is team-scoped: it sees itself, every current member of its teams (grouped by team,
+//   with each member's roles there) and, unless the owner turned `teamIsolation` on, sessions in no active team.
+//   Sessions seated only in teams the caller is not in are invisible; so are the caller's teammates' seats in teams
+//   the caller is not in (never listed). Under isolation, sessions in no team are hidden too.
+// - Sessions in no active team, the user (console/device) and app tokens keep today's owner-wide view (r3vv4eon),
+//   whatever teamIsolation says (the frozen contract: isolation hides non-team sessions FROM TEAM MEMBERS only).
+//   They may filter by team. Without any team the answers are exactly today's.
+// - An invisible session reads exactly like a foreign or unknown one: not_found "No session <addr>", and address
+//   resolution never counts it (no ambiguity, no candidate, no prefix match reveals it): Directory.resolve takes the
+//   visibility predicate for that.
+// - Every census reads the teams and seats fresh (no cache), so staffing, unstaffing, replacement generations,
+//   pause/archive and the isolation setting apply to the very next read.
+//
+// Directions: `reach` is what the caller may send to a member (`send`) and receive from it (`receive`), each kind
+// asked of teamDeliveryVerdict (never re-derived): per team with that team as the explicit context (the `#team`
+// address), and per entry without one (a plain address). Visibility is not authorization: delivery is still enforced
+// by the TeamPolicy (HWA-34) and acting by grants.
+//
+// Team role addresses (`@@role#team`, `@@role.project#team`) resolve here for reads (show, log, watch): the sessions
+// currently seated in that role of that active team, restricted to what the caller may see.
+//
+// Cost per census: one team list (paged, ≤ TEAM_LIMITS.teamsPerUser) and one current-seat read per active team, plus
+// the settings for team-scoped callers.
+import { parseTeamRoleAddress, teamDeliveryVerdict, type TeamMessageKind, type TeamSeat } from "../../protocol"
+import type { AgentActor } from "../agent/actor"
+import type { Directory, DirectoryEntry, Resolved } from "../agent/directory"
+import { AgentError } from "../agent/errors"
+import type { Registry } from "../registry"
+import type { TeamSeatStore } from "./seats"
+import type { Team, TeamStore } from "./store"
+
+const KINDS: readonly TeamMessageKind[] = ["msg", "ask"]
+/** Pages of the team list read per census (teamsPerUser is 100; a page holds the list's default limit). */
+const MAX_TEAM_PAGES = 20
+/** Most candidates listed in an ambiguous error (as the directory). */
+const CANDIDATES_MAX = 20
+
+/** What the caller may send to / receive from a session, from teamDeliveryVerdict. */
+export interface Reach {
+  readonly send: TeamMessageKind[]
+  readonly receive: TeamMessageKind[]
+  readonly direction: "two-way" | "outbound" | "inbound" | "none"
+  /** The caller can send nothing to it (a restricted path, or outside the caller's teams). */
+  readonly unreachable?: true
+}
+
+/** One team a listed session is seated in. */
+export interface TeamMembership {
+  readonly teamID: string
+  readonly team: string
+  readonly roles: string[]
+  /** Team-scoped callers only, never for themselves: with this team as the explicit context. */
+  readonly reach?: Reach
+}
+
+export interface TeamGroupMember {
+  readonly sessionID: string
+  readonly role: string
+  readonly generation: number
+}
+
+/** A team in a discovery answer, with its listed members. */
+export interface TeamGroup {
+  readonly teamID: string
+  readonly name: string
+  readonly title: string
+  readonly mode: "open" | "restricted"
+  readonly paused?: true
+  /** The caller's own roles there (team-scoped callers). */
+  readonly yourRoles?: string[]
+  readonly members: TeamGroupMember[]
+}
+
+/** A who entry: the directory entry plus additive team fields. */
+export type DiscoveryEntry = DirectoryEntry & {
+  readonly harness?: string
+  readonly teams?: TeamMembership[]
+  /** Team-scoped callers only, never for themselves: what a plain address (no #team) reaches. */
+  readonly reach?: Reach
+}
+
+export interface WhoAnswer {
+  readonly sessions: DiscoveryEntry[]
+  /** Present when any listed session is seated in a team (always for team-scoped callers). */
+  readonly teams?: TeamGroup[]
+  /** "team" when the caller sees its teams only; absent for the owner-wide view. */
+  readonly scope?: "team"
+}
+
+export interface WhoFilter {
+  readonly project?: string
+  readonly role?: string
+  /** A team name or ID. */
+  readonly team?: string
+}
+
+interface Seat extends TeamSeat {
+  readonly generation: number
+}
+
+/** One read of the user's active teams and current seats, and what the caller may see. */
+export interface Census {
+  readonly userID: string
+  /** Set when the caller is team-scoped. */
+  readonly callerID?: string
+  readonly callerTeams: ReadonlySet<string>
+  readonly isolation: boolean
+  readonly teams: ReadonlyMap<string, Team>
+  /** Current seats in active teams, per session. */
+  readonly seats: ReadonlyMap<string, readonly Seat[]>
+}
+
+export interface TeamDiscoveryDeps {
+  readonly teams: Pick<TeamStore, "list" | "settings">
+  readonly seats: Pick<TeamSeatStore, "list">
+  readonly directory: Pick<Directory, "who" | "resolve">
+  /** Harness per reported session of the user (who entries carry it when known). */
+  readonly harnesses?: (userID: string) => ReadonlyMap<string, string>
+}
+
+export const teamScoped = (census: Census): boolean => census.callerTeams.size > 0
+
+/** Whether the census's caller may see the session (always, for the owner-wide view). */
+export function visible(census: Census, sessionID: string): boolean {
+  if (!teamScoped(census) || sessionID === census.callerID) return true
+  const seats = census.seats.get(sessionID) ?? []
+  if (seats.some((s) => census.callerTeams.has(s.teamID))) return true
+  return !census.isolation && seats.length === 0
+}
+
+const missing = (addr: string) => new AgentError("not_found", `No session ${addr}`)
+
+/** Journal subject fields that name a session (an event naming any hidden one is hidden as a whole). */
+const SESSION_SUBJECT_FIELDS = ["sessionID", "rootID", "senderID", "recipientID", "sourceSessionID", "parentID"] as const
+
+/**
+ * The journal events a team-scoped caller may read (unfiltered GET /events and GET /watch, HWA-28): none naming a
+ * session it cannot see, nor a team it holds no seat in. Undefined for the owner-wide view (no filtering at all).
+ */
+export function eventVisibility(census: Census): ((subject: Readonly<Record<string, string>>) => boolean) | undefined {
+  if (!teamScoped(census)) return undefined
+  return (subject) => {
+    if (subject.teamID !== undefined && !census.callerTeams.has(subject.teamID)) return false
+    return SESSION_SUBJECT_FIELDS.every((field) => subject[field] === undefined || visible(census, subject[field]!))
+  }
+}
+
+export class TeamDiscovery {
+  constructor(private readonly deps: TeamDiscoveryDeps) {}
+
+  /** Reads the user's active teams, their current seats and the caller's scope. */
+  async census(userID: string, actor: AgentActor): Promise<Census> {
+    const teams = new Map<string, Team>()
+    let cursor: string | undefined
+    for (let page = 0; page < MAX_TEAM_PAGES; page++) {
+      const { items, cursor: next } = await this.deps.teams.list(userID, { state: "active", ...(cursor ? { cursor } : {}) })
+      for (const team of items) teams.set(team.id, team)
+      if (!next) break
+      cursor = next
+    }
+    const seats = new Map<string, Seat[]>()
+    for (const teamID of [...teams.keys()]) {
+      let current
+      try {
+        current = await this.deps.seats.list(userID, teamID, { current: true })
+      } catch {
+        teams.delete(teamID) // a seat aggregate this build cannot read takes no part (as in delivery)
+        continue
+      }
+      for (const s of current) seats.set(s.sessionID, [...(seats.get(s.sessionID) ?? []), { teamID, role: s.role, generation: s.generation }])
+    }
+    const callerID = actor.kind === "session" ? actor.sessionID : undefined
+    const callerTeams = new Set((callerID !== undefined ? (seats.get(callerID) ?? []) : []).map((s) => s.teamID))
+    let isolation = false
+    if (callerTeams.size) {
+      try {
+        isolation = (await this.deps.teams.settings(userID)).teamIsolation
+      } catch {
+        isolation = true // unreadable settings: show less, never more
+      }
+    }
+    return { userID, ...(callerTeams.size ? { callerID } : {}), callerTeams, isolation, teams, seats }
+  }
+
+  /**
+   * The sessions an address names for the caller (Directory.resolve plus `@@role#team`), never an invisible one.
+   * not_found when nothing visible matches; ambiguous lists visible candidates only.
+   */
+  resolve(census: Census, addr: string): Resolved {
+    const team = parseTeamRoleAddress(addr)
+    if (!team) return this.deps.directory.resolve(census.userID, addr, { visible: (id) => visible(census, id) })
+    const record = [...census.teams.values()].find((t) => t.name === team.team)
+    if (!record || (teamScoped(census) && !census.callerTeams.has(record.id))) throw missing(addr)
+    const sessions: DirectoryEntry[] = []
+    for (const [sessionID, seats] of census.seats) {
+      if (!seats.some((s) => s.teamID === record.id && s.role === team.role) || !visible(census, sessionID)) continue
+      const entry = this.entry(census.userID, sessionID)
+      if (entry && (team.project === undefined || entry.project === team.project)) sessions.push(entry)
+    }
+    if (!sessions.length) throw missing(addr)
+    return { address: { kind: "role", role: team.role, ...(team.project ? { project: team.project } : {}) }, sessions }
+  }
+
+  /** Exactly one visible session (a role with several visible holders is ambiguous). */
+  resolveOne(census: Census, addr: string): DirectoryEntry {
+    const { sessions } = this.resolve(census, addr)
+    if (sessions.length > 1) {
+      const candidates = sessions.slice(0, CANDIDATES_MAX).map((s) => ({ sessionID: s.sessionID, ...(s.name ? { name: s.name } : {}), ...(s.project ? { project: s.project } : {}) }))
+      throw new AgentError("ambiguous", `${addr} matches ${sessions.length} sessions`, { extra: { candidates } })
+    }
+    return sessions[0]!
+  }
+
+  /** GET /who: the caller's visible sessions, filtered, with team memberships, reach and groups. */
+  who(census: Census, filter: WhoFilter = {}): WhoAnswer {
+    const { userID } = census
+    const project = filter.project?.toLowerCase()
+    let role = filter.role?.replace(/^@@/, "")
+    let teamName = filter.team
+    if (role?.includes("#")) {
+      const parsed = parseTeamRoleAddress(`@@${role}`)
+      if (!parsed) throw new AgentError("invalid", "A role is 2–40 characters: a-z, 0-9 and -, optionally .project and #team")
+      if (teamName !== undefined && teamName !== parsed.team) throw new AgentError("invalid", "role names another team than team")
+      role = parsed.project ? `${parsed.role}.${parsed.project}` : parsed.role
+      teamName = parsed.team
+    }
+    const team = teamName !== undefined ? this.team(census, teamName) : undefined
+    const [roleName, inlineProject] = role?.split(".") ?? []
+    const roleProject = inlineProject?.toLowerCase() ?? project
+    // Global role holders (Directory.who validates the role) and the base list.
+    const globalHolders = role !== undefined ? new Set(this.deps.directory.who(userID, { ...(project ? { project } : {}), role }).map((e) => e.sessionID)) : undefined
+    const listed = new Map(this.deps.directory.who(userID, project ? { project } : {}).map((e) => [e.sessionID, e] as const))
+    // Seated members the directory does not list (offline, unnamed): every teammate, and a filtered team's members.
+    const extra = new Set(team ? [team.id] : [...census.callerTeams])
+    for (const [sessionID, seats] of census.seats) {
+      if (listed.has(sessionID) || !seats.some((s) => extra.has(s.teamID))) continue
+      const entry = this.entry(userID, sessionID)
+      if (entry && !entry.archived && (project === undefined || entry.project === project || entry.roles.some((r) => r.project === project))) listed.set(sessionID, entry)
+    }
+    const entries = [...listed.values()]
+      .filter((e) => visible(census, e.sessionID))
+      .filter((e) => !team || this.shown(census, e.sessionID).some((s) => s.teamID === team.id))
+      .filter((e) => {
+        if (role === undefined) return true
+        const seated = this.shown(census, e.sessionID).some((s) => s.role === roleName && (!team || s.teamID === team.id) && (roleProject === undefined || e.project === roleProject))
+        return seated || (!team && globalHolders!.has(e.sessionID))
+      })
+    const harnesses = this.deps.harnesses?.(userID)
+    const sessions = entries.map((e) => this.annotate(census, e, harnesses?.get(e.sessionID)))
+    const teams = this.groups(census, sessions.map((s) => s.sessionID), team?.id)
+    return { sessions, ...(teams.length ? { teams } : {}), ...(teamScoped(census) ? { scope: "team" as const } : {}) }
+  }
+
+  /** Team groups of the listed sessions (the caller's teams only, all of them, when team-scoped), by team name. */
+  groups(census: Census, sessionIDs: readonly string[], only?: string): TeamGroup[] {
+    const out = new Map<string, TeamGroupMember[]>()
+    if (teamScoped(census)) for (const teamID of census.callerTeams) if (only === undefined || only === teamID) out.set(teamID, [])
+    for (const id of sessionIDs) {
+      for (const s of this.shown(census, id)) {
+        if (only !== undefined && s.teamID !== only) continue
+        out.set(s.teamID, [...(out.get(s.teamID) ?? []), { sessionID: id, role: s.role, generation: s.generation }])
+      }
+    }
+    return [...out]
+      .map(([teamID, members]) => {
+        const team = census.teams.get(teamID)!
+        const yours = census.callerID !== undefined ? (census.seats.get(census.callerID) ?? []).filter((s) => s.teamID === teamID).map((s) => s.role) : []
+        return { teamID, name: team.name, title: team.title, mode: team.mode, ...(team.paused ? { paused: true as const } : {}), ...(yours.length ? { yourRoles: yours } : {}), members }
+      })
+      .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
+  }
+
+  /** The session's team memberships as the caller may see them (show), each with reach when team-scoped. */
+  memberships(census: Census, sessionID: string): TeamMembership[] {
+    const byTeam = new Map<string, string[]>()
+    for (const s of this.shown(census, sessionID)) byTeam.set(s.teamID, [...(byTeam.get(s.teamID) ?? []), s.role])
+    return [...byTeam].map(([teamID, roles]) => {
+      const reach = this.reachOf(census, sessionID, teamID)
+      return { teamID, team: census.teams.get(teamID)!.name, roles, ...(reach ? { reach } : {}) }
+    })
+  }
+
+  /** What a team-scoped caller may send to / receive from the session (undefined otherwise, and for itself). */
+  reachOf(census: Census, sessionID: string, teamID?: string): Reach | undefined {
+    const caller = census.callerID
+    if (!teamScoped(census) || caller === undefined || sessionID === caller) return undefined
+    const mine = census.seats.get(caller) ?? []
+    const theirs = census.seats.get(sessionID) ?? []
+    const allowed = (from: readonly Seat[], to: readonly Seat[], kind: TeamMessageKind) =>
+      teamDeliveryVerdict({ kind, toUser: false, replyToPermittedAsk: false, senderSeats: from, recipientSeats: to, ...(teamID !== undefined ? { teamID } : {}), teams: census.teams }).allow
+    const send = KINDS.filter((k) => allowed(mine, theirs, k))
+    const receive = KINDS.filter((k) => allowed(theirs, mine, k))
+    const direction = send.length && receive.length ? "two-way" : send.length ? "outbound" : receive.length ? "inbound" : "none"
+    return { send, receive, direction, ...(send.length ? {} : { unreachable: true as const }) }
+  }
+
+  // ---------- internals ----------
+
+  /** The seats of a session the caller may be told about: in its own teams when team-scoped, else all. */
+  private shown(census: Census, sessionID: string): readonly Seat[] {
+    const seats = census.seats.get(sessionID) ?? []
+    return teamScoped(census) ? seats.filter((s) => census.callerTeams.has(s.teamID)) : seats
+  }
+
+  private annotate(census: Census, entry: DirectoryEntry, harness: string | undefined): DiscoveryEntry {
+    const teams = this.memberships(census, entry.sessionID)
+    const reach = this.reachOf(census, entry.sessionID)
+    return { ...entry, ...(harness ? { harness } : {}), ...(teams.length ? { teams } : {}), ...(reach ? { reach } : {}) }
+  }
+
+  /** A team filter: by name or ID, among the caller's teams when team-scoped (else not_found, like a missing one). */
+  private team(census: Census, nameOrID: string): Team {
+    const team = census.teams.get(nameOrID) ?? [...census.teams.values()].find((t) => t.name === nameOrID)
+    if (!team || (teamScoped(census) && !census.callerTeams.has(team.id))) throw new AgentError("not_found", `No team ${nameOrID}`)
+    return team
+  }
+
+  private entry(userID: string, sessionID: string): DirectoryEntry | undefined {
+    try {
+      return this.deps.directory.resolve(userID, sessionID).sessions.find((e) => e.sessionID === sessionID)
+    } catch {
+      return undefined
+    }
+  }
+}
+
+/** The harness of each session the user's spokes report now (roots and their subagents), from the catalog. */
+export function catalogHarnesses(registry: Pick<Registry, "catalog" | "sessionTenant">): (userID: string) => ReadonlyMap<string, string> {
+  return (userID) => {
+    const out = new Map<string, string>()
+    for (const machine of registry.catalog()) {
+      for (const process of machine.processes) {
+        for (const s of process.sessions) {
+          if (registry.sessionTenant(s.id) !== userID) continue
+          for (const id of [s.id, ...s.status.map((e) => e.id)]) if (!out.has(id)) out.set(id, process.harness)
+        }
+      }
+    }
+    return out
+  }
+}

package/src/central/teams/draft-edits.ts

@@ -0,0 +1,46 @@
+// Role and policy-edge editing of a team's draft (HWA-37): small edits computed against the current draft spec (or
+// the published one) and saved through TeamStore.saveDraft, which validates the whole spec again. Nothing here
+// publishes: delivery and staffing keep using the published version until an explicit publish.
+//
+// - setRole: adds the role, or replaces the role of that name wholesale (its other fields are dropped).
+// - removeRole: drops the role and every edge touching it; the entry role cannot be removed (name another first).
+// - setEdge: replaces the edge drawn from → to (and, for a two-way edge, the one drawn to → from). An edge drawn the
+//   other way that already covers the pair is refused by the spec check (one edge per ordered pair).
+// - removeEdge: drops the edge drawn from → to, or a two-way edge drawn to → from.
+import { AgentError } from "../agent/errors"
+import type { TeamSpec } from "./validation"
+
+const isObj = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v)
+
+/** A patch replacing the roles (and edges) for saveDraft. */
+export interface DraftEdit {
+  readonly roles?: readonly unknown[]
+  readonly edges?: readonly unknown[]
+}
+
+export function setRole(spec: TeamSpec, name: string, fields: Record<string, unknown>): DraftEdit {
+  if (fields.name !== undefined && fields.name !== name) throw new AgentError("invalid", "The role's name is in the path; to rename, add the new role and remove the old one")
+  const role = { ...fields, name }
+  const at = spec.roles.findIndex((r) => r.name === name)
+  const roles = at < 0 ? [...spec.roles, role] : spec.roles.map((r, i) => (i === at ? role : r))
+  return { roles }
+}
+
+export function removeRole(spec: TeamSpec, name: string): DraftEdit {
+  if (!spec.roles.some((r) => r.name === name)) throw new AgentError("not_found", `The draft has no role ${name.slice(0, 40)}`)
+  if (spec.entryRole === name) throw new AgentError("invalid", `${name} is the entry role`, { hint: "Name another entry role first (team update entryRole)" })
+  return { roles: spec.roles.filter((r) => r.name !== name), edges: spec.edges.filter((e) => e.from !== name && e.to !== name) }
+}
+
+export function setEdge(spec: TeamSpec, edge: Record<string, unknown>): DraftEdit {
+  if (!isObj(edge) || typeof edge.from !== "string" || typeof edge.to !== "string") throw new AgentError("invalid", "An edge needs from and to (role names)")
+  const { from, to } = edge
+  const replaced = (e: TeamSpec["edges"][number]) => (e.from === from && e.to === to) || (edge.direction === "two-way" && e.from === to && e.to === from)
+  return { edges: [...spec.edges.filter((e) => !replaced(e)), edge] }
+}
+
+export function removeEdge(spec: TeamSpec, from: string, to: string): DraftEdit {
+  const drop = (e: TeamSpec["edges"][number]) => (e.from === from && e.to === to) || (e.direction === "two-way" && e.from === to && e.to === from)
+  if (!spec.edges.some(drop)) throw new AgentError("not_found", `The draft has no edge ${from.slice(0, 40)} → ${to.slice(0, 40)}`)
+  return { edges: spec.edges.filter((e) => !drop(e)) }
+}

package/src/central/teams/events.ts

@@ -0,0 +1,46 @@
+// Compact journal events of teams (HWA-33; contract TEAM_EVENT_TYPES, family `manage`). Allowlisted payloads only:
+// IDs, enums (state, change), revisions, version numbers, generations and flags. Never names, titles, descriptions,
+// role names or labels, responsibilities, tags, metadata, projects or any other definition text. The routes
+// (HWA-37) emit them after a store call succeeds; HWA-34 owns `team.denied`, HWA-36 `team.intake`.
+import type { EventInput } from "../agent/events"
+import type { TeamSeatRecord } from "./seats"
+import type { Team } from "./store"
+
+/** What a `team.updated` changed. */
+export type TeamChange = "draft" | "draft_discarded" | "published" | "paused" | "resumed"
+
+export const teamCreatedEvent = (team: Team): EventInput => ({
+  type: "team.created",
+  family: "manage",
+  subject: { teamID: team.id },
+  data: { revision: team.revision, version: team.version, state: team.state },
+})
+
+export const teamUpdatedEvent = (team: Team, change: TeamChange): EventInput => ({
+  type: "team.updated",
+  family: "manage",
+  subject: { teamID: team.id },
+  data: { change, revision: team.revision, version: team.version, paused: team.paused === true },
+})
+
+/** Archived (`state: archived`) or restored (`state: active`). */
+export const teamArchivedEvent = (team: Team): EventInput => ({
+  type: "team.archived",
+  family: "manage",
+  subject: { teamID: team.id },
+  data: { state: team.state, revision: team.revision, version: team.version },
+})
+
+export const teamStaffedEvent = (seat: TeamSeatRecord): EventInput => ({
+  type: "team.staffed",
+  family: "manage",
+  subject: { teamID: seat.teamID, staffingID: seat.id, sessionID: seat.sessionID },
+  data: { generation: seat.generation, revision: seat.revision, version: seat.teamVersion },
+})
+
+export const teamUnstaffedEvent = (seat: TeamSeatRecord): EventInput => ({
+  type: "team.unstaffed",
+  family: "manage",
+  subject: { teamID: seat.teamID, staffingID: seat.id, sessionID: seat.sessionID },
+  data: { generation: seat.generation, revision: seat.revision },
+})

package/src/central/teams/intake-routes.ts

@@ -0,0 +1,100 @@
+// Team intake routes on /api/agent (HWA-36; contract: Teams `POST /teams/:id/intake`, scope teams:submit). The rest
+// of the teams surface (definitions, staffing, roster, teams:read|manage) is HWA-37's.
+//
+//   POST /teams/:id/intake                     {title, brief?, priority?, labels?, due?, criteria?, ref?}  Idempotency-Key
+//   GET  /teams/:id/intake?status&limit&cursor → {items, cursor?}
+//   GET  /teams/:id/intake/:intake           → {intake}
+//   POST /teams/:id/intake/:intake/status    {status, expectedRevision, reason?} → {intake, assignment?}
+//
+// Who (TeamIntakeService decides the details): users; app tokens with teams:submit (submit, read and cancel their
+// own) — reads also accept teams:read/teams:manage once HWA-37 registers them; session tokens (submit under team
+// policy, entry seats report status). Another user's or an unknown team: 404 not_found. Bodies are bounded here.
+import { boundedText } from "../agent/body"
+import type { AgentContext, AgentRoute } from "../agent/routes"
+import { AgentError } from "../agent/errors"
+import { idempotencyKeyOf, storeAnswer } from "../agent/idempotency"
+import type { Store } from "../store"
+import type { TeamIntakeService } from "./intake"
+
+const PREFIX = "/api/agent/teams/:id/intake"
+const NO_STORE = { "cache-control": "no-store" }
+/** Request bodies (the brief is ≤ 16 000 characters). */
+export const INTAKE_BODY_MAX = 96 * 1024
+
+export interface IntakeRoutesDeps {
+  readonly intake: TeamIntakeService
+  readonly audit?: Pick<Store, "audit">
+}
+
+const ok = (body: unknown) => Response.json(body, { headers: NO_STORE })
+
+async function bodyOf(request: Request): Promise<Record<string, unknown>> {
+  const declared = Number(request.headers.get("content-length") ?? "0")
+  if (declared > INTAKE_BODY_MAX) throw new AgentError("invalid", `Body must be at most ${INTAKE_BODY_MAX} bytes`)
+  const text = await boundedText(request, INTAKE_BODY_MAX)
+  if (text.length > INTAKE_BODY_MAX) throw new AgentError("invalid", `Body must be at most ${INTAKE_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 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
+}
+
+export function intakeRoutes(deps: IntakeRoutesDeps): AgentRoute[] {
+  const { intake } = deps
+  const audited = async (context: AgentContext, action: string, target: string) => {
+    await deps.audit?.audit({ actor: context.user.id, action, target, detail: context.actor.kind })
+  }
+  return [
+    {
+      method: "POST",
+      path: PREFIX,
+      allow: { scope: "teams:submit", session: true },
+      async handle(context) {
+        const body = await bodyOf(context.request)
+        const key = idempotencyKeyOf(context.request)
+        const { intake: item, created } = await intake.submit(context.user.id, context.actor, context.params.id!, body, key === undefined ? {} : { idempotencyKey: key })
+        if (created) await audited(context, "team.intake.submit", item.id)
+        return storeAnswer(created, { intake: item })
+      },
+    },
+    {
+      method: "GET",
+      path: PREFIX,
+      allow: { app: true, session: true },
+      async handle({ url, user, actor, params }) {
+        const limit = intParam(url, "limit")
+        const status = url.searchParams.get("status") || undefined
+        const cursor = url.searchParams.get("cursor") || undefined
+        return ok(await intake.list(user.id, actor, params.id!, { ...(limit !== undefined ? { limit } : {}), ...(status ? { status } : {}), ...(cursor ? { cursor } : {}) }))
+      },
+    },
+    {
+      method: "GET",
+      path: `${PREFIX}/:intake`,
+      allow: { app: true, session: true },
+      async handle({ user, actor, params }) {
+        return ok({ intake: await intake.get(user.id, actor, params.id!, params.intake!) })
+      },
+    },
+    {
+      method: "POST",
+      path: `${PREFIX}/:intake/status`,
+      allow: { app: true, session: true },
+      async handle(context) {
+        const body = await bodyOf(context.request)
+        const result = await intake.setStatus(context.user.id, context.actor, context.params.id!, context.params.intake!, body)
+        await audited(context, `team.intake.${result.intake.status === "routed" ? "progress" : result.intake.status}`, result.intake.id)
+        return ok(result)
+      },
+    },
+  ]
+}